[ohm] ohm: Branch 'master' - 3 commits
Rob Taylor
robtaylor at kemper.freedesktop.org
Mon Sep 3 06:10:09 PDT 2007
autogen.sh | 6
docs/Makefile.am | 1
docs/index.html | 500 -------------------------------------------------------
3 files changed, 4 insertions(+), 503 deletions(-)
New commits:
diff-tree b5f76d26d2e94f9279b03b56aaf20038cd853cdd (from 2c39d1f89fc8d7cbeb7b676525349d3bdf53dbda)
Author: Rob Taylor <rob.taylor at codethink.co.uk>
Date: Mon Sep 3 11:46:06 2007 +0100
add missing ohm-logo-small.png to EXTRA_DIST
Add missing ohm-logo-small.png to EXTRA_DIST.
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 8c0a548..c3d3800 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -3,6 +3,7 @@ SUBDIRS = reference
IMAGE_FILES = \
ohm-logo.png \
ohm-logo.svg \
+ ohm-logo-small.png \
ohm-dbus-access.png \
ohm-dbus-access.svg \
ohm-structure.png \
diff-tree 2c39d1f89fc8d7cbeb7b676525349d3bdf53dbda (from 851bc4ec7d1d29b9671293a73c3c3aa3a8ad7c93)
Author: Rob Taylor <rob.taylor at codethink.co.uk>
Date: Mon Sep 3 11:45:22 2007 +0100
install automake, libtoolize and gtkdocize files with copy
Install automake, libtoolize and gtkdocize files with copy rather than symlink.
This is for supporting debian package building from a branch off master.
diff --git a/autogen.sh b/autogen.sh
index 1a0b417..f2a6f64 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -19,13 +19,13 @@ echo "Running $AUTOCONF..."
$AUTOCONF || exit 1
echo "Running $LIBTOOLIZE --automake..."
-$LIBTOOLIZE --automake || exit 1
+$LIBTOOLIZE --automake -c || exit 1
echo "Running gtkdocize..."
-gtkdocize || exit 1
+gtkdocize --copy || exit 1
echo "Running $AUTOMAKE..."
-$AUTOMAKE -a || exit 1
+$AUTOMAKE -a -c || exit 1
$AUTOMAKE -a ohmd/Makefile || exit 1
diff-tree 851bc4ec7d1d29b9671293a73c3c3aa3a8ad7c93 (from 466fc27d87f05fec747dbdffcfd7ecf0c06c54fd)
Author: Rob Taylor <rob.taylor at codethink.co.uk>
Date: Thu Aug 30 16:09:12 2007 +0100
docs/index.html should not be in the repo.
Removes docs/index.html, which is a generated file.
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index 792b9ef..0000000
--- a/docs/index.html
+++ /dev/null
@@ -1,500 +0,0 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Open Hardware Manager 0.1.1 Documentation</title><link rel="stylesheet" href="docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><meta name="description" content='Executive Summary OHM is a small open source systems daemon which sits above HAL and abstracts out common hardware management tasks such as system wide inhibit action control and controlling heat dissipation on embedded devices. OHM is built using a lightweight plugin architecture. Each plugin can query data from HAL or execute methods on HAL devices and expose preferences for session programs to modify. OHM is product and vendor neutral and is currently being developed by a small team of developers. OHM : "Resistance is futile"'></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="index"></a>Open Hardware Manager 0.1.1 Documentation</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Hughes</span></h3><div class="affiliation"><div class="address"><p><br>
- <code class="email"><<a href="mailto:richard at hughsie.com">richard at hughsie.com</a>></code><br>
- </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.1.1</p></div><div><div class="abstract"><p class="title"><b>Executive Summary</b></p><p>
- OHM is a small open source systems daemon which sits above HAL and
- abstracts out common hardware management tasks such as system wide
- inhibit action control and controlling heat dissipation on embedded
- devices.
- OHM is built using a lightweight plugin architecture.
- Each plugin can query data from HAL or execute methods on HAL devices
- and expose preferences for session programs to modify.
- OHM is product and vendor neutral and is currently being developed by
- a small team of developers.
- </p><p>
- OHM : <span class="emphasis"><em>"Resistance is futile"</em></span>
- </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#introduction">1. Open Hardware Manager Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="#introduction-description">Overall Description</a></span></dt><dt><span class="sect1"><a href="#introduction-usecases">Use Cases</a></span></dt><dd><dl><dt><span class="sect2"><a href="#introduction-usecases-embedded">Embedded use cases</a></span></dt><dt><span class="sect2"><a href="#introduction-usecases-pc">Desktop or laptop use cases</a></span></dt></dl></dd><dt><span class="sect1"><a href="#introduction-core">OHM Core Values</a></span></dt><dt><span class="sect1"><a href="#introduction-deps">Dependencies</a></span></dt></dl></dd><dt><span class="chapter"><a href="#plugins">2. Plugins</a></span></dt><dd><dl><dt><span class="sect1"><a href="#plugins-introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#plugins-key-defaults">Plugin Key Defaults</a></span></dt><dt><span class="sect2"><a href="#plugins-system-start">System Start</a></span></dt><dt><span class="sect2"><a href="#plugins-other-plugins">Plugin Dependencies</a></span></dt><dt><span class="sect2"><a href="#plugins-acccess-to-keys">Plugin access to keys</a></span></dt><dt><span class="sect2"><a href="#plugins-session-access">Session Access to keys</a></span></dt></dl></dd><dt><span class="sect1"><a href="#plugins-defaults">Default plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="#plugins-backlight">Backlight Adjustment</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#dbus-interface">3. DBUS Interface</a></span></dt><dd><dl><dt><span class="sect1"><a href="#pm-intro">Introduction</a></span></dt><dt><span class="sect1"><a href="#pm-manager">Manager functionality</a></span></dt><dd><dl><dt><span class="sect2"><a href="#pm-manager-keys">
- <code class="literal">Exported keys</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-manager-GetVersion">
- <code class="literal">GetVersion()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-manager-GetPlugins">
- <code class="literal">GetPlugins()</code>
- </a></span></dt></dl></dd><dt><span class="sect1"><a href="#pm-keystore">Keystore functionality</a></span></dt><dd><dl><dt><span class="sect2"><a href="#pm-keystore-GetKey">
- <code class="literal">GetKey()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-keystore-SetKey">
- <code class="literal">SetKey()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-keystore-AddNotifyKey">
- <code class="literal">AddNotifyKey()</code>
- </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#faq">4. Frequently Asked Questions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#faq-sessionpolicy">
- How does OHM fit in with other session policy agents?
- </a></span></dt><dt><span class="sect1"><a href="#faq-specificdevice">
- Why not just do a specific device hack for all the different
- embedded hardware?
- </a></span></dt><dt><span class="sect1"><a href="#faq-lgpl">
- So it's LGPL... does that mean some of the code is closed source?
- </a></span></dt><dt><span class="sect1"><a href="#faq-installcode">
- Can I install the latest stable code?
- </a></span></dt><dt><span class="sect1"><a href="#faq-releasedate">
- What is the release date plan for OHM?
- </a></span></dt><dt><span class="sect1"><a href="#faq-systemprefs">
- Do you need to use system GConf for the system preferences?
- </a></span></dt><dt><span class="sect1"><a href="#faq-noxml">
- Is OHM using XML to define the policy rules?
- </a></span></dt><dt><span class="sect1"><a href="#faq-whysessionlayer">
- Why include a session layer for embedded appliances?
- </a></span></dt><dt><span class="sect1"><a href="#faq-whysinglehash">
- Why are all the keys exposed in a single hash table?
- </a></span></dt><dt><span class="sect1"><a href="#faq-restartdeps">
- Will OHM break if I restart <code class="literal">messagebus</code> or
- <code class="literal">hald</code>?
- </a></span></dt><dt><span class="sect1"><a href="#faq-shellscripts">
- Can I execute shell scripts from OHM on an event?
- </a></span></dt></dl></dd></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Open Hardware Manager Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction-description">Overall Description</a></span></dt><dt><span class="sect1"><a href="#introduction-usecases">Use Cases</a></span></dt><dd><dl><dt><span class="sect2"><a href="#introduction-usecases-embedded">Embedded use cases</a></span></dt><dt><span class="sect2"><a href="#introduction-usecases-pc">Desktop or laptop use cases</a></span></dt></dl></dd><dt><span class="sect1"><a href="#introduction-core">OHM Core Values</a></span></dt><dt><span class="sect1"><a href="#introduction-deps">Dependencies</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-description"></a>Overall Description</h2></div></div></div><p>
- OHM is a small open source systems daemon which sits above HAL and
- abstracts out common hardware management tasks such as:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- System wide power management statistics (for instance calculating
- hysteresis of battery curves).
- </p></li><li><p>
- Managing system wide inhibit actions, for instance system
- firmware updating.
- </p></li><li><p>
- Controlling heat dissipation on embedded and PC devices.
- </p></li></ul></div><p>
- OHM is built using a plugin architecture with a low-overhead messaging
- structure.
- This gives a very configurable base system that can be configured in many
- different ways.
- Each plugin can query data from HAL or execute methods on HAL devices and
- expose preferences interfaces for session-space to use.
- </p><div class="mediaobject" align="center"><a name="ohm-structure"></a><img src="ohm-structure.png" align="middle"></div><p>
- OHM is LGPL licensed to allow proprietary licensed plug-ins to be used
- where absolutely required.
- It is also uses the minimum of memory and processor requirement to fulfill
- the task.
- This makes it suitable for use on the latest smart-phones, the OLPC device
- or any other embedded products such as set top boxes.
- </p><p>
- HAL has traditionally been seen too heavyweight for use on an embedded device.
- While this was once true, there have been very many developers working on
- adding conditional compilation to parts of HAL, and to reduce memory usage.
- This can be seen with the startup speed of 0.5.9 being 40% than of 0.5.8.
- Context switching has been reduced, and memory pressure on coldplug has been
- reduced for devices with a small amount of devices.
- It is expected that <code class="literal">hald</code> will start in the few hundred
- millisecond range and consume less than half a megabyte of RAM at coldplug.
- </p><p>
- Using HAL allows us to use a common framework for hardware management,
- which means plugins designed for one architecture or chip will work on
- any other system.
- Working together is the best way to get high quality, maintainable code
- rather than all the hacky systems we have now.
- </p><div class="mediaobject" align="center"><a name="ohm-sessions"></a><img src="ohm-sessions.png" align="middle"></div><p>
- Proof of concept code is available on the project page.
- There are no tarball releases yet, checking out using git is the best
- option.
- </p><p>
- OHM comprises:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- The <code class="literal">ohmd</code> system daemon which co-ordinates the
- rules and acts as a keystore for multiple users.
- </p></li><li><p>
- The interface specification which outlines core
- <code class="literal">ohmd</code> functionality.
- </p></li><li><p>
- A method for plugins to request notification when keys change, for
- example when the system AC state is changed.
- </p></li><li><p>
- The test suite which tests functionality.
- </p></li></ul></div><p>
- OHM is very suitable for embedded devices that need to manage power, heat
- and other critical tasks early in the boot sequence.
- Using HAL, it provides an abstract method for all plugins to be written in
- a generic way, not tied to the specific implementation of the device.
- </p><p>
- A library called <code class="literal">libohm</code> allows system and session
- programs to easily interface with <code class="literal">ohmd</code>.
- This library will remove the implementation detail from session software.
- This library, like the rest of OHM will not be API or ABI stable until
- version 1.0.0 is released.
- </p><p>
- What OHM is not:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- A power saving daemon.
- It is not doing power saving specifically, it is just doing device
- specific rules that manage power and heat dissipation and other
- hardware specific stuff.
- </p></li><li><p>
- An abstraction of HAL. HAL acts as the input and the output of OHM,
- and OHM enforces policy for HAL.
- </p></li><li><p>
- A huge daemon with lots of dependencies.
- </p></li><li><p>
- API or ABI stable. Expect the ABI and API to change on a regular
- basis until we ship 1.0.0.
- </p></li><li><p>
- Targeted to a particular architecture or platform.
- </p></li><li><p>
- Produced by any one vendor.
- There are many contributors helping to get this done.
- </p></li></ul></div><p>
- Why not do everything in a session daemon?:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- Sometimes we need to start very early in the boot sequence.
- </p></li><li><p>
- We don't want to die if X dies.
- </p></li><li><p>
- On a server with 100 logged in users we don't want an instance for
- each user.
- </p></li><li><p>
- We need to apply policy at boot-up or before X starts.
- </p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-usecases"></a>Use Cases</h2></div></div></div><p>
- Use cases should aim to be small specific problems that OHM should solve.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="introduction-usecases-embedded"></a>Embedded use cases</h3></div></div></div><p>
- A video player is started and requests processor core low latancy
- behaviour from the OHM CPU plugin.
- The CPU plugin approves an increase in CPU speed as battery level is
- not low.
- The heat management plugin reads that processor core is nearly out of
- operating temperature range, and denies the request.
- </p><p>
- In the lastest temperature probe readings, the heat management plugin
- notices that the board temperature over the battery is getting too hot,
- so requests a overal drop in power consumption from the other plugins.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="introduction-usecases-pc"></a>Desktop or laptop use cases</h3></div></div></div><p>
- Alice is logged in and starts a distribution upgrade and walks away,
- and the screen saver starts.
- Bob fast-user-switches to his account, does some work and clicks shutdown.
- At the moment the machine will suspend in middle of distribution upgrade.
- The desired behaviour would be for the managament system to inhibit the
- suspend until it is finished.
- When Bob tries to suspend, he should be informed that the dist-upgrade
- (by Alice) is in process and the suspend could not be done at this time
- and possibly be offered the option to suspend when it has.
- </p><p>
- Bob is logged in and starts a large download, the browser makes request
- to OHM that the machine is not shutdown for the duration of the download.
- Alice fast-user-switches to her account, does some stuff and clicks shutdown.
- Alice is informed that Bob is in the process of a large download, howver
- as she has admin rights she can override Bob's request and shut the
- machine down.
- </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-core"></a>OHM Core Values</h2></div></div></div><p>
- The OHM daemon with all management modules suitable for the platform loaded should:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- not have a binary size of over 200k in size
- </p></li><li><p>
- start in less than 200ms on 100MHz ARM
- </p></li><li><p>
- use less than 200k of private memory
- </p></li><li><p>
- be platform neutral, i.e. use HAL wherever possible
- </p></li><li><p>
- be plug-able so proprietary code can be used where required.
- </p></li><li><p>
- be simple to change preferences for the session
- </p></li><li><p>
- be secure so system policy cannot be changed
- </p></li><li><p>
- be session-aware so that multiple users can be active
- </p></li><li><p>
- not rely on any odd toolkits or high level programming frameworks
- </p></li><li><p>
- be efficient enough to do complex rule processing with minimum CPU load
- </p></li><li><p>
- be bug free and have no memory leaks so the daemon will never crash
- </p></li><li><p>
- be an open and supported project, rather than a quick custom hack
- </p></li><li><p>
- integrate well with modern desktops like GNOME where required
- </p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-deps"></a>Dependencies</h2></div></div></div><p>
- OHM is lightweight.
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- GLib 2.10.0 (required)
- </p></li><li><p>
- DBUS 0.70 (required)
- </p></li><li><p>
- HAL 0.5.8 (required)
- </p></li><li><p>
- PolicyKit (optional)
- </p></li><li><p>
- ConsoleKit (optional)
- </p></li></ul></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="plugins"></a>Chapter 2. Plugins</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#plugins-introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#plugins-key-defaults">Plugin Key Defaults</a></span></dt><dt><span class="sect2"><a href="#plugins-system-start">System Start</a></span></dt><dt><span class="sect2"><a href="#plugins-other-plugins">Plugin Dependencies</a></span></dt><dt><span class="sect2"><a href="#plugins-acccess-to-keys">Plugin access to keys</a></span></dt><dt><span class="sect2"><a href="#plugins-session-access">Session Access to keys</a></span></dt></dl></dd><dt><span class="sect1"><a href="#plugins-defaults">Default plugins</a></span></dt><dd><dl><dt><span class="sect2"><a href="#plugins-backlight">Backlight Adjustment</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="plugins-introduction"></a>Introduction</h2></div></div></div><p>
- Plugins are external modules that are loaded at runtime.
- Plugins have preference data and internal state known as keys and policy,
- and also install a default system preferences file.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-key-defaults"></a>Plugin Key Defaults</h3></div></div></div><p>
- We need to set system preferences when there is no user logged in or we
- are very early in the boot sequence.
- We do this with each plugin installing a text file with the plugin key
- name, the value, and if the key is modifiable from the user sesison.
- </p><p>
- The plugin preferences are read from <code class="filename">/etc/ohm/plugins/{name}</code>
- Comments are lines with first character <code class="literal">#</code> and then the
- rest of the line is ignored.
- Files are flat text with the following formal description,
- <code class="literal">plugin_prefix.key value public</code>
- There is a single space between the values, and all values are signed ints.
- By making a key public, all the session users are allowed to change the
- preference value, for instance the brightness on AC.
- If a key is private then the public keyword is omitted, and any attempt
- to change the key from the session will fail.
- </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
- The public and private key concept is a way to enforce fine-grained
- specific system policy on users when using PolicyKit rules for every
- action would be too great an overhead.
- </p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
- Do not set internal state keys with their initial value here.
- These should be added using <code class="literal">ohm_plugin_conf_provide()</code>
- during <code class="literal">load()</code> and then the values populated in the
- <code class="literal">coldplug()</code> method.
- This ensures the correct ordering of coldplug.
- </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-system-start"></a>System Start</h3></div></div></div><p>
- The file <code class="filename">/etc/ohm/modules.ini</code> allows the system
- builder to set the modules to be loaded at startup.
- For instance, on a fast PC we may want to suggest different modules
- to a embedded ARM.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-other-plugins"></a>Plugin Dependencies</h3></div></div></div><p>
- Plugins can tell <code class="literal">ohmd</code> that other plugins are required
- for certain functionality, for instance, the backlight unit on a mobile
- phone may require the temperature module to be present, so it can do the
- temperature shutdown checks.
- This is done with <code class="literal">ohm_plugin_require()</code>.
- <code class="literal">ohmd</code> daemon will fail to load if any required plugin
- is not present after the plugins have finished initializing.
- </p><p>
- Plugins can also tell <code class="literal">ohmd</code> that other plugins are suggested for certain
- functionality, for instance, the backlight unit may work best when the
- battery plugin is loaded so we can dim when we are low on power.
- This is done with <code class="literal">ohm_plugin_suggest()</code>.
- <code class="literal">ohmd</code> daemon will print a message to the console if any
- suggested plugin is not present.
- </p><p>
- Plugins can also tell <code class="literal">ohmd</code> that other plugins are
- banned, for instance, a proprietary battery discharge plugin maybe
- incompatible with the standard battery plugin.
- This is done with <code class="literal">ohm_plugin_prevent()</code>.
- <code class="literal">ohmd</code> will fail to load if any prevented plugin is
- manually loaded or loaded through a dependency of another plugin.
- </p><p>
- Plugins must also tell OHM that they will provide certain keys.
- This is done using <code class="literal">ohm_plugin_conf_provide()</code> and
- then OHM can check to see if the plugin is trying to provide keys
- that are managed by another plugin.
- This will stop the system doing odd things when two plugins try to write
- to one key and is a good check when building policy.
- In production code this check should be turned off using the command
- line argument <code class="literal">--no-checks</code> as this speeds up the
- initial coldplug considerably.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-acccess-to-keys"></a>Plugin access to keys</h3></div></div></div><p>
- To get key values from the global keystore, a plugin must use
- <code class="literal">ohm_plugin_conf_get_key()</code> which will return false
- if the key is not available.
- Keys can be set using <code class="literal">ohm_plugin_conf_set_key</code>.
- </p><p>
- A plugin may want to be notified when a key changes.
- In typical code, the key and the value would be passed to the plugin
- and then the key name compared against a fixed list.
- This is too slow for the plugin system in OHM, as many plugins may
- have to be chained together for a policy action.
- It was found that repeated <code class="literal">strcmp()</code>'s on all the
- changed value keys was causing high load on embedded machines.
- </p><p>
- To register interest in a key change, a plugin must call
- <code class="literal">ohm_plugin_conf_interested()</code> along with an integer ID
- unique to the plugin.
- The integer ID does not have to be unique among the other plugins.
- When the key is changed in OHM by another plugin of the session user,
- this is matched against a hash table for O(1) complexity, and then
- a list iterated over sending the indervidual ID's to the plugins.
- Matching integer ID's in plugins is much faster than matching strings,
- for a small coldplug overhead.
- See the example plugin code for more details.
- </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-session-access"></a>Session Access to keys</h3></div></div></div><p>
- Plugins have direct access to the keystore and can read and write any key
- even if private.
- The DBUS interface to the keystore is however limited to only setting
- public keys to enforce security policy.
- The DBUS interface should only be used to set preferences, it should
- never be used to set or change policy - this is the job for the plugin.
- </p><div class="mediaobject" align="center"><a name="plugins-dbus"></a><img src="ohm-dbus-access.png" align="middle"></div><p>
- The DBUS interface is protected from setting or creating keys to prevent
- malicious users overwriting system prefrences that are not to be changed.
- Session software can not load or unload plugins, as this would be a
- system and security risk.
- </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="plugins-defaults"></a>Default plugins</h2></div></div></div><p>
- Some plugins are shipped by default and provide typical use cases.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="plugins-backlight"></a>Backlight Adjustment</h3></div></div></div><p>
- Backlight brightness and state can be changed on most backlight hardware.
- These are the optional DBUS methods for controlling the brightness of
- the backlight.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="plugins-backlight-keys"></a>
- <code class="literal">Exported keys</code>
- </h4></div></div></div><p>
- Keys exported by this plugin:
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">backlight.value_ac</code></td><td>Brightness in percentage when on AC</td></tr><tr><td><code class="literal">backlight.value_battery</code></td><td>Brightness in percentage when on battery</td></tr><tr><td><code class="literal">backlight.value_idle</code></td><td>Brightness in percentage when idle</td></tr><tr><td><code class="literal">backlight.time_idle</code></td><td>
- The amount of time in seconds before the backlight is put
- into idle mode, or zero to disable.
- Idle mode is typically dimming for most backlight devices.
- </td></tr><tr><td><code class="literal">backlight.time_off</code></td><td>
- The amount of time in seconds before the backlight is turned
- off, or zero to disable.
- </td></tr></tbody></table></div></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="dbus-interface"></a>Chapter 3. DBUS Interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#pm-intro">Introduction</a></span></dt><dt><span class="sect1"><a href="#pm-manager">Manager functionality</a></span></dt><dd><dl><dt><span class="sect2"><a href="#pm-manager-keys">
- <code class="literal">Exported keys</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-manager-GetVersion">
- <code class="literal">GetVersion()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-manager-GetPlugins">
- <code class="literal">GetPlugins()</code>
- </a></span></dt></dl></dd><dt><span class="sect1"><a href="#pm-keystore">Keystore functionality</a></span></dt><dd><dl><dt><span class="sect2"><a href="#pm-keystore-GetKey">
- <code class="literal">GetKey()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-keystore-SetKey">
- <code class="literal">SetKey()</code>
- </a></span></dt><dt><span class="sect2"><a href="#pm-keystore-AddNotifyKey">
- <code class="literal">AddNotifyKey()</code>
- </a></span></dt></dl></dd></dl></div><p>
- This API is currently unstable and is likely to change in the future.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pm-intro"></a>Introduction</h2></div></div></div><p>
- Open Hardware Manager exposes a DBUS API for programs to obtain information about
- the power state and to change it if required.
- </p><p>
- The following constants are used to uniquely refer to the session-wide
- Open Hardware Manager object when making DBUS method calls:
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td>DBUS Service:</td><td><code class="literal">org.freedesktop.ohm</code></td></tr></tbody></table></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pm-manager"></a>Manager functionality</h2></div></div></div><p>
- The manager is the core of <code class="literal">ohmd</code> and processes all
- core functionality such as loading plugins.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td>DBUS Object Path:</td><td><code class="literal">/org/freedesktop/ohm/Manager</code></td></tr><tr><td>DBUS Interface:</td><td><code class="literal">org.freedesktop.ohm.Manager</code></td></tr></tbody></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-manager-keys"></a>
- <code class="literal">Exported keys</code>
- </h3></div></div></div><p>
- Keys exported by the manager:
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">manager.version.major</code></td><td>The major version number</td></tr><tr><td><code class="literal">manager.version.minor</code></td><td>The minor version number</td></tr><tr><td><code class="literal">manager.version.patch</code></td><td>The patch version number</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-manager-GetVersion"></a>
- <code class="literal">GetVersion()</code>
- </h3></div></div></div><p>
- Gets the version of the <code class="literal">ohmd</code> daemon.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Direction</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>out</td><td>string</td><td>The version, e.g. 0.2.3</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-manager-GetPlugins"></a>
- <code class="literal">GetPlugins()</code>
- </h3></div></div></div><p>
- Gets the plugings currently loaded in the daemon.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Direction</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>out</td><td>string array</td><td>A list of plugins, for instance,
- <code class="literal">backlight</code>, <code class="literal">heat-pol</code></td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pm-keystore"></a>Keystore functionality</h2></div></div></div><p>
- The keystore is the configuration plugin and processes all
- preferences functionality such as the getting and setting of keys.
- Session software can attempt to redefine any keys for the current user
- but these may not be marked override and the operation may fail.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td>DBUS Object Path:</td><td><code class="literal">/org/freedesktop/ohm/Keystore</code></td></tr><tr><td>DBUS Interface:</td><td><code class="literal">org.freedesktop.ohm.Keystore</code></td></tr></tbody></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-keystore-GetKey"></a>
- <code class="literal">GetKey()</code>
- </h3></div></div></div><p>
- Gets a 32 bit signed integer value.
- An error is returned if the key does not exist.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Direction</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>in</td><td>string</td><td>the key name, e.g. <code class="literal">ac.state</code></td></tr><tr><td>out</td><td>integer</td><td> </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-keystore-SetKey"></a>
- <code class="literal">SetKey()</code>
- </h3></div></div></div><p>
- Sets a 32 bit signed integer value.
- An error is returned if the key does not exist.
- The DBUS interface cannot be used to create keys for security.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Direction</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>in</td><td>string</td><td>the key name, e.g. <code class="literal">ac.state</code></td></tr><tr><td>in</td><td>integer</td><td> </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="pm-keystore-AddNotifyKey"></a>
- <code class="literal">AddNotifyKey()</code>
- </h3></div></div></div><p>
- Tells OHM that an application or plugin wants notification of this key
- change.
- This prevents uninteresting keys from being changed with no action
- causing unnecessary context switches and processor usage.
- <code class="literal">KeyChanged</code> signals will not be sent unless at least
- one application has requested notifications.
- </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Direction</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>in</td><td>string</td><td>the key name, e.g. <code class="literal">ac.state</code></td></tr><tr><td>in</td><td>integer</td><td> </td></tr></tbody></table></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Chapter 4. Frequently Asked Questions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#faq-sessionpolicy">
- How does OHM fit in with other session policy agents?
- </a></span></dt><dt><span class="sect1"><a href="#faq-specificdevice">
- Why not just do a specific device hack for all the different
- embedded hardware?
- </a></span></dt><dt><span class="sect1"><a href="#faq-lgpl">
- So it's LGPL... does that mean some of the code is closed source?
- </a></span></dt><dt><span class="sect1"><a href="#faq-installcode">
- Can I install the latest stable code?
- </a></span></dt><dt><span class="sect1"><a href="#faq-releasedate">
- What is the release date plan for OHM?
- </a></span></dt><dt><span class="sect1"><a href="#faq-systemprefs">
- Do you need to use system GConf for the system preferences?
- </a></span></dt><dt><span class="sect1"><a href="#faq-noxml">
- Is OHM using XML to define the policy rules?
- </a></span></dt><dt><span class="sect1"><a href="#faq-whysessionlayer">
- Why include a session layer for embedded appliances?
- </a></span></dt><dt><span class="sect1"><a href="#faq-whysinglehash">
- Why are all the keys exposed in a single hash table?
- </a></span></dt><dt><span class="sect1"><a href="#faq-restartdeps">
- Will OHM break if I restart <code class="literal">messagebus</code> or
- <code class="literal">hald</code>?
- </a></span></dt><dt><span class="sect1"><a href="#faq-shellscripts">
- Can I execute shell scripts from OHM on an event?
- </a></span></dt></dl></div><p>
- Please read through these common questions and answers before asking
- developers.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-sessionpolicy"></a>
- How does OHM fit in with other session policy agents?
- </h2></div></div></div><p>
- At the moment, no distributions ship OHM, so there is no problem.
- When they do, session power daemons will talk to <code class="literal">hald</code>
- and <code class="literal">ohmd</code> together, and there should be no visible
- changes to the user.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-specificdevice"></a>
- Why not just do a specific device hack for all the different
- embedded hardware?
- </h2></div></div></div><p>
- As lots of manufacturers are hacking the same thing, over and over.
- We need some sort of central common framework.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-lgpl"></a>
- So it's LGPL... does that mean some of the code is closed source?
- </h2></div></div></div><p>
- No. It just means that code protected by intellectual property laws
- can be used by manufacturers, but OHM works really well without any
- non-free stuff.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-installcode"></a>
- Can I install the latest stable code?
- </h2></div></div></div><p>
- No, at the moment it is proof of concept and only really useful for
- developers. Feel free to look at the code and spec and give feedback,
- but please don't expect anything to actually work well yet.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-releasedate"></a>
- What is the release date plan for OHM?
- </h2></div></div></div><p>
- Currently we are aiming at a 2 month stakeholder involvement prototype
- period, and then 10 months of code polishing and maturing.
- That gives an approximate release date of January 2008
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-systemprefs"></a>
- Do you need to use system GConf for the system preferences?
- </h2></div></div></div><p>
- No. We plan to use a flat file for minimum dependencies and speed,
- and also each file is going to be really small and simple.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-noxml"></a>
- Is OHM using XML to define the policy rules?
- </h2></div></div></div><p>
- No, as we don't need to.
- We are using compiled logic for speed and low dependencies.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-whysessionlayer"></a>
- Why include a session layer for embedded appliances?
- </h2></div></div></div><p>
- Devices can omit the session layer, and talk directly to OHM on the
- system bus. This removes the ability to do fast user switching or
- have multiple logged in users and does reduce security.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-whysinglehash"></a>
- Why are all the keys exposed in a single hash table?
- </h2></div></div></div><p>
- Plugins have to query to state of other plugins.
- To store the state of each plugin in itself, we would have to do
- inter-plugin methods, and expose the SetKey and GetKey methods on every
- plugin.
- We can also optimise the global keystore for a fast hash lookup to avoid
- scalability problems.
- This also makes it easier to code as the keystore can just be a
- compiled <code class="literal">.o</code> object rather than a shared library.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-restartdeps"></a>
- Will OHM break if I restart <code class="literal">messagebus</code> or
- <code class="literal">hald</code>?
- </h2></div></div></div><p>
- Yes. Please restart your computer if you want to restart these daemons.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faq-shellscripts"></a>
- Can I execute shell scripts from OHM on an event?
- </h2></div></div></div><p>
- Well you can, but you really don't want to.
- Executing a shell takes a long time on an embedded system, and OHM
- provides (deliberately) no methods to easily launch scripts.
- A critical design feature of <code class="literal">ohmd</code> is that it is fast
- and lightweight, with policy written in compiled modules, and so writing
- stuff in shell is very discouraged.
- </p></div></div></div></body></html>
More information about the Ohm-devel
mailing list