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 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572
|
.\" hey, Emacs: -*- nroff -*-
.\" pbbuttons is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; see the file COPYING. If not, write to
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH PBBUTTONSD 1 "September 30, 2006"
.\" Please update the above date whenever this man page is modified.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins (default)
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pbbuttonsd \- daemon to support Laptop specific functions
.SH SYNOPSIS
.B pbbuttonsd
.RI [ options ]
.SH DESCRIPTION
.ad b
\fBPBButtonsd\fP is a daemon which brings support for many Laptop specific
functions to Linux. Basically it was designed to support Apple iBooks,
Powerbooks or TiBooks but since version 0.5 the design has been changed to
support any Notebook.
.PP
For every supported Notebook a special module is necessary to do all the
hardware dependent jobs. At the moment only Apple Computers will be fully
supported but basic functions work also on Intel based machines. Help to
build up support for more machines is always welcome.
.PP
Supported features:
.PP
Advanced Power Management:
.ad l
.in +2
.ti -2
\- puts the machine to sleep if idle to save energy,
.ti -2
\- prevent the machine from entering sleep mode if CPU
or Net is busy until the job is finished,
.ti -2
\- send a warning if battery is running low,
.ti -2
\- configurable emergency actions if battery is critically low,
.ti -2
\- dims the display if user is passive to save energy
.ti -2
\- puts machine to sleep if cover was closed,
.ti -2
\- executes external scripts on certain power management events
to allow most flexibility,
.ti -2
\- is able to replace power management daemons like pmud, apmd, etc.
.PP
Support for laptop dependent hotkeys:
.in +2
.ti -2
\- to adjust display brightness
.ti -2
\- to adjust keyboard illumination,
.ti -2
\- to adjust the sound volume,
.ti -2
\- to mute/unmute the sound channels,
.ti -2
\- to open/close the CDROM tray,
.ti -2
\- to trigger sleep mode.
.ti -2
\- to switch external video on/off
.PP
Support for laptop dependent specialities:
.in +2
.ti -2
\- initializes trackpad and keyboard mode during startup,
.ti -2
\- disables trackpad's mouse click emulation while typing on the keyboard
.ti -2
\- keeps keyboard settings during sleep mode,
.ti -2
\- cycles through the trackpad operating mode via hotkeys,
.ti -2
\- supports PowerBook's ambient light sensor and automatic
adjustment of LCD and keyboard brightness.
.SH USER INTERFACE
.ad b
The main input to \fBPBButtonsd\fP works through key codes. Certain
keys ensure appropriate actions. This keys are widely user configurable
in the configuration file. In detail following keys are supported:
.PP
.nf
Config Option Modifier Description
LCD_IllumUpKey \-\- Increase display brightness.
shift Increase display brightness to maximum value.
The shift modifier here is hard coded and
can't be configured.
LCD_IllumDownKey \-\- Decrease display brightness until complete
darkness.
shift Decrease display brightness to minimum value.
The shift modifier here is hard coded and
can't be configured.
KBD_IllumUpKey \-\- Increase keyboard illumination brightness.
shift Increase keyboard illumination brightness to
maximum value. The shift modifier here is
hard coded and can't be configured.
KBD_IllumDownKey \-\- Decrease keyboard illumination brightness
until complete darkness.
shift Decrease keyboard illumination brightness to
minimum value. The shift modifier here is
hard coded and can't be configured.
KBD_IllumOnKey \-\- Switch keyboard illumination on/off. The
level won't change.
CRT_MirrorKey \-\- Enable/disable external video output.
SleepKey \-\- Trigger configured sleep action.
VolumeUpKey \-\- Increase volume of configured channels by
ten percent. This works on all sound hardware
the same way.
shift Increase volume level in fine steps. This function
uses the volume scale the hardware supports so
that small volume adjustment might not result in
audible volume change.
OSS always handle the volume level in percent
so that this function will change the volume
level by one percent.
The shift modifier here is hard coded and can't
be configured.
VolumeDownKey \-\- Decrease volume of configured channels by
ten percent.
shift Decrease volume level in small steps. Smallest
hardware supported step with ALSA and one
percent with OSS.
The shift modifier here is hard coded and
can't be configured.
MuteKey \-\- Disable/enable sound output. The volume level
won't change. Pressing any other volume con\-
trol key will automaticaly enable sound out\-
put again.
EjectCDKey \-\- Ejects a CDROM from CDROM drive. If necessary
the device will be unmounted before. This
would fail if the device was busy.
TPModeUpKey \-\- Cycle trackpad mode forward (notap, tap,
drag or lock).
TPModeDownKey \-\- Cycle trackpad mode backward (lock, drag,
tap or notap).
.fi
.PP
.ad b
Not all of this keys must work on your system. Most of them are hardware dependent
and if your notebook doesn't have the required hardware the related function will
not work. Read your notebook's manual and pbbuttonsd.conf (5) to figure out what
you could expect.
.PP
.SH COMMANDS AND SIGNALS
\fBPBButtonsd\fP has an IPC interface (Inter Process Communication)
and you could send commands to the server to trigger certain actions.
Use the command line tool 'pbbcmd' with following syntax to send
commands:
.PP
.ad c
pbbcmd <command>
.PP
.ad l
Following commands are understood:
.PP
.in +15
.ti -15
SAVECONFIG saves the configuration if enabled by pbbuttonsd's
security checks (see 'configuration file' section below) and you
have the right permission.
.br
.ti -15
EJECTCD unmount and ejects the CDROM or closes the tray
again, if already open.
.br
.ti -15
SLEEP puts the machine to sleep (also known as suspend
to RAM) if possible. If sleep was not supported on this machine
the screen will be blanked. Sleep is a kernel function and will
only be triggered by pbbuttonsd.
.br
.ti -15
HIBERNATE saves the memory and the process information to disk
(also known as suspend to Disk or Hibernate) if possible. If hibernate
was not supported on this machine nothing will happen. Hibernate is
a kernel function and will only be triggered by pbbuttonsd through a
PMCS script usually placed in /etc/power/.
.br
.ti -15
REINIT This command triggers reinitialization of hardware
under control of pbbuttonsd (for example trackpad and keyboard on
powerbooks). The PMCS script to reinitialize the power policy will
also be launched after receiving this command. This could be helpful
when after a 'suspend to disc' all the hardware needs to be
reinitialized.
.PP
Beside the IPC interface pbbuttonsd understands some signals:
.PP
.in +12
.ti -12
SIGHUP 1 pbbuttonsd reloads its configuration and scans for
input devices (see 'connecting/disconnecting new keyboards'
section below).
.br
.ti -12
SIGINT 2 usually emitted by CTRL-C. pbbuttonsd will clean up used
resources and terminates
.ti -12
SIGUSR1 10 pbbuttonsd reinitializes hardware components under its
control (for example trackpad and keyboard on powerbooks). Sending this
signal is the same as sending the command REINIT except that IPC will
not be used. This is for the complete paranoid guys ;-)
.ti -12
SIGTERM 15 pbbuttonsd will clean up its resources and terminates
.PP
.SH KERNEL CONFIGURATION
.ad b
In kernels before 2.4.18-rc2-benh the brightness of the display was
handled by the kernel itself. The brightness hotkeys were blocked by
the kernel and there was no chance for a user space daemon like
\fBPBButtonsd\fP to get the necessary information.
.PP
Nevertheless to get the brightness keys work with older kernels, a
special kernel patch could be applied. Without this patch the daemon
work as well with the little limitation not to control the display
brightness. This is done by the kernel, so a possibly attached client
wouldn't be informed on brightness level changes.
.PP
With kernel >= 2.6.18 a new SysFS interface to the backlight controller
has been introduced. Unfortunately the kernel configuration become very
confusing and misunderstanding. The Kernel has two options regarding the
backlight in section "Device Drivers -> Macintosh Device Drivers":
.PP
.in +4
.ti -4
.B "Backlight control for LCD screens"
.br
.RI ( CONF_PMU_BACKLIGHT )
.PP
.in +4
The help text says that this option enables generic backlight code. In
fact without this option you won't get any backlight interface running,
neither SysFS nor PMU, so say YES here.
.PP
.in +4
Unfortunately this option enables also code to control display brightness
for older PowerBooks. That means the kernel itself controls the backlight
brightness and interfere with any user space daemmon. The reference in the
help text to use a user space daemon like pbbuttonsd is very kind, but
The user space daemon is helpless if the kernel itself do the job.
Nevertheless say \fBYES\fP to this option.
.PP
.in +4
.ti -4
.B "Provide legacy ioctl's on /dev/pmu for the backlight"
.br
.RI ( CONF_PMU_BACKLIGHT_LEGACY )
.PP
.in +4
This option apears if backlight control has been enabled. This option adds
some code to read and write the backlight level via the pmu driver (/dev/pmu).
This interface was used by pbbuttonsd in the past and normaly it isn't needed
any longer because the SysFS interface should make it redundant.
.PP
.in +4
Unfortunately the function to disable the direct kernel control of the
backlight (for old PowerBooks, you remenber?) is part of the code added by
this option. That means if you say YES to PMAC_BACKLIGHT but say NO to
PMAC_BACKLIGHT_LEGACY, backlight will work but pbbuttonsd will never get the
chance to gain control over the backlight controller. Kernel and user space
daemon will interfere with eachother in an unacceptable way and that leads
to unwanted results.
.PP
.in +4
This mixture of related but independent functions make it necessary to say
\fBYES\fP to this option as well until the Kernel guys cleaned up this mess.
.PP
Finally your Kernel 2.6.18 configuration should look like this:
.PP
.ad l
.in +4
[*] \fBB\fPacklight control for LCD screens
.br
.in +6
[*] \fBP\fProvide legacy ioctl's on /dev/pmu for the backlight
.ad b
.PP
\fBPBButtonsd\fP will then automatically detect the best suited interface
and use it.
.SH GENERAL
To get visual feedback from the adjustments a user made, a SystemV IPC
interface is implemented to exchange messages with a client which for
example displays the brightness and volume levels on a X Desktop.
.PP
If battery level is critically low pbbuttonsd has multiple mechanism
to react on. The default behavior is to put the machine to sleep.
Alternatively it is possible to send the init process the SIGPWR signal
or to shut the machine down directly by a configurable script. Everything
could be done to bring the machine down in a controlled way before
the power management unit will switch the machine off the hard way due
to lack of energy. This would prevent data losses and other problems.
.PP
To be able to shut down the machine pbbuttonsd must be running as 'root'
because only the superuser is allowed to call the shutdown program or
could send init requests to the init process.
.PP
.SH POWER POLICIES
Since version 0.6 \fBPBButtonsd\fP supports so called power policies.
With this policies the user can roughly define how the machine should
handle the current load condition. If low current consumption, maximum
performance or anything in between is most important at this time. Three
policies are supported: 'powersave', 'custom' and 'performance'.
.PP
Each power source can be connected to a policy that becomes active as
soon as the power source changes. Sometimes it may not desirable
that the policy changes as soon as the power source changes. For this case
the policy connected to this power source can be set to 'nochange'.
.PP
The pmcs script is responsible to put the set policy into practice.
\fBPBButtonsd\fP will call this script among others every time the
policy changes or has to be reset after periods of sleep or suspend.
.PP
.SH PBButtonsd AND SLEEP MODE (Suspend to RAM)
\fBPBButtonsd\fP can't suspend the machine by its own. It uses kernel
API functions for that. This means pbbuttonsd only asks the kernel:
"Please suspend the machine". If the kernel do so and what happens after
the request is up to the kernel.
.PP
Problems in this stage often occour due to old device drivers which
don't support the suspend mode very well. The kernel API changed
a lot here and it took a lot of time to adapt all the device drivers
to the new interface. A solution could be to unload problematic device
drivers before triggering sleep and reload them after wake up.
\fBPBButtonsd\fP would support that via its Power Management Control
Scripts (see /etc/power/).
.PP
The machine went to sleep after the main CPU has been switched off. Now,
the computer is only controlled by the PMU which is a small (mostly 8bit)
microprocessor with ROM (Read Only Memory) code. After the occourence of
a dedicated event the PMU reactivates the main CPU and the machine wake
up again. Those events could be:
.PP
.ad l
.in +2
.ti -2
\- trigger a key on the keyboard
.ti -2
\- open the cover (closing the cover doesn't wake up the machine)
.ti -2
\- insert or remove an USB device
.ti -2
\- timer
.ti -2
\- other computers address the sleeping computer via LAN
.ad b
.PP
The PMU needs to know which events should trigger a wake up procedure. The
first two are explicitly enabled by the kernel before putting the machine to
sleep. The third seems to be not maskable by the PMU, that means it will
always wake up the computer. And the last two weren't supported at all yet on
Linux.
.PP
While the key trigger event will unconditionally wake up the machine, the
cover open event could be configured via the /proc/pmu/options interface. The
following command will prevent your machine from waking up after the cover
has been opened:
.br
.ad c
echo > "lid_wakeup=0" > /proc/pmu/options
.br
.ad b
.PP
And the following command enable the wake up on "cover open" again:
.br
.ad c
echo > "lid_wakeup=1" > /proc/pmu/options
.br
.ad b
.PP
Other wake up options are not foreseen by the kernel but may be added in the
future. \fBPBButtonsd\fP is completely out of control until the kernel has
finished its wake up procedure and gives control back to user space.
.SH IBaM (Intelligent Battery Monitoring)
IBaM is an advanced battery monitoring method, which uses statistical and
adaptive linear methods to provide accurate estimations of battery time
remaining or of the time needed until full recharge.
.PP
If IBaM is compiled into \fBpbbuttonsd\fP all internal time calculations
based on kernel battery information would be replaced. Through the IPC
signal TimeRemaining \fBpbbuttonsd\fP clients could benefit from accurate
time estimations too.
.PP
Once started \fBPbbuttonsd\fP will collect battery data and saves
them to disk for statistical analysis. The more data \fBpbbuttonsd\fP
have to analyse the more accurate the time estimations will be.
.PP
Because at the very beginning \fBpbbuttonsd\fP has no data to analyse
it is recommended to perform the initial procedure described below to fill
the database with real data. If \fBpbbuttonsd\fP has to initialize IBaM's
database during normal usage with arbitrary charge and discharge cycles,
it might take longer to get reliable time predictions and accurate battery
warnings.
.SH IBaM INITIAL PROCEDURE
This step is not necessary if you only update \fBPBButtonsd\fP. The
updated version will continue to use the existing data.
.PP
At the very beginnig \fBpbbuttonsd\fP has no data to analyse and all
estimations based on default values that won't be better than the kernel
battery data. Therefore it is recommended to do one complete battery
discharge/charge cycle after installing this version of \fBpbbuttonsd\fP
with integrated IBaM to initially fill the database with real data.
.PP
Unplug AC power from your laptop. IBaM will now save the time intervals
between changes in battery status. \fBPBButtonsd\fP will already use the
data in this early stage and the battery warnings might be unreliable or
won't occur at all. This is normal behaviour and will only happen during
initial discharge cycle.
.PP
The most important time of a battery discharge cycle is the last minutes.
During the last, let's say 20 minutes of battery time it is most important
to get reliable and accurate battery warnings. But this aim could only be
reached if the IBaM database contains data about the last minutes on battery.
It is very important that the battery will be completely drained during the
initial discharge cycle (until \fBpbbuttonsd\fP triggers sleep or the
hardware switch off hardly, prepare for the second case to prevent data
losses).
.PP
After your battery is completely drained, plug in your AC connector and
continue working as usual.
.PP
IBaM is fully initialized now and it's prepared to show its full power and
benefit. Depending on your load cases the time estimations will fluctuating
a bit the first time. But after roundabout three battery charge/discharge
cycles the predicted time and the battery warnings will be rather stable
and reliable.
.PP
The database is updated continously so that any aging of the battery is taken
into account. When \fBpbbuttons\fP tells you now, you still have 10 minutes
left on battery, then you \fBwill\fP have 10 minutes left even if your
battery is growing old and the capacity decreases.
.SH IBaM and multiple batteries
Currently IBaM is not able to handle multiple batteries seperatly. It always
sums up all batteries in system and calculates with the result. Therefore the
IBaM statistics will be influenced if you change your battery configuration
(adding or removing batteries).
.PP
Battery warnings will be slightly inaccurate after changing the battery
configuration. If you run a long time with a unchanged configuration this
changes would hardly be significant or not seen at all. The scenario described
in the paragraph below is only likely if you did only a few charge/discharge
cycles.
.PP
After plugging in an additional battery pbbuttonsd might show low battery
warnings too early and vica versa after you removed your second battery.
Especially after you decreased overall battery capacity by removing a second
battery, \fBpbbuttonsd\fP might get aware of low battery condition too late.
As result the machine will switch off the hard way. To prevent data losses in
this case you should not wait for the last warning before you plug in the AC
connector. IBaM will resync itself automatically during the next
charge/discharge cycles.
.PP
IBaM works best if you use always the same battery configuration (one or two
batteries).
.SH CONFIGURATION FILE
\fBPBButtonsd\fP uses a configuration file for setting up all it's features.
This file is usually located in \fIetc\fP. From version 0.5.4 on
\fBPBButtonsd\fP is also able to write the current configuration to a file.
.PP
To make this solution as secure as possible a batch of security checks
will be performed until configuration writing would be allowed:
.PP
.ad l
.in +3
.ti -3
1. The owner of the writable configuration file must be the same as
the owner of pbbuttonsd process.
.ti -3
2. The configuration file is only writable by the owner.
.ad b
.PP
If any of this conditions failed, writing of the configuration file would
be disabled.
.PP
.SH CONNECTING / DISCONNECTING NEW INPUT DEVICES
\fBPBButtonsd\fP uses for its input the event hander in /dev/input/event%,
which handles also hot-plugable devices such as USB or ADB (Mac only)
input devices. \fBPBButtonsd\fP scanns those devices at start time and
work with the found devices.
.PP
Before Hotplug, the only way for pbbuttonsd to realize newly connected
devices is to regularly scan the event devices. Unfortunately there is
no summary keyboard device as there is for mice and hotplug isn't available
for kernel 2.4 and before. Because external USB input devices become quite
common, the autorescan feature is enabled by default.
.PP
If your hard disk is prevented from spinning down due to the regular event
device scans, you might want to disable this feature. This could be done in
the configuration file. In this case you have to trigger a rescan manually
after connecting new input devices. Scanning is initiated by sending the HUP
signal to the server:
.PP
.ad c
kill \-HUP \`cat /var/run/pbbuttonsd.pid\`
.PP
.ad b
Be aware that the configuration file will also be reloaded in this case.
.PP
.SH OPTIONS
\fBPBButtonsd\fP accepts the following options:
.TP
\fB\-c\fR, \fB\-\-configfile\fR=\fICONFIGFILE\fR
Use an alternative configuration file, default is /etc/pbbuttonsd.conf.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-v, \-\-version
Show version of \fBPBButtonsd\fP.
.TP
.B \-q, \-\-quiet
Suppress the welcome message. Some startup scripts want to have full
control about their output.
.TP
\fB\-d\fR, \fB\-\-detach\fR[=\fIPIDFILE\fR]
Start \fBPBButtonsd\fP as background process. optional an alternative
pidfile. The daemon writes it's pid into this file.
.br
In this mode we can't assume to have a valid terminal so all outputs
will be blocked and no error message will be printed.
.TP
.in +7
If you don't use this flag and start \fBPBButtonsd\fP as background
process by adding a \'&\' to the command line, please redirect
\'stdout\' and \'stderr\' to a valid file as well (or at least to
/dev/null if you don't need error output). If you don't do so
\fBPBButtonsd\fP may be stopped by the shell because of using
invalid file descriptors.
.SH "SEE ALSO"
pbbuttonsd.conf (5), gtkpbbuttons (1)
.SH AUTHOR
Matthias Grimm.
|