HAL 0.5.10 Specification

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.

HAL represents a piece of hardware as a device object. A device object is identified by a unique identifer and carries a set of key/value paris referred to as device properties. Some properties are derived from the actual hardware, some are merged from device information files 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.

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.

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.

Havoc Pennington's article ''Making Hardware Just Work'' motivated this work. The specification and software would not exist without all the useful ideas, suggestions, comments and patches from the Free Desktop and HAL mailing lists.

All trademarks mentioned belong to their respective owners.

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 all implementation details.

Details on each component

The D-Bus system message bus is used 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.

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 the operating system kernel, such as SCSI emulation for USB Storage Devices, are also considered device objects in HAL. This implies that operating system kernel specific bits leak into the device object database. However applications using HAL will not notice this, 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 operating system 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 may prove to be 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 section called “Device Capabilities” and Chapter 5, Device Properties for details.

Finally, HAL provides one or more D-Bus interfaces for applications to configure and/or use the device. These interfaces are discussed in Chapter 6, D-Bus interfaces.

Summarizing, a device object is comprised by

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

The first category is determined by HAL, the second category includes information merged from either querying the hardware itself or from device information files. The third category is intercepted by monitoring the hardware and finally the last is merged from files under control of the system administrator. This document is concerned with precisely defining several properties; see Chapter 5, 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.

Mainstream hardware isn't very good at reporting what it really is, it only reports, at best, how to interact with it. 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 the device in fact is 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 and the hardware itself.

User mode drivers such as libgphoto2 and sane provides device information to merge information about devices they can drive. As such, device objects represent an USB interface gain additional properties such as ''scanner'' or ''camera''.

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 (e.g. Ogg and MP3), 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''.

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

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|addset] 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>, <prepend> and <addset> 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.originating_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:

The <merge>, <append>, <prepend> and <addset> directives all require the type attribute which specifies what to merge. The following values are supported

The <remove>, directive require only a key and can be used with all keys. For strlist there is additionally a special syntax to remove a item from the string list. For example to remove item 'bla' from property 'foo.bar': <remove key="foo.bar" type="strlist">bla</remove>

Device Information files are read from two directories

in exactly that order. This means that the files provided by the system administrator will be processed last such that they can overwrite / change properties caused by the device information files provided by packages. The following directory structure is used in /usr/share/hal/fdi

As evident, third party packages should drop device information files in

The /etc/hal/fdi tree uses this layout

All device information files are matched for every hal device object in the following order.

If HAL is built with --enable-acl-management (requires both --enable-console-kit and --enable-policy-kit) then ACL's on device objects with the capability access_control are automatically managed according to the properties defined in the section called “ access_control namespace ”. In addition, for this configuration, HAL ships with a device information file (normally installed in /usr/share/hal/fdi/policy/10osvendor/20-acl-management.fdi) that merges this capability on device objects that are normally accessed by unprivileged users through the device file. This includes e.g. sound cards, webcams and other devices but excludes drives and volumes as the latter two are normally accessed by a user through mounting them into the file system.

HAL uses PolicyKit to decide what users should have access according to PolicyKit configuration; see the PolicyKit privilege definition file /etc/PolicyKit/privileges/hal-device-file.priv on a system with HAL installed for the default access suggested by the HAL package and/or OS vendor.

In addition, 3rd party packages can supply device information files to specify (via the access_control.grant_user and access_control.grant_group properties) that a given user or group should always have access to a device file. This is useful for system-wide software (such as AV streaming management) that runs as an unprivileged system user. This interface is supposed to be stable so 3rd party packages can depend on it.

If HAL is built without ConsoleKit support (e.g. without --enable-console-kit) access to the various D-Bus interfaces that provides mechanisms is only protected by the D-Bus security configuration files (e.g. using at_console to restrict to console user on Red Hat systems) and, in certain cases, restricted to the super user.

If ConsoleKit support is enabled, access to D-Bus interfaces is currently hardcoded to only allow active users at the system console. If PolicyKit support is enabled, the PolicyKit library will be in charge of determining access; see the PolicyKit privilege definition files in /etc/PolicyKit/privileges on a system with HAL installed for the default access suggested by the HAL package and/or OS vendor.

HAL provides a mechanism to lock a specific D-Bus interface either for a specific device or for all the devices the caller have access to.

The former is achieved by using the AcquireInterfaceLock() and ReleaseInterfaceLock() methods on the org.freedesktop.Hal.Device interface that every device object implements (see the section called “org.freedesktop.Hal.Device interface”). By using this API, a caller can prevent any other caller from invoking methods on the given interface for the given device object - other callers will simply see the org.freedesktop.Hal.Device.InterfaceLocked exception if they attempt to invoke a method on the given interface on the given device. The locker can specify whether the lock is exclusive meaning if multiple clients clients can hold the lock or if only one client can hold the lock at one time. If a client don't have access to the interface of the device, attempts to lock will fail with a org.freedesktop.Hal.PermissionDenied exception. If a client loses access to a device (say, if his session is switched away from using fast user switching) while holding a lock, he will lose the lock; this can be tracked by listening to the InterfaceLockReleased signal.

All local clients, whether they are active or not, can always lock interfaces on the root computer device object (this doesn't mean that they are privileged to use the interfaces though) - the rationale is that this device object represents shared infrastructure, e.g. power management, and even inactive sessions needs to participate in managing this.

If another client already holds a lock exclusively, attempts from other clients to acquire the lock will fail with the org.freedesktop.Hal.Device.InterfaceAlreadyLocked exception even if they have access to the device.

In addition, a client may opt to lock all devices that he got access to by using the AcquireGlobalInterfaceLock() and ReleaseGlobalInterfaceLock() methods on the org.freedesktop.Hal.Manager interface on the /org/freedesktop/Hal/Manager object (see the section called “org.freedesktop.Hal.Manager interface”). Global interface locks can also be obtained exclusively if the caller so desires. Unlike per-device interface locking, it is not checked at locking time whether the locker have access to a given device; instead checking is done when callers attempt to access the interface.

The algorithm used for determining if a caller is locked out is shown below. A caller A is locked out of an interface IFACE on a device object DEVICE if, and only if,

In other words, a caller A can grab a global lock, but that doesn't mean A can lock other clients out of devices that A doesn't have access to. Specifically a caller is never locked out if he has locked an interface either globally or on the device in question. However, if two clients have a lock on a device, then both can access it. To ensure that everyone is locked out, a caller needs to use an exclusive lock.

Note that certain interfaces will also check whether other locks are being held on other device objects. This is specified on a per-interface basis in Chapter 6, D-Bus interfaces.

If a process holding locks disconnects from the system bus, the locks being held by that process will be released.

Locking is only useful if applications requiring exclusive access actually use the locking primitives to cooperate with other applications. Here is a list of guidelines.

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

CK_NUM_SEATS=1
CK_NUM_SESSIONS=2
CK_SEATS=Seat1
CK_SEAT_Seat1=Session1  Session3
CK_SEAT_NUM_SESSIONS_Seat1=2
CK_SESSION_IS_ACTIVE_Session1=true
CK_SESSION_IS_ACTIVE_Session3=false
CK_SESSION_IS_LOCAL_Session1=true
CK_SESSION_IS_LOCAL_Session3=true
CK_SESSION_SEAT_Session1=Seat1
CK_SESSION_SEAT_Session3=Seat1
CK_SESSION_UID_Session1=500
CK_SESSION_UID_Session3=501
      

HAL_METHOD_INVOKED_BY_UID=500
HAL_METHOD_INVOKED_BY_PID=22553
HAL_METHOD_INVOKED_BY_SELINUX_CONTEXT=user_u:system_r:unconfined_t
HAL_METHOD_INVOKED_BY_SYSTEMBUS_CONNECTION_NAME=:1.138
      

info.interfaces = {'org.freedesktop.Hal.Device.Volume'}
org.freedesktop.Hal.Device.Volume.method_argnames = {'mount_point fstype extra_options', 'extra_options', 'extra_options'}
org.freedesktop.Hal.Device.Volume.method_execpaths = {'hal-storage-mount', 'hal-storage-unmount', 'hal-storage-eject'}
org.freedesktop.Hal.Device.Volume.method_names = {'Mount', 'Unmount', 'Eject'}
org.freedesktop.Hal.Device.Volume.method_signatures = {'ssas', 'as', 'as'}
        

In this section properties for device objects that represent addressable hardware is described. Availability of these depends on the value of the info.subsystem 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 subsystem-specific technologies is assumed for this section to be useful.

The section describe functional properties of device objects, that is, properties that are merged onto device objects representing 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.

The section represents properties that are deprecated and should be no longer used. The properties/keys will be removed, but not before the date in the following table:

Only the /org/freedesktop/Hal/Manager object implements this interface. It's primarily used to discover devices. The following methods are available:

The following signals are emitted:

Every hal device object (e.g. objects where the object path is prefixed with /org/freedesktop/Hal/devices/) implements this interface. It provides generic functionality. The following methods are available:

The following signals are emitted:

This interface provides a mechanism to affect system-wide power management. Normally only the root computer device object (/org/freedesktop/Hal/devices/computer) implements this interface. The following methods are available:

This interface does not emit any signals.

Implementors of power management daemons should make sure that their software respects the locking guidelines described in Chapter 6, D-Bus interfaces.

This interface provides a mechanism to configure CPU frequency scaling. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to configure Wake On LAN capabilities. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to get/set the brightness of a laptop panel. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to get/set the brightness of the keyboard backlight. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to get information from a light sensor. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to interact with a storage device. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism to interact with a volume that has a mountable file system. The following methods are available:

This interface does not emit any signals.

If a volume originates from a storage device (and all volumes do), it also is checked whether the caller is locked out of the org.freedesktop.Hal.Device.Storage interface of the originating storage device. As a corollary, it is sufficient to just either a) lock the storage device; or b) globally lock the org.freedesktop.Hal.Device.Storage interface if one wants to lock out callers from mounting volumes from either a specific drive or all drives.

This interface provides a mechanism to interact with a volume that is encrypted at the block layer. The following methods are available:

This interface does not emit any signals.

For objects implementing this interface, it will also be checked if the caller is locked out of the Volume interface on the device (and per the section called “org.freedesktop.Hal.Device.Volume interface” this includes checking whether the caller is locked out of the org.freedesktop.Hal.Device.Storage interface for the storage device that the volume originates from).

This interface provides a mechanism for both querying whether a radio is on as well as turning it on and off. The following methods are available:

This interface does not emit any signals.

This interface provides a mechanism for discovering when an ACL is added or removed for a device file. The following signals are available:

This interface does not export any methods.

This interface is provided by singleton addons to allow the Manager to request handling of new devices and removal of old ones. This differs from other HAL interface definitions in that it is provided by addon processes, rather than the HAL daemon itself. It should be exported on the path /org/freedesktop/Hal/Manager.

This interface does not export any methods.