hal/doc/spec Makefile.am, 1.8, 1.9 hal-spec-examples.xml, NONE,
1.1 hal-spec-fdi-files.xml, NONE,
1.1 hal-spec-introduction.xml, NONE,
1.1 hal-spec-properties.xml, NONE, 1.1 hal-spec.html, 1.84,
1.85 hal-spec.xml.in, 1.72, 1.73
Richard Hughes
hughsient at kemper.freedesktop.org
Tue May 9 09:36:48 PDT 2006
- Previous message: hal ChangeLog,1.884,1.885
- Next message: hal/doc/spec Makefile.am, 1.8, 1.9 hal-spec-examples.xml, NONE,
1.1 hal-spec-fdi-files.xml, NONE,
1.1 hal-spec-introduction.xml, NONE,
1.1 hal-spec-properties.xml, NONE, 1.1 hal-spec.html, 1.84,
1.85 hal-spec.xml.in, 1.72, 1.73
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvs/hal/hal/doc/spec
In directory kemper:/tmp/cvs-serv12446/doc/spec
Modified Files:
Makefile.am hal-spec.html hal-spec.xml.in
Added Files:
hal-spec-examples.xml hal-spec-fdi-files.xml
hal-spec-introduction.xml hal-spec-properties.xml
Log Message:
2006-05-09 Richard Hughes <richard at hughsie.com>
* doc/spec/Makefile.am: * doc/spec/hal-spec.html: * doc/spec/hal-spec.xml.in: * doc/spec/hal-spec-introduction.xml: * doc/spec/hal-spec-fdi-files.xml: * doc/spec/hal-spec-properties.xml: * doc/spec/hal-spec-examples.xml: Split up the spec file into more managable lumps using XInclude, and change to using xmlto to convert the docbook xml to html as docbook2html cannot handle the XInclude stuff as it's not valid docbook. This is the first of many cleanup patches to the spec, so expect the filenames to (maybe) change, or for files to be split even further.
Index: Makefile.am
===================================================================
RCS file: /cvs/hal/hal/doc/spec/Makefile.am,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- Makefile.am 1 Jul 2005 18:16:46 -0000 1.8
+++ Makefile.am 9 May 2006 16:36:45 -0000 1.9
@@ -1,31 +1,36 @@
-
-FIGURE_FILES = \
- hal-arch.png \
- hal-devices1.png \
+FIGURE_FILES = \
+ hal-arch.png \
+ hal-devices1.png \
hal-fdi-example1.png \
hal-fdi-example2.png \
hal-fdi-example3.png \
hal-linux26.png
+SPEC_XML_FILES = \
+ hal-spec.xml \
+ hal-spec-examples.xml \
+ hal-spec-introduction.xml \
+ hal-spec-fdi-files.xml \
+ hal-spec-properties.xml
+
if DOCBOOK_DOCS_ENABLED
htmldocdir = $(DOCDIR)/spec
htmldoc_DATA = hal-spec.html $(FIGURE_FILES)
-hal-spec.html : hal-spec.xml $(FIGURE_FILES)
- $(DOCBOOK) --nochunks hal-spec.xml -o .
+hal-spec.html : $(SPEC_XML_FILES) $(FIGURE_FILES)
+ xmlto html-nochunks hal-spec.xml
clean-local:
rm -f *~
rm -f hal-spec.html hal-spec.xml
-
endif # DOCBOOK_DOCS_ENABLED
-EXTRA_DIST = hal-spec.html \
- hal-spec.xml.in \
- example-manager.py \
- hal-arch.dia \
- hal-linux26.dia \
- $(FIGURE_FILES)
+EXTRA_DIST = hal-spec.html \
+ hal-spec.xml.in \
+ example-manager.py \
+ hal-arch.dia \
+ hal-linux26.dia \
+ $(FIGURE_FILES)
--- NEW FILE: hal-spec-examples.xml ---
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id: hal-spec-examples.xml,v 1.1 2006/05/09 16:36:45 hughsient Exp $ -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter id="examples">
<title>Examples and other stuff</title>
<sect1 id="callouts">
<title>Callouts</title>
<para>
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
<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 the
string list in listed order.
</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.callouts.add</literal> (string list)
</entry>
<entry></entry>
<entry>No</entry>
<entry>
A string list with all programmes/callouts which should be
executed (with <literal>HALD_ACTION=add</literal>) when the device
is added to the GDL (global device list) but just before it is
announced through the D-BUS network API.
</entry>
</row>
<row>
<entry>
<literal>info.callouts.remove</literal> (string list)
</entry>
<entry></entry>
<entry>No</entry>
<entry>
A string list with all programmes/callouts which should be
executed (with <literal>HALD_ACTION=remove</literal>) when the
device is removed from the GDL (global device list). The device
isn't removed before the last callout has finished.
</entry>
</row>
<row>
<entry>
<literal>info.callouts.preprobe</literal> (string list)
</entry>
<entry></entry>
<entry>No</entry>
<entry>
A string list with all programmes/callouts which should be
executed (with <literal>HALD_ACTION=preprobe</literal>) before
the device is added to the GDL (global device list) and before
the callouts from <literal>info.callouts.add</literal> are executed.
</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>. If a device is added or
removed is exported in the environment variable <literal>HALD_ACTION
</literal>
,if HAL is in shutdown mode the variable <literal>
HALD_SHUTDOWN
</literal>
is set to environment.
</para>
<para>
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>
</sect1>
<sect1 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>
<sect2>
<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>
<sect3>
<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>
</sect3>
</sect2>
<sect2>
<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>
</sect2>
</sect1>
<sect1 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 section contains recommendations
about how to enforce policy to achieve that goal.
</para>
<sect2 id="enforcing-stor-vol">
<title>Storage Devices</title>
<sect3 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>
</sect3>
<sect3 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>
</sect3>
<sect3 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>
</sect3>
</sect2>
</sect1>
</chapter>
--- NEW FILE: hal-spec-fdi-files.xml ---
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id: hal-spec-fdi-files.xml,v 1.1 2006/05/09 16:36:45 hughsient Exp $ -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<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><match key="some_property"
[string|int|bool|..]="required_value" >
</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><[merge|append|prepend] key="some_property"
type="[string|int|bool|..]">
</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><match></literal>,
<literal><merge></literal>, <literal><append></literal>
and <literal><prepend></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><match></literal>
tag:
<itemizedlist>
<listitem>
<para>
<literal>string</literal> - match a string property; for example
<literal><match key="foo.bar" string="baz"></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><match key="foo.bar" exists="true"></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>
<listitem>
<para>
<literal>contains</literal> - 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.
</para>
</listitem>
<listitem>
<para>
<literal>contains_ncase</literal> - like <literal>contains</literal>
but the property and the given key are converted to lowercase before check.
</para>
</listitem>
</itemizedlist>
The <literal><merge></literal>, <literal><append></literal>
and <literal><prepend></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><merge key="foo.bar" type="string">baz</merge></literal>
will merge the value 'baz' into the property 'foo.bar'.
</para>
</listitem>
<listitem>
<para>
<literal>strlist</literal> - For <literal><merge></literal> the value is
copied to the property and the current property will be overwritten. For
<literal><append></literal> and <literal><prepend></literal> the
value is append or prepend to the list as new item.
</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><merge key="foo.bar" type="copy_property">@info.parent:baz.bat</merge></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>
The <literal><remove></literal>, directive require only a key and can be used with all keys.
For <literal>strlist</literal> there is additionally a special syntax to remove a item from the
string list. For example to remove item 'bla' from property 'foo.bar':
<literal><remove key="foo.bar" type="strlist">bla</merge></literal>
</para>
<para>
Device Information files are stored in the following standard hierachy with the following default
top level directories <literal>information</literal>, <literal>policy</literal> and
<literal>preprobe</literal>:
<itemizedlist>
<listitem>
<para>
<literal>information</literal> - device information files to merge device information
<itemizedlist>
<listitem>
<para>
<literal>10freedesktop</literal> - device information files included with
the hal tarball
</para>
</listitem>
<listitem>
<para>
<literal>20thirdparty</literal> - device information files from the device
manufacturer and installed from media accompanying the hardware
</para>
</listitem>
<listitem>
<para>
<literal>30user</literal> - device information for specific devices
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<literal>policy</literal> - device information files to merge policy propertys
<itemizedlist>
<listitem>
<para>
<literal>10osvendor</literal> - device information files included with the
hal tarball and supplied by the operating system vendor for policy rules
</para>
</listitem>
<listitem>
<para>
<literal>20thirdparty</literal> - Policy rules from the device
manufacturer and installed from media accompanying the hardware
</para>
</listitem>
<listitem>
<para>
<literal>30user</literal> - Policy rules for specific devices
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<literal>preprobe</literal> - device information files to information before probe devices
<itemizedlist>
<listitem>
<para>
<literal>10osvendor</literal> - device information files included with the
hal tarball and supplied by the operating system vendor
</para>
</listitem>
<listitem>
<para>
<literal>20thirdparty</literal> - device information files from the device
manufacturer and installed from media accompanying the hardware
</para>
</listitem>
<listitem>
<para>
<literal>30user</literal> - device information for specific devices
</para>
</listitem>
</itemizedlist>
</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>
<programlisting>
<inlinegraphic format="linespecific" fileref="../conf/match-USB-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>
<programlisting>
<inlinegraphic format="linespecific" fileref="../conf/match-USB-camera.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>
<programlisting>
<inlinegraphic format="linespecific" fileref="../conf/match-cardreader.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>
<programlisting>
<inlinegraphic format="linespecific" fileref="../conf/storage-policy-examples.fdi"/>
</programlisting>
</sect2>
</sect1>
</chapter>
--- NEW FILE: hal-spec-introduction.xml ---
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id: hal-spec-introduction.xml,v 1.1 2006/05/09 16:36:45 hughsient Exp $ -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<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>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>
<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 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>
<sect1>
<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>strlist</literal> - sorted list with UTF8 strings
</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>
</sect1>
<sect1 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>
</sect1>
<sect1 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>
</sect1>
</chapter>
--- NEW FILE: hal-spec-properties.xml ---
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id: hal-spec-properties.xml,v 1.1 2006/05/09 16:36:45 hughsient Exp $ -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<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, 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.
</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
[...5342 lines suppressed...]
</row>
<row>
<entry>
<literal>volume.policy.mount_option.*</literal> (bool)
</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>
Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.84
retrieving revision 1.85
diff -u -d -r1.84 -r1.85
--- hal-spec.html 28 Apr 2006 18:48:07 -0000 1.84
+++ hal-spec.html 9 May 2006 16:36:45 -0000 1.85
@@ -1,898 +1,170 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<HTML
-><HEAD
-><TITLE
->HAL 0.5.8 Specification</TITLE
-><META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
-><BODY
-CLASS="book"
-BGCOLOR="#FFFFFF"
[...14906 lines suppressed...]
+ <code class="literal">volume</code> and <code class="literal">storage</code> has
+ a corresponding entry if applicable cf.
+ <a href="#stor-vol-policy" title="Policy for Volumes and Storage devices">the section called “Policy for Volumes and Storage devices”</a>
+ .
+ </p><p>
+ The reasoning behind this is, among other things, to
+ maintain the invariant that <code class="literal">/etc/fstab</code>
+ list all available filesystems. In addition
+ the <code class="literal">mount(1)</code> program should enable users
+ without superuser privileges to mount filesystems mentioned
+ in the <code class="literal">/etc/fstab</code> file as long as they
+ have the <code class="literal">user</code> option set.
+ </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="enforcing-storage-locking"></a>Disabling policy agents</h4></div></div></div><p>
+ 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.
+ </p></div></div></div></div></div></body></html>
Index: hal-spec.xml.in
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.xml.in,v
retrieving revision 1.72
retrieving revision 1.73
diff -u -d -r1.72 -r1.73
--- hal-spec.xml.in 8 May 2006 18:39:32 -0000 1.72
+++ hal-spec.xml.in 9 May 2006 16:36:45 -0000 1.73
@@ -2,6251 +2,27 @@
<!-- 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 -->
+ <date>May 9th, 2006</date> <!-- Update this manually -->
[...6232 lines suppressed...]
- 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>
- Previous message: hal ChangeLog,1.884,1.885
- Next message: hal/doc/spec Makefile.am, 1.8, 1.9 hal-spec-examples.xml, NONE,
1.1 hal-spec-fdi-files.xml, NONE,
1.1 hal-spec-introduction.xml, NONE,
1.1 hal-spec-properties.xml, NONE, 1.1 hal-spec.html, 1.84,
1.85 hal-spec.xml.in, 1.72, 1.73
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the hal-commit
mailing list