'\" te
.\" This manual page is dervied from documentation obtained from David Zeuthen.
.\" Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH FDI 4 "Sep 5, 2006"
.SH NAME
fdi \- HAL device information file format
.SH SYNOPSIS
.LP
.nf
/usr/share/lib/xml/dtd/fdi.dtd.1
.fi

.SH DESCRIPTION
.sp
.LP
The hardware abstraction layer facility, described in \fBhal\fR(5), uses an
\fBXML\fR-based file format to merge arbitrary properties onto device objects.
The way device information files works is that once all physical properties are
merged onto a device object, it is tried against the set of installed device
information files. Device information files are used for both merging facts and
policy settings for devices.
.sp
.LP
Each device information file has a number of match directives that are tested
against the properties of the device object. The directives have the form:
.sp
.in +2
.nf
<match key="property" [string|int|bool|..]="value">
.fi
.in -2

.sp
.LP
These directives are used to merge new properties or append to existing
properties on the device object. Any previously property stemming from device
detection can be overridden by a device information file.
.sp
.LP
The \fBmatch\fR, \fBmerge\fR, \fBappend\fR, and \fBprepend\fR directives
require that the key attribute be either a property name on the device object
in question or a path to a property on another device object. The path to a
property is expressed either through direct specification of the \fBUDI\fR,
such as \fB/org/freedesktop/Hal/devices/computer:foo.bar\fR or through indirect
references such as "\fB@info.parent:baz\fR", meaning that the device object
specified by the \fBUDI\fR in the string property "\fBinfo.parent\fR" should be
used to query the property "\fBbaz\fR". It is also possible to use multiple
indirections. For example, for a volume on a \fBUSB\fR memory stick, the
indirection
"\fB@block.storage_device:@storage.physical_device:usb.vendor_id\fR" references
the "\fBusb.vendor_id\fR" property on the device object representing the
\fBUSB\fR interface.
.sp
.LP
When the property to match has been determined, the following attributes can be
used within the "\fBmatch\fR" tag:
.sp
.ne 2
.na
\fB\fBstring\fR\fR
.ad
.RS 20n
Match a string property. For example, <match key= "foo.bar" string="baz">
matches only if "\fBfoo.bar\fR" is a string property assuming the value
"\fBbaz\fR".
.RE

.sp
.ne 2
.na
\fB\fBint\fR\fR
.ad
.RS 20n
Match an integer property
.RE

.sp
.ne 2
.na
\fB\fBuint64\fR\fR
.ad
.RS 20n
Match property with the 64-bit unsigned type
.RE

.sp
.ne 2
.na
\fB\fBbool\fR\fR
.ad
.RS 20n
Match a boolean property
.RE

.sp
.ne 2
.na
\fB\fBdouble\fR\fR
.ad
.RS 20n
Match a property of type double
.RE

.sp
.ne 2
.na
\fB\fBexists\fR\fR
.ad
.RS 20n
Used as <match key="foo.bar" exists="true">. This attribute can be used with
"true" and "false", respectively to match when a property exists or does not
exist.
.RE

.sp
.ne 2
.na
\fB\fBempty\fR\fR
.ad
.RS 20n
This attribute can only be used on string properties with "true" and "false".
The semantics for "true" is to match only when the string is non-empty.
.RE

.sp
.ne 2
.na
\fB\fBis_absolute_path\fR\fR
.ad
.RS 20n
Matches only when a string property represents an absolute path (the path does
not have to exist). This attribute can be can be used with "true" or "false".
.RE

.sp
.ne 2
.na
\fB\fBis_ascii\fR\fR
.ad
.RS 20n
Matches only when a string property contains \fBASCII\fR characters. This
attribute can be used with "true" or "false".
.RE

.sp
.ne 2
.na
\fB\fBcompare_lt\fR\fR
.ad
.RS 20n
This attribute can be used with \fBint\fR, \fBuint64\fR, \fBdouble\fR and
\fBstring\fR properties to compare with a constant. It matches when the given
property is less than the given constant using the default ordering.
.RE

.sp
.ne 2
.na
\fB\fBcompare_le\fR\fR
.ad
.RS 20n
Similar to \fBcompare_lt\fR, but matches when the given property is less than
or equal than the given constant using the default ordering.
.RE

.sp
.ne 2
.na
\fB\fBcompare_gt\fR\fR
.ad
.RS 20n
Similar to \fBcompare_lt\fR, but matches when the given property is greater
than the given constant using the default ordering.
.RE

.sp
.ne 2
.na
\fB\fR
.ad
.RS 20n
Similar to \fBcompare_lt\fR, but matches when the given property is greater
than or equal than the given constant using the default ordering.
.RE

.sp
.ne 2
.na
\fB\fR
.ad
.RS 20n
This attribute can only be used with \fBstring\fR and \fBstrlist\fR (string
list). For a string key, this matches when the property contains the given
(sub)string. For a string list, this matches if the given string matches a item
in the list.
.RE

.sp
.ne 2
.na
\fB\fBcontains_ncase\fR\fR
.ad
.RS 20n
Similar to \fBcontains\fR, but the property and the given key are converted to
lowercase before it is checked.
.RE

.sp
.LP
The \fBmerge\fR, \fBappend\fR, and \fBprepend\fR directives all require the
attribute type which specifies what is to be merged. The following values are
supported:
.sp
.ne 2
.na
\fB\fBstring\fR\fR
.ad
.RS 17n
The value is copied to the property. For example, <merge key="foo bar"
type="string"> baz</merege> merges the value "baz" into the property "foo.bar".
.RE

.sp
.ne 2
.na
\fB\fBstrlist\fR\fR
.ad
.RS 17n
For \fBmerge\fR, the value is copied to the property and the current property
is overwritten. For \fBappend\fR and \fBprepend\fR, the value is appended or
prepended to the list as a new item.
.RE

.sp
.ne 2
.na
\fB\fBbool\fR\fR
.ad
.RS 17n
This attribute can merge the values "true" or "false"
.RE

.sp
.ne 2
.na
\fB\fBint\fR\fR
.ad
.RS 17n
Merges an integer
.RE

.sp
.ne 2
.na
\fBuint64\fR
.ad
.RS 17n
Merges an unsigned 64-bit integer
.RE

.sp
.ne 2
.na
\fB\fBdouble\fR\fR
.ad
.RS 17n
Merges a double precision floating point number
.RE

.sp
.ne 2
.na
\fB\fBcopy_property\fR\fR
.ad
.RS 17n
Copies the value of a given property; supports paths with direct and indirect
UDI's. For example, <merge key="foo.bar"
type="copy_property">@info.parent:baz.bat</merge> merges the value of the
property "baz.bat" on the device object with the \fBUDI\fR from the property
"info.parent" into the property "foo.bar" on the device object being processed.
.RE

.sp
.LP
The \fBremove\fR directive requires only a key and can be used with all keys.
For \fBstrlist\fR, there is also a special syntax to remove a item from the
string list. For example, to remove item "bla" from property "foo.bar", use the
following syntax:
.sp
.in +2
.nf
<remove key="foo.bar" type="strlist">bla</merge>
.fi
.in -2

.sp
.LP
Device Information files are stored in the following standard hierachy with the
following default top level directories \fBinformation\fR, \fBpolicy\fR and
\fBpreprobe\fR:
.sp
.ne 2
.na
\fB\fBinformation\fR\fR
.ad
.RS 15n
Device information files to merge device information.
.sp
.ne 2
.na
\fB\fB10freedesktop\fR\fR
.ad
.RS 17n
Device information files included with the \fBhal\fR tarball.
.RE

.sp
.ne 2
.na
\fB\fB20thirdparty\fR\fR
.ad
.RS 17n
Device information files from the device manufacturer and installed from media
accompanying the hardware.
.RE

.sp
.ne 2
.na
\fB\fB30user\fR\fR
.ad
.RS 17n
Device information for specific devices.
.RE

.RE

.sp
.ne 2
.na
\fB\fBpolicy\fR\fR
.ad
.RS 15n
Device information files to merge policy propertys
.sp
.ne 2
.na
\fB10osvendor\fR
.ad
.RS 16n
Device information files included with the hal tarball and supplied by the
operating system vendor for policy rules
.RE

.sp
.ne 2
.na
\fB20thirdparty\fR
.ad
.RS 16n
Policy rules from the device manufacturer and installed from media accompanying
the hardware
.RE

.sp
.ne 2
.na
\fB30user\fR
.ad
.RS 16n
Policy rules for specific devices.
.RE

.RE

.sp
.ne 2
.na
\fBpreprobe\fR
.ad
.RS 15n
Device information files to merge information before probe devices.
.sp
.ne 2
.na
\fB10osvendor\fR
.ad
.RS 16n
Device information files included with the \fBhal\fR tarball and supplied by
the operating system vendor.
.RE

.sp
.ne 2
.na
\fB20thirdparty\fR
.ad
.RS 16n
Device information files from the device manufacturer and installed from media
accompanying the hardware.
.RE

.sp
.ne 2
.na
\fB30user\fR
.ad
.RS 16n
Device information for specific devices.
.RE

.RE

.sp
.LP
All device information files are matched for every \fBhal\fR device object.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Interface Stability Volatile
.TE

.SH SEE ALSO
.sp
.LP
\fBhald\fR(1M), \fBattributes\fR(5), \fBhal\fR(5), \fBlocale\fR(5),
\fBsmf\fR(5)