usr/src/man/man4/fdi.4

   1 '\" te
   2 .\" This manual page is dervied from documentation obtained from David Zeuthen.
   3 .\" Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH FDI 4 "April 9, 2016"
   8 .SH NAME
   9 fdi \- HAL device information file format
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 /usr/share/lib/xml/dtd/fdi.dtd.1
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .LP
  18 The hardware abstraction layer facility, described in \fBhal\fR(5), uses an
  19 \fBXML\fR-based file format to merge arbitrary properties onto device objects.
  20 The way device information files works is that once all physical properties are
  21 merged onto a device object, it is tried against the set of installed device
  22 information files. Device information files are used for both merging facts and
  23 policy settings for devices.
  24 .sp
  25 .LP
  26 Each device information file has a number of match directives that are tested
  27 against the properties of the device object. The directives have the form:
  28 .sp
  29 .in +2
  30 .nf
  31 <match key="property" [string|int|bool|..]="value">
  32 .fi
  33 .in -2
  34
  35 .sp
  36 .LP
  37 If all the match directives pass, then the device information can include the
  38 following property directives in the form:
  39 .sp
  40 .in +2
  41 .nf
  42 <[merge|append|prepend] key="property" type="[string|int|bool|..]">
  43 .fi
  44 .in -2
  45
  46 .sp
  47 .LP
  48 These directives are used to merge new properties or append to existing
  49 properties on the device object. Any previously property stemming from device
  50 detection can be overridden by a device information file.
  51 .sp
  52 .LP
  53 The \fBmatch\fR, \fBmerge\fR, \fBappend\fR, and \fBprepend\fR directives
  54 require that the key attribute be either a property name on the device object
  55 in question or a path to a property on another device object. The path to a
  56 property is expressed either through direct specification of the \fBUDI\fR,
  57 such as \fB/org/freedesktop/Hal/devices/computer:foo.bar\fR or through indirect
  58 references such as "\fB@info.parent:baz\fR", meaning that the device object
  59 specified by the \fBUDI\fR in the string property "\fBinfo.parent\fR" should be
  60 used to query the property "\fBbaz\fR". It is also possible to use multiple
  61 indirections. For example, for a volume on a \fBUSB\fR memory stick, the
  62 indirection
  63 "\fB@block.storage_device:@storage.physical_device:usb.vendor_id\fR" references
  64 the "\fBusb.vendor_id\fR" property on the device object representing the
  65 \fBUSB\fR interface.
  66 .sp
  67 .LP
  68 When the property to match has been determined, the following attributes can be
  69 used within the "\fBmatch\fR" tag:
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBstring\fR\fR
  74 .ad
  75 .RS 20n
  76 Match a string property. For example, <match key= "foo.bar" string="baz">
  77 matches only if "\fBfoo.bar\fR" is a string property assuming the value
  78 "\fBbaz\fR".
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBint\fR\fR
  85 .ad
  86 .RS 20n
  87 Match an integer property
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBuint64\fR\fR
  94 .ad
  95 .RS 20n
  96 Match property with the 64-bit unsigned type
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBbool\fR\fR
 103 .ad
 104 .RS 20n
 105 Match a boolean property
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBdouble\fR\fR
 112 .ad
 113 .RS 20n
 114 Match a property of type double
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBexists\fR\fR
 121 .ad
 122 .RS 20n
 123 Used as <match key="foo.bar" exists="true">. This attribute can be used with
 124 "true" and "false", respectively to match when a property exists or does not
 125 exist.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBempty\fR\fR
 132 .ad
 133 .RS 20n
 134 This attribute can only be used on string properties with "true" and "false".
 135 The semantics for "true" is to match only when the string is non-empty.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBis_absolute_path\fR\fR
 142 .ad
 143 .RS 20n
 144 Matches only when a string property represents an absolute path (the path does
 145 not have to exist). This attribute can be can be used with "true" or "false".
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBis_ascii\fR\fR
 152 .ad
 153 .RS 20n
 154 Matches only when a string property contains \fBASCII\fR characters. This
 155 attribute can be used with "true" or "false".
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBcompare_lt\fR\fR
 162 .ad
 163 .RS 20n
 164 This attribute can be used with \fBint\fR, \fBuint64\fR, \fBdouble\fR and
 165 \fBstring\fR properties to compare with a constant. It matches when the given
 166 property is less than the given constant using the default ordering.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBcompare_le\fR\fR
 173 .ad
 174 .RS 20n
 175 Similar to \fBcompare_lt\fR, but matches when the given property is less than
 176 or equal than the given constant using the default ordering.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBcompare_gt\fR\fR
 183 .ad
 184 .RS 20n
 185 Similar to \fBcompare_lt\fR, but matches when the given property is greater
 186 than the given constant using the default ordering.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fR
 193 .ad
 194 .RS 20n
 195 Similar to \fBcompare_lt\fR, but matches when the given property is greater
 196 than or equal than the given constant using the default ordering.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fR
 203 .ad
 204 .RS 20n
 205 This attribute can only be used with \fBstring\fR and \fBstrlist\fR (string
 206 list). For a string key, this matches when the property contains the given
 207 (sub)string. For a string list, this matches if the given string matches a item
 208 in the list.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBcontains_ncase\fR\fR
 215 .ad
 216 .RS 20n
 217 Similar to \fBcontains\fR, but the property and the given key are converted to
 218 lowercase before it is checked.
 219 .RE
 220
 221 .sp
 222 .LP
 223 The \fBmerge\fR, \fBappend\fR, and \fBprepend\fR directives all require the
 224 attribute type which specifies what is to be merged. The following values are
 225 supported:
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBstring\fR\fR
 230 .ad
 231 .RS 17n
 232 The value is copied to the property. For example, <merge key="foo bar"
 233 type="string"> baz</merege> merges the value "baz" into the property "foo.bar".
 234 .RE
 235
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBstrlist\fR\fR
 240 .ad
 241 .RS 17n
 242 For \fBmerge\fR, the value is copied to the property and the current property
 243 is overwritten. For \fBappend\fR and \fBprepend\fR, the value is appended or
 244 prepended to the list as a new item.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBbool\fR\fR
 251 .ad
 252 .RS 17n
 253 This attribute can merge the values "true" or "false"
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBint\fR\fR
 260 .ad
 261 .RS 17n
 262 Merges an integer
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fBuint64\fR
 269 .ad
 270 .RS 17n
 271 Merges an unsigned 64-bit integer
 272 .RE
 273
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBdouble\fR\fR
 278 .ad
 279 .RS 17n
 280 Merges a double precision floating point number
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBcopy_property\fR\fR
 287 .ad
 288 .RS 17n
 289 Copies the value of a given property; supports paths with direct and indirect
 290 UDI's. For example, <merge key="foo.bar"
 291 type="copy_property">@info.parent:baz.bat</merge> merges the value of the
 292 property "baz.bat" on the device object with the \fBUDI\fR from the property
 293 "info.parent" into the property "foo.bar" on the device object being processed.
 294 .RE
 295
 296 .sp
 297 .LP
 298 The \fBremove\fR directive requires only a key and can be used with all keys.
 299 For \fBstrlist\fR, there is also a special syntax to remove a item from the
 300 string list. For example, to remove item "bla" from property "foo.bar", use the
 301 following syntax:
 302 .sp
 303 .in +2
 304 .nf
 305 <remove key="foo.bar" type="strlist">bla</merge>
 306 .fi
 307 .in -2
 308
 309 .sp
 310 .LP
 311 Device Information files are stored in the following standard hierarchy with the
 312 following default top level directories \fBinformation\fR, \fBpolicy\fR and
 313 \fBpreprobe\fR:
 314 .sp
 315 .ne 2
 316 .na
 317 \fB\fBinformation\fR\fR
 318 .ad
 319 .RS 15n
 320 Device information files to merge device information.
 321 .sp
 322 .ne 2
 323 .na
 324 \fB\fB10freedesktop\fR\fR
 325 .ad
 326 .RS 17n
 327 Device information files included with the \fBhal\fR tarball.
 328 .RE
 329
 330 .sp
 331 .ne 2
 332 .na
 333 \fB\fB20thirdparty\fR\fR
 334 .ad
 335 .RS 17n
 336 Device information files from the device manufacturer and installed from media
 337 accompanying the hardware.
 338 .RE
 339
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fB30user\fR\fR
 344 .ad
 345 .RS 17n
 346 Device information for specific devices.
 347 .RE
 348
 349 .RE
 350
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fBpolicy\fR\fR
 355 .ad
 356 .RS 15n
 357 Device information files to merge policy properties.
 358 .sp
 359 .ne 2
 360 .na
 361 \fB10osvendor\fR
 362 .ad
 363 .RS 16n
 364 Device information files included with the hal tarball and supplied by the
 365 operating system vendor for policy rules.
 366 .RE
 367
 368 .sp
 369 .ne 2
 370 .na
 371 \fB20thirdparty\fR
 372 .ad
 373 .RS 16n
 374 Policy rules from the device manufacturer and installed from media accompanying
 375 the hardware.
 376 .RE
 377
 378 .sp
 379 .ne 2
 380 .na
 381 \fB30user\fR
 382 .ad
 383 .RS 16n
 384 Policy rules for specific devices.
 385 .RE
 386
 387 .RE
 388
 389 .sp
 390 .ne 2
 391 .na
 392 \fBpreprobe\fR
 393 .ad
 394 .RS 15n
 395 Device information files to merge information before probe devices.
 396 .sp
 397 .ne 2
 398 .na
 399 \fB10osvendor\fR
 400 .ad
 401 .RS 16n
 402 Device information files included with the \fBhal\fR tarball and supplied by
 403 the operating system vendor.
 404 .RE
 405
 406 .sp
 407 .ne 2
 408 .na
 409 \fB20thirdparty\fR
 410 .ad
 411 .RS 16n
 412 Device information files from the device manufacturer and installed from media
 413 accompanying the hardware.
 414 .RE
 415
 416 .sp
 417 .ne 2
 418 .na
 419 \fB30user\fR
 420 .ad
 421 .RS 16n
 422 Device information for specific devices.
 423 .RE
 424
 425 .RE
 426
 427 .sp
 428 .LP
 429 All device information files are matched for every \fBhal\fR device object.
 430 .SH ATTRIBUTES
 431 .LP
 432 See \fBattributes\fR(5) for descriptions of the following attributes:
 433 .sp
 434
 435 .sp
 436 .TS
 437 box;
 438 c | c
 439 l | l .
 440 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 441 _
 442 Interface Stability     Volatile
 443 .TE
 444
 445 .SH SEE ALSO
 446 .LP
 447 \fBhald\fR(1M), \fBattributes\fR(5), \fBhal\fR(5), \fBlocale\fR(5),
 448 \fBsmf\fR(5)