README revision 208289
1214501SrpauloFreeBSD apmd Package Release Notes (19990711 version) 2214501Srpaulo 3214501Srpaulo1. What is "apmd"? 4214501Srpaulo================== 5214501Srpaulo 6214501SrpauloThe apmd package provides a means of handling various APM events from 7214501Srpaulouserland code. Using apmd.conf, the apmd(8) configuration file, you 8214501Srpaulocan select the APM events to be handled from userland and specify the 9214501Srpaulocommands for a given event, allowing APM behaviour to be configured 10214501Srpauloflexibly. 11214501Srpaulo 12214501Srpaulo 13214501Srpaulo2. How to install the apmd package 14214501Srpaulo================================== 15214501Srpaulo 16214501Srpaulo2.1 Making the apmd control device file 17214501Srpaulo--------------------------------------- 18214501Srpaulo 19214501Srpauloapmd(8) uses the new special device file /dev/apmctl. This should be 20214501Srpaulocreated as follows: 21214501Srpaulo 22214501Srpaulo# cd /dev 23214501Srpaulo# mknod apmctl c 39 8 24214501Srpaulo 25214501Srpaulo2.2 Applying the kernel patch and building a new kernel 26214501Srpaulo------------------------------------------------------- 27214501Srpaulo 28214501SrpauloThe next step is to apply the patch against the sys source tree. 29214501SrpauloGo to the source directory (eg. /usr/src/ or /usr/PAO3/src/) and run 30214501Srpaulothe patch command as follows: 31214501Srpaulo 32214501Srpaulo# gzip -cd [somewhere]/apmd-sys-R320.diff | patch 33214501Srpaulo 34214501SrpauloFor PAO3 users, the patch file name would be apmd-sys-PAO3.diff 35214501Srpauloinstead of apmd-sys-R320.diff. After this step has completed 36214501Srpaulosuccessfully, build and install a new kernel and reboot your system. 37214501Srpaulo 38214501Srpaulo2.3 Making the apmd program 39214501Srpaulo--------------------------- 40214501Srpaulo 41214501SrpauloGo to src/usr.sbin/ and extract the apmd tarball as follows: 42214501Srpaulo 43214501Srpaulo# tar xzpvf [somewhere]/apmd-usr.sbin.tar.gz 44214501Srpaulo 45214501SrpauloBefore doing a make all, you need to copy apm_bios.h in the sys source 46214501Srpaulotree to /usr/include/machine/ first: 47214501Srpaulo 48214501Srpaulo# cp /sys/i386/include/apm_bios.h /usr/include/machine/ 49214501Srpaulo 50214501SrpauloThen do the build and install steps in the apmd directory: 51214501Srpaulo 52214501Srpaulo# cd src/usr.sbin/apmd 53214501Srpaulo# make depend all install 54214501Srpaulo 55214501Srpaulo2.4 Setting up the configuration file and userland script 56214501Srpaulo--------------------------------------------------------- 57214501Srpaulo 58214501SrpauloIn src/usr.sbin/apm/etc/ there are example configuration and userland 59214501Srpauloscript files which are invoked automatically when the APM BIOS informs 60214501Srpauloapmd of an event, such as suspend request. Copy these files to 61214501Srpaulo/etc/ as follows: 62214501Srpaulo 63214501Srpaulo# cp src/usr.sbin/apm/etc/* /etc/ 64214501Srpaulo 65214501Srpaulo 66214501Srpaulo3. Running the apmd daemon program 67214501Srpaulo================================== 68214501Srpaulo 69214501SrpauloTo run apmd(8) in background mode, simply type ``apmd''. 70214501Srpaulo 71214501Srpaulo# apmd 72214501Srpaulo 73214501SrpauloTo make a running apmd reload /etc/apmd.conf, send a SIGHUP signal to 74214501Srpaulothe apmd(8) process. 75214501Srpaulo 76214501Srpaulo# kill -HUP [apmd pid] 77214501Srpauloor 78214501Srpaulo# killall -HUP apmd 79214501Srpaulo 80214501Srpauloapmd has some command line options. For the details, please 81214501Srpaulorefer to the manpage of apmd. 82214501Srpaulo 83214501Srpaulo4. Configuration file 84214501Srpaulo===================== 85214501Srpaulo 86214501SrpauloThe structure of the apmd configuration file is quite simple. For 87214501Srpauloexample: 88214501Srpaulo 89214501Srpauloapm_event SUSPENDREQ { 90214501Srpaulo exec "sync && sync && sync"; 91214501Srpaulo exec "sleep 1"; 92214501Srpaulo exec "zzz"; 93214501Srpaulo} 94214501Srpaulo 95214501SrpauloWill cause apmd to receive the APM event SUSPENDREQ (which may be 96214501Srpauloposted by an LCD close), run the sync command 3 times and wait for a 97214501Srpaulowhile, then execute zzz (apm -z) to put the system in the suspend 98214501Srpaulostate. 99214501Srpaulo 100214501Srpaulo4.1 The apm_event keyword 101214501Srpaulo------------------------- 102214501Srpaulo`apm_event' is the keyword which indicates the start of configuration for 103214501Srpauloeach events. 104214501Srpaulo 105214501Srpaulo4.2 APM events 106214501Srpaulo-------------- 107214501Srpaulo 108214501SrpauloIf you wish to execute the same commands for different events, the 109214501Srpauloevent names should be delimited by a comma. The following are valid 110214501Srpauloevent names: 111214501Srpaulo 112214501Srpauloo Events ignored by the kernel if apmd is running: 113214501Srpaulo 114214501SrpauloSTANDBYREQ 115214501SrpauloSUSPENDREQ 116214501SrpauloUSERSUSPENDREQ 117214501SrpauloBATTERYLOW 118214501Srpaulo 119214501Srpauloo Events passed to apmd after kernel handling: 120214501Srpaulo 121214501SrpauloNORMRESUME 122214501SrpauloCRITRESUME 123214501SrpauloSTANDBYRESUME 124214501SrpauloPOWERSTATECHANGE 125214501SrpauloUPDATETIME 126214501Srpaulo 127214501Srpaulo 128214501SrpauloOther events will not be sent to apmd. 129214501Srpaulo 130214501Srpaulo4.3 command line syntax 131214501Srpaulo----------------------- 132214501Srpaulo 133214501SrpauloIn the example above, the three lines beginning with `exec' are commands 134214501Srpaulofor the event. Each line should be terminated with a semicolon. The 135214501Srpaulocommand list for the event should be enclosed by `{' and `}'. apmd(8) 136214501Srpaulouses /bin/sh for double-quotation enclosed command execution, just as 137214501Srpaulowith system(3). Each command is executed in order until the end of 138214501Srpaulothe list is reached or a command finishes with a non-zero status code. 139214501Srpauloapmd(8) will report any failed command's status code via syslog(3) 140214501Srpauloand will then reject the request event posted by APM BIOS. 141214501Srpaulo 142214501Srpaulo4.4 Built-in functions 143214501Srpaulo---------------------- 144214501Srpaulo 145214501SrpauloYou can also specify apmd built-in functions instead of command lines. 146214501SrpauloA built-in function name should be terminated with a semicolon, just as 147214501Srpaulowith a command line. 148214501SrpauloThe following built-in functions are currently supported: 149214501Srpaulo 150214501Srpauloo reject; 151214501Srpaulo 152214501Srpaulo Reject last request posted by the APM BIOS. This can be used to reject a 153214501Srpaulo SUSPEND request when the LCD is closed and put the system in a STANDBY 154214501Srpaulo state instead. 155214501Srpaulo 156214501Srpaulo 157214501Srpaulo 158214501Srpaulo5. EXAMPLES 159214501Srpaulo=========== 160214501Srpaulo 161214501SrpauloSample configuration commands include: 162214501Srpaulo 163214501Srpauloapm_event SUSPENDREQ { 164214501Srpaulo exec "/etc/rc.suspend"; 165214501Srpaulo} 166214501Srpaulo 167214501Srpauloapm_event USERSUSPENDREQ { 168214501Srpaulo exec "sync && sync && sync"; 169214501Srpaulo exec "sleep 1"; 170214501Srpaulo exec "apm -z"; 171214501Srpaulo} 172214501Srpaulo 173214501Srpauloapm_event NORMRESUME, STANDBYRESUME { 174214501Srpaulo exec "/etc/rc.resume"; 175214501Srpaulo} 176214501Srpaulo 177214501Srpaulo# resume event configuration for serial mouse users by 178214501Srpaulo# reinitializing a moused(8) connected to a serial port. 179214501Srpaulo# 180214501Srpaulo#apm_event NORMRESUME { 181214501Srpaulo# exec "kill -HUP `cat /var/run/moused.pid`"; 182214501Srpaulo#} 183214501Srpaulo 184214501Srpaulo# suspend request event configuration for ATA HDD users: 185214501Srpaulo# execute standby instead of suspend. 186214501Srpaulo# 187214501Srpaulo#apm_event SUSPENDREQ { 188214501Srpaulo# reject; 189214501Srpaulo# exec "sync && sync && sync"; 190214501Srpaulo# exec "sleep 1"; 191214501Srpaulo# exec "apm -Z"; 192214501Srpaulo#} 193214501Srpaulo 194214501Srpaulo 195214501Srpaulo6. Call for developers 196214501Srpaulo====================== 197214501Srpaulo 198214501SrpauloThe initial version of apmd(8) was implemented primarily to test the 199214501Srpaulokernel support code and was ALPHA quality. Based on that code, the 200214501Srpaulocurrent version was developed by KOIE Hidetaka <hide@koie.org>. 201214501SrpauloHowever, we're still looking around for interesting new features and 202214501Srpauloideas, so if you have any thoughts, please let us know. 203214501SrpauloDocumentation is also sparse, and the manpage have just written. 204214501SrpauloIf you wish to collaborate on this work, please e-mail me: 205214501Srpauloiwasaki@freebsd.org. 206214501Srpaulo 207214501Srpaulo 208214501SrpauloJune 1, 1999 209214501SrpauloCreated by: iwasaki@FreeBSD.org 210214501SrpauloEdited by: jkh@FreeBSD.org 211214501Srpaulo nick@foobar.org 212214501Srpaulo 213214501Srpaulo$FreeBSD: head/usr.sbin/apmd/README 208289 2010-05-19 08:52:51Z uqs $ 214214501Srpaulo