HAL 0.2.95

Introduction

This is a specification of a hardware abstraction layer (HAL) that allows applications to enumerate and use devices present in a typical desktop system, in an operating system independent way.

A device, in the context of the HAL, is identified by a unique id and a set of properties (key/value pairs). This document specifies a set of known properties and gives them well-defined meaning. This enables applications and desktop environments to make a distinction between the different device objects and use the devices based on certain well-known properties.

For instance, the info.category property specifies what the device is (such as a digital camera or an audio device), and the block.mount_point property specifies where in the filesystem a storage device is mounted.

In addition, the HAL provides generic device operations such as locking devices for exclusive access. Furthermore, hooks for non-generic operations (such as retrieve pictures from a camera) is also provided.

Finally, this specification is concerned with so called device information files. A device info file matches a subset of devices (from properties derived from the physical bus the device is on) and populates them with other, often well-defined, properties. Device info files are by no means a substitute for driver software, they are simply hints to the desktop environment / applications about what the device is, what it does and how it can be used.

The HAL is built upon D-BUS which is a framework that, among other things, provides a message-bus that allows applications to talk to one another. Apart from D-BUS, HAL has no other major dependencies which, in theory, allows it to work on many UNIX-like systems. The major focus, initially, is systems running the Linux 2.6 kernel.

Overview

Device Objects

It is important to precisely define the term ''device object'' - it is actually intended to mean two things:

• A device as recognized by the USB, PCI etc. standards and treated as such by the operating system kernel and base OS.

• Storage volumes - e.g. partitions on a storage device. While partitions are not real devices (they lend space on a real device such as a hard disk or an optical disc), they are on the same conceptual level as hard disks or optical discs.

HAL is not concerned with this duality of either one-to-one or many-to-one relationships between ''device objects'' and the actual iron constituting what users normally understand as a single device.

A device object consist of the following information

• Unique Device ID (referred to as the UDI in the following)

  This is an identifier that is unique for a device object - that is, no other device object can have this ID at the same time. This ID is computed from bus-specific information so it is unique across device insertions and when multiple instances of the same kind of device is plugged in.

• Properties

  Each device 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

  • int - 32-bit signed integer

  • bool - truth value

  • double - IEEE754 double precision floating point number

• Bus specific information - vendor, product ID etc.

• Network link status, Storage mount location etc.

• User or application information related to the device, for instance which account to hotsync a PDA device with.

Below is a screenshot of a device manager application communicating with the HAL daemon and displaying the devices. The shown properties are for a device representing a partition on a harddisk:

Note that HAL also support device objects which doesn't represent a device; these are marked with the boolean property info.virtual and always contain a link to the physical device in question using the property info.physical_device. For USB devices, for instance, the USB interfaces are represented as separate virtual devices. The following screenshot shows a software SCSI host adaptor sitting in the chain between USB storage and a storage volume.

The reason for supporting virtual devices is that it greatly simplies the implementation.

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

Note that the HAL daemon has the concept of a Global Device List (GDL in the following) that contains the devices that the clients can search and subscribe on changes to. When a device have been detected, either from inside the HAL daemon or from an HAL agent, devices are not initially in the GDL; instead, they are added later when a number of properties have been merged.

# 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                       List of UDI's
#
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                       List of UDI's
#
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)

# Set property
#
# @param  key                   Property to set
# @param  value                 Value to set
# @raises                       org.freedesktop.Hal.(NoSuchDevice|TypeMismatch)
#
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)
#
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.ethernet'
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
void AddCapability(string capability)

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

# Notification that property have been added
#
# @param  key                   Property
#
void PropertyAdded(string key)

# Notification that property have been removed
#
# @param  key                   Property
#
void PropertyRemoved(string key)

# Notification that property have changed value
#
# @param  key                   Property
#
void PropertyChanged(string key)

# Create a new device object not in the GDL (ie. hidden from 
# applications). This object can be obtained using the given UDI as
# as the D-BUS object reference. 
#
# The object implements the org.freedesktop.Hal.Device interface
#
# @return                       Temporary UDI for new device object
#
string NewDevice()

# When a device have been built, an application can add it to the GDL.
#
# A side-effect of this call, is that the Manager object will emit the
# signal DeviceAdded.
# 
# @param  tempUdi               Temporary UDI as obtained from the NewDevice call
# @param  newUdi                New UDI to use.
# @raises                       org.freedesktop.Hal.(NoSuchDevice|UdiInUse)
#
void CommitToGDL(string tempUdi, string newUdi)

# Remove a device object. 
#
# Depending on the info.persistent property, the device may not be removed but
# rather acquire the property info.not_available with value true.
#
# @param  udi                   UDI of device
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
void Remove(string udi)

# Merge all properties from one device to another device.
#
# If the source device got any capabilities, then the target device
# will acquire these capabilities and a NewCapability signal will be
# emitted for the target device for every capability in the source
# device.
#
# @param  targetUdi             UDI of device to receive properties
# @param  sourceUdi             UDI of device to copy properties from
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
void MergeProperties(string targetUdi, string sourceUdi)

# Checks that all properties where keys, starting with a given value
# (namespace), of the first device is present in the second device and that
# they got the same value and type. 
#
# Note that the other inclusion isn't tested, so there could be
# properties (from the given namespace) in the second device not present
# in the first device.
#
# @param  udi1                  UDI of device 1
# @param  udi2                  UDI of device 2
# @param  namespace             Namespace used for matching, e.g. 'usb'
# @return                       TRUE if, and only if, all properties starting
#                               with the namespace parameter from udi1 is
#                               in udi2 and assume the same value
# @raises                       org.freedesktop.Hal.NoSuchDevice
#
bool DeviceMatches(string udi1, string udi2, string namespace)

Using devices

One of the goals of the HAL is to provide easy access to devices on a system. This includes obtaining device specific information, such as CPU frequency, and invoking device specific methods such as getting the pictures on a camera or changing the volume on a sound device.

While the HAL daemon provides generic operations that apply to all devices (though some may be no-ops) and provide some level of monitoring for well-know class devices (such as networking devices), it is not concerned with providing non-generic device operations.

The architecture of the HAL allows a number of ways of dealing with specific device information and operations

• Out-of-process D-BUS Service

  For example, one could write a volume manager that manages the different storage devices present on the system and mount the partitions/volumes available on those into the filesystem according to certain rules. The volume manager would run as a daemon monitoring the device list of the HAL daemon and act appropriately when devices having Storage and StorageVolume in the Capabilitites property appear and disappear.

  The volume manager could also offer an operation for writing ISO images to e.g. CD-R devices through a D-BUS interface on HAL device object. In this scenario, a desktop file manager would use the HAL daemon to query for the HAL device object that is a CD recorder and pass the object reference to the D-BUS service offered by the volume manager.

• In-process library

  Another example is device objects having capability camera. One could use an existing library, such as libgphoto2, and make wrapper functions such that the application programmer simple passes the HAL UDI to the library. The library would then, via D-BUS, acquire the bus-specific information required from the HAL daemon, and then interact with the device.

Capabilities

As previously mentioned the capabilities of a device specify what the device does. For instance, a CompactFlash card reader can be thought of as a camera, a handheld music device and removable storage.

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 has 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 a desktop environment policy daemon. This gives maximum flexibility, while maintaining a base level of capability detection.

Note that, for instance, a number of USB devices doesn't advertise anything in their device class, so a repository of device information files coupled with an interactive dialog (provided by a desktop environment daemon) asking the user what he just plugged in, will probably yield the best experience for users. Incidently, this is how certain non-free operating systems appear to handle hardware.

Returning to the example of the card reader, this might just happen to be a digital camera with the only interface being a card reader - HAL, or the base OS, wouldn't be able to tell the difference - it's just looks like a storage device. So, to handle hardware well to meet the expectation of the users, device information files and desktop environment policy daemons need to be available on top of HAL (notably, the desktop environment daemon might look at the files on the device to infer whether it's music, pictures or something else) and adjust the capabilities and category of certain devices.

Finally, what a given capability means, needs to be precisely defined. 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. At some point in time, we may define an uniform in-process extension framework akin to e.g. OpenGL extensions for accessing said libraries and services.

Having a capability also means that part of the property namespace, prefixed with the capability name, can (but it's not a requirement) be populated with more specific information about the capability. Virtual devices will not have any capabilities assigned to them.

The following table define the capabilities supported in HAL at the time of writing.

As evident, most of the capabilities in the above list is derived directly from USB and PCI classes (the careful reader will even note that not all classes from the USB and PCI standards are mentioned), and as such, are not very interesting to desktop applications.

However, if HAL becomes adopted by applications, new and interesting capabilities (for example pda, camera or handheld_music_player), based on what the device is used for, can begin to appear.

Properties of a device

Properties are arranged in a namespaces using . (dot) 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.

      storage_controller.ide -> ide_host -> ide -> block -> block
      

Specification of device info files

The format is almost self-explanatory; here's an example

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

<deviceinfo version="0.2">
  <device>
    <match key="info.bus" string="usb">
      <match key="usb.vendor_id" int="0x04a9">
        <match key="usb.product_id" int="0x3052">
          <merge key="info.category" type="string">camera</merge>
          <merge key="info.capabilities" type="string">camera</merge>
          <merge key="info.persistent" type="bool">true</merge>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>

This .fdi file matches a Canon Digital IXUS V (for this device no device or interface class is advertised), so we match the USB vendor and product identifers. Then we merge category and capabilities into the device object along with setting the persistent property, and this is what it looks like after being matched

It's important to emphasize that any previously property stemming from device detection can be overridden by a device information file.