hasapm(ADM)

hasapm -- check power management BIOS-APM firmware

Syntax

/etc/pwr/bin/hasapm [ -ABcPsuV ] [ test ]

Description

hasapm is used during during system installation and startup to check if the machine has BIOS-APM firmware suitable for use with the operating system's Power Management (PM) facilities.

hasapm accepts the following options:

-A: Print the status of the A/C mains power supply when the system was booted.
-B: Print the status of the battery when the system was booted.
-c: Check if boot(HW) connected to the BIOS-APM successfully. If boot failed to connect, the firmware cannot be used.
-P: Print the BIOS-APM firmware's operational parameters.
-s: Do not print the results of the -c and -u checks, or of any test condition. The exit(S-osr5) status indicates which check (if any) failed.
-u: Check if the operating system can use the BIOS-APM. A non-zero exit value means the system cannot use the firmware successfully, but a zero exit value does not mean the system can.
-V: Print the BIOS-APM firmware version.

The optional test is a boolean expression checking the power supply's status when the system was booted. It is built from primitives combined with the following operations (listed from highest to lowest precedence):

Operation Description

!expr true if expr is not true

expr1 & expr2 true if both expr1 and expr2 are true

expr1 | expr2 true if either or both of expr1 and expr2 are true

expr1 ^ expr2 true if exactly one of expr1 and expr2 is true

The primitives which are combined to form test include:

Operation	Description
!*expr*	true if *expr* is not true
*expr1* & *expr2*	true if both *expr1* and *expr2* are true
*expr1* \| *expr2*	true if either or both of *expr1* and *expr2* are true
*expr1* ^ *expr2*	true if exactly one of *expr1* and *expr2* is true

Primitive Description

(expr) true if expr is true

always true

never false (equivalent to !always)

ac.online true if using A/C mains power

ac.unknown true if the status of the A/C mains power is unknown

battery.online true if using batteries rather than A/C mains power

battery.unknown true if the status of the batteries is unknown

charge.unknown true if the remaining battery charge is unknown

charge.high true if the remaining battery charge is high

charge.low true if the remaining battery charge is low

charge.critical true if the remaining battery charge is critically low

charge.charging true if the battery is recharging

% < percent true if the percentage of battery charge remaining (if known) is less than percent

% <= percent true if the percentage of battery charge remaining (if known) is less than or equal to percent

% = percent true if the percentage of battery charge remaining (if known) is equal to percent

% >= percent true if the percentage of battery charge remaining (if known) is greater than or equal to percent

% > percent true if the percentage of battery charge remaining (if known) is greater than percent

% != percent true if the percentage of battery charge remaining (if known) is not equal to percent

percent can take the values 0 though 100.

Primitive	Description
(*expr*)	true if *expr* is true
always	true
never	false (equivalent to !always)
ac.online	true if using A/C mains power
ac.unknown	true if the status of the A/C mains power is unknown
battery.online	true if using batteries rather than A/C mains power
battery.unknown	true if the status of the batteries is unknown
charge.unknown	true if the remaining battery charge is unknown
charge.high	true if the remaining battery charge is high
charge.low	true if the remaining battery charge is low
charge.critical	true if the remaining battery charge is critically low
charge.charging	true if the battery is recharging
% < *percent*	true if the percentage of battery charge remaining (if known) is less than *percent*
% <= *percent*	true if the percentage of battery charge remaining (if known) is less than or equal to *percent*
% = *percent*	true if the percentage of battery charge remaining (if known) is equal to *percent*
% >= *percent*	true if the percentage of battery charge remaining (if known) is greater than or equal to *percent*
% > *percent*	true if the percentage of battery charge remaining (if known) is greater than *percent*
% != *percent*	true if the percentage of battery charge remaining (if known) is not equal to *percent*

If the charge of the battery is unknown (charge.unknown is true) then none of the six relational comparisons evaluates as true.

At most, one of ac.online, battery.online, and ac.unknown is true.

At most, one of battery.unknown, charge.high, charge.low, charge.critical, and charge.charging is true.

Different manufacturers' firmware interprets different percentages of charge remaining as being ``high'', ``low'', or ``critical''.

Typically, an installed battery is considered to be recharging whenever A/C mains power is supplied. However, some machines report a fully-charged battery as having a ``high'' charge.

The example below discusses some other unusual power conditions some BIOS-APM firmware is known to report.

The test condition should be quoted to prevent interpretation by the shell.

The test condition has the same syntax as that understood by the status command of pwrsh(ADM), and the apm.warn and apm.boot checks of boot .

If no options or test are supplied, hasapm behaves as though the options -P and -V were specified.

Exit values

hasapm exits with one of the following values:

0

No errors occurred.

If the -u option was specified, the machine's BIOS-APM may be usable by the operating system.

If the -c option was specified, boot connected to the firmware successfully.

test was true when the system was booted.

1

An illegal argument was given.

2

Missing, unknown, or extraneous arguments were given.

21

Invalid information was obtained about this machine's BIOS-APM firmware.

55

An unexpected error occurred when trying to obtain information about this machine's BIOS-APM firmware.

56

boot did not supply any information about this machine's BIOS-APM firmware. Either the machine has none, or boot was configured not to supply the information.

58

The operating system does not support Power Management.

59

The test condition was not met (test is false). Only possible if a test condition was given.

60

Corrupt information was obtained about this machine's BIOS-APM firmware.

203

boot failed to connect to this machine's BIOS-APM firmware. Only possible if the -c option was specified.

208

This machine's BIOS-APM firmware cannot be used by the operating system. Only possible if the -u option was specified.

Examples

Print a warning message if, when the system was booted, there was no A/C mains power and the batteries were either critically low or had less then ten percent of a full charge remaining:

   powertest="!ac.online & (charge.critical | (!charge.unknown & % < 10))"
   nopowermsg="No power - the system should not have been booted"
   
   /etc/pwr/bin/hasapm -s $powertest && echo $nopowermsg

The test in this example could be simplified to:

   powertest="!ac.online & (charge.critical | % < 10)"

This is because any check on the percentage of charge remaining will evaluate as false if the battery's charge is unknown.

On some machines, the BIOS-APM firmware does not know the condition of the battery; it will report no charge remaining (% = 0 is true) rather than admitting that the charge is unknown (charge.unknown is true). Consequently, either of the above test conditions will always be true when such machines are using batteries rather than A/C mains power.

To try to overcome this problem, the test could be changed to:

   powertest="!ac.online & !battery.unknown & (charge.critical | % < 10)"

However, this will not work on all such machines; some systems can deduce the approximate status of the battery without knowing the percentage charge remaining.

Different manufacturers interpret different percentages of remaining charge or approximate battery status as being ``high'', ``low'', or ``critical''. These interpretations may have been designed to be used with proprietary software, and so may be misleading. They may not produce satisfactory results if they are used as indicators of the battery's charge state. Checking the percentage of remaining charge should be more satisfactory, but is not possible on all machines.

Warning

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.

Limitations

The test condition checks the situation when the system was booted. The -A and -B options print the A/C mains and battery status when the system was booted. To check the current situation or print the current status, use the status command of pwrsh(ADM).