pwrsh(ADM)

pwrsh -- Power Management control shell

Syntax

/etc/pwr/bin/pwrsh [ -einv ] [ -c "commands ... " ] [ file ]

Description

The operating system's Power Management (PM) facilities are configured, controlled, and queried using pwrsh. The options include:

-c commands...: pwrsh executes commands rather than reading the input file.
-e: Exit on error: a parse or execution failure causes pwrsh to exit immediately.
-i: Interactive: pwrsh prompts to the standard error output and does not exit when interrupted. This is the default mode unless -c was specified or the input file is not a terminal. When not interactive, pwrsh error messages include the input file name and line number of the failing command.
-n: No execution: the pwrsh commands are parsed but not executed.
-v: Verbose: pwrsh prints each command before execution.

If the -c option is not given, pwrsh reads commands from the input file. If no file is specified, pwrsh reads the standard input.

There is one command to a line. Each line consists of zero or more words. Blank lines are ignored. A word is any sequence of non-blank or quoted characters. One or more characters may be quoted by surrounding them within single (') or double (") quotes. Newlines within the quoted sequence are included in the word. Single characters (except for newline) may be quoted with backslash (\). Except within single quotes, the sequence \newline is deleted. Single-quoting preserves all characters whilst backslash escapes are processed inside double quotes. This is analogous to the Bourne ( sh(C)) and Korn ( ksh(C) ) shells. Comments start with the first word beginning with a hash (#) and continue until end-of-line. A line beginning with bang (!) is a shell command, which is treated specially and not subject to the normal quoting rules.

There are two categories of pwrsh commands: Normal and Diagnostic. Diagnostic commands are either unsupported or dangerous, and should not be used without supervision or by untrained staff. Diagnostic commands are normally disabled; they are enabled by the diagnostics command. Usual operations do not require the use of any diagnostic command.

pwrsh commands are sent using one of several ``protocols'' over an open ``channel.'' If there is no currently-open channel, and one is needed for a pwrsh command, pwrsh automatically opens /dev/pwr/pm as the channel and uses the pwr(HW) packet protocol. The channel diagnostic command controls the channel and protocol used.

The ultimate destination depends on the command. If the ultimate destination is the BIOS-APM firmware then it must usually be ``connected'', establishing an interface for the operating system to use. The BIOS-APM firmware is normally connected by boot(HW); if ever disconnected by the disconnect command (which is not a diagnostic command) the system must usually be rebooted to reestablish the connection. (The connect diagnostic command is mostly non-functional.)

Most commands destined for the BIOS-APM firmware also require the BIOS-APM to be ``enabled'' or actively managing the machine's power consumption. The BIOS-APM firmware may be enabled and disabled as required with the enable and disable commands. When pwrd(ADM) is running it usually arranges for the BIOS-APM firmware to be enabled.

The pwrsh commands include:

! pipeline

The remainder of the line (pipeline) is a command run by the shell defined by the SHELL environment variable. If SHELL is not set, then the Bourne shell ( sh ) is assumed. If no pipeline is given, an interactive shell is started.

?

A synonym (alias) for the help command.

apm [ -n ] eax [ ebx ecx edx esi edi ]

(Diagnostic command.) Raw interface to the machine's BIOS-APM firmware. Issue command eax with parameters ebx, ecx, edx, esi, and edi using the current channel, then wait for a response. The commands, parameters, results, and effects depend on the machine's firmware. The regs and error commands can be used to examine the response, if the system survives the experience. The -n option prevents command eax from being send down the currently-open channel to be executed.

busy

Insures the CPU is operating at full speed.

channel [ -c ] [ -o type [ special ]]

(Diagnostic command.) Open, or close a channel, or list the available protocols.

-c: Close the currently-open channel (if any).
-o: Opens a channel (device special file to use protocol type. If no special file is given, the default device for the given protocol is assumed. If the open succeeds, it becomes the current channel. A failed open leaves the current channel (if any) untouched.

If neither -c nor -o is specified, the available protocol types and default special device channels are listed. If there is a currently-open channel, it is also listed along with the protocol being used.

check [ -snb ] [ -PV ]

Check for the existence of the BIOS-APM firmware. The options are:

-s: Silent: if the BIOS-APM firmware exists, its configuration information is not printed. By default, the firmware's configuration is printed.
-n: Do not issue the appropriate commands to firmware; instead, just interpret the last response received.
-b: Instead of issuing the appropriate commands, interpret the equivalent information boot(HW) obtained.
-P: Print the operational parameters.
-V: Print the BIOS-APM firmware's version.

If none of -s, -P, or -V is specified, -PV is assumed. Some BIOS-APM firmware disallows this command if the firmware is currently connected.

connect -rwl

(Diagnostic command.) Establish a communications path between the firmware BIOS-APM and the operating system. A -r connection opens the Real Mode interface; -w opens the 16-bit Protected Mode interface; and -l opens the 32-bit Protected Mode interface. Exactly one of -r, -w, or -l must be specified. boot normally establishes a 32-bit Protected Mode interface. Unless that path is closed (``disconnected''), it should not be possible to open a new path but this depends on the machine's firmware. Most paths established by the connect command cannot be used by the operating system or any of the special files opened by the channel command.

diagnostics [ -ynvs ]

Enable, disable, and report on the dangerous or unsupported diagnostic commands. The -y option enables the diagnostic commands; -n disables those commands. -s suppresses reporting whether or not the commands are enabled; otherwise, or if -v is specified, pwrsh prints whether or not the diagnostic commands are enabled.

disable

Disable the BIOS-APM firmware. Exactly what this does depends on the firmware, but generally no active power monitoring or management occurs.

disconnect

Break all previously established paths between the operating system and the BIOS-APM firmware. It is usually impossible to re-establish a connection other than by rebooting. An automatic disconnection is usually done when the system shuts down.

enable

Enable the BIOS-APM firmware. This should reverse whatever the disable command does to the machine's BIOS-APM firmware; generally, active power monitoring and management resumes.

error [ * ] [ value ] ...

Print a description of BIOS-APM error code value, or of all known errors if * is specified. If no arguments are given, any error reported by the last command issued to the firmware is explained.

flush [ -s ] -qrwb ...

Discard PM events previously obtained by the operating system (usually by polling the BIOS-APM firmware) but not yet read by pwrd or the poll command.

-s: Silent: no error messages are printed.
-q: Flush the pwr PM events queue.
-r: Flush the current channel's STREAMS read queue.
-w: Flush the current channel's STREAMS write queue.
-b: Flush both the read and write queues.

The queues are flushed in the order specified by the options.

freq [ -s ] [ -d | ms ]

Set or print the frequency the operating system polls the BIOS-APM firmware.

-s: Silent: The frequency is not printed.
-d: Set the frequency to the value defined as POLLFREQ in /etc/default/pwr, or to 1000 milliseconds (one second) if not defined.
ms: Set the polling frequency to ms milliseconds; a value of 0 disables polling.

Unless the -s option is specified the polling frequency is printed. Typically the BIOS-APM is not automatically polled by the operating system until pwrd is started.

help [ -usda ] [ command ] ...

(Aliased as ?.) Print information about the given commands. If no commands are specified, information about all enabled commands is printed. The options include:

-u: Print the commands usage reminder.
-s: Print a short summary of command.
-d: Print a longer description of command.
-a: Do not consider disabled (diagnostic) commands invisible.

If no commands or more than one command is specified, the usage reminder (-u) is always printed. If any commands and no options are specified, -us (usage and summary) is assumed.

idle: Slow or stop the CPU until the BIOS-APM firmware detects some activity. A busy command restores a slow CPU to full-speed operation.
include file: Read pwrsh commands from file.

lock [ -s ] [ -u | -tdp ]

Lock this process into core, unlock it, or print what is currently locked into core.

-s: Silent: does not print what is locked.
-u: Unlock everything from core.
-t: Lock text (code) into core.
-d: Lock data and stack into core.
-p: Lock entire process into core.

The -u option cannot be specified with any of the -t, -d, or -p options.

poll [ -sne ]

Get the next PM event, if any, from the BIOS-APM firmware. The options include:

-s: Silent: if there was a waiting event, do not print it.
-n: Do not issue any commands to the firmware. Instead, interpret the results of the last command issued.
-e: Consider lack of any PM event an error. Normally, not obtaining any PM event is not considered an error.

print [ message ]

Print message on the standard output.

quit [ status ]

(Or EOF.) pwrsh exits with exit(S) code status. If status is not specified, the return code of the proceeding pwrsh command is used.

regs [ -cs ] [ name ] ...

Print machine registers passed to or returned by the BIOS-APM firmware. The -c option clears the error flag; -s sets it. If no names are specified, the error flag (%efl.cf) and value (%err), plus %eax, %ebx, %ecx, %edx, %esi, and %edi are printed.

restore

(Diagnostic command.) Restore BIOS-APM configuration to initial power-on values. What values are restored depends on the machine's firmware.

sched [ -s ] [ [policy@]priority ]

Print or set the operating system scheduling parameters for this pwrsh process and any subsequentially-spawned children. The policy is the method the operating system uses to choose this process to run (and influences how long the process subsequently runs):

nice: Traditional nice(S) round-robin scheduling: The numerically-lower the priority, the more likely this is to be chosen; once chosen the process runs for up to one second.
other: Same as nice except the priority values are in the natural order: The numerically-greater the priority, the more important the process.
rr: Strict round-robin: every process at the same priority is run in turn.
fifo: First-in-first-out: the highest priority process runs until it chooses not to.
value: The identifying number of some other system-defined scheduling policy.

The legal priority values depend on the policy. A priority of max makes the process the most important possible within the policy; similarly, min makes the process the least important within the policy. If no policy is specified the priority of the policy currently in use is changed.

Unless the -s option is given, the scheduling policy and priority are printed.

state -rifo device

state -rifo class,unit

Idle, make Ready, Freeze, or turn Off a peripheral (or the entire system).

-r: Make the peripheral Ready: fully powered up and available for immediate use.
-i: Idle the peripheral: reduces the power consumption without losing any data. If the peripheral is subsequently needed, it is automatically made Ready (possibly after a short delay).
-f: Freeze the peripheral: reduces the power consumption as far as possible without losing any data. If the peripheral is subsequently needed, it must first be explicitly made Ready.
-o: Turn the peripheral Off: no power is supplied to the peripheral. Data may be lost. If the peripheral is subsequently needed, it must first be explicitly made Ready.

Some BIOS-APM firmware can only Freeze the entire system, or turn Off individual peripherals.

The peripheral can be identified in one of two ways: either by a single direct identifier (device), or via an implied identity (class plus unit). device is a complete peripheral identifier:

all: The entire system.
bios: The BIOS-APM firmware itself.
system: Same as all.
A class is a BIOS-APM firmware-defined category of peripheral:
display: Video screen and keyboard (see screen(HW)).
parallel: Parallel I/O devices (see lp(HW)).
serial: Serial I/O devices (see sio(HW)).
storage: Hard and floppy discs (see hd(HW) and fd(HW)).
system: Miscellaneous parts, including the CPU itself and the BIOS-APM firmware (see uapm(HW)).
value: A number, which identifies a firmware-dependent peripheral category.
The unit is one or more peripherals defined by the BIOS-APM firmware within that class:
all: Every peripheral of that class.
value: A number, which is mapped by the firmware to one or more peripherals in class.

status [ -snb ] [ -AB ] [ test ]

Print the current power situation. The options include:

-s: Silent: the situation is obtained but not printed. By default, the situation is printed after being obtained.
-n: Do not issue the appropriate commands to firmware; instead, just interpret the last response received.
-b: Instead of issuing the appropriate commands, interpret the equivalent information boot obtained.
-A: Print the A/C mains power situation.
-B: Print the battery's situation.

The optional test is a hasapm(ADM) boolean expression which is evaluated if the status is successfully obtained.

If neither -s, -A, -B, or a test condition is given, -AB is assumed.

Warning

The check command does not return valid data nor errors after booting with all BIOS-APMs since it is not defined for the 32-bit Protected Mode BIOS-APM interface. However, it is always defied for the Real Mode interface, and so should always return valid data or errors to boot. The apm.check= bootstring allows boot to check whether APM is working.

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.

Careless use of the lock or sched commands may have an adverse affect on the system for other users.

Files