1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Open Hardware Manager 0.0.1 Documentation</title><link rel="stylesheet" href="docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"><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.0.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@hughsie.com">richard@hughsie.com</a>></code><br>
</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.0.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>
|
