path: root/doc/spec/hal-spec.xml.in

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id$ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!-- THIS FILE IS AUTOGENERATED FROM hal-spec.xml.in -->

<book id="index">
  <bookinfo>
    <title>HAL @VERSION@ Specification</title>
    <releaseinfo>Version @VERSION@</releaseinfo>
    <date>August 6th, 2004</date> <!-- Update this manually -->
    <authorgroup>
      <author>
	<firstname>David</firstname>
	<surname>Zeuthen</surname>
	<affiliation>
	  <address>
	    <email>david@fubar.dk</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
  </bookinfo>
  
  <chapter id="introduction">
    <title>Introduction</title>

    <sect1>
      <title>About</title>

      <para>
	This document concerns the specification of HAL which is a
	piece of software that provides a view of the various hardware
	attached to a system. In addition to this, HAL keeps detailed
	metadata for each piece of hardware and provide hooks such
	that system- and desktop-level software can react to changes
	in the hardware configuration in order to maintain system
	policy.

      </para>
      <para>

	HAL represents a piece of hardware as a 
	<emphasis>device object</emphasis>. A device object is
	identified by a unique identifer and carries a set of
	key/value paris referred to as <emphasis>device
	properties</emphasis>. Some properties are derived from the
	actual hardware, some are merged from <emphasis>device
	information files</emphasis> and some are related to the
	actual device configuration. This document specifies the set
	of device properties and gives them well-defined meaning. This
	enable system and desktop level components to distinguish
	between the different device objects and discover and
	configure devices based on these properties.

      </para>
      <para>
	
	HAL provides an easy-to-use API through D-BUS which is an IPC
	framework that, among other things, provides a system-wide
	message-bus that allows applications to talk to one
	another. Specifically, D-BUS provides asynchronous
	notification such that HAL can notify other peers on the
	message-bus when devices are added and removed as well as when
	properties on a device are changing.  

      </para>
      <para>

	The most important goal of HAL is to provide plug-and-play
	facilities for UNIX-like desktops with focus on providing a
	rich and extensible description of device characteristics and
	features. HAL has no other major dependencies apart from D-BUS
	which, given sufficient infrastructure, allows it to be
	implemented on many UNIX-like systems. The major focus,
	initially, is systems running the Linux 2.6 series kernels.

      </para>

    </sect1>

    <sect1>
      <title>Document History</title>
      <informaltable>
        <tgroup cols="3">
          <thead>
            <row>
              <entry>Version</entry>
              <entry>Date</entry>
              <entry>Comment</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>0.1</entry>
              <entry>September 28, 2003</entry>
              <entry>Still important things missing. Released with version
                     0.1 of the implementation</entry>
            </row>
            <row>
              <entry>0.2</entry>
              <entry>December 22, 2003</entry>
              <entry>A major rewrite.</entry>
            </row>
            <row>
              <entry>@VERSION@</entry>
              <entry></entry>
              <entry>Current draft from CVS</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect1>

    <sect1>
      <title>Acknowledgements</title>
      <para>

      Havoc Pennington's article
      <ulink url="http://www.ometer.com/hardware.html">''Making
      Hardware Just Work''</ulink> motivated this
      work. The specification and software would not exist
      without all the useful ideas, suggestions, comments and patches
      from the 
      <ulink url="http://freedesktop.org/mailman/listinfo/xdg">Free Desktop</ulink> and
      <ulink url="http://freedesktop.org/mailman/listinfo/hal">HAL</ulink>
      mailing lists.

      </para><para>

      All trademarks mentioned belong to their respective owners.

      </para>
    </sect1>

  </chapter>

  <chapter id="overview"><title>Overview</title>

  <sect1 id="ov_halarch"><title>Architecture of HAL</title>
    <para>

      The HAL consists of a number of components as outlined in the
      diagram below. Note that this diagram is high-level and doesn't
      capture implementation details.

    </para>
    <para>
      <inlinegraphic fileref="hal-arch.png" format="PNG"/>
    </para>
    <para>

      Details on each component

      <itemizedlist>

	<!-- ####################################################### -->

        <listitem><para>
          <emphasis>HAL daemon</emphasis></para><para> 

          A system-wide daemon that maintains a persistent database of
          device objects. The daemon is also responsible for merging
          information from the device information file repository and
          managing the life cycle of device objects. The HAL daemon
          also contains detection and monitoring code for
          buses (such as PCI and USB buses) and devices (such as
          networking and storage devices). The HAL daemon notifies system
          level components through callouts and session level
          components using the D-BUS interface.

        </para></listitem>

	<!-- ####################################################### -->

        <listitem><para>
          <emphasis>Applications</emphasis></para><para> 

            This represents the end consumers of the HAL and comprises
            both applications that need to search for a device, but
            also (existing) device specific libraries and/or services
            that provide access to devices. Specifically, the
            application or device library can obtain the ''address''
            (the special device file or other details), of the device
            through HAL, to interact with the device through the
            kernel as usual.

          </para><para>

            In addition, this group include desktop environments such
            as GNOME or KDE. Specifically, using HAL, desktop
            environments may include session-level daemons enforcing
            certain policies when the device database managed by the
            HAL daemon changes. Such policies may include starting a
            photo management application when a camera is plugged in,
            assisting the user in finding driver software and device
            information files for a new device, displaying link status
            information about network devices, mounting removable
            storage and so on.

          </para><para>

	    Note that several desktop sessions may be active on the
	    same system; it is the responsibility of session-level
	    software to arbitrate the device access between sessions.

        </para></listitem>

	<!-- ####################################################### -->

        <listitem><para>
          <emphasis>Callouts</emphasis></para><para> 

	    Callouts are programs invoked when the device object list
	    is modified or when a device property changes. As such, callouts
	    can be used to maintain system-wide policy (that may be
	    specific to the particular OS) such as changing
	    permissions on device nodes, updating the
	    systemwide <literal>/etc/fstab</literal> file or
	    configuring the networking subsystem.

        </para></listitem>

      </itemizedlist>
      </para>
      <para>

      The HAL uses D-BUS to provide a ''network API'' to
      applications. As D-BUS is designed to be language independent,
      potentially many languages / runtime systems will be able to
      easily access the services offered by HAL. The D-BUS API is
      detailed in <xref linkend="dbus-api"/>. Note that HAL doesn't
      enforce any policy at all, this is left for desktop environments
      and operating systems vendors to implement.  However, to ensure
      interoperability between operating systems and desktop
      environments, recommendations and best practises on how to
      enforce policy is discussed in <xref
      linkend="enforcing-policy"/>.

    </para>
  </sect1>

  <sect1 id="ov_hal_linux26"><title>HAL on Linux 2.6</title>
    <para>

      On a Linux 2.6 system HAL is implemented as shown in the diagram
      below:

      </para>
      <para>
	<inlinegraphic fileref="hal-linux26.png" format="PNG"/>
      </para>
      <para>

      Highlights

      <itemizedlist>

        <listitem><para>
	    HAL depends on the <literal>udev</literal> and 
	    <literal>linux-hotplug</literal> packages
        </para></listitem>

        <listitem><para>
	    The diagram shows an example callout program, 
	    <literal>fstab-sync</literal>, that creates/destroys
	    mount points and modifies the <literal>/etc/fstab</literal>
	    file accordingly whenever storage devices are added or
	    removed.
        </para></listitem>

        <listitem><para>
	    A session-level daemon, <literal>*-volume-manager</literal>,
	    for mounting storage devices is shown. This piece of software
	    depends on a properly updated <literal>/etc/fstab</literal>
	    file and a setuid <literal>mount(1)</literal> binary that 
	    allows an unprivileged user to mount devices marked with option
	    <literal>user</literal> in the <literal>/etc/fstab</literal> file.
        </para></listitem>

        <listitem><para>
	    The <literal>fstab-sync</literal> and 
	    <literal>*-volume-manager</literal> programs are only
	    examples on how to enforce policy and are not part of HAL
	    proper.  An OS vendor may choose to enforce policy in a
	    different way e.g. he might want to ignore the 
	    <literal>/etc/fstab</literal> file and mount storage volumes
	    in the callout, run a daemon with sufficient privileges
	    or use another setuid mount wrapper.
	    See <xref linkend="enforcing-policy"/> for more details.
        </para></listitem>

      </itemizedlist>

    </para>
  </sect1>


  </chapter>

  <chapter>
    <title>Device Objects</title>
      <para>

	It is important to precisely define the term HAL device
	object. It's actually a bit blurry to define in general, it
	includes what most UNIX-like systems consider first class
	objects when it comes to hardware. In particular, a device
	object should represent the smallest unit of addressable
	hardware. This means there can be a one-to-many relationship
	between a physical device and the device objects exported by
	HAL. Specifically, a multi-function printer, which appear to
	users as a single device may show up as several device
	objects; e.g. one HAL device object for each of the printing,
	scanning, fax and storage interfaces. Conversely, some devices
	may be implemented such that the HAL device object represent
	several functional interfaces. HAL is not concerned with this
	duality of either one-to-many or many-to-one relationships
	between device objects and the actual iron constituting what
	users normally understand as a single piece of hardware;
	a device object represents the smallest addressable unit.

      </para><para>

	Device objects in HAL are organised on a by-connection basis,
	e.g. for a given device object X it is possible to find the
	device object Y where X is attached to Y. This gives structure
	to the device database of HAL; it is possible to map the
	devices out in a tree. Further, software emulation devices
	exported by a kernel, such as SCSI emulation for USB Storage
	Devices, are also considered device objects in HAL. This
	implies that kernel specific bits leak into the device object
	database. However users of HAL won't notice, such device
	objects are not referenced anywhere in the device objects that
	users are interested in; they are merely used as glue to build
	the device tree.

      </para><para>

	In addition to provide information about what kind of hardware
	a device object represents (such as a PCI or USB device) and
	how to address it, HAL merges information about the functional
	interfaces the OS kernel provides in order to use the device;
	in most cases this is represented on the device object as a
	string property with the name of the special device file in
	<literal>/dev</literal>. In addition to the special device
	file, a number of other useful properties are merged. This
	means that both hardware and functional properties are on the
	same device object, which is very useful for an application
	programmer. For example, an application might query HAL for
	the device object that exports the special device file
	<literal>/dev/input/mouse2</literal> and learn that this is
	provide by an USB mouse from a certain manufacturer by
	checking the properties that export the USB vendor and product
	identifiers.  See <xref linkend="device-capabilities"/> and
	<xref linkend="device-properties"/> for details.

      </para><para>

	On a formal level, a device object is comprised by

      </para>

      <itemizedlist>
        <listitem><para>

          <emphasis>UDI</emphasis></para><para> 

          This is an identifier, the Unique Device Identifer, that is
          unique for a device object - that is, no other device object
          can have the same UDI at the same time.  The UDI is computed
          using bus-specific information and is meant to be unique
          across device insertions and independent of the physical
          port or slot the device may be plugged into.

        </para></listitem>
        <listitem><para>

          <emphasis>Properties</emphasis></para><para> 

          Each device object got a set of properties which are
          key/value pairs.  The key is an ASCII string while the value
          can be one of several types

          <itemizedlist>
            <listitem><para><literal>string</literal> - 
		UTF8 string</para></listitem>
            <listitem><para><literal>int</literal> - 
		32-bit signed integer</para></listitem>
            <listitem><para><literal>uint64</literal> - 
		64-bit unsigned integer</para></listitem>
            <listitem><para><literal>bool</literal> - 
		truth value</para></listitem>
            <listitem><para><literal>double</literal> - 
		IEEE754 double precision floating point number</para></listitem>
          </itemizedlist>

        </para></listitem>
      </itemizedlist>

      <para>
	Properties of a device object carry all the important
	information about a device object. For organisational reasons
	properties are also namespaced using ''.'' as a separator.
	
      </para><para>

	It can be useful to classify properties into four groups

      </para>
      
      <itemizedlist>

	<listitem><para>Metadata - Information about how the devices
	                are connected with respect to each other
	                (parent/child relationships), what kind of
	                device it is, what functionality it provides
	                etc.
	</para></listitem>

        <listitem><para>Facts - 
                        vendor ID, product ID, disk serial numbers, 
	                number of buttons on a mouse, formats accepted
	                by a mp3 player and so on.</para></listitem>

        <listitem><para>Usage specific information - 
	                Network link status, special device file name, 
                        filesystem mount location etc.</para></listitem>

        <listitem><para>Policy - 
                        How the device is to be used be users; usually
	                defined by the system administrator.</para></listitem>

      </itemizedlist>

      <para>

	The first category is determined by HAL, the next is merged
	from either the hardware itself or device information files,
	the third is intercepted by monitoring the operating system
	and the last is merged from files that only the system
	administrator can edit. This specification is concerned with
	precisely defining several properties; see <xref
	linkend="device-properties"/> and onwards for more
	information.  As a complement to device properties, HAL also
	provides <emphasis>conditions</emphasis> on HAL device
	objects. Conditions are used to relay events that are
	happening on devices which are not easily expressed in
	properties. This includes events such as ''processor is
	overheating'' or ''block device unmounted''.

      </para><para>

	There is a special hal device object referred to as the ''root
	computer device object''. This device object represent the
	entire system as a whole and all other devices are either
	directly or indirectly childs of this device object. It has
	the
	UDI <literal>/org/freedesktop/Hal/devices/computer</literal>.

      </para><para>

	The fundamental idea about HAL is that all ''interesting''
	information about hardware that a desktop application needs,
	can be obtained by querying HAL. Below is a screenshot of a
	simple device manager application shipped with HAL
	called <literal>hal-device-manager</literal>.  This
	application is communicating with the HAL daemon and displays
	the tree of device objects. The shown properties are for a
	device object representing a harddisk.
      </para><para>
        <inlinegraphic fileref="hal-devices1.png" format="PNG"/>
      </para><para>

      </para>
  </chapter>

  <chapter id="device-capabilities">
     <title>Device Capabilities</title>
     <para>

       Mainstream hardware isn't very good at reporting what they are,
       they only report, at best, how to interact with them. This is a
       problem; many devices, such as MP3 players or digital still
       cameras, appear to the operating system as plain USB Mass
       Storage devices when they in fact are a lot more than just
       that. The core of the problem is that without external
       metadata, the operating system and desktop environment will
       present it to the user as just e.g. a mass storage device.

     </para><para>

       As HAL is concerned with merging of external metadata, through
       e.g. device information files, there needs to be some scheme on
       how to record what the device actually is. This is achieved by
       two textual properties, <literal>info.category</literal> and
       <literal>info.capabilities</literal>. The former describes
       <emphasis>what the device is</emphasis> (as a single
       alphanumeric keyword) and the latter describes
       <emphasis>what the device does</emphasis> (as a number of
       alphanumeric keywords separated by whitespace). The keywords
       available for use is defined in this document; we'll refer to
       them in following simply as <emphasis>capabilities</emphasis>.

     </para><para>

       HAL itself, assigns capabilities on device detection time by
       inspecting the device class (if available, it depends on the
       bus type) and looking at information from the operating system
       (most OS'es have a concept of device classes). At this time the
       category is also determined by selecting the most prominent
       capability. However, both capabilities and category can be
       overridden by either device information files or callouts. This
       gives maximum flexibility, while maintaining a base level of
       capability detection.

     </para><para>

       The idea of HAL is that existing device capability specific
       libraries (such as libghoto2), would advertise what kind of HAL
       capabilities they are able to handle. As this happens over
       time, this specification will grow to precisely define what a
       device with a given capability is supposed to do and what
       library, or service, the application programmer can use to
       access the device.
     
     </para><para>

       Having a capability also means that part of the property
       namespace, prefixed with the capability name, will be populated
       with more specific information about the capability. Indeed,
       some properties may even be required such that applications and
       device libraries have something to expect. For instance, the
       capability for being a MP3 player may require properties
       defining what audio formats the device support, whether it
       support recording of audio, and how to interact with the
       device. For example, the latter may specify ''USB Storage
       Device'' or ''proprietary protocol, use libfooplayer''.

     </para><para>

       Just as device objects can appear and disappear at any time
       (e.g. when a device is plugged in respectively removed),
       capabilities can also appear and disappear - one example of
       this happening is when device drivers are loaded and unloaded.

     </para><para>

       Finally, capabilities have an inheritance scheme, e.g. if a device
       has a capability <literal>foo.bar</literal>, it must also have
       the capability <literal>foo</literal>.

     </para>
  </chapter>

  <chapter id="using-devices">
    <title>Using devices</title>
    <para>

      While the HAL daemon provides generic operations that apply to
      all devices (though some may be no-ops), HAL is not concerned
      with providing non-generic device operations. Specifically, one
      goal of HAL is to integrate with existing and future libraries
      that target a specific class of devices such as cameras or mp3
      players.

    </para><para>

      For instance, <literal>libgphoto2</literal> could be extended
      such that the application programmer can simply pass the UDI of
      the camera he wishes to interact with
      and <literal>libghoto2</literal> would then, via D-BUS, acquire
      the bus-specific information required, the address so to speak,
      from the HAL daemon, and then interact directly with the
      hardware.

    </para><para>

      Another option is to use the existing API of the device library
      to discover devices (the library would be using HAL under the
      hood) and provide a function to retrieve the HAL UDI of the
      device. When the library is built without HAL support this
      function returns <literal>NULL</literal>, however, when the UDI
      is available, then applications using the library can use the
      UDI both as stable reference to the device and also to extract
      more information directly from the HAL daemon.

    </para>
  </chapter>

  <chapter id="device-properties">
    <title>Device Properties</title>

    <para>
      Properties are arranged in a namespaces using ''.'' as a separator
      and are key/value pairs. The value may assume different types; currently
      int32, double, bool and UTF8 strings are supported. The key of a property
      is always an ASCII string without any whitespace. The properties are
      updated in real-time.
    </para>

    <sect1 id="properties-metadata">
      <title>Metadata Properties</title>

      <para>

	The section represents properties that aren't tied to either
	physical or functional characteristics of what the device
	object represents.

      </para>

    <sect2 id="device-properties-info">
      <title><literal>info</literal> namespace</title>
      <para>

      The <literal>info</literal> namespace contain properties that
      can be considered metadata about device objects. These
      properties are always available.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>info.bus</literal> (string)</entry>
              <entry>pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi</entry>
              <entry>Yes</entry>
              <entry>Describes what ''physical'' bus the device is connected to</entry>
            </row>
            <row>
              <entry><literal>info.udi</literal> (string)</entry>
              <entry>example: /org/freedesktop/Hal/devices/pci_10ec_8139</entry>
              <entry>Yes</entry>
              <entry>The HAL unique device id</entry>
            </row>
            <row>
              <entry><literal>info.persistent</literal> (bool)</entry>
              <entry></entry>
              <entry>No, but required if <literal>info.not_available</literal> is set to TRUE</entry>
              <entry>If this property is set, the device will remain in the
                     the GDL even if the device is unplugged</entry>
            </row>
            <row>
              <entry><literal>info.not_available</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>The device is currently not available (it may be unplugged
                     or powered down)</entry>
            </row>
            <row>
              <entry><literal>info.capabilities</literal> (string)</entry>
              <entry>example: block storage storage.cdrom</entry>
              <entry>No</entry>
              <entry>A white-space separated list of capabilities describing what the devices does</entry>
            </row>
            <row>
              <entry><literal>info.category</literal> (string)</entry>
              <entry>example: storage.cdrom</entry>
              <entry>No</entry>
              <entry>The prominent capability describing what the device is</entry>
            </row>
            <row>
              <entry><literal>info.product</literal> (string)</entry>
              <entry>examples: ''SleekKeyboard'', ''MouseMan 2003'', ''Volume'', ''LS-120 SLIM3 00 UHD Floppy''</entry>
              <entry>No</entry>
              <entry>The name of the device</entry>
            </row>
            <row>
              <entry><literal>info.vendor</literal> (string)</entry>
              <entry>examples: Logitch, Mustek</entry>
              <entry>No</entry>
              <entry>The name of the vendor of the device</entry>
            </row>
            <row>
              <entry><literal>info.parent</literal> (string)</entry>
              <entry>example: /org/freedesktop/Hal/devices/ide_1_0</entry>
              <entry>Yes, for all non-root device objects</entry>
              <entry>The UDI of the device object that this device object
	      is connected to.</entry>
            </row>

	    <row>
              <entry><literal>info.locked</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		If this property is available and set
		to <literal>TRUE</literal> it means that a process
		is using the device that the hal device object in
		question represents and no other process should attempt
		to use or configure the device. The lock is only
		advisory.
	      </entry>
	    </row>
	    <row>
              <entry><literal>info.locked.reason</literal> (string)</entry>
              <entry>
		example: ''The optical drive is currently being used to
		record a CD-RW disc.''
	      </entry>
              <entry>
		Only available if <literal>info.locked</literal> is set
		to <literal>TRUE</literal>.
	      </entry>
              <entry>A localized text suitable for UI display</entry>
	    </row>
	    <row>
              <entry><literal>info.locked.dbus_service</literal> (string)</entry>
              <entry>example: :1.278</entry>
              <entry>
		Only available if <literal>info.locked</literal> is set
		to <literal>TRUE</literal>.
	      </entry>
              <entry>The base D-BUS service of the process holding the lock.</entry>
	    </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-linux">
      <title><literal>linux</literal> namespace</title>
      <para>
	This namespace is used to store Linux-specific metadata about the
	device object and is only available on Linux systems.
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>linux.sysfs_path</literal> (string)</entry>
              <entry>examples: /sys/block/sda/sda1, /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0</entry>
              <entry>Yes</entry>
              <entry>A fully-qualified path into the sysfs filesystem for the
              physical device</entry>
            </row>
            <row>
              <entry><literal>linux.sysfs_path_device</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Normally this property assumes the same value as 
              linux.sysfs_path, however for some devices it assumes an
              alternate location in the sysfs filesystem. It is used
              internally in HAL</entry>
            </row>
            <row>
              <entry><literal>linux.acpi_path</literal> (string)</entry>
              <entry>example: /proc/acpi/button/power/PWRF, /proc/pmu/battery_0</entry>
              <entry>No</entry>
              <entry>
                A fully-qualified path into the procfs filesystem for a
                device object representing an ACPI abstraction.
              </entry>
            </row>
            <row>
              <entry><literal>linux.driver</literal> (string)</entry>
              <entry>examples: agpgart-intel, yenta_cardbus, usb, hub, usbhid</entry>
              <entry>No</entry>
              <entry>Name of the driver bound to this device</entry>
            </row>
            <row>
              <entry><literal>linux.kernel_devname</literal> (string)</entry>
              <entry>example: usb-0000:00:07.2-1.2</entry>
              <entry>No</entry>
              <entry>A name used internally in the Linux kernel to identify
              the device. Used internally in HAL.</entry>
            </row>

            <row>
              <entry><literal>linux.is_selinux_enabled</literal> (bool)</entry>
              <entry></entry>
              <entry>No; can only appear on the root computer device object</entry>
              <entry>Whether SELinux is enabled on the system</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>
      </para>
    </sect2>

    </sect1>
    <sect1 id="properties-bus">
      <title>Physical Properties</title>

      <para>

	In this section properties for device objects that represent
	physically addressable hardware is described. Availability of
	these depends on the value of the <literal>info.bus</literal>
	property.  These properties are not of particular interest to
	application developers, instead they are useful for libraries
	and userspace drivers that needs to interact with the device
	given a UDI. Knowledge of various bus interconnect
	technologies is assumed for this section to be useful.

      </para>

    <sect2 id="device-properties-pci">
      <title><literal>pci</literal> namespace</title>

      <para>

	This namespace contains properties for device objects representing
	functions on devices on a PCI bus. These properties are available
	exactly when <literal>info.bus</literal> equals <literal>pci</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>pci.device_class</literal> (int)</entry>
              <entry>example: 3</entry>
              <entry>Yes</entry>
              <entry>Device Class</entry>
            </row>
            <row>
              <entry><literal>pci.device_subclass</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>PCI Device Sub Class</entry>
            </row>
            <row>
              <entry><literal>pci.device_protocol</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>Device Protocol</entry>
            </row>
            <row>
              <entry><literal>pci.product_id</literal> (int)</entry>
              <entry>example: 0x4c4d</entry>
              <entry>Yes</entry>
              <entry>Product ID</entry>
            </row>
            <row>
              <entry><literal>pci.vendor_id</literal> (int)</entry>
              <entry>example: 0x1002</entry>
              <entry>Yes</entry>
              <entry>Vendor ID</entry>
            </row>
            <row>
              <entry><literal>pci.subsys_product_id</literal> (int)</entry>
              <entry>example: 0x009e</entry>
              <entry>Yes</entry>
              <entry>Subsystem product id</entry>
            </row>
            <row>
              <entry><literal>pci.subsys_vendor_id</literal> (int)</entry>
              <entry>example: 0x1028</entry>
              <entry>Yes</entry>
              <entry>Subsystem vendor id</entry>
            </row>
            <row>
              <entry><literal>pci.linux.sysfs_path</literal> (string)</entry>
              <entry>example: /sys/devices/pci0000:00/0000:00:01/0000:01:00.0</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Equals <literal>linux.sysfs_path</literal></entry>
            </row>
            <row>
              <entry><literal>pci.product</literal> (string)</entry>
              <entry>Rage Mobility P/M AGP 2x</entry>
              <entry>No</entry>
              <entry>Name of the product per the PCI database</entry>
            </row>
            <row>
              <entry><literal>pci.vendor</literal> (string)</entry>
              <entry>ATI Technologies Inc</entry>
              <entry>No</entry>
              <entry>Name of the vendor per the PCI database</entry>
            </row>
            <row>
              <entry><literal>pci.subsys_product</literal> (string)</entry>
              <entry>Inspiron 7500</entry>
              <entry>No</entry>
              <entry>Name of the subsystem product per the PCI database</entry>
            </row>
            <row>
              <entry><literal>pci.subsys_vendor</literal> (string)</entry>
              <entry>Dell Computer Corporation</entry>
              <entry>No</entry>
              <entry>Name of the subsystem vendor per the PCI database</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      (FIXME: Some key PCI information (bus, slot, port, function
      etc.) is missing here)

      </para>
    </sect2>


    <sect2 id="device-properties-usb">
      <title><literal>usb_device</literal> namespace</title>
      <para>

	For device objects representing USB devices the property
	<literal>info.bus</literal> will be <literal>usb_device</literal>, 
	and the following properties will be available. Note that the 
	corresponding USB interfaces are represented by separate
	device objects as children.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>usb_device.bus_number</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>The USB bus the device is attached to</entry>
            </row>
            <row>
              <entry><literal>usb_device.configuration_value</literal> (int) </entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>The current configuration the USB device is in;
              starting from 1</entry>
            </row>
            <row>
              <entry><literal>usb_device.num_configurations</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Number of configurations this USB device 
              can assume</entry>
            </row>
            <row>
              <entry><literal>usb_device.device_class</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>USB Device Class</entry>
            </row>
            <row>
              <entry><literal>usb_device.device_subclass</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>USB Device Sub Class</entry>
            </row>
            <row>
              <entry><literal>usb_device.device_protocol</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>USB Device Protocol</entry>
            </row>

            <row>
              <entry><literal>usb_device.is_self_powered</literal> (bool)</entry>
              <entry>example: false</entry>
              <entry>Yes</entry>
              <entry>The device, in the current configuration, is self 
		powered</entry>
            </row>
            <row>
              <entry><literal>usb_device.can_wake_up</literal> (bool)</entry>
              <entry>example: true</entry>
              <entry>Yes</entry>
              <entry>The device, in the current configuration, can wake up</entry>
            </row>

            <row>
              <entry><literal>usb_device.max_power</literal> (int)</entry>
              <entry>example: 98</entry>
              <entry>Yes</entry>
              <entry>Max power drain of device, in mA</entry>
            </row>
            <row>
              <entry><literal>usb_device.num_interfaces</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Number of USB Interfaces in the current configuration</entry>
            </row>
            <row>
              <entry><literal>usb_device.num_ports</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>Number of ports on a hub. Zero for non-hubs</entry>
            </row>
            <row>
              <entry><literal>usb_device.port_number</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>The port number on the parent hub that the device is attached to, starting from 1</entry>
            </row>
            <row>
              <entry><literal>usb_device.speed_bcd</literal> (int)</entry>
              <entry>examples: 0x00150, 0x01200, 0x48000</entry>
              <entry>Yes</entry>
              <entry>Speed of device, in Mbit/s, in BCD with two decimals</entry>
            </row>
            <row>
              <entry><literal>usb_device.version_bcd</literal> (int)</entry>
              <entry>examples: 0x0100, 0x0110, 0x0200</entry>
              <entry>Yes</entry>
              <entry>USB version of device in BCD with two decimals</entry>
            </row>
            <row>
              <entry><literal>usb_device.level_number</literal> (int)</entry>
              <entry>example: 2</entry>
              <entry>Yes</entry>
              <entry>Depth in physical USB tree, where the virtual root hub
              is at depth 0</entry>
            </row>
            <row>
              <entry><literal>usb_device.linux.device_number</literal> (string)</entry>
              <entry>example: 19</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>USB Device Number as assigned by the Linux kernel</entry>
            </row>
            <row>
              <entry><literal>usb_device.linux.parent_number</literal> (string)</entry>
              <entry>example: 19</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Device number of parent device as assigned by the
              Linux kernel</entry>
            </row>
            <row>
              <entry><literal>usb_device.linux.sysfs_path</literal> (string)</entry>
              <entry>example: /sys/devices/pci0000:00/0000:00:07.2/usb1/1-1/1-1.1</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Equals <literal>linux.sysfs_path</literal></entry>
            </row>
            <row>
              <entry><literal>usb_device.product_id</literal> (int)</entry>
              <entry>example: 0x3005</entry>
              <entry>Yes</entry>
              <entry>USB Product ID</entry>
            </row>
            <row>
              <entry><literal>usb_device.vendor_id</literal> (int)</entry>
              <entry>example: 0x04b3</entry>
              <entry>Yes</entry>
              <entry>USB Vendor ID</entry>
            </row>
            <row>
              <entry><literal>usb_device.device_revision_bcd</literal> (int)</entry>
              <entry>example: 0x0100</entry>
              <entry>Yes</entry>
              <entry>Device Revision Number encoded in BCD with two decimals</entry>
            </row>
            <row>
              <entry><literal>usb_device.serial</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>A string uniquely identifying the instance 
              of the device; ie. it will be different for two devices
              of the same type. Note that the serial number is broken
	      on some USB devices.</entry>
            </row>
            <row>
              <entry><literal>usb_device.product</literal> (string)</entry>
              <entry>example: IBM USB HUB KEYBOARD</entry>
              <entry>No</entry>
              <entry>Name of the product per the USB ID Database</entry>
            </row>
            <row>
              <entry><literal>usb_device.vendor</literal> (string)</entry>
              <entry>example: IBM Corp.</entry>
              <entry>No</entry>
              <entry>Name of the vendor per the USB ID Database</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
	
    </sect2>


    <sect2 id="device-properties-usbif">
      <title><literal>usb</literal> namespace</title>
      <para>

	Device objects that represent USB interfaces, ie. when
	<literal>info.bus</literal> assumes <literal>usb</literal>,
	are represented by the properties below. In addition all
	the <literal>usb_device.*</literal> properties from the parent
	USB device is available in this namespace but only with
	the <literal>usb</literal> prefix instead of
	<literal>usb_device</literal>.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>usb.interface.class</literal> (int)</entry>
              <entry>example: 0x03</entry>
              <entry>Yes</entry>
              <entry>USB Class for the interface</entry>
            </row>
            <row>
              <entry><literal>usb.interface.subclass</literal> (int)</entry>
              <entry>example: 0x01</entry>
              <entry>Yes</entry>
              <entry>USB Sub Class for this interface</entry>
            </row>
            <row>
              <entry><literal>usb.interface.protocol</literal> (int)</entry>
              <entry>example: 0x01</entry>
              <entry>Yes</entry>
              <entry>USB Protocol for the interface</entry>
            </row>
            <row>
              <entry><literal>usb.interface.number</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Number of this interface, starting from zero</entry>
            </row>
            <row>
              <entry><literal>usb.linux.sysfs_path</literal> (string)</entry>
              <entry>example: /sys/devices/pci0000:00/0000:00:07.2/usb1/1-1/1-1.1/1-1.1:1.0</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Equals <literal>linux.sysfs_path</literal></entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
	
    </sect2>


    <sect2 id="device-properties-ide-host">
      <title><literal>ide_host</literal> namespace</title>

      <para>

	The <literal>ide_host</literal> namespace is present for
	device objects where <literal>info.bus</literal> is set
	to <literal>ide_host</literal>.  Such device objects represent
	IDE and ATA host adaptors for harddisks and optical drives as
	found in the majority of computer systems.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ide_host.number</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>A unique number identifying the IDE host adaptor</entry>
            </row>
            <row>
              <entry><literal>ide_host.linux.sysfs_path</literal> (string)</entry>
              <entry>example: /sys/devices/pci0000:00/0000:00:07.1/ide0</entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Equals <literal>linux.sysfs_path</literal></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

    </sect2>


    <sect2 id="device-properties-ide">
      <title><literal>ide</literal> namespace</title>
      <para>

	ATA and IDE drives are represented by device objects where
	<literal>info.bus</literal> equals <literal>ide</literal>. The
	following properties are available for such device objects.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ide.host</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Corresponds
		to <literal>ide_host.host_number</literal> of
		the <literal>ide_host</literal> device that is the
		parent of this device object</entry>
            </row>
            <row>
              <entry><literal>ide.channel</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Identifies the IDE channel of the host interface</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-scsi_host">
      <title><literal>scsi_host</literal> namespace</title>
      <para>

	The <literal>scsi_host</literal> namespace is present for
	device objects where <literal>info.bus</literal> is set
	to <literal>scsi_host</literal>.  Such device objects represent
	SCSI host adaptors for SCSI devices as found in some computer
	systems.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>scsi_host.host</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>A unique number identifying the SCSI host adaptor</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-scsi">
      <title><literal>scsi</literal> namespace</title>
      <para>

	SCSI devices are represented by device objects where
	<literal>info.bus</literal> equals <literal>scsi</literal>.
	The following properties are available for such device objects.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>scsi.host</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Corresponds to <literal>scsi_host.host</literal>
		of the <literal>scsi_host</literal> device that is the
		parent of this device object</entry>
            </row>
            <row>
              <entry><literal>scsi.bus</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>SCSI channel number</entry>
            </row>
            <row>
              <entry><literal>scsi.target</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>SCSI identifier number</entry>
            </row>
            <row>
              <entry><literal>scsi.lun</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>SCSI Logical Unit Number</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-ieee1394_host">
      <title><literal>ieee1394_host</literal> namespace</title>
      <para>

	Device objects with <literal>info.bus</literal> set to
	<literal>ieee1394_host</literal> represent IEEE 1394 host
	adaptors. The following properties are available for such
	device objects.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ieee1394_host.is_busmgr</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>

            <row>
              <entry><literal>ieee1394_host.is_irn</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>

            <row>
              <entry><literal>ieee1394_host.is_root</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>

            <row>
              <entry><literal>ieee1394_host.node_count</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>

            <row>
              <entry><literal>ieee1394_host.nodes_active</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-ieee1394_node">
      <title><literal>ieee1394_node</literal> namespace</title>
      <para>

	Device objects with <literal>info.bus</literal> set to 
	<literal>ieee1394_node</literal> represent IEEE 1394 nodes on
	a IEEE 1394 bus. The following properties are available for
	such device objects.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ieee1394_node.capabilities</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>ieee1394_node.guid</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>ieee1394_node.nodeid</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>ieee1394_node.vendor</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>ieee1394_node.vendor_id</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-ieee1394">
      <title><literal>ieee1394</literal> namespace</title>
      <para>

	Device objects with <literal>info.bus</literal> set to 
	<literal>ieee1394</literal> represent IEEE 1394 devices. The 
	following properties are available for such device objects.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ieee1394.specifier_id</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-ccw">
      <title><literal>ccw</literal> namespace</title>

      <para>

	Device objects that represent s390 ccw devices (when <literal>info.bus
	</literal> is set to <literal>ccw</literal>) are represented by the
	properties below.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccw.devtype</literal> (string)</entry>
              <entry>example: 1732/01</entry>
              <entry>Yes</entry>
              <entry>Device type/model or n/a</entry>
            </row>
            <row>
              <entry><literal>ccw.cutype</literal> (string)</entry>
              <entry>example: 1731/01</entry>
              <entry>Yes</entry>
              <entry>Control unit type/model</entry>
            </row>
            <row>
              <entry><literal>ccw.cmb_enable</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>If channel measurements are enabled</entry>
            </row>
            <row>
              <entry><literal>ccw.availability</literal> (string)</entry>
              <entry>example: good</entry>
              <entry>Yes</entry>
              <entry>Can be one of 'good', 'boxed', 'no path',
		or 'no device'</entry>
            </row>
            <row>
              <entry><literal>ccw.online</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Online status</entry>
            </row>
            <row>
              <entry><literal>ccw.bus_id</literal> (string)</entry>
              <entry>example: 0.0.f588</entry>
              <entry>Yes</entry>
              <entry>The device's bus id in sysfs</entry>
            </row>
            <row>
              <entry><literal>ccw.subchannel.pim</literal> (int)</entry>
              <entry>example: 0x80</entry>
              <entry>No</entry>
              <entry>path installed mask</entry>
            </row>
            <row>
              <entry><literal>ccw.subchannel.pam</literal> (int)</entry>
              <entry>example: 0x80</entry>
              <entry>No</entry>
              <entry>path available mask</entry>
            </row>
            <row>
              <entry><literal>ccw.subchannel.pom</literal> (int)</entry>
              <entry>example: 0xff</entry>
              <entry>No</entry>
              <entry>path operational mask</entry>
            </row>
            <row>
              <entry><literal>ccw.subchannel.chpid0..7</literal> (int)</entry>
              <entry>example: 0x40</entry>
              <entry>No</entry>
              <entry>channel path ids</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>

	<para>

	The following properties describe <literal>ccw</literal> devices where
	<literal>linux.driver</literal> is either <literal>dasd-eckd</literal>
	or <literal>dasd-fba</literal>.

	</para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ccw.dasd.use_diag</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>If the device driver shall use diagnose calls to access
	      the device</entry>
            </row>
            <row>
              <entry><literal>ccw.dasd.readonly</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>If the device can only be accessed readonly</entry>
            </row>
            <row>
              <entry><literal>ccw.dasd.discipline</literal> (string)</entry>
              <entry>example: ECKD</entry>
              <entry>No</entry>
              <entry>The dasd discipline used to access the device</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>

	<para>

	The following properties describe <literal>ccw</literal> devices where
	<literal>linux.driver</literal> is <literal>zfcp</literal>. They are
	only present when <literal>ccw.online = 1</literal>.

	</para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ccw.zfcp.in_recovery</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>Shows whether the adapter is currently in recovery</entry>
            </row>
            <row>
              <entry><literal>ccw.zfcp.failed</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>Shows whether the adapter is in failed state</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>

	<para>

	The following properties describe <literal>ccw</literal> devices where
	<literal>linux.driver</literal> is of the form <literal>tape_3xxx
	</literal>.

	</para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ccw.tape.state</literal> (string)</entry>
              <entry>example: IN_USE</entry>
              <entry>Yes</entry>
              <entry>The current status of the tape</entry>
            </row>
            <row>
              <entry><literal>ccw.tape.operation</literal> (string)</entry>
              <entry>example: REW</entry>
              <entry>Yes</entry>
              <entry>A three-letter mnemonic of the current tape operation
	      </entry>
            </row>
            <row>
              <entry><literal>ccw.tape.mediumstate</literal> (string)</entry>
              <entry>example: no medium</entry>
              <entry>No</entry>
              <entry>If <literal>ccw.online = 1</literal>, shows whether a tape 
	      is loaded</entry>
            </row>
            <row>
              <entry><literal>ccw.tape.blocksize</literal> (int)</entry>
              <entry>example: 512</entry>
              <entry>No</entry>
              <entry>If <literal>ccw.online = 1</literal>, shows the blocksize
	      used for reads and writes to the tape</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>

	<para>

	The following properties describe <literal>ccw</literal> devices where
	<literal>linux.driver</literal> is <literal>3270</literal>.

	</para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ccw.3270.model</literal> (int)</entry>
              <entry>example: 3</entry>
              <entry>Yes</entry>
              <entry>The model of the device, determining rows and columns
	      </entry>
            </row>
            <row>
              <entry><literal>ccw.3270.rows</literal> (int)</entry>
              <entry>example: 32</entry>
              <entry>Yes</entry>
              <entry>The number of rows</entry>
            </row>
            <row>
              <entry><literal>ccw.3270.columns</literal> (int)</entry>
              <entry>example: 80</entry>
              <entry>Yes</entry>
              <entry>The number of columns</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-ccwgroup">
      <title><literal>ccwgroup</literal> namespace</title>

      <para>

	Device objects that represent groups of <literal>ccw</literal> devices
	(when <literal>info.bus</literal> is set to <literal>ccwgroup</literal>
	have the properties specified below.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccwgroup.online</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Online status</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.bus_id</literal> (string)</entry>
              <entry>example: 0.0.f588</entry>
              <entry>Yes</entry>
              <entry>The device's bus id in sysfs</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      The following properties describe <literal>ccwgroup</literal> devices
      where <literal>linux.driver</literal> is <literal>qeth</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccwgroup.qeth.large_send</literal> (string)
	      </entry>
              <entry>example: TSO</entry>
              <entry>No</entry>
              <entry>Whether large send is provided. Can be "no", "EDDP"
	      (software) or "TSO" (hardware).</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.card_type</literal> (string)</entry>
              <entry>example: OSD_1000</entry>
              <entry>Yes</entry>
              <entry>Type of the card</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.checksumming</literal> (string)
	      </entry>
              <entry>example: sw checksumming</entry>
              <entry>No</entry>
              <entry>The method used to checksum incoming packets</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.canonical_macaddr</literal> (int)
	      </entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>Specifies the token ring macaddress format. Not valid in
	      layer2 mode and for ethernet devices.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.broadcast_mode</literal> (string)
	      </entry>
              <entry>example: broadcast_allrings</entry>
              <entry>No</entry>
              <entry>The scope of token ring broadcasts. Not valid in layer2
	      mode and for ethernet devices.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.fake_broadcast</literal> (int)
	      </entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>Whether to fake broadcast capability. Not valid in layer2
	      mode.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.fake_ll</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>Whether to add a faked link level header to packets.
	      Not valid in layer2 mode.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.layer2</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>Whether the card operates in layer 2 mode</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.portname</literal> (string)</entry>
              <entry>example: OSAPORT</entry>
              <entry>No</entry>
              <entry>The port name which has been specified for the card</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.portno</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>The relative port number on the card</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.buffer_count</literal> (int)</entry>
              <entry>example: 16</entry>
              <entry>Yes</entry>
              <entry>Number of inbound buffers used</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.add_hhlen</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>No</entry>
              <entry>How much additional space is provided in the hardware
	      header in skbs in front of packets</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.priority_queueing</literal> 
	      (string)</entry>
              <entry>example: always queue 2</entry>
              <entry>No</entry>
              <entry>Which priority queueing algorithm is to be used</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.route4</literal> (string)</entry>
              <entry>example: no</entry>
              <entry>No</entry>
              <entry>Whether the card has a routing functionality for ipv4.
	      Not valid in layer2 mode.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.route6</literal> (string)</entry>
              <entry>example: no</entry>
              <entry>No</entry>
              <entry>Whether the card has a routing functionality for ipv6.
	      Not valid in layer2 mode.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.qeth.state</literal> (string)</entry>
              <entry>example: UP (LAN ONLINE)</entry>
              <entry>Yes</entry>
              <entry>The device's current state</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      The following properties describe <literal>ccwgroup</literal> devices
      where <literal>linux.driver</literal> is <literal>ctc</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccwgroup.ctc.protocol</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>The protocol/method used by the connection</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.ctc.type</literal> (string)</entry>
              <entry>example: CTC/A</entry>
              <entry>Yes</entry>
              <entry>The device/connection type</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.ctc.buffer</literal> (int) </entry>
              <entry>example: 32768</entry>
              <entry>No</entry>
              <entry>The maximum buffer size of the connection</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      The following properties describe <literal>ccwgroup</literal> devices
      where <literal>linux.driver</literal> is <literal>lcs</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccwgroup.lcs.portnumber</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>The port on the card that is used</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.lcs.type</literal> (string)</entry>
              <entry>example: OSA LCS card</entry>
              <entry>Yes</entry>
              <entry>The type of the card</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.lcs.lancmd_timeout</literal> (int)
	      </entry>
              <entry>example: 5</entry>
              <entry>Yes</entry>
              <entry>The timeout value for LAN commands in seconds</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      The following properties describe <literal>ccwgroup</literal> devices
      where <literal>linux.driver</literal> is <literal>claw</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>ccwgroup.claw.api_type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Determines the packing algorithm for outgoing pakets
	      (matching the remote peer)
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry>IP</entry>
              <entry></entry>
              <entry>Using the IP protocol</entry>
            </row>
            <row>
              <entry></entry>
              <entry>PACKED</entry>
              <entry></entry>
              <entry>Using an enhanced packing algorithm</entry>
            </row>
            <row>
              <entry></entry>
              <entry>TCPIP</entry>
              <entry></entry>
              <entry>Using the TCP/IP protocol</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.claw.adapter_name</literal> (string)
	      </entry>
              <entry>example: RS1</entry>
              <entry>Yes</entry>
              <entry>The host name of the remote communication peer.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.claw.host_name</literal> (string)</entry>
              <entry>example: LNX1</entry>
              <entry>Yes</entry>
              <entry>The host name of the local adapter.</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.claw.read_buffer</literal> (int)</entry>
              <entry>example: 4</entry>
              <entry>Yes</entry>
              <entry>The number of read buffers allocated</entry>
            </row>
            <row>
              <entry><literal>ccwgroup.claw.write_buffer</literal> (int)</entry>
              <entry>example: 5</entry>
              <entry>Yes</entry>
              <entry>The number of write buffers allocated</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-iucv">
      <title><literal>iucv</literal> namespace</title>

      <para>

	Device objects with <literal>info.bus</literal> set to <literal>iucv
	</literal> are using the "Intra-User Comminication Vehicle" and are
	described by the following properties.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>iucv.bus_id</literal> (string)</entry>
              <entry>example: netiucv0</entry>
              <entry>Yes</entry>
              <entry>The device's bus id in sysfs</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
      <para>

      The following properties describe <literal>iucv</literal> devices
      where <literal>linux.driver</literal> is <literal>netiucv</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>iucv.netiucv.user</literal> (string) </entry>
              <entry>example: linux12</entry>
              <entry>Yes</entry>
              <entry>The guest name of the connection's target</entry>
            </row>
            <row>
              <entry><literal>iucv.netiucv.buffer</literal> (int) </entry>
              <entry>example: 32768</entry>
              <entry>Yes</entry>
              <entry>The maximum buffer size of the connection</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-block">
      <title><literal>block</literal> namespace</title>
      <para>

	Device objects representing addressable block devices, such as
	drives and partitions, will have <literal>info.bus</literal>
	set to <literal>block</literal> and will export a number of
	properties in the <literal>block</literal> namespace.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>block.device</literal> (string)</entry>
              <entry>example: /dev/sda </entry>
              <entry>Yes</entry>
              <entry>Special device file to interact with the block device</entry>
            </row>
            <row>
              <entry><literal>block.major</literal> (int)</entry>
              <entry>example: 8</entry>
              <entry>Yes</entry>
              <entry>Major number of special file to interact with the 
              device</entry>
            </row>
            <row>
              <entry><literal>block.minor</literal> (int)</entry>
              <entry>example: 1</entry>
              <entry>Yes</entry>
              <entry>Minor number of special file to interact with the 
              device</entry>
            </row>
            <row>
              <entry><literal>block.is_volume</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>True only when the block device is a volume that can
		be mounted into the file system. In this case the
		<literal>volume</literal> capability will be set and
		thus, properties, in the <literal>volume</literal>
		namespace are available.</entry>
            </row>
            <row>
              <entry><literal>block.no_partitions</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>For toplevel block devices, this is TRUE only
		when no known partition tables have been found on the
		media (In this case, if the storage device contain a
		file system it will be accessible using the same
		special device file as the one for this device object
		and the device object representing the filesystem will
		appear as a separate device object as a child). For
		the child, that is
		when <literal>block.is_volume</literal> is true, this
		property is TRUE exactly when it was created for a
		storage device with
		the <literal>storage.no_partitions_hint</literal> set
		to TRUE.
	      </entry>
            </row>
            <row>
              <entry><literal>block.have_scanned</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		An internal property used by HAL to specify whether a top
		level block device have already been scanned for filesystems.
	      </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

    </sect2>

    



    </sect1>
    <sect1 id="properties-functional">
      <title>Functional Properties</title>

      <para>

	The section describe functional properties of device objects,
	that is, properties that are merged onto device objects
	representing physically addressable hardware. In most
	circumstances such properties stem from a kernel level
	driver attached to the device represented by the device object,
	however, as HAL can merge properties from anywhere, they
	may have been merged from device information files or callouts.

      </para>



    <sect2 id="device-properties-volume">
      <title><literal>volume</literal> namespace</title>
      <para>

	This namespace is for device objects that represent storage
	devices with a filesystem that can be mounted. Such device
	objects will have the capability <literal>volume</literal> and
	they will export the properties below. Note that device
	objects can only have the <literal>volume</literal> capability
	if they already have the capability <literal>block</literal>
	and the property <literal>block.is_volume</literal> set to TRUE.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>volume.is_mounted</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>This property is TRUE if and only if the volume is mounted</entry>
            </row>
            <row>
              <entry><literal>volume.mount_point</literal> (string)</entry>
              <entry>example: /media/compact_flash1  </entry>
              <entry>Yes (is blank only when volume.is_mounted is FALSE)</entry>
              <entry>A fully qualified path to the mount point of the volume</entry>
            </row>
            <row>
              <entry><literal>volume.fsusage</literal> (string)</entry>
              <entry>example: filesystem</entry>
              <entry>Yes</entry>
              <entry>
                This property specifies the expected usage of the volume
              </entry>
            </row>
            <row>
              <entry></entry>
              <entry>filesystem</entry>
              <entry></entry>
              <entry>The volume is a mountable filesystem</entry>
            </row>
            <row>
              <entry></entry>
              <entry>partitiontable</entry>
              <entry></entry>
              <entry>The volume conatains a partitiontable</entry>
            </row>
            <row>
              <entry></entry>
              <entry>raid</entry>
              <entry></entry>
              <entry>The volume is a member of a raid set and not mountable</entry>
            </row>
            <row>
              <entry></entry>
              <entry>other</entry>
              <entry></entry>
              <entry>The volume is not mountable like a swap partition</entry>
            </row>
            <row>
              <entry></entry>
              <entry>unused</entry>
              <entry></entry>
              <entry>The volume is marked a unused or free</entry>
            </row>
            <row>
              <entry><literal>volume.fstype</literal> (string)</entry>
              <entry>example: ext3</entry>
              <entry>Yes (is blank if the filesystem type is unknown)</entry>
              <entry></entry>
            </row>
            <row>
              <entry><literal>volume.fsversion</literal> (string)</entry>
              <entry>example: FAT32</entry>
              <entry></entry>
              <entry>Version number or subtype of the filesystem</entry>
            </row>
            <row>
              <entry><literal>volume.label</literal> (string)</entry>
              <entry>example: 'Fedora Core 1.90' </entry>
              <entry>Yes (is blank if no label is found)</entry>
              <entry>The label of the volume</entry>
            </row>
            <row>
              <entry><literal>volume.uuid</literal> (string)</entry>
              <entry>example: 4060-6C11</entry>
              <entry>Yes (is blank if no UUID is found)</entry>
              <entry>The Universal Unique Identifer for the volume</entry>
            </row>
            <row>
              <entry><literal>volume.is_disc</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>If the volume stems from an optical disc, this
              property is true and the device object will also have
              the capability <literal>volume.disc</literal></entry>
            </row>

            <row>
              <entry><literal>volume.block_size</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		The block size of the volume
	      </entry>
            </row>
            <row>
              <entry><literal>volume.num_blocks</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Number of blocks on the volume
	      </entry>
            </row>
            <row>
              <entry><literal>volume.size</literal> (uint64)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Size of the volume in bytes
	      </entry>
            </row>

            <row>
              <entry><literal>volume.is_partition</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		If the volume stems from a partition on e.g. a hard
		disk, this property is set to <literal>TRUE</literal>.
	      </entry>
            </row>
            <row>
              <entry><literal>volume.partition.number</literal> (int)</entry>
              <entry></entry>
              <entry>
		If, and only if, <literal>volume.is_partition</literal>
		is set to <literal>TRUE</literal>.
	      </entry>
              <entry>
		The number of the partition.
	      </entry>
            </row>
            <row>
              <entry><literal>volume.partition.x86_type</literal> (int)</entry>
              <entry>examples: 0x83, 0xfd, 0x8e</entry>
              <entry>
		No
	      </entry>
              <entry>
		If available, this is the partition type if the disk for which
		this volume stems from is using an MS-DOS-style partition table.
	      </entry>
            </row>


				      
          </tbody>
        </tgroup>
      </informaltable>

      <para>
	Device objects with this capability may emit the following
	device conditions
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Condition Name</entry>
              <entry>Parameters</entry>
              <entry>Example</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>VolumeMount</literal></entry>
              <entry>
		<literal>block.device</literal> (string),
		<literal>volume.mount_point</literal> (string)
	      </entry>
              <entry>
		<literal>/dev/sda1</literal>,
		<literal>/media/compact_flash</literal>
	      </entry>
              <entry>Emitted when a volume is mounted</entry>
            </row>

            <row>
              <entry><literal>VolumeUnmount</literal></entry>
              <entry>
		<literal>block.device</literal> (string),
		<literal>volume.mount_point</literal> (string)
	      </entry>
              <entry>
		<literal>/dev/sda1</literal>,
		<literal>/media/compact_flash</literal>
	      </entry>
              <entry>Emitted when a volume is unmounted</entry>
            </row>

            <row>
              <entry><literal>VolumeUnmountForced</literal></entry>
              <entry>
		<literal>block.device</literal> (string),
		<literal>volume.mount_point</literal> (string)
	      </entry>
              <entry>
		<literal>/dev/sda1</literal>,
		<literal>/media/compact_flash</literal>
	      </entry>
              <entry>
		Emitted when a volume is forcibly unmounted because
		the media backing the volume was removed.
	      </entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>

    </sect2>


    <sect2 id="device-properties-kernel">
      <title><literal>kernel</literal> namespace</title>
      <para>

	This namespace is found on the toplevel "Computer" device,
	and represents information about the currently running kernel.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>kernel.name</literal> (string)</entry>
              <entry>example: Linux</entry>
              <entry>No</entry>
              <entry>
                The name of the kernel, usually the equivalent of
                <literal>uname -s</literal>.
              </entry>
            </row>
            <row>
              <entry><literal>kernel.version</literal> (string)</entry>
              <entry>example: 2.6.5-7.104-default</entry>
              <entry>No</entry>
              <entry>
                The version of the currently running kernel.  Usually
                the equivalent of <literal>uname -r</literal>.
              </entry>
            </row>
            <row>
              <entry><literal>kernel.machine</literal> (string)</entry>
              <entry>example: i686</entry>
              <entry>No</entry>
              <entry>
                The "machine hardware name" of the currently running kernel.
                Usually the equivalent of <literal>uname -m</literal>.
	      </entry>
            </row>
				      
          </tbody>
        </tgroup>
      </informaltable>

    </sect2>


    <sect2 id="device-properties-volume-disc">
      <title><literal>volume.disc</literal> namespace</title>
      <para>

	This namespace is for device objects that represent optical
	discs, e.g. device objects with the capability 
	<literal>volume.disc</literal>. Such device objects will
	also have the capability <literal>volume</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>volume.disc.has_audio</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Is true only if the disc contains audio</entry>
            </row>
            <row>
              <entry><literal>volume.disc.has_data</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Is true only if the disc contains data</entry>
            </row>
            <row>
              <entry><literal>volume.disc.is_appendable</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Is true only if it's possible to write additional data</entry>
            </row>
            <row>
              <entry><literal>volume.disc.is_blank</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Is true only if the disc is blank</entry>
            </row>
            <row>
              <entry><literal>volume.disc.is_rewritable</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Is true only if the disc is rewritable</entry>
            </row>
            <row>
              <entry><literal>volume.disc.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>This property specifies the physical type of the disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>cd_rom</entry>
              <entry></entry>
              <entry>CD-ROM disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>cd_r</entry>
              <entry></entry>
              <entry>CD-R disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>cd_rw</entry>
              <entry></entry>
              <entry>CD-RW disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_rom</entry>
              <entry></entry>
              <entry>DVD-ROM disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_ram</entry>
              <entry></entry>
              <entry>DVD-RAM disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_r</entry>
              <entry></entry>
              <entry>DVD-R disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_rw</entry>
              <entry></entry>
              <entry>DVD-RW disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_plus_r</entry>
              <entry></entry>
              <entry>DVD+R disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>dvd_plus_rw</entry>
              <entry></entry>
              <entry>DVD+RW disc</entry>
            </row>
            <row>
              <entry></entry>
              <entry>unknown</entry>
              <entry></entry>
              <entry>Unknown type or lack of support from drive to determine the type</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-storage">
      <title><literal>storage</literal> namespace</title>
      <para>

	This namespace is used to describe physical storage devices
	and their capabilities. Such device objects will have the 
	capability <literal>storage</literal> and
	they will export the properties below. Note that device
	objects can only have the <literal>storage</literal> capability
	if they already got capability <literal>block</literal> and the
	property <literal>block.is_volume</literal> set to FALSE.
	One significant between the <literal>storage</literal> and
	<literal>block</literal> namespace is that the properties
	exported in the <literal>storage</literal> represents
	constant vital product information, whereas the properties
	in the <literal>block</literal> namespace represent 
	variable system-dependent information.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>storage.bus</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Physical interface the storage device is attached to</entry>
            </row>
            <row>
              <entry></entry>
              <entry>ide</entry>
              <entry></entry>
              <entry>IDE or ATA interface</entry>
            </row>
            <row>
              <entry></entry>
              <entry>usb</entry>
              <entry></entry>
              <entry>USB interface</entry>
            </row>
            <row>
              <entry></entry>
              <entry>ieee1394</entry>
              <entry></entry>
              <entry>IEEE 1394 interface</entry>
            </row>
            <row>
              <entry></entry>
              <entry>scsi</entry>
              <entry></entry>
              <entry>SCSI interface</entry>
            </row>
            <row>
              <entry></entry>
              <entry>sata</entry>
              <entry></entry>
              <entry>SATA interface</entry>
            </row>
            <row>
              <entry></entry>
              <entry>platform</entry>
              <entry></entry>
              <entry>Legacy device that is part of the platform</entry>
            </row>

            <row>
              <entry></entry>
              <entry></entry>
              <entry></entry>
              <entry></entry>
            </row>

            <row>
              <entry><literal>storage.drive_type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		The type of the drive. Note that it may not be
		possible to probe for some of these properties so in
		some cases memory card readers may appear as
		harddisks. Device information files can be used to
		override this value.
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry>disk</entry>
              <entry></entry>
              <entry>The device is a harddisk</entry>
            </row>
            <row>
              <entry></entry>
              <entry>cdrom</entry>
              <entry></entry>
              <entry>The device is an optical drive. The device object will also have the capability <literal>storage.cdrom</literal> in this case.</entry>
            </row>
            <row>
              <entry></entry>
              <entry>floppy</entry>
              <entry></entry>
              <entry>The device is a floppy disk drive</entry>
            </row>
            <row>
              <entry></entry>
              <entry>tape</entry>
              <entry></entry>
              <entry>The device is a tape drive</entry>
            </row>
            <row>
              <entry></entry>
              <entry>compact_flash</entry>
              <entry></entry>
              <entry>The device is a card reader for Compact Flash memory cards</entry>
            </row>
            <row>
              <entry></entry>
              <entry>memory_stick</entry>
              <entry></entry>
              <entry>The device is a card reader for MemoryStick memory cards</entry>
            </row>
            <row>
              <entry></entry>
              <entry>smart_media</entry>
              <entry></entry>
              <entry>The device is a card reader for SmartMedia memory cards</entry>
            </row>
            <row>
              <entry></entry>
              <entry>sd_mmc</entry>
              <entry></entry>
              <entry>The device is a card reader for SecureDigital/MultiMediaCard memory cards</entry>
            </row>

            <row>
              <entry></entry>
              <entry></entry>
              <entry></entry>
              <entry></entry>
            </row>


            <row>
              <entry><literal>storage.removable</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Media can be removed from the storage device</entry>
            </row>
            <row>
              <entry><literal>storage.requires_eject</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The eject ioctl is required to properly eject the media</entry>
            </row>
            <row>
              <entry><literal>storage.hotpluggable</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The storage device can be removed while the system is running</entry>
            </row>
            <row>
              <entry><literal>storage.media_check_enabled</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>If this property is set to FALSE then HAL will not continuosly poll for media changes. </entry>
            </row>
            <row>
              <entry><literal>storage.automount_enabled_hint</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>This property is a hint to desktop file managers that they shouldn't automount volumes of the storage device when they appear.</entry>
            </row>
            <row>
              <entry><literal>storage.no_partitions_hint</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		This property is a hint to programs that maintain the 
		<literal>/etc/fstab</literal> file to signal, when
		TRUE, that the storage drive (such as floppy or
		optical drives) is used for media with no partition
		table so an entry can be added ahead of media
		insertion time. Note that this is only a hint; media
		may be inserted that has partition tables that the
		kernel may respect. Conversely, when this is FALSE
		media without partition tables may be inserted (an
		example is a Compact Flash card; this media is normally
		formatted with a PC style partition table and a single
		FAT partition. However, it may be formatted with just
		a single FAT partition and no partition table).
	      </entry>
            </row>
            <row>
              <entry><literal>storage.physical_device</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		This contains the UDI of the device object
		representing the physical device or blank if 
		there is no such device (which is TRUE for legacy
		devices such as x86 floppy drives). Additionally, a
		number of properties are merged from that device
		object. Specifically, all properties prefixed
		with <literal>storage</literal> and, if the physical
		device has several storage ports,
		<literal>storage_lunX</literal> (where X is number of
		the port starting from zero) are merged and will have 
		the prefix <literal>storage</literal>.  See <xref
		linkend="fdi-example-6in1"/> for an example.
	      </entry>
            </row>
            <row>
              <entry><literal>storage.model</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The name of the drive</entry>
            </row>
            <row>
              <entry><literal>storage.vendor</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The vendor of the drive</entry>
            </row>

            <row>
              <entry><literal>storage.serial</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>The serial number of the drive</entry>
            </row>
            <row>
              <entry><literal>storage.firmware_revision</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>The revision of the firmware of the drive</entry>
            </row>

            <row>
              <entry><literal>storage.icon.drive</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Name of icon to use for displaying the drive. The name
		must comply with freedesktop.org icon-theme specification
		and must not be an absolute path.
		
		This property exists such that e.g. OEM's can install
		icons in <literal>/usr/share/icons/hicolor</literal>
		a device information file matching their device.
	      </entry>
            </row>

            <row>
              <entry><literal>storage.icon.volume</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Name of icon to use for displaying volumes from the drive.
		The name must comply with freedesktop.org icon-theme
		specification and must not be an absolute path.
		
		This property exists such that e.g. OEM's can install
		icons in <literal>/usr/share/icons/hicolor</literal>
		a device information file matching their device.
	      </entry>
            </row>


          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-storage-cdrom">
      <title><literal>storage.cdrom</literal> namespace</title>
      <para>

	This namespace is used to describe optical storage drives
	and their capabilities.Such device objects will have the 
	capability <literal>storage.cdrom</literal> and
	they will export the properties below. Note that device
	objects can only have the <literal>storage.cdrom</literal> capability
	if they already got the capability <literal>storage</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>storage.cdrom.cdr</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can write CD-R discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.cdrw</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can blank and write to CD-RW discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvd</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can read DVD-ROM discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvdr</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can write to DVD-R discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvdrw</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can blank and write to DVD-RW discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvdram</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can write to DVD-RAM discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvdplusr</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can write to DVD+R discs</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.dvdplusrw</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE when the optical drive can blank and write to DVD+RW discs</entry>
            </row>

            <row>
              <entry><literal>storage.cdrom.support_media_changed</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TRUE if the drive can generate media changed events</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.read_speed</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The maximum reading speed, in kb/s</entry>
            </row>
            <row>
              <entry><literal>storage.cdrom.write_speed</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The maximum writing speed, in kb/s</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-net">
      <title><literal>net</literal> namespace</title>
      <para>

	This namespace is used to describe networking devices and
	their capabilities.Such device objects will have the
	capability <literal>net</literal> and they will export the
	properties below. This namespace only describe the generic
	aspect of networking devices; specific networking technologies
	such as IEEE 802.3 and IEEE 802.11 have separate namespaces.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>net.address</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Hardware address as a string. Is hardware dependant</entry>
            </row>
            <row>
              <entry><literal>net.arp_proto_hw_id</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>ARP protocol hardware identifier</entry>
            </row>
            <row>
              <entry><literal>net.interface</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Name of the interface; may change if an interface is
	      renamed</entry>
            </row>
            <row>
              <entry><literal>net.interface_up</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Whether the interface is up</entry>
            </row>
            <row>
              <entry><literal>net.linux.ifindex</literal> (string)</entry>
              <entry></entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Index of the interface</entry>
            </row>
            <row>
              <entry><literal>net.linux.sysfs_path</literal> (string)</entry>
              <entry></entry>
              <entry>Yes (only on Linux)</entry>
              <entry>Path of device in sysfs</entry>
            </row>
            <row>
              <entry><literal>net.media</literal> (string)</entry>
              <entry>example: Ethernet</entry>
              <entry>Yes</entry>
              <entry>Textual description of the networking media</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>



    <sect2 id="device-properties-net-80203">
      <title><literal>net.80203</literal> namespace</title>
      <para>

	Ethernet networking devices is described in this namespace
	for device objects with the capability 
	<literal>net.80203</literal>.
	Note that device
	objects can only have the <literal>net.80203</literal> capability
	if they already have the capability <literal>net</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>net.80203.link</literal> (bool)</entry>
              <entry></entry>
              <entry>
		Only if the <literal>net.80203</literal> capability is set
		and <literal>net.interface_up</literal> is
		<literal>TRUE</literal>.
	      </entry>
              <entry>True iff the ethernet adaptor is connected to a
              another transceiver</entry>
            </row>
            <row>
              <entry><literal>net.80203.rate</literal> (uint64)</entry>
              <entry>example: 100000000</entry>
              <entry>
		Only if the <literal>net.80203</literal> capability is set
		and <literal>net.80203.link</literal> is
		<literal>TRUE</literal>.
	      </entry>
              <entry>Bandwidth of connection, in bits/s</entry>
            </row>
            <row>
              <entry><literal>net.80203.mac_address</literal> (uint64)</entry>
              <entry>example: 0x0010605d8ef4</entry>
              <entry>Only if the <literal>net.80203</literal> is set</entry>
              <entry>48-bit address</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      <para>
      </para>
    </sect2>



    <sect2 id="device-properties-net-80211">
      <title><literal>net.80211</literal> namespace</title>
      <para>

	Wireless ethernet networking devices is described in this namespace
	for device objects with the capability 
	<literal>net.80211</literal>.
	Note that device
	objects can only have the <literal>net.80211</literal> capability
	if they already have the capability <literal>net</literal>.

      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>net.80211.mac_address</literal> (uint64)</entry>
              <entry>example: 0x0010605d8ef4</entry>
              <entry>
		Only if the <literal>net.80211</literal> capability is set
	      </entry>
              <entry>48-bit address</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      <para>
      </para>
    </sect2>



    <sect2 id="device-properties-input">
      <title><literal>input</literal> namespace</title>
      <para>
      
	This namespace is concerned with human input devices such as
	keyboards, mice, pointing devices and game controllers. If a
	device object has the capability <literal>input</literal> then
	the following properties are available
      
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>input.device</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>Special device file for recieving input events</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-pcmcia_socket">
      <title><literal>pcmcia_socket namespace</literal></title>
      <para>
      
	Device objects with the capability <literal>pcmcia_socket</literal>
	represent bridge devices (the actual bus of the device may differ)
	that PCMCIA cards can be attached to. The following properties are
	available.
      
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>pcmcia_socket.number</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>PCMCIA socket number, starting from zero</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-printer">
      <title><literal>printer</literal> namespace</title>
      <para>
      
	Device objects with the capability <literal>printer</literal>
	represent printers. The following properties are available.
      
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>printer.device</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>printer.vendor</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>printer.product</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>printer.serial</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>
            <row>
              <entry><literal>printer.description</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>TODO</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-portable_audio_player">
      <title><literal>portable_audio_player</literal> namespace</title>
      <para>
      
	Device objects with the capability 
	<literal>portable_audio_player</literal> represent portable
	audio players that can be attached to a computer to exchange
	files. They can also playback audio. Sometimes they can also
	record audio. This capability can't, in general, be reliably
	probed from the hardware so the information needs to be merged
	from either device information files or callouts. Therefore
	this capability should be merged on the appropriate device
	object that represents the addressable piece of hardware that
	is the portable music player; for USB devices this would be
	the device object representing the appropriate USB
	interface. The following properties are available:
      
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>portable_audio_player.access_method</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>This property defines how the device is accessed </entry>
            </row>
            <row>
              <entry></entry>
              <entry>storage</entry>
              <entry></entry>
              <entry>
		The device is accessed as a Mass Storage device
		through a kernel driver.  Application Developers
		should descent down the device object tree to find the
		device object of capability
		<literal>storage</literal> in order to access the
		device.
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry>user</entry>
              <entry></entry>
              <entry>
		The device is accessed from userspace through
		a userspace driver.
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry></entry>
              <entry></entry>
              <entry></entry>
            </row>

            <row>
              <entry><literal>portable_audio_player.output_formats</literal> (string)</entry>
              <entry>example: 'audio/mpeg audio/x-ms-wma</entry>
              <entry>Yes</entry>
              <entry>
		A whitespace-separated list of MIME-types representing 
		the kind of audio formats that the device can play back
	      </entry>
            </row>

            <row>
              <entry><literal>portable_audio_player.input_formats</literal> (string)</entry>
              <entry>example: 'audio/x-wav</entry>
              <entry>Yes</entry>
              <entry>
		A whitespace-separated list of MIME-types representing 
		the kind of audio formats that the device can record. If
		empty, it means that the device is not capable of recording.
	      </entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

   <sect2 id="device-properties-alsa">
      <title><literal>alsa</literal> namespace</title>
      <para>

       Device objects with the capability <literal>alsa</literal>
       represent all the streams available through ALSA on a soundcard.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>alsa.card</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		Card number in system as registered by ALSA.
             </entry>
            </row>
            <row>
              <entry><literal>alsa.card_id</literal> (string)</entry>
              <entry>
                Examples: <literal>I82801DBICH4</literal>, <literal>MP3</literal>
              </entry>
              <entry>No</entry>
              <entry>
		Textual description of the card.
             </entry>
            </row>
            <row>
              <entry><literal>alsa.device</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		Device number assigned by ALSA for a current card.
             </entry>
            </row>
            <row>
              <entry><literal>alsa.device_id</literal> (string)</entry>
              <entry>
                Examples: <literal>Intel 82801DB-ICH4 MIC2 ADC</literal>
              </entry>
              <entry>No</entry>
              <entry>
		Textual description of the specific device for a card
             </entry>
            </row>
            <row>
              <entry><literal>alsa.physical_device</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		UDI of the physical device the ALSA device is bound to.
             </entry>
           </row>
            <row>
              <entry><literal>alsa.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
               The type of the stream.
             </entry>
            </row>
           <row>
             <entry></entry>
             <entry><literal>control</literal></entry>
             <entry></entry>
             <entry>
               Stream is control device.
             </entry>
           </row>
           <row>
             <entry></entry>
             <entry><literal>capture</literal></entry>
             <entry></entry>
             <entry>
               Stream is capture device.
             </entry>
           </row>
           <row>
             <entry></entry>
             <entry><literal>playback</literal></entry>
             <entry></entry>
             <entry>
               Stream is playback device.
             </entry>
           </row>
           <row>
             <entry></entry>
             <entry><literal>unknown</literal></entry>
             <entry></entry>
             <entry>
               Stream is unknown device.
             </entry>
           </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-camera">
      <title><literal>camera</literal> namespace</title>
      <para>
      
	Device objects with the capability <literal>camera</literal>
	represent digital still cameras that can be attached to a
	computer to exchange files. This does not include card readers
	for memory cards used for cameras. This capability can't, in
	general, be reliably probed from the hardware so the
	information needs to be merged from either device information
	files or callouts. Therefore this capability should be merged
	on the appropriate device object that represents the
	addressable piece of hardware that is the digital still
	camera; for USB devices this would be the device object
	representing the appropriate USB interface. The following
	properties are available:
      
      </para>

      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>camera.access_method</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>This property defines how the device is accessed </entry>
            </row>
            <row>
              <entry></entry>
              <entry>storage</entry>
              <entry></entry>
              <entry>
		The device is accessed as a Mass Storage device
		through a kernel driver.  Application Developers
		should descent down the device object tree to find the
		device object of capability
		<literal>storage</literal> in order to access the
		device.
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry>user</entry>
              <entry></entry>
              <entry>
		The device is accessed from userspace through
		a userspace driver.
	      </entry>
            </row>
            <row>
              <entry></entry>
              <entry></entry>
              <entry></entry>
              <entry></entry>
            </row>

            <row>
              <entry><literal>camera.libgphoto2.support</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		If true, the device is supported by a userspace driver
		from the libgphoto2 project.
	      </entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-ac_adaptor">
      <title><literal>ac_adaptor</literal> namespace</title>
      <para>

        Device objects with the capability <literal>ac_adaptor</literal>
        represent all the devices capable of powering the system from AC power

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ac_adaptor.present</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
                The state of the adaptor, i.e. whether it is providing power to
                the unit from mains power.
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-battery">
      <title><literal>battery</literal> namespace</title>
      <para>
      
	Device objects with the capability <literal>battery</literal>
	represent all the devices having some battery (in many cases - 
	rechargeable) inside. 

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>battery.present</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		This is present as some smart batteries can have acpi/pmu 
                entries, and be physically missing.
	      </entry>
            </row>
            <row>
              <entry><literal>battery.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		This property defines the type of the device holding the 
	        battery. This property is defined for the development 
		simplicity - battery indicators can use it to find the
		proper iconic representation.
	      </entry>
            </row>
	    <row>
	      <entry></entry>
	      <entry><literal>pda</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is a personal digital 
		assistant, e.g. a device that looks like a handheld computer
		to do specific tasks such as keeping notes or containing
		a personal database
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>ups</literal></entry>
	      <entry></entry>
	      <entry> 
		A battery powered power supply that is
		guaranteed to provide power to a computer in the event of
		interruptions in the incoming electrical power. Most of the
		time this is an external device.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>primary</literal></entry>
	      <entry></entry>
	      <entry>
		The battery is a primary power source for the system - an
		example are laptop batteries.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>mouse</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is a mouse.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>keyboard</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is a keyboard.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>keyboard_mouse</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is a combined mouse and keyboard.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>camera</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is a camera.
	      </entry>
	    </row>
	    <row>
	      <entry></entry>
	      <entry><literal>unknown</literal></entry>
	      <entry></entry>
	      <entry>
		The device containing the battery is not covered by other types.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.charge_level.unit</literal> (string)</entry>
              <entry>Examples: <literal>mWh</literal>, <literal>VA</literal>, 
		<literal>percent</literal></entry>
              <entry>No</entry>
              <entry>
		The physical unit used by the charge level properties
		(maximum and current). In many cases, this property is
		omitted - which indicates that the charge properties
		are measured in some unknown units.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.charge_level.design</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		The maximum level of charge the device was designed for.
	        Measured in <literal>"battery.charge_level.unit"</literal>
		units.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.charge_level.last_full</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		The maximum level of charge the device could hold the last
		time it was full.
	        Measured in <literal>"battery.charge_level.unit"</literal>
		units.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.charge_level.current</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
		The current level of charge which the device can hold. 
	        Measured in <literal>"battery.charge_level.unit"</literal> 
		units.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.charge_level.rate</literal> (int)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		The discharge/charge rate measured
		in <literal>"battery.charge_level.unit"</literal>
		units per second.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.remaining_time</literal> (int)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Remaining time, in seconds, that the battery can provide
		power if it's discharging. This is an estimate and may be
		imprecise.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.is_rechargeable</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		True if the battery unit is rechargeable, false if its is 
	        one-time (disposable after one usage).
	      </entry>
	    </row>

            <row>
              <entry><literal>battery.rechargeable.is_charging</literal> (bool)</entry>
              <entry></entry>
              <entry>Only if <literal>battery.is_rechargeable</literal> is TRUE</entry>
              <entry>
		TRUE if, and only if, the battery is charging.
              </entry>
	    </row>
            <row>
              <entry><literal>battery.rechargeable.is_discharging</literal> (bool)</entry>
              <entry></entry>
              <entry>Only if <literal>battery.is_rechargeable</literal> is TRUE</entry>
              <entry>
		TRUE if, and only if, the battery is discharging.
              </entry>
	    </row>

            <row>
              <entry><literal>battery.command_interface</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		The abstract name allowing daemons and/or user-level apps 
	        to distinguish some groups of devices having similar 
		programming  interface. Introduced mostly for the daemons' 
		coding simplicity.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.vendor</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Vendor of the battery.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.model</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Make of the battery.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.technology</literal> (string)</entry>
              <entry>example: LION</entry>
              <entry>No</entry>
              <entry>
		The technology of the battery.
	      </entry>
	    </row>
            <row>
              <entry><literal>battery.serial</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		A string uniquely identifying the instance of the battery; 
		it will be different for two (otherwise) identical batteries.
	      </entry>
	    </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-button">
      <title><literal>button</literal> namespace</title>
      <para>

        Device objects with the capability <literal>button</literal>
        represent the devices capable of providing a state to the system.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>button.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The type of button</entry>
            </row>
            <row>
              <entry></entry>
              <entry>lid</entry>
              <entry></entry>
              <entry>
                The switch on a laptop that senses whether the lid is
                open or closed
              </entry>
            </row>
            <row>
              <entry></entry>
              <entry>power</entry>
              <entry></entry>
              <entry>The main power button on the computer.</entry>
            </row>
            <row>
              <entry></entry>
              <entry>sleep</entry>
              <entry></entry>
              <entry>
                The sleep button on a computer capable of putting the computer
                into a suspend state
              </entry>
            </row>
            <row>
              <entry><literal>button.has_state</literal> (bool)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>True if the button maintains state, e.g. can toggled on/off</entry>
            </row>
            <row>
              <entry><literal>button.state.value</literal> (bool)</entry>
              <entry></entry>
              <entry>
                Only when <literal>button.has_state</literal> is
                TRUE
              </entry>
              <entry>State of the button, TRUE if it is enabled</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>

        Device objects with this capability may emit the following events.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Condition Name</entry>
              <entry>Parameters</entry>
              <entry>Example</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>ButtonPressed</literal></entry>
              <entry><literal>button.type (string)</literal></entry>
              <entry>sleep</entry>
              <entry>Emitted when a button is pressed</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>  
    </sect2>

    <sect2 id="device-properties-processor">
      <title><literal>processor</literal> namespace</title>
      <para>

        Device objects with the capability <literal>processor</literal>
        represent CPU's in the system.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>processor.number</literal> (int)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>
                The internal processor number in the system, starting from zero
              </entry>
            </row>
            <row>
              <entry><literal>processor.can_throttle</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
                Whether the processor supports throttling to decrease it's
                own clock speed
              </entry>
            </row>
            <row>
              <entry><literal>processor.maximum_speed</literal> (long)</entry>
              <entry>example: 2200</entry>
              <entry>No</entry>
              <entry>The maximum speed of the processor in units of MHz</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-display_device">
      <title><literal>display_device</literal> namespace</title>
      <para>

        Device objects with the capability <literal>display_device</literal>
        represent display devices attached to the system.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>display_device.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The type of display device</entry>
            </row>
            <row>
              <entry></entry>
              <entry>lcd</entry>
              <entry></entry>
              <entry>LCD panel</entry>
            </row>
            <row>
              <entry></entry>
              <entry>crt</entry>
              <entry></entry>
              <entry>CRT tube</entry>
            </row>
            <row>
              <entry></entry>
              <entry>tv_out</entry>
              <entry></entry>
              <entry>TV Out</entry>
            </row>
            <row>
              <entry><literal>display_device.lcd.brightness</literal> (int)</entry>
              <entry></entry>
              <entry>Only if <literal>display_device.type</literal> is lcd</entry>
              <entry>Brightness level in percent</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-sensor">
      <title><literal>sensor</literal> namespace</title>
      <para>

        Device objects with the capability <literal>sensor</literal>
        represent light or temperature sensors in the system.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>sensor.type</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The type of sensor device</entry>
            </row>
            <row>
              <entry></entry>
              <entry>light</entry>
              <entry></entry>
              <entry>Light sensor</entry>
            </row>
            <row>
              <entry></entry>
              <entry>temperature</entry>
              <entry></entry>
              <entry>Temperature sensor</entry>
            </row>
            <row>
              <entry><literal>sensor.location</literal> (string)</entry>
              <entry></entry>
              <entry>Yes</entry>
              <entry>The location of the sensor device</entry>
            </row>
            <row>
              <entry></entry>
              <entry>gpu</entry>
              <entry></entry>
              <entry>Measures GPU source</entry>
            </row>
            <row>
              <entry></entry>
              <entry>cpu</entry>
              <entry></entry>
              <entry>Measures CPU source</entry>
            </row>
            <row>
              <entry></entry>
              <entry>external</entry>
              <entry></entry>
              <entry>Measures external source</entry>
            </row>
            <row>
              <entry></entry>
              <entry>unknown</entry>
              <entry></entry>
              <entry>Measuring other source</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>

    <sect2 id="device-properties-tape">
      <title><literal>tape</literal> namespace</title>
      <para>

	Device objects with the capability <literal>tape</literal>
	represent tape devices.

      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>tape.major</literal> (int)</entry>
              <entry>example: 254</entry>
              <entry>Yes</entry>
              <entry>The device's major number</entry>
            </row>
            <row>
              <entry><literal>tape.minor</literal> (int)</entry>
              <entry>example: 0</entry>
              <entry>Yes</entry>
              <entry>The device's minor number</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>
    </sect1>

    <sect1 id="properties-policy">
      <title>Policy Properties</title>
      <para>

	The properties on a hal device object can be used to express
	certain policies about how the device is to be used. This
	information can be used by either programs querying hal
	directly or by hal callouts. Default policy (e.g. always
	mount a file system with the option 'exec') can also be
	merged on the root computer device object.
      </para>

    <sect2 id="device-properties-storage-policy-default">
      <title><literal>storage.policy.default</literal> namespace</title>
      <para>
	This namespace specifies the default policy for storage 
	devices - these properties should be merged on the root computer
	device object.
      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>storage.policy.default.use_managed_keyword</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Whether to use a <emphasis>managed no
	        operation</emphasis> keyword when adding entries to
	        the File Systems file (<literal>/etc/fstab</literal>) - 
		this is used to identify entries added by a program
		that modifies this file.
	      </entry>
            </row>

            <row>
              <entry><literal>storage.policy.default.managed_keyword.primary</literal> (string)</entry>
              <entry>Example: 'managed'</entry>
              <entry>No</entry>
              <entry>No-op keyword to use when adding entries to the file systems file</entry>
            </row>

            <row>
              <entry><literal>storage.policy.default.managed_keyword.secondary</literal> (string)</entry>
              <entry>Example: 'kudzu'</entry>
              <entry>No</entry>
              <entry>
		Secondary no-op keyword that identifies entries added
		to the file systems file. The secondary keyword is never
		written; only read. This is useful when making a transition
		from one managed keyword to another.
	      </entry>
            </row>

            <row>
              <entry><literal>storage.policy.default.mount_option.*</literal> (bool)</entry>
              <entry>Examples: 
		<literal>.noauto</literal>, 
		<literal>.exec</literal>, 
		<literal>.console</literal>, 
		<literal>.fscontext=system_u:object_r:removable_t</literal></entry>
              <entry>No</entry>
              <entry>
		This is actually an entire namespace that specifies
	        what options a storage device should be mounted with,
	        e.g. the example <literal>.exec</literal> should be read as
		<literal>storage.policy.default.mount_option.exec</literal>
	      </entry>
            </row>

            <row>
              <entry><literal>storage.policy.default.mount_root</literal> (string)</entry>
              <entry>Example: <literal>/media</literal> </entry>
              <entry>No</entry>
              <entry>
		The default mount root to use when computing what
		mount point to use for a storage device
	      </entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-storage-policy">
      <title><literal>storage.policy</literal> namespace</title>
      <para>
	This namespace contains properties that can be merged on
	individual storage devices to specify how and if the storage
	device should be mounted.
      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>storage.policy.should_mount</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>Whether any volumes from this storage device
              should be mounted</entry>
            </row>
            <row>
              <entry><literal>storage.policy.desired_mount_point</literal> (string)</entry>
              <entry></entry>
              <entry>
		No (only applicable if the
		property <literal>storage.no_partitions_hint</literal>
		is set to TRUE)
	      </entry>
              <entry>
		The desired mount point for this storage device. The
		path must not be fully qualified and there is no
		guarantee that and storage policy agents, such as
		policy mount wrappers or programs modifying the file
		systems file will use this mount point.
	      </entry>
            </row>
            <row>
              <entry><literal>storage.policy.mount_option.*</literal> (bool)</entry>
              <entry></entry>
              <entry>
		No (only applicable if the
		property <literal>storage.no_partitions_hint</literal>
		is set to TRUE)
	      </entry>
              <entry>
		Mount options to use, see property <literal>storage.policy.default.mount_option.*</literal>
		for details.
	      </entry>
            </row>
            <row>
              <entry><literal>storage.policy.mount_filesystem</literal> (string)</entry>
              <entry></entry>
              <entry>
		No (only applicable if the
		property <literal>storage.no_partitions_hint</literal>
		is set to TRUE)
	      </entry>
              <entry>File system to use when mounting the storage device.</entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    <sect2 id="device-properties-volume-policy">
      <title><literal>volume.policy</literal> namespace</title>
      <para>
	This namespace contains properties that can be merged on
	individual volumes to specify how and if the volume
	should be mounted.
      </para>
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Key (type)</entry>
              <entry>Values</entry>
              <entry>Mandatory</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>

            <row>
              <entry><literal>volume.policy.should_mount</literal> (bool)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>Whether this volume should be mounted at all</entry>
            </row>
            <row>
              <entry><literal>volume.policy.mount_filesystem</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>File system to use when mounting the volume.</entry>
            </row>

            <row>
              <entry><literal>volume.policy.desired_mount_point</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
	      <entry>
		The desired mount point for this volume. The
		path must not be fully qualified and there is no
		guarantee that and storage policy agents, such as
		policy mount wrappers or programs modifying the file
		systems file will use this mount point.
	      </entry>
            </row>
            <row>
              <entry><literal>volume.policy.mount_options.*</literal> (string)</entry>
              <entry></entry>
              <entry>No</entry>
              <entry>
		Mount options to use, see property <literal>storage.policy.default.mount_option.*</literal>
		for details.
	      </entry>
            </row>

          </tbody>
        </tgroup>
      </informaltable>
    </sect2>


    </sect1>

  </chapter>



  <chapter id="spec-device-info">
    <title>Device Information Files</title>
    <para>

      Device information files (<literal>.fdi</literal> files is a
      shorthand) are used 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 about devices.

    </para><para>

      Each device information file got a number of
      <literal>&#60;match key="some_property"
      [string|int|bool|..]="required_value" &#62;</literal> directives
      that is tested against the properties of the device object. If
      all the match directives passes then the device information can
      include <literal>&#60;[merge|append] key="some_property"
      type="[string|int|bool|..]"&#62;</literal> directives to
      respectively merge new properties or append to existing
      properties on the device object. It's important to emphasize
      that any previously property stemming from device detection can
      be overridden by a device information file.

    </para><para>

      The <literal>&#60;match&#62;</literal>, 
      <literal>&#60;merge&#62;</literal> and
      <literal>&#60;append&#62;</literal> directives always requires
      the <literal>key</literal> attribute which must be either a
      property name on the device object in question or a path to a
      property on another device object. The latter case is expressed
      either through direct specification of the UDI, such as 
      <literal>/org/freedesktop/Hal/devices/computer:foo.bar</literal>
      or indirect references such as 
      <literal>@info.parent:baz</literal> where the latter means that
      the device object specified by the UDI in the string property 
      <literal>info.parent</literal> should be used to query the
      property <literal>baz</literal>. It is also possible to use
      multiple indirections, e.g. for a volume on a USB memory stick
      the indirection <literal>@block.storage_device:@storage.physical_device:usb.vendor_id</literal>
      will reference the <literal>usb.vendor_id</literal> property
      on the device object representing the USB interface.

    </para><para>

      When the property to match have been determined a number of
      attributes can be used within the <literal>&#60;match&#62;</literal>
      tag:
       <itemizedlist>
         <listitem><para>
	     <literal>string</literal> - match a string property; for example
	     <literal>&#60;match key="foo.bar" string="baz"&#62;</literal>
	     will match only if 'foo.bar' is a string property assuming the value 'baz'.
	 </para></listitem>
         <listitem><para>
	     <literal>int</literal> - match an integer property
	 </para></listitem>
         <listitem><para>
	     <literal>uint64</literal> - match property with the 64-bit unsigned type
	 </para></listitem>
         <listitem><para>
	     <literal>bool</literal> - match a boolean property
	 </para></listitem>
         <listitem><para>
	     <literal>double</literal> - match a property of type double
	 </para></listitem>
         <listitem><para>
	     <literal>exists</literal> - used as 
	     <literal>&#60;match key="foo.bar" exists="true"&#62;</literal>. Can be used with
	     'true' and 'false' respectively to match when a property exists and it doesn't.
	 </para></listitem>
         <listitem><para>
	     <literal>empty</literal> - 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.
	 </para></listitem>
         <listitem><para>
	     <literal>is_absolute_path</literal> - matches only when a string property represents an absolute path
	     (the path doesn't have to exist). Can be used with 'true' or 'false'.
	 </para></listitem>
         <listitem><para>
	     <literal>is_ascii</literal> - matches only when a string property contain only ASCII characters. 
	     Can be used with 'true' or 'false'.
	 </para></listitem>
         <listitem><para>
	     <literal>compare_lt</literal> - can be used on int, uint64, double and string properties to compare
	     with a constant. Matches when the given property is less than the given constant
	     using the default ordering.
	 </para></listitem>
         <listitem><para>
	     <literal>compare_le</literal> - like <literal>compare_lt</literal> but matches when less than or equal.
	 </para></listitem>
         <listitem><para>
	     <literal>compare_gt</literal> - like <literal>compare_lt</literal> but matches when greater than.
	 </para></listitem>
         <listitem><para>
	     <literal>compare_ge</literal> - like <literal>compare_lt</literal> but matches when greater than or equal.
	 </para></listitem>
       </itemizedlist>

       The <literal>&#60;merge&#62;</literal> 
       and <literal>&#60;append&#62;</literal> directives all require 
       the <literal>type</literal> attribute which specifies what to
       merge. The following values are supported

       <itemizedlist>
         <listitem><para>
	     <literal>string</literal> - The value is copied to the property. For example
	     <literal>&#60;merge key="foo.bar" type="string"&#62;baz&#60;/merge&#62;</literal>
	     will merge the value 'baz' into the property 'foo.bar'.	     
	 </para></listitem>
         <listitem><para>
	     <literal>bool</literal> - Can merge the values 'true' or 'false'
	 </para></listitem>
         <listitem><para>
	     <literal>int</literal> - Merges an integer
	 </para></listitem>
         <listitem><para>
	     <literal>uint64</literal> - Merges an unsigned 64-bit integer
	 </para></listitem>
         <listitem><para>
	     <literal>double</literal> - Merges a double precision floating point number
	 </para></listitem>
         <listitem><para>
	     <literal>copy_property</literal> - Copies the value of a given property - supports paths with
	     direct and indirect UDI's. For example
	     <literal>&#60;merge key="foo.bar" type="copy_property"&#62;@info.parent:baz.bat&#60;/merge&#62;</literal>
	     will merge the value of the property <literal>baz.bat</literal> on the device object with the UDI from
	     the property <literal>info.parent</literal> into the property <literal>foo.bar</literal> on 
	     the device object being processed.
	 </para></listitem>
       </itemizedlist>

       Device Information files are stored in the following standard hierachy with the following default
       top level directories:

       <itemizedlist>
         <listitem><para>
	     <literal>20freedesktop</literal> - device information files included with the hal tarball
	 </para></listitem>
         <listitem><para>
	     <literal>30osvendor</literal> - device information files supplied by the operating system vendor
	 </para></listitem>
         <listitem><para>
	     <literal>40oem</literal> - device information files from the device manufacturer and 
	     installed from media accompanying the hardware
	 </para></listitem>
         <listitem><para>
	     <literal>90defaultpolicy</literal> - Default policy determined by the operating system vendor and
	     possibly edited by the system administrator
	 </para></listitem>
         <listitem><para>
	     <literal>95userpolicy</literal> - Policy rules for specific devices.
	 </para></listitem>
       </itemizedlist>

       All device information files are matched for every hal device object.
      
    </para>

    <sect1 id="fdi-facts">
      <title>Facts about devices</title>
      
    <sect2 id="fdi-example-mp3player">
      <title>Example: MP3 player</title>
      
      <para>
	
	This device information file matches an USB Mass Storage
	based MP3 player by the matching on the USB vendor and
	product identifiers.
	
      </para>
      
      <programlisting>
	<inlinegraphic format="linespecific" fileref="../../fdi/20freedesktop/jetflash-mp3-player.fdi"/>
      </programlisting>
      
      <para>
	
	The final set of properties look like this:
	
      </para>
      <para>
	<inlinegraphic fileref="hal-fdi-example2.png" format="PNG"/>
      </para>
      
    </sect2>
    
    
    <sect2 id="fdi-example-camera">
      <title>Example: Digital Still Camera</title>
      
      <para>
	
	This device information file matches a Sony digital still camera
	by matching on the USB vendor and product identifers.
	
      </para>
      
      <programlisting>
	<inlinegraphic format="linespecific" fileref="../../fdi/20freedesktop/sony_dsc.fdi"/>
      </programlisting>
      
      <para>
	
	The final set of properties look like this:
	
      </para>
      <para>
	<inlinegraphic fileref="hal-fdi-example1.png" format="PNG"/>
      </para>
    </sect2>

    <sect2 id="fdi-example-6in1">
      <title>Example: Card Reader</title>
      
      <para>
	
	This device information file matches a memory card reader with
	multiple storage ports that can be active at the same time.
	
      </para>
      
      <programlisting>
	<inlinegraphic format="linespecific" fileref="../../fdi/20freedesktop/6in1-card-reader.fdi"/>
      </programlisting>
      
      <para>
	
	As described in the documentation for the
	<literal>storage.physical_device</literal> property in <xref
	linkend="device-properties-storage"/> this device information
	file export information about each storage port through the
	property <literal>storage.drive_type</literal>. Thus, one
	of the four <literal>storage</literal> devices has the
	following properties that are merged from the device object
	that the device information file targets:
	
      </para>
      <para>
	<inlinegraphic fileref="hal-fdi-example3.png" format="PNG"/>
      </para>
    </sect2>
    </sect1>


    <sect1 id="fdi-policy">
      <title>Policy settings for devices</title>
      
      <para>
	Policy settings specifies system specific settings that a
	system administrator associates with a device instance. In the
	context of hal, this can be expressed in terms of device
	properties merged on the device object in question. Default
	policy can also be merged on the root computer device object.
      </para>

    <sect2 id="fdi-example-mountsetting">
      <title>Storage Devices</title>
      <para>

	Policy for storage devices is expressed in the 
	<literal>storage.policy.default</literal>, 
	<literal>storage.policy</literal> and
	<literal>volume.policy</literal> namespaces, see
	<xref linkend="properties-policy"/> for details.

      </para><para>
	The default policy for storage devices shipped with hal looks like this
      </para>

      <programlisting>
	<inlinegraphic format="linespecific" fileref="../../fdi/90defaultpolicy/storage-policy.fdi"/>
      </programlisting>

      <para>
	and can be overridden by OS vendors to suit their purposes.
      </para>
      <para>
	Users can also customize their own rules; some examples follow	
      </para>

      <programlisting>
	<inlinegraphic format="linespecific" fileref="../conf/storage-policy-examples.fdi"/>
      </programlisting>



    </sect2>
    </sect1>

  </chapter>

  <chapter id="callouts">
    <title>Callouts</title>
    <para>

      Callouts are programs invoked when the device object list is
      modified or when a device changes. As such, callouts can be used
      to maintain system-wide policy (that may be specific to the
      particular OS) such as changing permissions on device nodes,
      updating the systemwide <literal>/etc/fstab</literal> file or
      configuring the networking subsystem.
      
    </para><para>
      
      There are three different classes of callouts. A callout
      involves sequentially invoking all executable programs in a
      given directory in alphabetic order.

    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Type</entry>
            <entry>Description</entry>
            <entry>Callout Directory</entry>
            <entry>Positional Parameters</entry>
          </row>
        </thead>
        <tbody>
	  
          <row>
            <entry>Device Add/Remove</entry>
            <entry>
	      When a new device object have been added, this callout
	      is invoked just after a device have entered the GDL
	      (global device list) but just before it is announced
	      through the D-BUS network API (the device isn't
	      announced until the last callout has finished).
	      When a device object is to be removed this callout is
	      invoked and the device isn't removed before the last
	      callout has finished.
	    </entry>
            <entry><literal>/etc/hal/device.d</literal></entry>
            <entry><literal>add</literal> or <literal>remove</literal></entry>
          </row>

          <row>
            <entry>Capability Add/Remove</entry>
            <entry>
	      Invoked when a capability have been added or removed.
	    </entry>
            <entry><literal>/etc/hal/capability.d</literal></entry>
            <entry><literal>add</literal> or <literal>remove</literal></entry>
          </row>

          <row>
            <entry>Property Change</entry>
            <entry>
	      Invoked when a device property have been added, removed
	      or is modified.
	    </entry>
            <entry><literal>/etc/hal/property.d</literal></entry>
            <entry>
	      <literal>add</literal>, <literal>remove</literal> or 
	      <literal>modify</literal>
	    </entry>
          </row>
	  
        </tbody>
      </tgroup>
    </informaltable>
    <para>
      
      All callouts execute in the same environment as which the HAL
      daemon was started. In addition, the UDI of the device object is
      exported in the environment variable <literal>UDI</literal>. All
      properties of the device object are exported in the environment
      prefixed with <literal>HAL_</literal>. The HAL daemon isn't
      suspended while callouts are executing. Thus, callouts can
      communicate with the HAL daemon using the D-BUS network
      API. Hence, one application of callouts is to merge or modify
      properties on a device object.

    </para>

  </chapter>

      
  <chapter id="dbus-api">
    <title>D-BUS Network API</title> <para> 

      The HAL daemon is a system-wide process that keeps track of a
      number of device objects. It communicates with the operating
      system and intercepts hotplug events as devices are plugged in
      and removed.  The daemon is also responsible for providing
      services to applications that wants to locate devices and
      perform generic operations on them such as obtaining exclusive
      access.  Non-generic operations, such as obtaining pictures from
      a camera device, is outside the scope of the HAL daemon; see
      <xref linkend="using-devices"/> for more information.

      </para><para>

      HAL has the concept of device stores. When a device is detected
      it is placed in the TDL (temporary device list) and then properties
      are merged from several sources including device information files
      and possibly callouts. Eventually, the device transitions to the
      GDL (global device list) and first then it becomes ''visible'' for 
      desktop applications.

      </para>

      <sect1><title>Interface org.freedesktop.Hal.Manager</title>

      <para> 

      Using D-BUS terminology, the HAL daemon provides the D-BUS
      service <literal>org.freedesktop.Hal</literal>. This service
      offers a D-BUS object at a well-known
      location <literal>/org/freedesktop/Hal/Manager</literal>. This
      object offers a D-BUS
      interface, <literal>org.freedesktop.Hal.Manager</literal>, for
      querying device objects with the following methods:
      </para>

<programlisting>
# Return a list of all devices in the GDL
#
# @return                       List of UDI's
#
array{string} GetAllDevices()

# Determine if a device with a given Unique Device Id exists in the GDL
#
# @param  udi                   Device UDI, for example '/org/freedesktop/Hal/devices/pci_8086_7111'
# @return                       TRUE iff the device with the given UDI exists
#
bool DeviceExists(string udi)

# Find the set of devices in the GDL that has a given property matching
# a given value
#
# @param  key                   Key, for example 'block.fstype'
# @param  value                 Value, for example 'ext3'
# @return                       Array of UDI's, may be empty
#
array{string} FindDeviceStringMatch(string key, string value)

# Find the set of devices in the GDL that has a given capability
#
# @param  capability            Capability, for example 'volume'
# @return                       Array of UDI's, may be empty
#
array{string} FindDeviceByCapability(string capability)
  
</programlisting>

      <para>

      This object also emits the following signals on the
      <literal>/org/freedesktop/Hal/Manager</literal> object on the
      <literal>org.freedesktop.Hal.Manager</literal> interface that
      applications can subscribe to using D-BUS:

      </para>

<programlisting>

# Notification that a new device have been added to the GDL
#
# @param  udi                   Unique Device Id
#
void DeviceAdded(string udi)

# Notification that a new device have been removed from the GDL. The
# application cannot use this UDI anymore.
#
# @param  udi                   Unique Device Id
#
void DeviceRemoved(string udi)

# Notification that a device in the GDL have got a new capability. Note that
# this is emitted even though the device already had the old capability
#
# @param  udi                   Unique Device Id
#
void NewCapability(string udi, string capability)

</programlisting>


      <sect2><title>Example</title>

      <para>

      The following brief Python program demonstrates some of the API

      </para>

<programlisting>
  <inlinegraphic format="linespecific" fileref="example-manager.py"/>
</programlisting>

      <para>

      which gives the following output

      </para>

<programlisting>
Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001-disc
Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001
Found device /org/freedesktop/Hal/devices/block_37332a77-105e-4e76-8e99-27d3746e0531
Found device /org/freedesktop/Hal/devices/block_3_2
Found device /org/freedesktop/Hal/devices/block_LS-120 SLIM3 00 UHD Floppy-0208MBA00211
Found device /org/freedesktop/Hal/devices/block_IC25N020ATCS05-0-CLP225F2G3UR4A
Found device /org/freedesktop/Hal/devices/ide_1_1
Found device /org/freedesktop/Hal/devices/ide_0_0
Found device /org/freedesktop/Hal/devices/ide_1_0
Found device /org/freedesktop/Hal/devices/usbif_usb_0_0_206_-1_0000:00:07.2_0
Found device /org/freedesktop/Hal/devices/ide_host_0
Found device /org/freedesktop/Hal/devices/ide_host_1
Found device /org/freedesktop/Hal/devices/pci_104c_8400
Found device /org/freedesktop/Hal/devices/usb_0_0_206_-1_0000:00:07.2
Found device /org/freedesktop/Hal/devices/pci_1002_4c4d
Found device /org/freedesktop/Hal/devices/pci_125d_1978
Found device /org/freedesktop/Hal/devices/pci_8086_7111
Found device /org/freedesktop/Hal/devices/pci_104c_ac1c/0
Found device /org/freedesktop/Hal/devices/pci_8086_7112
Found device /org/freedesktop/Hal/devices/pci_8086_7110
Found device /org/freedesktop/Hal/devices/input_13_65
Found device /org/freedesktop/Hal/devices/pci_104c_ac1c
Found device /org/freedesktop/Hal/devices/pci_8086_7190
Found device /org/freedesktop/Hal/devices/input_13_64
Found device /org/freedesktop/Hal/devices/pci_8086_7113
Found device /org/freedesktop/Hal/devices/pci_8086_7191
Found device /org/freedesktop/Hal/devices/computer

(insert USB mouse)

Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was added
Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was added

(remove USB mouse)

Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was removed
Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was removed
</programlisting>

      <para>

      </para>

      </sect2>

      </sect1>

      <sect1><title>Interface org.freedesktop.Hal.Device</title><para>

      Applications use
      the <literal>org.freedesktop.Hal.Manager</literal> interface to
      locate the device objects they are interested in. When a device
      object (which is really a D-BUS object, note that the UDI is the
      objects object_path) is obtained, the HAL daemon provides the
      <literal>org.freedesktop.Hal.Device</literal> interface on the
      object denoted by the UDI. This interface has the following
      methods

      </para>

<programlisting>

# Set property
#
# @param  key                   Property to set
# @param  value                 Value to set
# @raises                       org.freedesktop.Hal.(NoSuchDevice|TypeMismatch|PermissionDenied)
#
void SetProperty(string key, any value)
void SetPropertyString(string key, string value)
void SetPropertyInteger(string key, int32 value)
void SetPropertyBoolean(string key, bool value)
void SetPropertyDouble(string key, double value)

# Get property
#
# @param  key                   Property to get
# @return                       The value of the property
# @raises                       org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty|TypeMismatch)
#
any GetProperty(string key)
string GetPropertyString(string key)
int32 GetPropertyInteger(string key)
bool GetPropertyBoolean(string key)
double GetPropertyDouble(string key)

# Get all properties
#
# @return                       Dictionary from key to value
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
map{string, any} GetAllProperties()

  
# Remove a property
#
# @param  key                   Property to remove
# @raises                       org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty|PermissionDenied)
#
void RemoveProperty(string key)

# Get the type of a property
#
# @param  key                   Property
# @return                       D-BUS type of property
# @raises                       org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty)
#
int32 GetPropertyType(string key)

# Determine if a property exists
#
# @param  key                   Property
# @return                       TRUE iff the property exists
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
bool PropertyExists(string key)

# Add a capability to a device. Note that this will trigger a NewCapability
# signal to all client applications subscribing to signals from the Manager
# interface.
#
# @param  capability            Capability, e.g. 'net.80211'
# @raises                       org.freedesktop.Hal.(NoSuchDevice|PermissionDenied)
#
void AddCapability(string capability)

# Determine if a device got a given capability
#
# @param  capability            Capability, e.g. 'storage.cdrom'
# @return                       TRUE iff the device got the given capability
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
bool QueryCapability(string capability)

# Take an advisory lock on the device.
#
# @param  reason                A user-presentable reason why the device
#                               is locked.
# @raises                       org.freedesktop.Hal.NoSuchDevice,
#                               org.freedesktop.Hal.DeviceAlreadyLocked
#
void Lock(string reason)

# Release an advisory lock on the device.
#
# @raises                       org.freedesktop.Hal.NoSuchDevice,
#                               org.freedesktop.Hal.DeviceAlreadyLocked,
#                               org.freedesktop.Hal.PermissionDenied
#
void Unlock()
</programlisting>

      <para>

      The device objects also emits the following signals on the
      org.freedesktop.Hal interface that applications can subscribe to 
      using D-BUS

      </para>
<programlisting>
# Notification that property have been modified
#
# @param  key                   Property
# @param  added                 True iff the property have been added
# @param  removed               True iff the property have been removed
#
void PropertyModified(string key, bool added, bool removed)

# Notification that an event happened on the device has occured.
#
# Normally this is used to signal events that aren't or can't be expressed
# in properties, e.g. 'ProcessorOverheating' etc. 
#
# @param  condition             Name of condition
# @param  ...                   Dependent on the condition name
void Condition(string condition, ...)

</programlisting>
      <para>

      Note that D-BUS supports that applications can opt to receive
      signals for only a subset of the devices available.

      </para>

      </sect1>

  </chapter>


  <chapter id="enforcing-policy">
    <title>Enforcing Policy</title>
    <para> 

      Notwithstanding the fact that HAL avoids to enforce any policy,
      it is useful to have a minimal set of guidelines such that
      applications using HAL written for one operating system can
      easily run on another. This chapter contains recommendations
      about how to enforce policy to achieve that goal.

    </para>
    
    <sect1 id="enforcing-stor-vol">
      <title>Storage Devices</title>

      <sect2 id="stor-vol-policy">
	<title>Policy for Volumes and Storage devices</title>
	<para>
	  The properties in the <literal>storage.policy</literal>, 
	  <literal>volume.policy</literal> and 
	  <literal>storage.policy.default</literal> namespaces should
	  be the preferred way to determine how and if a filesystem
	  can be mounted. See <xref linkend="properties-policy"/>
	  for details.
	</para>
      </sect2>

      <sect2 id="enforcing-storage-fstab">
	<title>File systems file</title>
	<para>
	  An operating system vendor should maintain the 
	  <literal>/etc/fstab</literal> file through the HAL callout
	  mechanism such that device objects of capability
	  <literal>volume</literal> and <literal>storage</literal> has
	  a corresponding entry if applicable cf. 
	  <xref linkend="stor-vol-policy"/>.
	</para>
	<para>
	  The reasoning behind this is, among other things, to
	  maintain the invariant that <literal>/etc/fstab</literal>
	  list all available filesystems. In addition
	  the <literal>mount(1)</literal> program should enable users
	  without superuser privileges to mount filesystems mentioned
	  in the <literal>/etc/fstab</literal> file as long as they
	  have the <literal>user</literal> option set.
	</para>
      </sect2>

      <sect2 id="enforcing-storage-locking">
	<title>Disabling policy agents</title>
	<para>
	  Policy agents like volume mounters should ignore when media
	  is inserted into a drive that is locked by another
	  application. Thus, CD burning applications should lock the
	  device to disable auto mounting or automatic start of the
	  users preferred CD burning application when respectively
	  non-blank rewritable or blank media is inserted.
	</para>
      </sect2>

    </sect1>
  </chapter>

</book>