hal/doc/spec hal-spec.html,1.2,1.3 hal-spec.xml.in,1.1,1.2
David Zeuthen
david at freedesktop.org
Thu Jul 29 10:07:11 PDT 2004
Update of /cvs/hal/hal/doc/spec
In directory pdx:/tmp/cvs-serv11505/doc/spec
Modified Files:
hal-spec.html hal-spec.xml.in
Log Message:
2004-07-29 David Zeuthen <david at fubar.dk>
* libhal/libhal.[ch]: s/namespace/property_namespace/ to not break
using libhal from C++. Pointed out by Simone Gotti
<simone.gotti at email.it>
2004-07-29 David Zeuthen <david at fubar.dk>
Patch from Kay Sievers <kay.sievers at vrfy.org>
* configure.in:
* doc/spec/hal-spec.html:
* doc/spec/hal-spec.xml.in:
* hald/linux/block_class_device.c:
* hald/linux/volume_id/volume_id.c: (get_buffer),
(probe_hfs_hfsplus), (probe_ntfs), (volume_id_probe):
* hald/linux/volume_id/volume_id.h:
Here is support for recognition of hfs and hfsplus filesystems on
a main block device, like a CD. Only the first partition is
returned with the probe.
Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- hal-spec.html 22 Jul 2004 19:40:20 -0000 1.2
+++ hal-spec.html 29 Jul 2004 17:07:08 -0000 1.3
@@ -74,7 +74,7 @@
></DT
><DT
><A
-HREF="#AEN144"
+HREF="#AEN148"
>D-BUS Network API</A
></DT
><DT
@@ -108,21 +108,26 @@
>Introduction</A
></H2
><P
-> This is a specification of a hardware abstraction
+>
+ 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.
+
</P
><P
-> A device, in the context of the HAL, is identified by a unique
+>
+ 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.
+
</P
><P
-> For instance, the <I
+>
+ For instance, the <I
CLASS="emphasis"
>info.category</I
> property specifies
@@ -132,32 +137,43 @@
>block.mount_point</I
> property
specifies where in the filesystem a storage device is mounted.
+
</P
><P
-> In addition, the HAL provides generic device operations such as
+>
+ 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.
+
</P
><P
-> Finally, this specification is concerned with so called
+>
+ Finally, this specification is concerned with so called
<I
CLASS="emphasis"
>device information files</I
>.
- 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.
+
+ A device information file matches a subset of devices (from
+ properties derived from the physical bus the device is on or
+ what functionality the underlying kernel provides) and populates
+ them with other, often well-defined, properties.
+
+ Device information 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.
+
</P
><P
-> The HAL is built upon D-BUS which is a framework that, among other
+>
+ 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.
+
</P
><DIV
CLASS="sect2"
@@ -210,11 +226,11 @@
></TR
><TR
><TD
->0.3-beta</TD
+>0.2.95</TD
><TD
->July 21, 2004</TD
+> </TD
><TD
->Updated to reflect the state of the code.</TD
+>Current draft from CVS</TD
></TR
></TBODY
></TABLE
@@ -239,7 +255,7 @@
>
motivated this specification. This specification would not exist without
all the useful suggestions and comments on the Free Desktop mailing
- list.
+ list and the HAL mailing list.
</P
><P
@@ -266,32 +282,39 @@
>Architecture of HAL</A
></H3
><P
-> The HAL consists of a number of components as outlined in the diagram
+>
+ The HAL consists of a number of components as outlined in the diagram
below
+
</P
><P
> <IMG
SRC="hal-arch.png">
</P
><P
-> Detail on components
+>
+ Detail on components
+
<P
></P
><UL
><LI
><P
-> <I
+>
+ <I
CLASS="emphasis"
>HAL daemon</I
></P
><P
>
+
A system-wide daemon that maintains a persistent database of device
objects. It is also responsible for merging information from the
device info file repository and managing the life cycle of device
objects.
The HAL daemon also contains detection and monitoring code for
standard busses (PCI, USB etc.) and devices.
+
</P
></LI
><LI
@@ -313,11 +336,13 @@
</P
><P
-> Any program can be a HAL agent; all it means is that the program
+>
+ Any program can be a HAL agent; all it means is that the program
communicates with the HAL daemon using a specific interface.
Examples of use that come to mind are prototypes for supporting
new busses/devices, integration of existing device
detection/monitoring frameworks etc.
+
</P
></LI
><LI
@@ -328,24 +353,30 @@
></P
><P
>
+
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 operations
on devices using HAL objects.
+
</P
><P
-> In addition, this group include desktop environments such as
+>
+ In addition, this group include desktop environments such as
GNOME or KDE. Specifically, using HAL, desktop environments
may include system- or session-daemons enforcing certain
policies when the device database managed by the HAL daemon
changes.
+
</P
><P
-> Such policies may include starting a photo management
+>
+ 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 information about network
devices, mounting removable storage and so on.
+
</P
></LI
></UL
@@ -389,56 +420,72 @@
><UL
><LI
><P
-> Maintaining a live list of device objects that correspond to
+>
+ Maintaining a live list of device objects that correspond to
the list maintained by the operating system kernel. This
include bus specific information such as the PCI slot location
etc.
+
</P
></LI
><LI
><P
-> Merging class device information (derived from the hardware)
+>
+ Merging class device information (derived from the hardware)
into a device object. For example, for an USB mouse HAL will
merge well-defined properties describing the input-related
capabilities of the mouse (e.g. how many buttons etc.)
+
</P
><P
> As device classes are mostly related to the nature of the
device rather than operating system, HAL can still be OS
independent. For example, both the USB and PCI standards
discuss devices classes.
+
</P
></LI
><LI
><P
-> Merging information (produced by human beings) into a device
+>
+ Merging information (produced by human beings) into a device
from device information files. This allows applications to
think in terms of ''capabilities'' rather than relying on
device class information derived from the hardware.
+
</P
><P
-> For example, this allows PIM applications to define a
+>
+ For example, this allows PIM applications to define a
capability called 'pda', define properties that characterizes
different PDA's they happen to support in their PIM library,
and finally (either the PIM authors or the PDA vendors)
provide device information files describing the particular PDA
being plugged in.
+
</P
></LI
><LI
><P
-> Provide monitoring of detected devices in a non-intrusive way.
+>
+ Provide monitoring of detected devices in a non-intrusive way.
+
</P
></LI
><LI
><P
-> Provide space, such that applications can store data per device.
+>
+ Provide space, such that applications can store data per device
+ and per user.
+
</P
></LI
><LI
><P
-> Providing a simple to use query/notification API for use in
+>
+ Providing a simple to use query/notification API for use in
applications.
+
</P
></LI
></UL
@@ -451,21 +498,25 @@
><UL
><LI
><P
-> Device configuration; that is the task of loading an operating
+>
+ Device configuration; that is the task of loading an operating
system driver, uploading firmware, mounting a disk or
configure/initiate a network connection. It should be noted,
though, that HAL provides excellent infrastructure for doing
some of these tasks in an operating system independent way.
+
</P
></LI
><LI
><P
-> Providing device-specific operations such as extracting
+>
+ Providing device-specific operations such as extracting
pictures from a digital camera. Naturally, there already
exists libraries and frameworks for dealing with hardware. The
motivation behind HAL is to get authors of said
libraries/frameworks to integrate HAL into their software (see
PIM example above).
+
</P
></LI
></UL
@@ -483,23 +534,29 @@
>Device Objects</A
></H2
><P
-> It is important to precisely define the term ''device object'' - it is
+>
+ It is important to precisely define the term ''device object'' - it is
actually intended to mean two things:
+
<P
></P
><UL
><LI
><P
-> A device as recognized by the USB, PCI etc. standards and treated as
+>
+ A device as recognized by the USB, PCI etc. standards and treated as
such by the operating system kernel and base OS.
+
</P
></LI
><LI
><P
-> Storage volumes - e.g. partitions on a storage device. While partitions
+>
+ 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.
+
</P
></LI
></UL
@@ -522,37 +579,47 @@
</P
><P
-> A device object consist of the following information
+>
+ A device object consist of the following information
+
<P
></P
><UL
><LI
><P
-> <I
+>
+ <I
CLASS="emphasis"
>Unique Device ID (referred to as the UDI in the
following)</I
></P
><P
>
+
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
+ is, no other device object can have the same UDI at the same time.
+ The UDI 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.
+ kind of device is plugged in. It is also independent of the
+ physical location of the device.
+
+
</P
></LI
><LI
><P
-> <I
+>
+ <I
CLASS="emphasis"
>Properties</I
></P
><P
>
+
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
+
<P
></P
><UL
@@ -562,7 +629,11 @@
></LI
><LI
><P
->int - 32-bit signed integer</P
+>int32 - 32-bit signed integer</P
+></LI
+><LI
+><P
+>int64 - 64-bit signed integer</P
></LI
><LI
><P
@@ -573,8 +644,13 @@
>double - IEEE754 double precision
floating point number</P
></LI
+><LI
+><P
+>array - A container where each element has one of the above types</P
+></LI
></UL
>
+
</P
></LI
></UL
@@ -653,7 +729,7 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN144"
+NAME="AEN148"
>D-BUS Network API</A
></H2
><P
@@ -691,7 +767,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN149"
+NAME="AEN153"
>Interface org.freedesktop.Hal.Manager</A
></H3
><P
@@ -792,7 +868,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN155"
+NAME="AEN159"
>Interface org.freedesktop.Hal.Device</A
></H3
><P
@@ -936,7 +1012,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN162"
+NAME="AEN166"
>Interface org.freedesktop.Hal.AgentManager</A
></H3
><P
@@ -1203,7 +1279,7 @@
><P
></P
><A
-NAME="AEN191"
+NAME="AEN195"
></A
><TABLE
BORDER="1"
@@ -1583,7 +1659,7 @@
><P
></P
><A
-NAME="AEN358"
+NAME="AEN362"
></A
><TABLE
BORDER="1"
@@ -1774,7 +1850,7 @@
><P
></P
><A
-NAME="AEN430"
+NAME="AEN434"
></A
><TABLE
BORDER="1"
@@ -1875,7 +1951,7 @@
><P
></P
><A
-NAME="AEN468"
+NAME="AEN472"
></A
><TABLE
BORDER="1"
@@ -2051,7 +2127,7 @@
><P
></P
><A
-NAME="AEN541"
+NAME="AEN545"
></A
><TABLE
BORDER="1"
@@ -2333,7 +2409,7 @@
><P
></P
><A
-NAME="AEN671"
+NAME="AEN675"
></A
><TABLE
BORDER="1"
@@ -2483,7 +2559,7 @@
><P
></P
><A
-NAME="AEN722"
+NAME="AEN726"
></A
><TABLE
BORDER="1"
@@ -2527,7 +2603,7 @@
><P
></P
><A
-NAME="AEN737"
+NAME="AEN741"
></A
><TABLE
BORDER="1"
@@ -2612,7 +2688,7 @@
><P
></P
><A
-NAME="AEN763"
+NAME="AEN767"
></A
><TABLE
BORDER="1"
@@ -3214,7 +3290,7 @@
><P
></P
><A
-NAME="AEN1046"
+NAME="AEN1050"
></A
><TABLE
BORDER="1"
@@ -3369,7 +3445,7 @@
><P
></P
><A
-NAME="AEN1109"
+NAME="AEN1113"
></A
><TABLE
BORDER="1"
@@ -3444,7 +3520,7 @@
><P
></P
><A
-NAME="AEN1139"
+NAME="AEN1143"
></A
><TABLE
BORDER="1"
Index: hal-spec.xml.in
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.xml.in,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- hal-spec.xml.in 21 Jul 2004 23:07:45 -0000 1.1
+++ hal-spec.xml.in 29 Jul 2004 17:07:08 -0000 1.2
@@ -26,47 +26,63 @@
<sect1 id="introduction">
<title>Introduction</title>
<para>
+
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.
+
</para>
<para>
+
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.
+
</para>
<para>
+
For instance, the <emphasis>info.category</emphasis> property specifies
what the device is (such as a digital camera or an audio device), and the
<emphasis>block.mount_point</emphasis> property
specifies where in the filesystem a storage device is mounted.
+
</para>
<para>
+
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.
+
</para>
<para>
+
Finally, this specification is concerned with so called
<emphasis>device information files</emphasis>.
- 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.
+
+ A device information file matches a subset of devices (from
+ properties derived from the physical bus the device is on or
+ what functionality the underlying kernel provides) and populates
+ them with other, often well-defined, properties.
+
+ Device information 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.
+
</para>
<para>
+
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.
+
</para>
<sect2>
@@ -93,9 +109,9 @@
<entry>A major rewrite.</entry>
</row>
<row>
- <entry>0.3-beta</entry>
- <entry>July 21, 2004</entry>
- <entry>Updated to reflect the state of the code.</entry>
+ <entry>@VERSION@</entry>
+ <entry></entry>
+ <entry>Current draft from CVS</entry>
</row>
</tbody>
</tgroup>
@@ -109,7 +125,7 @@
<ulink url="http://www.ometer.com/hardware.html">"Making Hardware Just Work"</ulink>
motivated this specification. This specification would not exist without
all the useful suggestions and comments on the Free Desktop mailing
- list.
+ list and the HAL mailing list.
</para><para>
@@ -124,24 +140,31 @@
<sect2 id="ov_halarch"><title>Architecture of HAL</title>
<para>
+
The HAL consists of a number of components as outlined in the diagram
below
+
</para>
<para>
<inlinegraphic fileref="hal-arch.png" format="PNG"/>
</para>
<para>
+
Detail on components
+
<itemizedlist>
<listitem><para>
+
<emphasis>HAL daemon</emphasis></para><para>
+
A system-wide daemon that maintains a persistent database of device
objects. It is also responsible for merging information from the
device info file repository and managing the life cycle of device
objects.
The HAL daemon also contains detection and monitoring code for
standard busses (PCI, USB etc.) and devices.
+
</para></listitem>
<listitem><para>
@@ -153,31 +176,39 @@
daemon.
</para><para>
+
Any program can be a HAL agent; all it means is that the program
communicates with the HAL daemon using a specific interface.
Examples of use that come to mind are prototypes for supporting
new busses/devices, integration of existing device
detection/monitoring frameworks etc.
+
</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 operations
on devices using HAL objects.
+
</para><para>
+
In addition, this group include desktop environments such as
GNOME or KDE. Specifically, using HAL, desktop environments
may include system- or session-daemons enforcing certain
policies when the device database managed by the HAL daemon
changes.
+
</para><para>
+
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 information about network
devices, mounting removable storage and so on.
+
</para></listitem>
</itemizedlist>
@@ -209,80 +240,89 @@
concerned with
<itemizedlist>
-
<listitem><para>
+
Maintaining a live list of device objects that correspond to
the list maintained by the operating system kernel. This
include bus specific information such as the PCI slot location
etc.
- </para></listitem>
+ </para></listitem>
<listitem><para>
+
Merging class device information (derived from the hardware)
into a device object. For example, for an USB mouse HAL will
merge well-defined properties describing the input-related
capabilities of the mouse (e.g. how many buttons etc.)
+
</para><para>
As device classes are mostly related to the nature of the
device rather than operating system, HAL can still be OS
independent. For example, both the USB and PCI standards
discuss devices classes.
- </para></listitem>
+ </para></listitem>
<listitem><para>
+
Merging information (produced by human beings) into a device
from device information files. This allows applications to
think in terms of ''capabilities'' rather than relying on
device class information derived from the hardware.
+
</para><para>
+
For example, this allows PIM applications to define a
capability called 'pda', define properties that characterizes
different PDA's they happen to support in their PIM library,
and finally (either the PIM authors or the PDA vendors)
provide device information files describing the particular PDA
being plugged in.
- </para></listitem>
+ </para></listitem>
<listitem><para>
+
Provide monitoring of detected devices in a non-intrusive way.
- </para></listitem>
- <listitem><para>
- Provide space, such that applications can store data per device.
</para></listitem>
+ <listitem><para>
+
+ Provide space, such that applications can store data per device
+ and per user.
+ </para></listitem>
<listitem><para>
+
Providing a simple to use query/notification API for use in
applications.
- </para></listitem>
+ </para></listitem>
</itemizedlist>
HAL is not concerned with
<itemizedlist>
-
<listitem><para>
+
Device configuration; that is the task of loading an operating
system driver, uploading firmware, mounting a disk or
configure/initiate a network connection. It should be noted,
though, that HAL provides excellent infrastructure for doing
some of these tasks in an operating system independent way.
- </para></listitem>
+ </para></listitem>
<listitem><para>
+
Providing device-specific operations such as extracting
pictures from a digital camera. Naturally, there already
exists libraries and frameworks for dealing with hardware. The
motivation behind HAL is to get authors of said
libraries/frameworks to integrate HAL into their software (see
PIM example above).
- </para></listitem>
+ </para></listitem>
</itemizedlist>
</para>
-
</sect2>
</sect1>
@@ -290,18 +330,24 @@
<sect1>
<title>Device Objects</title>
<para>
+
It is important to precisely define the term ''device object'' - it is
actually intended to mean two things:
+
<itemizedlist>
<listitem><para>
+
A device as recognized by the USB, PCI etc. standards and treated as
such by the operating system kernel and base OS.
+
</para></listitem>
<listitem><para>
+
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.
+
</para></listitem>
</itemizedlist>
@@ -320,29 +366,42 @@
constituting what users normally understand as a single device.
</para><para>
+
A device object consist of the following information
+
<itemizedlist>
<listitem><para>
+
<emphasis>Unique Device ID (referred to as the UDI in the
following)</emphasis></para><para>
+
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
+ is, no other device object can have the same UDI at the same time.
+ The UDI 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.
+ kind of device is plugged in. It is also independent of the
+ physical location of the device.
+
+
</para></listitem>
<listitem><para>
+
<emphasis>Properties</emphasis></para><para>
+
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
+
<itemizedlist>
<listitem><para>string - UTF8 string</para></listitem>
- <listitem><para>int - 32-bit signed integer</para></listitem>
+ <listitem><para>int32 - 32-bit signed integer</para></listitem>
+ <listitem><para>int64 - 64-bit signed integer</para></listitem>
<listitem><para>bool - truth value</para></listitem>
<listitem><para>double - IEEE754 double precision
floating point number</para></listitem>
+ <listitem><para>array - A container where each element has one of the above types</para></listitem>
</itemizedlist>
+
</para></listitem>
</itemizedlist>
More information about the hal-commit
mailing list