Open Hardware Manager 0.0.1 Documentation

Richard Hughes

+ <richard@hughsie.com>
+

Version 0.0.1

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" +

Table of Contents

1. Open Hardware Manager Introduction

Overall Description
Plugins
Dependencies

2. DBUS Interface

Introduction

Manager functionality

+ Exported keys +
+ GetVersion() +
+ GetPlugins() +

Keystore functionality

+ GetKey() +
+ SetKey() +
+ AddNotifyKey() +

Backlight Adjustment

+ Exported keys +

3. Frequently Asked Questions

+ How does OHM fit in with other session policy agents? +
+ Why not just do a specific device hack for all the different + embedded hardware? +
+ So it's LGPL... does that mean some of the code is closed source? +
+ Can I install the latest stable code? +
+ What is the release date plan for OHM? +
+ Do you need to use system GConf for the system preferences? +
+ Is OHM using XML to define the policy rules? +
+ Why include a session layer for embedded appliances? +
+ Why are all the keys exposed in a single hash table? +
+ Will OHM break if I restart messagebus or + hald? +

Chapter 1. Open Hardware Manager Introduction

Table of Contents

Overall Description
Plugins
Dependencies

Overall Description

+ OHM is a small open source systems daemon which sits above HAL and + abstracts out common hardware management tasks such as: +

+ System wide power management statistics (for instance calculating + hysteresis of battery curves). +
+ Managing system wide inhibit actions, for instance system + firmware updating. +
+ Controlling heat dissipation on embedded and PC devices. +

+ 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. +

+ 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. +

+ 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 hald will start in the few hundred + millisecond range and consume less than half a megabyte of RAM at coldplug. +

+ 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. +

+ Proof of concept code is available on the project page. + There are no tarball releases yet, checking out using git is the best + option. +

+ OHM comprises: +

+ The ohmd system daemon which co-ordinates the + rules and acts as a keystore for multiple users. +
+ The interface specification which outlines core + ohmd functionality +
+ A method for plugins to request notification when keys change, for + example when the system AC state is changed. +
+ The test suite which tests functionality +

+ 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. +

+ What OHM is not: +

+ 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. +
+ An abstraction of HAL. HAL acts as the input and the output of OHM, + and OHM enforces policy for HAL. +
+ A huge daemon with lots of dependencies. +
+ API or ABI stable. Expect the ABI and API to change on a regular + basis until we ship 1.0.0. +
+ Targeted to a particular architecture or platform. +
+ Produced by any one vendor. + There are many contributors helping to get this done. +

+ Why not do everything in a session daemon?: +

+ Sometimes we need to start very early in the boot sequence. +
+ We don't want to die if X dies. +
+ On a server with 100 logged in users we don't want an instance for + each user. +
+ We need to apply policy at boot-up or before X starts. +

Plugins

+ Plugins have keys and policy, and also install a default system + preferences file. +

+ 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 optionally the public switch. +

+ The core setup file is read from /etc/ohm/core and + plugin preferences are read from /etc/ohm/plugins/{name} + Comments are lines with first character # and then the + rest of the line is ignored. + Files are flat text with the following formal description, + plugin_prefix.key value type public +

Important

+ There is a single space between the values. + Line endings have to be UNIX not WIN or MAC. + Parsing is very strict, and ohmd will exit with an + error if the syntax is not perfect. This is by design. +

Note

+ Public is only set if the key can be changed by the session, and if the + key is tried to be set, the set method will fail. + This is a way to enforce fine-grained rules on users when writing + PolicyKit rules for every action would be too great an overhead. +

+ Plugins can tell ohmd 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 ohm_module_require(). + ohmd daemon will fail to load if any required plugin + is not present after the plugins have finished initializing. +

+ Plugins can also tell ohmd 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 ohm_module_suggest(). + ohmd daemon will print a message to the console if any + suggested plugin is not present. +

+ Plugins can also tell ohmd that other plugins are banned, for instance, + a proprietary battery discharge plugin maybe incompatible with the + standard battery plugin. + This is done with ohm_module_prevent(). + ohmd will fail to load if any prevented plugin is + manually loaded or loaded through a dependency of another plugin. +

+ In ohmd, keys are created read/write by the plugin. + Other plugins can watch for changes on these keys (even on other modules) + using ohm_key_monitor(). + The callback will be issued local to the plugin when the state of this + key changes. +

+ NOTE: There is no ordering of priority (yet?) of monitored keys. + Make sure that policy per key is kept to one plugin, else strange + races might start happening. +

+ A library called libohm allows system and session + programs to easily interface with ohmd. + This library will remove the implementation detail from plugins and + session applications. + This library, like the rest of OHM will not be API or ABI stable until + version 1.0.0 is released. +

Dependencies

+ OHM is lightweight. +

+ GLib 2.10.0 (required) +
+ DBUS 0.70 (required) +
+ HAL 0.5.8 (required) +
+ PolicyKit (optional) +
+ ConsoleKit (optional) +

Chapter 2. DBUS Interface

Table of Contents

Introduction

Manager functionality

+ Exported keys +
+ GetVersion() +
+ GetPlugins() +

Keystore functionality

+ GetKey() +
+ SetKey() +
+ AddNotifyKey() +

Backlight Adjustment

+ Exported keys +

+ This API is currently unstable and is likely to change in the future. +

Introduction

+ Open Hardware Manager exposes a DBUS API for programs to obtain information about + the power state and to change it if required. +

+ The following constants are used to uniquely refer to the session-wide + Open Hardware Manager object when making DBUS method calls: +

DBUS Service: org.freedesktop.ohm

Manager functionality

+ The manager is the core of ohmd and processes all + core functionality such as loading plugins. +

DBUS Object Path:	`/org/freedesktop/ohm/Manager`
DBUS Interface:	`org.freedesktop.ohm.Manager`

+ `Exported keys` +

+ Keys exported by the manager: +

Key	Description
`manager.version.major`	The major version number
`manager.version.minor`	The minor version number
`manager.version.patch`	The patch version number

+ `GetVersion()` +

+ Gets the version of the ohmd daemon. +

Direction	Type	Description
out	string	The version, e.g. 0.2.3

+ `GetPlugins()` +

+ Gets the plugings currently loaded in the daemon. +

Direction	Type	Description
out	string array	A list of plugins, for instance, + `backlight`, `heat-pol`

Keystore functionality

+ 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. +

DBUS Object Path:	`/org/freedesktop/ohm/Keystore`
DBUS Interface:	`org.freedesktop.ohm.Keystore`

+ `GetKey()` +

+ Gets a 32 bit signed integer value. +

Direction	Type	Description
in	string	the key name, e.g. `ac.state`
out	integer

+ `SetKey()` +

+ Sets a 32 bit signed integer value. +

Direction	Type	Description
in	string	the key name, e.g. `ac.state`
in	integer

+ `AddNotifyKey()` +

+ 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. + KeyChanged signals will not be sent unless at least + one application has requested notifications. +

Direction	Type	Description
in	string	the key name, e.g. `ac.state`
in	integer

Backlight Adjustment

+ Backlight brightness and state can be changed on most backlight hardware. + These are the optional DBUS methods for controlling the brightness of + the backlight. +

DBUS Object Path:	`/org/freedesktop/ohm/Backlight`
DBUS Interface:	`org.freedesktop.ohm.Backlight`

+ `Exported keys` +

+ Keys exported by this plugin: +

Key	Description
`backlight.value_ac`	Brightness in percentage when on AC
`backlight.value_battery`	Brightness in percentage when on battery
`backlight.value_idle`	Brightness in percentage when idle
`backlight.time_idle`	+ 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. +
`backlight.time_off`	+ The amount of time in seconds before the backlight is turned + off, or zero to disable. +

Chapter 3. Frequently Asked Questions

Table of Contents

+ How does OHM fit in with other session policy agents? +
+ Why not just do a specific device hack for all the different + embedded hardware? +
+ So it's LGPL... does that mean some of the code is closed source? +
+ Can I install the latest stable code? +
+ What is the release date plan for OHM? +
+ Do you need to use system GConf for the system preferences? +
+ Is OHM using XML to define the policy rules? +
+ Why include a session layer for embedded appliances? +
+ Why are all the keys exposed in a single hash table? +
+ Will OHM break if I restart messagebus or + hald? +

+ Please read through these common questions and answers before asking + developers. +

+ How does OHM fit in with other session policy agents? +

+ At the moment, no distributions ship OHM, so there is no problem. + When they do, session power daemons will talk to hald + and ohmd together, and there should be no visible + changes to the user. +

+ Why not just do a specific device hack for all the different + embedded hardware? +

+ As lots of manufacturers are hacking the same thing, over and over. + We need some sort of central common framework. +

+ So it's LGPL... does that mean some of the code is closed source? +

+ 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. +

+ Can I install the latest stable code? +

+ 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. +

+ What is the release date plan for OHM? +

+ 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 +

+ Do you need to use system GConf for the system preferences? +

+ 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. +

+ Is OHM using XML to define the policy rules? +

+ No, as we don't need to. + We are using compiled logic for speed and low dependencies. +

+ Why include a session layer for embedded appliances? +

+ 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. +

+ Why are all the keys exposed in a single hash table? +

+ 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 .o object rather than a shared library. +

+ Will OHM break if I restart `messagebus` or + `hald`? +

+ Yes. Please restart your computer if you want to restart these daemons. +

Open Hardware Manager 0.0.1 Documentation

Richard Hughes

Chapter 1. Open Hardware Manager Introduction

Overall Description

Plugins

Important

Note

Dependencies

Chapter 2. DBUS Interface

Introduction

Manager functionality

+ Exported keys +

+ GetVersion() +

+ GetPlugins() +

Keystore functionality

+ GetKey() +

+ SetKey() +

+ AddNotifyKey() +

Backlight Adjustment

+ Exported keys +

Chapter 3. Frequently Asked Questions

+ How does OHM fit in with other session policy agents? +

+ Why not just do a specific device hack for all the different + embedded hardware? +

+ So it's LGPL... does that mean some of the code is closed source? +

+ Can I install the latest stable code? +

+ What is the release date plan for OHM? +

+ Do you need to use system GConf for the system preferences? +

+ Is OHM using XML to define the policy rules? +

+ Why include a session layer for embedded appliances? +

+ Why are all the keys exposed in a single hash table? +

+ Will OHM break if I restart messagebus or + hald? +

+ `Exported keys` +

+ `GetVersion()` +

+ `GetPlugins()` +

+ `GetKey()` +

+ `SetKey()` +

+ `AddNotifyKey()` +

+ `Exported keys` +

+ Will OHM break if I restart `messagebus` or + `hald`? +