share/man/man4/apm.4

   1 .\" LP (Laptop Package)
   2 .\"
   3 .\" Copyright (c) 1994 by HOSOKAWA, Tatsumi <hosokawa@mt.cs.keio.ac.jp>
   4 .\"
   5 .\" This software may be used, modified, copied, and distributed, in
   6 .\" both source and binary form provided that the above copyright and
   7 .\" these terms are retained. Under no circumstances is the author
   8 .\" responsible for the proper functioning of this software, nor does
   9 .\" the author assume any responsibility for damages incurred with its
  10 .\" use.
  11 .\"
  12 .\" $FreeBSD: src/share/man/man4/man4.i386/apm.4,v 1.13.2.5 2001/08/17 13:08:45 ru Exp $
  13 .\"
  14 .Dd September 9, 2012
  15 .Dt APM 4
  16 .Os
  17 .Sh NAME
  18 .Nm apm
  19 .Nd APM BIOS interface
  20 .Sh SYNOPSIS
  21 .Cd device apm0 at nexus?
  22 .Sh DESCRIPTION
  23 .Nm
  24 is an interface to the Intel / Microsoft APM (Advanced Power Management) BIOS
  25 on laptop PCs.
  26 It has been largely superseded by
  27 .Xr acpi 4 ,
  28 which emulates
  29 .Nm Ap s
  30 ioctls (see below) so userland can use them as a uniform interface
  31 (to get at the battery status, for example).
  32 .Pp
  33 Note that
  34 .Em real
  35 .Nm
  36 (in the absence of
  37 .Xr acpi 4 )
  38 is not available on the
  39 .Sy x86_64
  40 platform.
  41 .Pp
  42 .Nm
  43 provides the following power management functions.
  44 .Bl -enum -offset indent
  45 .It
  46 When the system wakes up from suspended mode,
  47 .Nm
  48 adjusts the system clock to RTC.
  49 .It
  50 When the system wakes up from suspended mode,
  51 .Nm
  52 passes a message to
  53 .Xr syslogd 8
  54 comprising of system wakeup time and elapsed time during suspended mode.
  55 .It
  56 .Nm
  57 slows CPU clock when there are no system activities (runnable processes,
  58 interrupts, etc.).
  59 This function is available only on systems whose APM supports CPU idling.
  60 .It
  61 .Nm
  62 exports an application interface as a character device.
  63 Applications can control APM, or retrieve APM status information via this
  64 interface.
  65 .Nm
  66 exports the following interfaces.
  67 These symbols are defined in
  68 .In machine/apm_bios.h .
  69 .Bl -tag -width 4n -offset indent
  70 .It Dv APMIO_SUSPEND
  71 Suspend system.
  72 .It Dv APMIO_GETINFO
  73 Get power management information.
  74 .It Dv APMIO_ENABLE
  75 .It Dv APMIO_DISABLE
  76 Enable / Disable power management.
  77 .It Dv APMIO_HALTCPU
  78 .It Dv APMIO_NOTHALTCPU
  79 Control execution of HLT in the kernel context switch routine.
  80 .It Dv APMIO_GETPWSTATUS
  81 Get per battery information.
  82 .Pp
  83 Some APM implementations execute the HLT
  84 (Halt CPU until an interrupt occurs)
  85 instruction in the
  86 .Dq Em Idle CPU
  87 call, while others do not.
  88 Thus enabling this may result in redundant HLT executions because
  89 .Dq Em Idle CPU
  90 is called from the kernel context switch routine that inherently executes
  91 HLT.
  92 This may reduce peak system performance.
  93 .Pp
  94 Also the system hangs up if HLT instruction is disabled in the kernel
  95 context switch routine, and if the APM implementation of the machine
  96 does not execute HLT in
  97 .Dq Em Idle CPU .
  98 On some implementations that do not support CPU clock slowdown, APM
  99 might not execute HLT.
 100 .Nm
 101 disables
 102 .Dv APMIO_NOTHALTCPU
 103 operation on such machines.
 104 .Pp
 105 The current version of
 106 .Nm
 107 does not call
 108 .Dq Em Idle CPU
 109 from the kernel context switch routine if clock slowdown is not supported,
 110 and it executes HLT instruction by default.
 111 Therefore, there is no need to use these two operations in most cases.
 112 .El
 113 .Pp
 114 These interfaces are used by
 115 .Xr apm 8 .
 116 .It
 117 .Nm
 118 polls APM events and handles the following events:
 119 .Bl -column PMEV_USERSUSPENDREQ "suspend system" "critical suspend request"
 120 .It Sy Name                Ta Sy Action        Ta Sy Description
 121 .It Dv PMEV_STANDBYREQ     Ta "suspend system" Ta "standby request"
 122 .It Dv PMEV_SUSPENDREQ     Ta "suspend system" Ta "suspend request"
 123 .It Dv PMEV_USERSUSPENDREQ Ta "suspend system" Ta "user suspend"
 124 .It ""                     Ta ""               Ta "request"
 125 .It Dv PMEV_CRITSUSPEND    Ta "suspend system" Ta "critical suspend"
 126 .It ""                     Ta ""               Ta "request"
 127 .It Dv PMEV_NORMRESUME     Ta "resume system"  Ta "normal resume"
 128 .It Dv PMEV_CRITRESUME     Ta "resume system"  Ta "critical resume"
 129 .It Dv PMEV_STANDBYRESUME  Ta "resume system"  Ta "standby resume"
 130 .It Dv PMEV_BATTERYLOW     Ta "notify message" Ta "battery low"
 131 .It Dv PMEV_UPDATETIME     Ta "adjust clock"   Ta "update time"
 132 .El
 133 .El
 134 .Sh SEE ALSO
 135 .Xr apm 8 ,
 136 .Xr zzz 8
 137 .Sh AUTHORS
 138 .An Tatsumi Hosokawa Aq Mt hosokawa@jp.FreeBSD.org
 139 .Sh BUGS
 140 WARNING!
 141 Many, if not most, of the implementations of APM-bios in laptops
 142 today are buggy.
 143 You may be putting your LCD-display and batteries at a risk by using this
 144 interface.
 145 (The reason this isn't a problem for MS-windows is that they use the
 146 real-mode interface.)
 147 If you see any weird behavior from your system with this code in use,
 148 unplug the power and batteries ASAP, if not immediately, and disable
 149 this code.
 150 .Pp
 151 We are very interested in getting this code working, so please send your
 152 observations of any anomalous behavior to us.
 153 .Pp
 154 When
 155 .Nm
 156 is active, calling the BIOS setup routine by using hot-keys,
 157 may cause serious trouble when resuming the system.
 158 BIOS setup programs should be called during bootstrap, or from DOS.
 159 .Pp
 160 Some APM implementations cannot handle events such as pushing the
 161 power button or closing the cover.
 162 On such implementations, the system
 163 .Ar must
 164 be suspended
 165 .Ar only
 166 by using
 167 .Xr apm 8
 168 or
 169 .Xr zzz 8 .
 170 .Pp
 171 Disk spin-down, LCD backlight control, and power on demand have not
 172 been supported on the current version.