DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

uapm(HW)


uapm -- Advanced Power Management BIOS-APM firmware

Description

Some machines equipped with APM (Advanced Power Management) support in the BIOS firmware can cooperate with the operating system to reduce power consumption, extending the life of batteries or decreasing electricity costs. Not all machines have BIOS-APM firmware, and not all BIOS-APM firmware can cooperate with the operating system. This cooperation is Power Management (PM).

The BIOS-APM has three modes of operation:


Never
No Power Management activity occurs. This mode of operation is normally selected via the machine's SETUP procedure. On some machines, whenever A/C mains power is being using this mode is forced. On many machines, this mode is equivalent to ``disabling'' the BIOS-APM firmware.

Automatic
The firmware monitors some activity, and guesses appropriate power levels for some peripherals. This is usually the initial operating mode, especially if batteries rather than A/C mains power are being used. On some machines, disabled BIOS-APM firmware is (partially) functional and operates in a (partial) automatic mode.

Cooperative
In addition to possible firmware monitoring, the operating system sends instructions to, and receives status data and hints from, the BIOS-APM firmware. This mode is usually selected by boot(HW) if the firmware supports the facilities required by the operating system. Selecting the cooperative mode is called connecting to the firmware. The pwrd(ADM) daemon controls the cooperation using actions defined in a pwraction(F) file. PM events are compared with the defined actions; the actions which match run tasks which usually use pwrsh(ADM) and pwrsend(ADM) to control the cooperation, thereby managing the system's power.
When connected (in cooperative mode) the BIOS-APM firmware is periodically polled for APM events. These include warnings that the battery's power is running low and notices about the apparent lack of any recent activity. Within the more general context of the Power Management system APM events are some of the many possible PM events.

PM events sent to the BIOS-APM may include status inquires and commands to shut down or fully power up various peripherals. Additionally, using the pwr(HW) STREAMS protocol stack, the operating system may generate and process assorted events not directly handled by the BIOS-APM firmware, including notices that a peripheral is no longer in use or that the Uninterruptible Power Supply (UPS) is now supplying power after a mains-supply failure.

The uapm driver is the interface between the pwr STREAMS stack and the BIOS-APM firmware. It may be used independently of the pwr PM system via the pwrsh diagnostic commands.

Electrical circuits (typically entire peripherals or controllers) are considered to be in one of four states:


Ready
Fully powered up and available for use; however, the peripheral may not actually be in use.

Idle (Stand-by)
Not in use and consuming minimal power while not losing any data. Whenever the peripheral is needed, it is automatically made Ready (possibly after a short delay).

Frozen (Suspended)
Similar to Idle, except that the peripheral is not automatically made Ready when needed. An explicit action (the appropriate PM event or pressing a button) is needed to make the peripheral Ready. No data is lost. Freezing a peripheral may cause it to consume less power than merely Idling it.

Off
The peripheral is not powered up at all. Some or all data may be lost.
Some machines can only Freeze the entire system. Some machines can only turn Off individual peripherals, but not the entire system. Not every peripheral on all machines are controlled by the BIOS-APM firmware; uncontrolled peripherals are either Ready or Off but never Idle or Frozen.

Any of the four states can be entered by a PM event sent to the BIOS-APM firmware. Some states are entered automatically, either by the peripheral or due to the BIOS-APM firmware. Some states can be entered or left by outside action, such as the ON/OFF power switch. On some machines, the ON/OFF switch can be configured in SETUP mode to either turn the entire system's power on and off, or else to Freeze and resume (un-Freeze) the entire system.

Mode + State + What -> New state
Never Ready ON/OFF switch Off
Never Ready other firmware-defined
Cooperative Ready ``Idle'' event Idle
Cooperative Ready ``Freeze'' event Frozen
Cooperative Ready ``Off'' event Off
Automatic Ready no recent activity Idle
or Ready system inactive Frozen
Cooperative Ready ON/OFF switch Off or Frozen
Ready other firmware-defined
Cooperative Idle ``Ready'' event Ready
Automatic Idle interrupt or I/O Ready
or Idle ON/OFF switch Off or Frozen
Cooperative Idle other firmware-defined
Cooperative Frozen ``Ready'' event Ready
Automatic or Frozen ON/OFF switch Ready
Cooperative Frozen other firmware-defined
any Off ON/OFF switch Ready
any Off other firmware-defined

 +-------------+---------+--------------------+------------------+
 |Mode         | + State | + What             |  New state       |
 +-------------+---------+--------------------+------------------+
 |Never        | Ready   | ON/OFF switch      | Off              |
 +-------------+---------+--------------------+------------------+
 |Never        | Ready   | other              | firmware-defined |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Ready   | ``Idle'' event     | Idle             |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Ready   | ``Freeze'' event   | Frozen           |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Ready   | ``Off'' event      | Off              |
 +-------------+---------+--------------------+------------------+
 |Automatic    | Ready   | no recent activity | Idle             |
 +-------------+---------+--------------------+------------------+
 |or           | Ready   | system inactive    | Frozen           |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Ready   | ON/OFF switch      | Off or Frozen    |
 +-------------+---------+--------------------+------------------+
 |             | Ready   | other              | firmware-defined |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Idle    | ``Ready'' event    | Ready            |
 +-------------+---------+--------------------+------------------+
 |Automatic    | Idle    | interrupt or I/O   | Ready            |
 +-------------+---------+--------------------+------------------+
 |or           | Idle    | ON/OFF switch      | Off or Frozen    |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Idle    | other              | firmware-defined |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Frozen  | ``Ready'' event    | Ready            |
 +-------------+---------+--------------------+------------------+
 |Automatic or | Frozen  | ON/OFF switch      | Ready            |
 +-------------+---------+--------------------+------------------+
 |Cooperative  | Frozen  | other              | firmware-defined |
 +-------------+---------+--------------------+------------------+
 |any          | Off     | ON/OFF switch      | Ready            |
 +-------------+---------+--------------------+------------------+
 |any          | Off     | other              | firmware-defined |
 +-------------+---------+--------------------+------------------+
The uapm interface neither read's nor write's any data. All operations are done with the following ioctl(S) commands. If the pwr STREAMS driver is installed and a polling frequency defined, then the operating system periodically polls the firmware for APM events. All events so obtained plus all errors (except for ``no event'') are added to a first-in-first-out queue of pmevent structures (defined in <sys/pmmsg.h>) as described in pwr(HW). The pwrd daemon drains this queue by retrieving messages from the pwr STREAMS stack.

The uapm ioctl commands defined in <sys/apm.h> include:


APM_BOOTDATA
Returns a copy of the bootapm structure initialized by boot in the core pointed to by arg. At least the number of bytes returned by the APM_BOOTSIZE ioctl must be allocated.
#pragma pack(1)
struct bootapm {
    ushort  sizeof_bootapm; /* sizeof(struct bootapm)           */
    uchar_t majvers;        /* Major APM version number (BCD)   */
    uchar_t minvers;        /* Minor APM version number (BCD)   */
    char    apmstr[2];      /* ASCII "PM" (sans trailing '\0') */
    ushort  check;          /* Assorted APM flags   APMCHK_xxx  */
    uchar_t acmains;        /* A/C mains status     APMAC_xxx   */
    uchar_t battery;        /* Battery status       APMBAT_xxx  */
    uchar_t charge;         /* % of full battery charge         */
    uchar_t connecterror;   /* connect error code   APMERR_xxx  */
    ushort  pm32cs;         /* PM 32-bit code segment           */
    ulong_t pmentry;        /* offset of entry point            */
    ushort  pm16cs;         /* PM 16-bit code segment           */
    ushort  pmds;           /* PM data segment                  */
};
#pragma pack()
Should a future release or update of the system require an expanded bootapm structure, the additional fields will be added at the end of the structure. Programs should therefore not assume that sizeof(struct bootapm) bytes are returned by the APM_BOOTDATA ioctl -- the APM_BOOTSIZE ioctl returns the size in bytes of the system's bootapm structure.

APM_BOOTSIZE
Returns the size in bytes of the bootapm structure returned by APM_BOOTDATA.

APM_CALLBIOS
``Raw'' BIOS-APM interface. The arg points to an array of longwords which contains the machine's register set as defined in <sys/reg.h>. There must be as many longwords as returned by the APM_NUMREGS ioctl. Only certain registers are used in the call to the firmware. Other registers are used to return information: The legal register argument values depend on the BIOS-APM firmware.

Register Argument Result
EAX always Depends on firmware
EBX sometimes Depends on firmware
ECX sometimes Depends on firmware
EDX sometimes Depends on firmware
ESI future use Reserved
EDI future use Reserved
EFL -- CF (carry) set on error
ERR -- Error code if CF set in EFL
ESP -- Ticks since boot when started
UESP -- Ticks since boot when completed
SS -- PM event classification
DS -- BIOS-APM data selector
CS -- BIOS-APM 32-bit code selector
EIP -- BIOS-APM entry point

 Register   Argument     Result
 EAX        always       Depends on firmware
 EBX        sometimes    Depends on firmware
 ECX        sometimes    Depends on firmware
 EDX        sometimes    Depends on firmware
 ESI        future use   Reserved
 EDI        future use   Reserved
 EFL                     CF (carry) set on error
 ERR                     Error code if CF set in EFL
 ESP                     Ticks since boot when started
 UESP                    Ticks since boot when completed
 SS                      PM event classification
 DS                      BIOS-APM data selector
 CS                      BIOS-APM 32-bit code selector
 EIP                     BIOS-APM entry point

APM_DEQEVENT
Returns in the pmevent structure pointed to by arg the oldest PM event in the queue.

APM_ENQEVENT
Adds the pmevent structure pointed to by arg to the tail of the queue.

APM_FUNCTION
(Write access required.) Identical to the APM_CALLBIOS ioctl except if there are any events in the queue, APMCALL_EVENT returns the oldest PM event in the queue.

APM_GETATTACH
The unsigned ioctl return value is a bitwise-OR of the flags:

APMATCH_STATUS
Can the firmware be called? See the APM_SETSTATUS ioctl for possible values of these bits.

APMATCH_EXISTS
If set, this machine has BIOS-APM firmware.

APMATCH_CONNECTED
If set, boot established a 32-bit Protected Mode path to the BIOS-APM firmware.

APMATCH_IGNORED
If set, the apm.ignore boot option was specified, causing uapm to never use the firmware.

The initial setting obviously depends on the machine.


APM_GETCONFIG
Gets the current setting of various configuration flags. The unsigned ioctl return value is a bitwise-OR of the flags:

APMCFG_SHUTDIS
The operating system automatically disconnects from the BIOS-APM firmware when the system is shutdown.

APMCFG_DISNEVER
When the BIOS-APM firmware is disconnected for any reason (including system shutdown and explicit disconnect event) the APMATCH_STATUS is set to APMSTAT_NEVERUSE, preventing all further use of the firmware until the system is rebooted.

APMCFG_DISNEVER
Whenever APMATCH_STATUS becomes APMSTAT_NEVERUSE for any reason (including disconnections and the APM_SETSTATUS ioctl), the working memory set aside for the connection's use is freed.

The initial value is configurable via the system's Link Kit, but usually all defined bits are set.


APM_GETFREQ
The long ioctl return value is the frequency (in milliseconds) the firmware is being polled for new PM events.

APM_GETSHUTDN
Returns in the core pointed to by arg a long_t array defining the power state the entire system is to enter on each of the different system shutdown uadmin(S) methods:

Method Default state Description
0 AD_HALT Ready No automatic reboot
1 AD_BOOT Ready Automatic reboot
2 AD_IBOOT Ready (same as AD_BOOT)
3 AD_PWRDOWN Frozen Turn off power
4 AD_PWRNAP Idle unless no A/C mains then AD_PWRDOWN
-- -- Frozen (anything else)

 Method   Default state   Description
 0        AD_HALT         Ready No automatic reboot
 1        AD_BOOT         Ready Automatic reboot
 2        AD_IBOOT        Ready (same as AD_BOOT)
 3        AD_PWRDOWN      Frozen Turn off power
 4        AD_PWRNAP       Idle unless no A/C mains then
                          AD_PWRDOWN
                          Frozen (anything else)
The ``Ready'' state is ignored -- the firmware is not called to place the entire system into any particular state. If there is no A/C mains power, then AD_PWRNAP is treated identically to AD_PWRDOWN. Since most firmware cannot turn Off the entire system's power, the default is to Freeze the system instead. The defaults are configurable via the system's Link Kit; those listed above are the usual values.
The core pointed to by arg must contain at least the number of bytes returned by the APM_SHUTDNSIZE ioctl. The last ulong_t in the array is the ``anything else'' state used when an unknown shutdown method is attempted. Should a future release or update of the system define additional methods, the array will grow in size and this entry will still be the last.

APM_NUMCALLS
The int ioctl return value is a count of the number of calls to the BIOS-APM firmware. The int arg determines which count is returned:

0
Calls which succeeded (no errors).

1
Calls which failed (an error occurred).

APM_NUMREGS
The int ioctl return value is the number of longwords used by the APM_CALLBIOS and APM_FUNCTION ioctls.

APM_QDEPTH
The int ioctl return value is the number of PM events currently in the queue.

APM_QFLUSH
Deletes all previously saved events from the queue, returning the number of deleted events.

APM_QMAXDEPTH
The int ioctl return value is the maximum number of PM events the queue can hold. If the queue is full, no further events can be entered.

APM_SETCONFIG
(Write access required.) Sets various configuration flags. The unsigned arg is a bitwise-OR of the flags described in the APM_GETCONFIG ioctl. Returned is the previous setting.

APM_SHUTDNSIZE
Returns the number of bytes in the array mapping shutdown methods to system power states. This array is returned by the APM_GETSHUTDN ioctl and set by APM_SETSHUTDN.

APM_SETFREQ
(Write access required.) The long arg is the number of milliseconds between checking the BIOS-APM firmware for new PM events. The frequency is rounded up to the nearest multiple of the resolution of the system's clock (usually ten milliseconds). A frequency of zero (0) stops further polling. The previous frequency is returned.

APM_SETSHUTDN
The core pointed to by arg defines the ulong_t array of power states the system is enters based on the shutdown method, as described in the APM_GETSHUTDN ioctl. arg must point to at least the number of bytes returned by APM_SHUTDNSIZE.

APM_SETSTATUS
(Write access required.) The unsigned long arg defines the current APMATCH_STATUS setting:

APMSTAT_NEVERUSE
Permanently disallow any further calls to the BIOS-APM firmware. Rebooting the system is necessary to reset this status.

APMSTAT_OFFHOOK
BIOS-APM firmware calls are not allowed at the moment.

APMSTAT_CANCALL
BIOS-APM calls (APM_CALLBIOS and APM_FUNCTION ioctls plus polling) are allowed.
The previous APMATCH_STATUS value is returned.

If boot failed to connect to the firmware the initial value is always APMSTAT_NEVERUSE. Otherwise the initial value can be configured via the system's Link Kit to either remain APMSTAT_NEVERUSE or else to be APMSTAT_CALLBIOS (default).

Various constants are defined in <sys/apm.h> for the possible BIOS-APM commands, arguments, return values, and errors.

Diagnostics

In addition to the various errors described in the open(S) and ioctl(S) manual pages, the following errors are also possible:

[ EAGAIN ]
The BIOS-APM firmware is currently busy.

[ EFAULT ]
arg points outside the address space.

[ EINVAL ]
An unknown ioctl was attempted or attempted with an invalid arg.

[ EIO ]
A pmevent could not be enqueued because the queue is full; or could not be dequeued because the queue is empty; or no calls to the BIOS-APM firmware are currently allowed.

[ ENOPKG ]
The pwr driver is not installed so no queue exists to save APM events obtained by polling the BIOS-APM firmware.

[ ENXIO ]
An attempt was made to open a device other than minor 0; an ioctl requiring write access was attempted on a file not open for writing; or boot(HW) did not supply any information about this machine's BIOS-APM firmware.

If the BIOS-APM returns an error, the ``Carry'' flag (bit 0x1) is set in the EFL register and the firmware's error code is saved in the ERR pseudo-register. The ioctl command itself does not return an error.

Limitations

BIOS-APM firmware from different manufacturers varies considerably in both operation and efficacy. What may be a safe or useful sequence of commands on one machine may be ineffectual or worse on another.

If you see the warning:

   WARNING:uapm: uapm_mkpgtab - APM PM Mapping includes page 0
displayed at boot-time, this version of the APM bios cannot cooperate with the operating system when making power management decisions. The driver can be removed from the link kit; the machine will continue to use power management, but will not inform the operating system when it does so.

Files


/dev/pwr/bios
uapm character special file

/usr/include/sys/apm.h
uapm ioctl definitions

/usr/include/sys/pmmsg.h
PM STREAMS stack definitions

See also

ioctl(S), pwr(HW), pwrd(ADM), pwrsh(ADM), uadmin(S)

Standards conformance

The uapm driver implements the 32-bit Protected Mode interface described in Advanced Power Management -- The Next Generation, Version 1.0 (undated), Intel Corporation and Microsoft Corporation.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003