Introduction

Overview

Device Objects

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.

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.

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 /dev. 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 /dev/input/mouse2 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 the Chapter called Device Capabilities and the Chapter called Device Properties for details.

On a formal level, a device object is comprised by

• UDI

  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.

• Properties

  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

  • string - UTF8 string

  • strlist - sorted list with UTF8 strings

  • int - 32-bit signed integer

  • uint64 - 64-bit unsigned integer

  • bool - truth value

  • double - IEEE754 double precision floating point number

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.

It can be useful to classify properties into four groups

• 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.

• Facts - vendor ID, product ID, disk serial numbers, number of buttons on a mouse, formats accepted by a mp3 player and so on.

• Usage specific information - Network link status, special device file name, filesystem mount location etc.

• Policy - How the device is to be used be users; usually defined by the system administrator.

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 the Chapter called Device Properties and onwards for more information. As a complement to device properties, HAL also provides conditions 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''.

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 /org/freedesktop/Hal/devices/computer.

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 hal-device-manager. 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.

Device Capabilities

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.

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, info.category and info.capabilities. The former describes what the device is (as a single alphanumeric keyword) and the latter describes what the device does (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 capabilities.

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.

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.

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''.

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.

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

Using devices

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.

For instance, libgphoto2 could be extended such that the application programmer can simply pass the UDI of the camera he wishes to interact with and libghoto2 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.

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 NULL, 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.

Device Properties

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, UTF8 strings and UTF8 string lists are supported. The key of a property is always an ASCII string without any whitespace. The properties are updated in real-time.

Device Information Files

Device information files (.fdi 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.

Each device information file got a number of <match key="some_property" [string|int|bool|..]="required_value" > directives that is tested against the properties of the device object. If all the match directives passes then the device information can include <[merge|append|prepend] key="some_property" type="[string|int|bool|..]"> 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.

The <match>, <merge>, <append> and <prepend> directives always requires the key 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 /org/freedesktop/Hal/devices/computer:foo.bar or indirect references such as @info.parent:baz where the latter means that the device object specified by the UDI in the string property info.parent should be used to query the property baz. It is also possible to use multiple indirections, e.g. for a volume on a USB memory stick the indirection @block.storage_device:@storage.physical_device:usb.vendor_id will reference the usb.vendor_id property on the device object representing the USB interface.

When the property to match have been determined a number of attributes can be used within the <match> tag:

• string - match a string property; for example <match key="foo.bar" string="baz"> will match only if 'foo.bar' is a string property assuming the value 'baz'.

• int - match an integer property

• uint64 - match property with the 64-bit unsigned type

• bool - match a boolean property

• double - match a property of type double

• exists - used as <match key="foo.bar" exists="true">. Can be used with 'true' and 'false' respectively to match when a property exists and it doesn't.

• empty - 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.

• is_absolute_path - matches only when a string property represents an absolute path (the path doesn't have to exist). Can be used with 'true' or 'false'.

• is_ascii - matches only when a string property contain only ASCII characters. Can be used with 'true' or 'false'.

• compare_lt - 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.

• compare_le - like compare_lt but matches when less than or equal.

• compare_gt - like compare_lt but matches when greater than.

• compare_ge - like compare_lt but matches when greater than or equal.

• contains - can only be used with string and strlist (string list). For a string key this matches when the property contains the given (sub-)string. For a string list this match if the given string match a item of the list.

• contains_ncase - like contains but the property and the given key are converted to lowercase before check.

• string - The value is copied to the property. For example <merge key="foo.bar" type="string">baz</merge> will merge the value 'baz' into the property 'foo.bar'.

• strlist - For <merge> the value is copied to the property and the current property will be overwritten. For <append> and <prepend> the value is append or prepend to the list as new item.

• bool - Can merge the values 'true' or 'false'

• int - Merges an integer

• uint64 - Merges an unsigned 64-bit integer

• double - Merges a double precision floating point number

• copy_property - Copies the value of a given property - supports paths with direct and indirect UDI's. For example <merge key="foo.bar" type="copy_property">@info.parent:baz.bat</merge> will merge the value of the property baz.bat on the device object with the UDI from the property info.parent into the property foo.bar on the device object being processed.

Device Information files are stored in the following standard hierachy with the following default top level directories information, policy and preprobe:

• information - device information files to merge device information

  • 10freedesktop - device information files included with the hal tarball

  • 20thirdparty - device information files from the device manufacturer and installed from media accompanying the hardware

  • 30user - device information for specific devices

• policy - device information files to merge policy propertys

  • 10osvendor - device information files included with the hal tarball and supplied by the operating system vendor for policy rules

  • 20thirdparty - Policy rules from the device manufacturer and installed from media accompanying the hardware

  • 30user - Policy rules for specific devices

• preprobe - device information files to information before probe devices

  • 10osvendor - device information files included with the hal tarball and supplied by the operating system vendor

  • 20thirdparty - device information files from the device manufacturer and installed from media accompanying the hardware

  • 30user - device information for specific devices

	<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- --> 

<!-- Example: This device information file matches an USB Mass Storage based MP3 player 
              by the matching on the USB vendor and product identifiers. -->

<deviceinfo version="0.2">
  <device>
    <match key="info.bus" string="usb">
      <match key="usb.vendor_id" int="0x066f">
        <match key="usb.product_id" int="0x8000">
          <merge key="info.category" type="string">portable_audio_player</merge>
          <merge key="info.capabilities" type="string">portable_audio_player</merge>
          <merge key="portable_audio_player.access_method" type="string">storage</merge>
          <merge key="portable_audio_player.output_formats" type="string">audio/mpeg audio/x-ms-wma</merge>
          <merge key="portable_audio_player.input_formats" type="string">audio/x-wav</merge>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>
      

	<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- --> 

<!-- Example: This device information file matches a Sony digital still 
              camera by matching on the USB vendor and product identifers.  -->

<deviceinfo version="0.2">
  <device>
    <match key="info.bus" string="usb">
      <match key="usb.vendor_id" int="0x054c">
        <match key="usb.product_id" int="0x0010">
          <merge key="info.category" type="string">camera</merge>
          <merge key="info.capabilities" type="string">camera</merge>
          <merge key="camera.access_method" type="string">storage</merge>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>
      

	<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- --> 

<!-- Example: This device information file matches a memory card reader with 
              multiple storage ports that can be active at the same time. -->

<deviceinfo version="0.2">
  <device>
    <match key="storage.bus" string="usb">
      <match key="@storage.physical_device:usb.vendor_id" int="0x0424">
        <match key="@storage.physical_device:usb.product_id" int="0x20fc">
          <match key="storage.lun" int="0">
            <merge key="storage.drive_type" type="string">compact_flash</merge>
	  </match>
          <match key="storage.lun" int="1">
            <merge key="storage.drive_type" type="string">memory_stick</merge>
	  </match>
          <match key="storage.lun" int="2">
            <merge key="storage.drive_type" type="string">smart_media</merge>
	  </match>
          <match key="storage.lun" int="3">
            <merge key="storage.drive_type" type="string">sd_mmc</merge>
	  </match>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>
      

	<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- --> 

<deviceinfo version="0.2">

  <!-- Example: Match volumes from an external USB harddisk enclosure by 
                matching on vendor and model. Use mount points 

  		    my_usbdisk_part_<partition-number>

		NB: some drives (ieee1394 based IIRC) even export the
		property storage.serial, the unique serial number of the
		disk which is a better match -->
  <device>
    <match key="block.is_volume" bool="true">
      <match key="volume.fsusage" string="filesystem">
	<match key="@block.storage_device:storage.vendor" string="ST360021">
	  <match key="@block.storage_device:storage.model" string="A">
	    <merge key="volume.policy.desired_mount_point" type="string">my_usbdisk_partition_</merge>
	    <append key="volume.policy.desired_mount_point" type="copy_property">volume.partition.number</append>
	  </match>
	</match>
      </match>
    </match>
  </device>

  <!-- Example: Match a volume from an USB Storage Based mp3 player
                by the file system UUID and assign a mount point.

                NB: When reformatting the volume a new UUID will be
                used and this rule will have to be altered -->
  <device>
    <match key="block.is_volume" bool="true">
      <match key="volume.fsusage" string="filesystem">
	<match key="volume.uuid" string="4150-3F34">
	  <merge key="volume.policy.desired_mount_point" type="string">my_mp3_player</merge>
	</match>
      </match>
    </match>
  </device>

</deviceinfo>
      

Callouts

Callouts are programs invoked when the device object list is modified. 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 /etc/fstab file or configuring the networking subsystem.

There are three different classes of callouts. A callout involves sequentially invoking all executable programs in the string list in listed order.

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 UDI. All properties of the device object are exported in the environment prefixed with HAL_. If a device is added or removed is exported in the environment variable HALD_ACTION , if HAL is in shutdown mode the variable HALD_SHUTDOWN is set to environment.

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.

D-BUS Network API

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 the Chapter called Using devices for more information.

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.

# 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)
  

# 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)

  #!/usr/bin/python
 
import gtk
import dbus

def device_added(interface, signal_name, service, path, message):
    [udi] = message.get_args_list ()
    print 'Device %s was added'%udi

def device_removed(interface, signal_name, service, path, message):
    [udi] = message.get_args_list ()
    print 'Device %s was removed'%udi

 
bus = dbus.Bus (dbus.Bus.TYPE_SYSTEM)
hal_service = bus.get_service ('org.freedesktop.Hal')
hal_manager = hal_service.get_object ('/org/freedesktop/Hal/Manager',
				      'org.freedesktop.Hal.Manager')

devices = hal_manager.GetAllDevices ()
for d in devices:
    print 'Found device %s'%d

bus.add_signal_receiver (device_added,
			 'DeviceAdded',
			 'org.freedesktop.Hal.Manager',
			 'org.freedesktop.Hal',
			 '/org/freedesktop/Hal/Manager')
bus.add_signal_receiver (device_removed,
			 'DeviceRemoved',
			 'org.freedesktop.Hal.Manager',
			 'org.freedesktop.Hal',
			 '/org/freedesktop/Hal/Manager')
gtk.main()

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

# 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()

# 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, ...)

Enforcing Policy

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.