hal: Branch 'master' - 2 commits
David Zeuthen
david at kemper.freedesktop.org
Sun Mar 25 18:22:59 PDT 2007
doc/spec/Makefile.am | 5 -
doc/spec/hal-spec-interfaces.xml | 54 +++++++++----
doc/spec/hal-spec-locking.xml | 160 +++++++++++++++++++++++++++++++++++++++
doc/spec/hal-spec.xml.in | 3
4 files changed, 206 insertions(+), 16 deletions(-)
New commits:
diff-tree ecc0342a2ebca8b1c5fa802385c8721feee7ada6 (from efb4c3a5722d59d2635cbac055087f8418f791b4)
Author: David Zeuthen <davidz at redhat.com>
Date: Sun Mar 25 21:22:59 2007 -0400
fixup speling
diff --git a/doc/spec/hal-spec-locking.xml b/doc/spec/hal-spec-locking.xml
index a7ddcef..443ac48 100644
--- a/doc/spec/hal-spec-locking.xml
+++ b/doc/spec/hal-spec-locking.xml
@@ -21,13 +21,13 @@
Further, for multi-user systems, several desktop sessions may run
on a system each on their own display. Suppose that one session
becomes idle and the power management daemon in that session
- decides to suspend the suspend according to user preferences. Then
- users at other seats will see the system suspend and this is not
- desirable. The power management daemons need to cooperate to
- ensure that the system only suspends when e.g. all sessions are
- idle or not at all. The mechanism that each power management
- daemon uses, HAL, provides locking primitives that can be used to
- achieve this.
+ decides to suspend the system according to user preferences in the
+ idle session. The result is that users at other seats will see the
+ system suspend and this is not desirable. The power management
+ daemons in all sessions need to cooperate to ensure that the
+ system only suspends when e.g. all sessions are idle or not at
+ all. The mechanism that each power management daemon uses, HAL,
+ provides locking primitives that can be used to achieve this.
</para>
<sect1 id="locking-overview">
diff-tree efb4c3a5722d59d2635cbac055087f8418f791b4 (from 16a87091fc6da9190feae9e19d4eb99165d5328c)
Author: David Zeuthen <davidz at redhat.com>
Date: Sun Mar 25 21:11:56 2007 -0400
add docs for how locking work
diff --git a/doc/spec/Makefile.am b/doc/spec/Makefile.am
index 3e49ecd..cf909a2 100644
--- a/doc/spec/Makefile.am
+++ b/doc/spec/Makefile.am
@@ -4,10 +4,11 @@ FIGURE_FILES = \
hal-devices1.png
SPEC_XML_EXTRA_FILES = \
- hal-spec-interfaces.xml \
hal-spec-introduction.xml \
hal-spec-fdi-files.xml \
- hal-spec-properties.xml
+ hal-spec-properties.xml \
+ hal-spec-locking.xml \
+ hal-spec-interfaces.xml
if DOCBOOK_DOCS_ENABLED
diff --git a/doc/spec/hal-spec-interfaces.xml b/doc/spec/hal-spec-interfaces.xml
index 7057e58..6bf5fce 100644
--- a/doc/spec/hal-spec-interfaces.xml
+++ b/doc/spec/hal-spec-interfaces.xml
@@ -19,7 +19,11 @@ $ dbus-send --system --print-reply --des
supports. For brevity, the <literal>org.freedesktop.Hal</literal>
prefix have been stripped from the exceptions listed in the
following sections. Also note that other exceptions than the ones
- listed may be thrown.
+ listed may be thrown; for example
+ the <literal>org.freedesktop.Hal.Device.InterfaceLocked</literal>
+ exception may be thrown regardless of how the interface is
+ implemented depending on if some other process is holding a lock
+ on the device cf. <xref linkend="locking"/>.
</para>
<sect1 id="interface-manager">
@@ -375,26 +379,37 @@ $ dbus-send --system --print-reply --des
</row>
<row>
- <entry>AcquireMandatoryLock</entry>
+ <entry>AcquireInterfaceLock</entry>
<entry></entry>
- <entry>String lock_name</entry>
- <entry>PermissionDenied, DeviceAlreadyLocked</entry>
+ <entry>String interface_name, Bool exclusive</entry>
+ <entry>PermissionDenied, Device.InterfaceAlreadyLocked</entry>
<entry>
- Acquires a named mandatory lock. The lock is recursive
- (multiple callers may hold the lock). See TODO for how
- mandatory locks work.
+ Acquires a lock on an interface for a specific
+ device. See <xref linkend="locking"/> for details.
</entry>
</row>
<row>
- <entry>ReleaseMandatoryLock</entry>
+ <entry>ReleaseInterfaceLock</entry>
<entry></entry>
- <entry>String lock_name</entry>
- <entry>PermissionDenied, DeviceNotLocked</entry>
+ <entry>String interface_name</entry>
+ <entry>PermissionDenied, Device.InterfaceNotLocked</entry>
<entry>
- Releases a named mandatory lock. The lock is recursive
- (multiple callers may hold the lock). See TODO for how
- mandatory locks work.
+ Releases a lock on an interface for a specific device. See
+ <xref linkend="locking"/> for details.
+ </entry>
+ </row>
+
+ <row>
+ <entry>IsCallerLockedOut</entry>
+ <entry>Bool</entry>
+ <entry>String interface_name, String caller_unique_name</entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Determines whether a given process on the system message
+ bus is locked out from an interface on a specific
+ device. Only HAL helpers are privileged to use this
+ method. See <xref linkend="locking"/> for details.
</entry>
</row>
@@ -986,6 +1001,19 @@ $ dbus-send --system --print-reply --des
<para>
This interface does not emit any signals.
</para>
+
+ <para>
+ If a volume originates from a storage device (and all volumes
+ do), it also is checked whether the caller is locked out of the
+ <literal>org.freedesktop.Hal.Device.Storage</literal> 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 <literal>org.freedesktop.Hal.Device.Storage</literal>
+ interface if one wants to lock out callers from mounting
+ volumes from either a specific drive or all drives.
+
+ </para>
</sect1>
<sect1 id="interface-device-volume-crypto">
diff --git a/doc/spec/hal-spec-locking.xml b/doc/spec/hal-spec-locking.xml
new file mode 100644
index 0000000..a7ddcef
--- /dev/null
+++ b/doc/spec/hal-spec-locking.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!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="locking">
+ <title>Locking</title>
+
+ <para>
+ As HAL enables programs in a desktop session to automatically
+ enforce the policy of the users choice, unexpected things can
+ happen. For example, if the user is in the middle of partitioning
+ a disk drive, it is desirable to keep the desktop from mounting
+ partitions that have not yet been prepared with a suitable file
+ system. In fact, in such a situation data loss may be the result
+ if a volume have an old file system signature indicating it's
+ mountable and, simultenously, another tool is writing to the raw
+ block device. The mechanism that automounters use, HAL, provides
+ locking primitives to avoid this.
+ </para>
+
+ <para>
+ Further, for multi-user systems, several desktop sessions may run
+ on a system each on their own display. Suppose that one session
+ becomes idle and the power management daemon in that session
+ decides to suspend the suspend according to user preferences. Then
+ users at other seats will see the system suspend and this is not
+ desirable. The power management daemons need to cooperate to
+ ensure that the system only suspends when e.g. all sessions are
+ idle or not at all. The mechanism that each power management
+ daemon uses, HAL, provides locking primitives that can be used to
+ achieve this.
+ </para>
+
+ <sect1 id="locking-overview">
+ <title>Overview</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ The former is achieved by using
+ the <literal>AcquireInterfaceLock()</literal>
+ and <literal>ReleaseInterfaceLock()</literal> methods on
+ the <literal>org.freedesktop.Hal.Device</literal> interface that
+ every device object implements (see
+ <xref linkend="interface-device"/>). 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 <literal>org.freedesktop.Hal.Device.InterfaceLocked</literal>
+ exception if they attempt to invoke a method on the given
+ interface on the given device. The locker can specify whether
+ the lock is <emphasis>exclusive</emphasis> 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 a device,
+ attempts to lock will fail with
+ a <literal>org.freedesktop.Hal.PermissionDenied</literal>
+ exception. If another client already holds the lock exclusively,
+ attempts from other clients to acquire the lock will fail with
+ the <literal>org.freedesktop.Hal.Device.InterfaceAlreadyLocked</literal>
+ exception even if they have access to the device.
+ </para>
+
+ <para>
+ In addition, a client may opt to lock all devices that he got
+ access to by using
+ the <literal>AcquireGlobalInterfaceLock()</literal>
+ and <literal>ReleaseGlobalInterfaceLock()</literal> methods on
+ the <literal>org.freedesktop.Hal.Manager</literal> interface on
+ the <literal>/org/freedesktop/Hal/Manager</literal> object (see
+ <xref linkend="interface-manager"/>). 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.
+ </para>
+
+ <para>
+ The algorithm used for determining if a caller is locked out is
+ shown below. A caller is locked out if:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ another caller is holding a lock on the interface on the
+ device (non-withstanding that the caller to check for holds
+ the lock himself).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Another caller is holding the global lock for the interface
+ and that other caller has access to the device in question.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ In other words, a client Foo can grab a global lock, but that
+ doesn't mean Foo can lock other clients out of devices that Foo
+ doesn't have access to. Specifically a caller is not locked out
+ if he has locked an interface and he is the only one holding the
+ lock. However, if two clients have a lock on a device neither of
+ them can access the device.
+ </para>
+
+ <para>
+ 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 <xref linkend="interfaces"/>.
+ </para>
+
+ <para>
+ If a process holding locks disconnects from the system bus, the
+ locks being held by that process will be released.
+ </para>
+ </sect1>
+
+ <sect1 id="locking-guidelines">
+ <title>Guidelines</title>
+ <para>
+ 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.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Disk Management / Partitioning</emphasis>
+ </para>
+ <para>
+ In order to prevent HAL-based automounters from mounting
+ partitions that are being prepared, applications that access
+ block devices directly (and pokes the kernel to reload the
+ partitioning table) should lock out automounters by either
+ a) obtaining
+ the <literal>org.freedesktop.Hal.Device.Storage</literal> on
+ each drive being processed; or b) obtaintaing the global
+ <literal>org.freedesktop.Hal.Device.Storage</literal>
+ lock. This includes programs like fdisk, gparted, parted and
+ operating system installers. See also
+ <xref linkend="interface-device-volume"/>.
+ </para>
+ </listitem>
+
+ <listitem><para>
+ <emphasis>System-wide Power Management</emphasis>
+ </para>
+ <para>
+ (this guideline is not finalized!)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+</chapter>
+
diff --git a/doc/spec/hal-spec.xml.in b/doc/spec/hal-spec.xml.in
index dc94ad0..acc0d40 100644
--- a/doc/spec/hal-spec.xml.in
+++ b/doc/spec/hal-spec.xml.in
@@ -12,7 +12,7 @@
<surname>Zeuthen</surname>
<affiliation>
<address>
- <email>david at fubar.dk</email>
+ <email>david at fubar.dk</email>
</address>
</affiliation>
</author>
@@ -22,6 +22,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-introduction.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-properties.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-fdi-files.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-locking.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-interfaces.xml" />
</book>
More information about the hal-commit
mailing list