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_POWERSTATECHANGEXXX "suspend system xxxxx"
 120 .It Sy "Name                  " "Action          " "Description"
 121 .It Dv "PMEV_STANDBYREQ       " No "suspend system  " "standby request"
 122 .It Dv "PMEV_SUSPENDREQ       " No "suspend system  " "suspend request"
 123 .It Dv "PMEV_USERSUSPENDREQ   " No "suspend system  " "user suspend request"
 124 .It Dv "PMEV_CRITSUSPEND      " No "suspend system  " "critical suspend request"
 125 .It Dv "PMEV_NORMRESUME       " No "resume system   " "normal resume"
 126 .It Dv "PMEV_CRITRESUME       " No "resume system   " "critical resume"
 127 .It Dv "PMEV_STANDBYRESUME    " No "resume system   " "standby resume"
 128 .It Dv "PMEV_BATTERYLOW       " No "notify message  " "battery low"
 129 .It Dv "PMEV_UPDATETIME       " No "adjust clock    " "update time"
 130 .El
 131 .El
 132 .Sh SEE ALSO
 133 .Xr apm 8 ,
 134 .Xr zzz 8
 135 .Sh AUTHORS
 136 .An Tatsumi Hosokawa Aq hosokawa@jp.FreeBSD.org
 137 .Sh BUGS
 138 WARNING!
 139 Many, if not most, of the implementations of APM-bios in laptops
 140 today are buggy.
 141 You may be putting your LCD-display and batteries at a risk by using this
 142 interface.
 143 (The reason this isn't a problem for MS-windows is that they use the
 144 real-mode interface.)
 145 If you see any weird behavior from your system with this code in use,
 146 unplug the power and batteries ASAP, if not immediately, and disable
 147 this code.
 148 .Pp
 149 We are very interested in getting this code working, so please send your
 150 observations of any anomalous behavior to us.
 151 .Pp
 152 When
 153 .Nm
 154 is active, calling the BIOS setup routine by using hot-keys,
 155 may cause serious trouble when resuming the system.
 156 BIOS setup programs should be called during bootstrap, or from DOS.
 157 .Pp
 158 Some APM implementations cannot handle events such as pushing the
 159 power button or closing the cover.
 160 On such implementations, the system
 161 .Ar must
 162 be suspended
 163 .Ar only
 164 by using
 165 .Xr apm 8
 166 or
 167 .Xr zzz 8 .
 168 .Pp
 169 Disk spin-down, LCD backlight control, and power on demand have not
 170 been supported on the current version.