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

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.

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 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

APM_DEQEVENT

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

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)

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.

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 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

Standards conformance