usr.sbin/apmd/README

   1 FreeBSD apmd Package Release Notes (19990711 version)
   2
   3 1. What is "apmd"?
   4 ==================
   5
   6 The apmd package provides a means of handling various APM events from
   7 userland code.  Using apmd.conf, the apmd(8) configuration file, you
   8 can select the APM events to be handled from userland and specify the
   9 commands for a given event, allowing APM behaviour to be configured
  10 flexibly.
  11
  12
  13 2. How to install the apmd package
  14 ==================================
  15
  16 2.1 Making the apmd control device file
  17 ---------------------------------------
  18
  19 apmd(8) uses the new special device file /dev/apmctl.  This should be
  20 created as follows:
  21
  22 # cd /dev
  23 # mknod apmctl c 39 8
  24
  25 2.2 Applying the kernel patch and building a new kernel
  26 -------------------------------------------------------
  27
  28 The next step is to apply the patch against the sys source tree.
  29 Go to the source directory (eg. /usr/src/ or /usr/PAO3/src/) and run
  30 the patch command as follows:
  31
  32 # gzip -cd [somewhere]/apmd-sys-R320.diff | patch
  33
  34 For PAO3 users, the patch file name would be apmd-sys-PAO3.diff
  35 instead of apmd-sys-R320.diff.  After this step has completed
  36 successfully, build and install a new kernel and reboot your system.
  37
  38 2.3 Making the apmd program
  39 ---------------------------
  40
  41 Go to src/usr.sbin/ and extract the apmd tarball as follows:
  42
  43 # tar xzpvf [somewhere]/apmd-usr.sbin.tar.gz
  44
  45 Before doing a make all, you need to copy apm_bios.h in the sys source
  46 tree to /usr/include/machine/ first:
  47
  48 # cp /sys/i386/include/apm_bios.h /usr/include/machine/
  49
  50 Then do the build and install steps in the apmd directory:
  51
  52 # cd src/usr.sbin/apmd
  53 # make depend all install
  54
  55 2.4 Setting up the configuration file and userland script
  56 ---------------------------------------------------------
  57
  58 In src/usr.sbin/apm/etc/ there are example configuration and userland
  59 script files which are invoked automatically when the APM BIOS informs
  60 apmd of an event, such as suspend request.  Copy these files to
  61 /etc/ as follows:
  62
  63 # cp src/usr.sbin/apm/etc/* /etc/
  64
  65
  66 3. Running the apmd daemon program
  67 ==================================
  68
  69 To run apmd(8) in background mode, simply type ``apmd''.
  70
  71 # apmd
  72
  73 To make a running apmd reload /etc/apmd.conf, send a SIGHUP signal to
  74 the apmd(8) process.
  75
  76 # kill -HUP [apmd pid]
  77 or
  78 # killall -HUP apmd
  79
  80 apmd has some command line options.  For the details, please
  81 refer to the manpage of apmd.
  82
  83 4. Configuration file
  84 =====================
  85
  86 The structure of the apmd configuration file is quite simple.  For
  87 example:
  88
  89 apm_event SUSPENDREQ {
  90         exec "sync && sync && sync";
  91         exec "sleep 1";
  92         exec "zzz";
  93 }
  94
  95 Will cause apmd to recieve the APM event SUSPENDREQ (which may be
  96 posted by an LCD close), run the sync command 3 times and wait for a
  97 while, then execute zzz (apm -z) to put the system in the suspend
  98 state.
  99
 100 4.1 The apm_event keyword
 101 -------------------------
 102 `apm_event' is the keyword which indicates the start of configuration for
 103 each events.
 104
 105 4.2 APM events
 106 --------------
 107
 108 If you wish to execute the same commands for different events, the
 109 event names should be delimited by a comma.  The following are valid
 110 event names:
 111
 112 o Events ignored by the kernel if apmd is running:
 113
 114 STANDBYREQ
 115 SUSPENDREQ
 116 USERSUSPENDREQ
 117 BATTERYLOW
 118
 119 o Events passed to apmd after kernel handling:
 120
 121 NORMRESUME
 122 CRITRESUME
 123 STANDBYRESUME
 124 POWERSTATECHANGE
 125 UPDATETIME
 126
 127
 128 Other events will not be sent to apmd.
 129
 130 4.3 command line syntax
 131 -----------------------
 132
 133 In the example above, the three lines begining with `exec' are commands
 134 for the event.  Each line should be terminated with a semicolon.  The
 135 command list for the event should be enclosed by `{' and `}'. apmd(8)
 136 uses /bin/sh for double-quotation enclosed command execution, just as
 137 with system(3).  Each command is executed in order until the end of
 138 the list is reached or a command finishes with a non-zero status code.
 139 apmd(8) will report any failed command's status code via syslog(3)
 140 and will then reject the request event posted by APM BIOS.
 141
 142 4.4 Built-in functions
 143 ----------------------
 144
 145 You can also specify apmd built-in functions instead of command lines.
 146 A built-in function name should be terminated with a semicolon, just as
 147 with a command line.
 148 The following built-in functions are currently supported:
 149
 150 o reject;
 151
 152   Reject last request posted by the APM BIOS.  This can be used to reject a
 153   SUSPEND request when the LCD is closed and put the system in a STANDBY
 154   state instead.
 155
 156
 157
 158 5. EXAMPLES
 159 ===========
 160
 161 Sample configuration commands include:
 162
 163 apm_event SUSPENDREQ {
 164         exec "/etc/rc.suspend";
 165 }
 166
 167 apm_event USERSUSPENDREQ {
 168         exec "sync && sync && sync";
 169         exec "sleep 1";
 170         exec "apm -z";
 171 }
 172
 173 apm_event NORMRESUME, STANDBYRESUME {
 174         exec "/etc/rc.resume";
 175 }
 176
 177 # resume event configuration for serial mouse users by
 178 # reinitializing a moused(8) connected to a serial port.
 179 #
 180 #apm_event NORMRESUME {
 181 #       exec "kill -HUP `cat /var/run/moused.pid`";
 182 #}
 183
 184 # suspend request event configuration for ATA HDD users:
 185 # execute standby instead of suspend.
 186 #
 187 #apm_event SUSPENDREQ {
 188 #       reject;
 189 #       exec "sync && sync && sync";
 190 #       exec "sleep 1";
 191 #       exec "apm -Z";
 192 #}
 193
 194
 195 6. Call for developers
 196 ======================
 197
 198 The initial version of apmd(8) was implemented primarily to test the
 199 kernel support code and was ALPHA quality.  Based on that code, the
 200 current version was developed by KOIE Hidetaka <hide@koie.org>.
 201 However, we're still looking around for interesting new features and
 202 ideas, so if you have any thoughts, please let us know.
 203 Documentation is also sparse, and the manpage have just written.
 204 If you wish to collaborate on this work, please e-mail me:
 205 iwasaki@freebsd.org.
 206
 207
 208 June 1, 1999
 209 Created by: iwasaki@FreeBSD.org
 210 Edited by: jkh@FreeBSD.org
 211            nick@foobar.org
 212
 213 $FreeBSD: src/usr.sbin/apmd/README,v 1.2 1999/08/28 01:15:24 peter Exp $
 214 $DragonFly: src/usr.sbin/apmd/README,v 1.2 2003/06/17 04:29:52 dillon Exp $