Input/Output Device Driver Reference/Advanced Power Management Architecture
Advanced Power Management Architecture
This chapter contains a brief description of the Advanced Power Management (APM) hardware and software architecture as it applies to the OS/2 operating system. Also included is a list of supported functions.
Refer to APM IOCtl Device Driver Test Tool for information on testing APM hardware.
Overview
Advanced Power Management is an industry standard that covers the division of responsibilities for power management between hardware and software. The Advanced Power Management Specification defines the Advanced Power Management BIOS Extension interfaces available to the operating system software layers. The OS/2 Power Management Subsystem supports and extends the Advanced Power Management Specification. The OS/2 operating system runs on and exploits the wide range of manufacturers' hardware that provides industry-standard Advanced Power Management BIOS Extensions.
The OS/2 Power Management Architecture is based on the APM 1.1 Architecture and includes functions specific to the OS/2 system components.
OS/2 APM Software Components
There are four major software components defined in the OS/2 Power Management Architecture:
- Power Object manages and tracks power consumption in battery-powered computers that support the APM standard. This component is provided in OS/ 2 but might be extended by APM-aware device drivers or APM BIOS vendors.
- APM Subsystem interacts with the APM BIOS, APM-aware device drivers, and the Power object to process power management state changes. This component is provided in OS/2.
- APM-Aware Device Drivers manage specific device details across power management state changes. There are numerous device drivers that can fit into this component category. Some of the OS/2-provided device drivers are APM-aware (such as MOUSE.SYS). Other OS/2 APM-aware device drivers are provided by OEM hardware manufacturers that produce power managed add-on devices (such as data/fax modems).
- APM BIOS encapsulates the underlying hardware characteristics and provides a consistent industry-wide function base for higher layers of software (such as OS/2). The APM BIOS component is provided by the Personal Computer Manufacturer (PCM) if the system is meant to provide power management capabilities. A machine's APM BIOS will support a given version of the APM Specification. OS/2 currently supports the Advanced Power Management Specification. Older machines may only support APM 1.0. Older versions of the APM Specification will not support all of the features of newer versions, and the following discussion makes note of these cases.
Power Object
As previously mentioned, the OS/2 Power object provides the GUI for power management actions. The complete explanation of the Power object GUI details are documented in the OS/2 V2.1 Update Redbook. In addition, the Power object provides a set of Workplace Shell* methods as an application programming interface (API). The complete explanation of the Power object methods are documented in the Presentation Manager Programming Reference for OS/2.
The Power object is located in the System Setup folder, which is located inside the OS/2 System Folder. The Power object is automatically installed on systems containing the APM BIOS interfaces. In addition, the user can selectively install the Power object (and subsystem) by way of the OS/2 Selective Installation procedures.
A useful tool to customize the Power Object Notebook is the OEM extensions. Some OEM computer vendors add additional power savings capabilities outside the 1.1 specifications and the OS/2 Power object adheres to the 1.1 specification. To provide the OEM extensions, replace the WPPower class and use the wpAddSettingsPages and wpInsertSettingsPage methods with a tab label of "Options".
The ability to perform an immediate conservation of power is controlled by way of selections in the object's pop-up menu. Any Power object extensions can be added in device-specific power state controls by subclassing the pop-up menu and adding or replacing specific menu selections. Furthermore, the conditional cascade menu control (right pointing arrow) should be used to provide the conditional cascade submenu with its additional suboptions. One of the cascaded submenu suboptions should be an "All" option that acts as a replacement for the existing system-wide menu option. A device specific option for the customized device support should also be added to the cascade submenu. The cascaded submenu option that is currently active (defined by check box control) is the option which will be executed when the pop-up menu option is selected.
Pop-up menu options are added by way of the wpModifyPopupMenu method. The OEM extension DLL code maps wpMenuItemSelected notifications for the "All" condition to the original pop-up menu option value. The extension passes the notification on to the OS/2 Power object for normal processing.
The following figure depicts the user's view of the topics previously discussed.
APM Subsystem
The OS/2 APM Subsystem provides the support hub for the OS/2 Power Management Architecture. The APM Subsystem provides both Category OCh Generic IOCtl interfaces for specialized applications (such as Power object) and an inter-device-driver communication (IDC) programming interface for APM-aware device drivers. Both the generic IOCtl and IDC interfaces are defined later in this section of the document.
The OS/2 APM Subsystem is contained in two separate files, APM.SYS and VAPM.SYS. The APM.SYS file is a physical device driver (PDD) and contains the key OS/2 APM Subsystem support (BIOS interactions, IDC and IOCtl interface support, and so on). The VAPM.SYS file is a virtual device driver (VDD) and contains power management support for the DOS and WIN-OS/2 application environments. The real DOS and Windows environments utilize the APM BIOS INT 15h, Ah=53h interfaces as well as the INT 2Fh broadcast interface for power state change notifications. These DOS and Windows interfaces are not supported in the DOS and WIN-OS/2 environments by the OS/2 VAPM.SYS device driver. The VAPM.SYS support simply rejects requests made to INT 15h, Ah= 53h by setting the returned AH value to 86h, indicating power management support functions are not available.
Because the APM Subsystem (APM.SYS) is the hub of the OS/2 Power Management support, it must be specified in the CONFIG.SYS file before the other power management components. If the APM BIOS is being implemented as an OS/2 device driver, then it must appear in the CONFIG.SYS file before the APM device driver. (See #APM BIOS for more details.) In addition, the APM Subsystem provides the following DEVICE= command line switches:
- /B
This switch directs APM.SYS to first locate and connect to the APM ROM BIOS. If the APM ROM BIOS support is not available, then the APM Subsystem will attempt to locate and connect to a device driver implementation of the BIOS support. - /D
This switch directs APM.SYS to first locate and connect to a device driver implementation of the BIOS support. If the device driver support is not available then the APM Subsystem will attempt to locate and connect to the APM ROM BIOS support. - /V version
This switch specifies the version of APM the OS/2 APM Subsystem should support. The default is to support the highest version of APM supported by both BIOS and the APM driver. This switch allows the APM Subsystem to run at a lower APM version, perhaps for compatibility reasons.
The version parameter is specified in the form d.d , where d is a digit. The following example specifies APM version 1.0: /V 1.0
Note: If no DEVICE= command line switch is specified then the /B option is used as the APM.SYS default switch setting.
The APM Subsystem IDC and IOCtl programming interfaces utilize the values defined by the Advanced Power Management Specification for the Power Management Device IDs and the Power Management States. (see #APM-Aware Device Drivers). Furthermore, Power Management Event Messages are utilized in the APM Subsystem IDC and IOCtl programming interfaces.
Power Management Event Messages
The OS/2 Power Management Subsystem uses a messaging, event-driven interface. The OS/2 Power Management event messages are summarized in the following figure, with message-specific parameter values. A client registers with the APM Subsystem to receive notification of power management events. IDC clients register a callback function to be invoked when a power management event occurs. Clients using the IOCtl programming interface are notified of power management events through a registered semaphore, and subsequent use of the Query Power Event function. Message names containing the word Event are reported directly from the Advanced Power Management BIOS interface. The other events are generated programatically through use of the Send Power Event function. Only a subset of the listed events can be generated by Send Power Event. Specifically, only event SubIds 0003h through 0006h, and 000Bh through 000Ch can be generated by Send Power Event.
Event SubIds 000Ah through 0010h are only available on systems running APM version 1.1 or higher. They are not available under APM version 1.0. An attempt to send an event which is not supported under the current APM version will return a PowerNotSupported error.
| OS/2 Power Management Event Messages | ulParm1 | ulParm2 | ||
|---|---|---|---|---|
| SubId | Reserved | (msg-specific) | ||
| Enable Pwr Mgt Functions | 0003h | 0000h | DevId | - - - |
| Disable Pwr Mgt Functions | 0004h | 0000h | DevId | - - - |
| Restore BIOS Defaults | 0005h | 0000h | - - - | - - - |
| Set Power State | 0006h | 0000h | DevId | PwrState |
| Battery Low Event | 0007h | 0000h | - - - | - - - |
| Normal Resume Event | 0008h | 0000h | - - - | - - - |
| Critical Resume Event | 0009h | 0000h | - - - | - - - |
| Standby Resume Event | 000Ah | 0000h | - - - | - - - |
| Engage Pwr Mgt Functions | 000Bh | 0000h | DevId | - - - |
| Disengage Pwr Mgt Functions | 000Ch | 0000h | DevId | - - - |
| Power Status Change Event | 000Dh | 0000h | - - - | - - - |
| Update Time Event | 000Eh | 0000h | - - - | - - - |
| OEM Defined APM Event | 000Fh | 0000h | EvtCode | - - - |
| Query Power State | 0010h | 0000h | DevId | PwrState |
| Note: All other values are reserved. | ||||
The general descriptions for each of the Power Management event message values follow.
Note: Many of the descriptions that follow use a C-language macro called MAKEULONG in the definition of the parameters. A description of MAKEULONG is included at the end of this section.
- Enable Power Management Function
Indicates that the Advanced Power Management BIOS request for power management assistance is being enabled, either for the entire system or a particular device or device class.- Parameters
SubId(USHORT) = 0003H DevId(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,0)
DevId is the ID of the device whose power management assistance is being enabled. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
Note: When running with APM version 1.0, DevId must be 0 or 1 (specifying all devices managed by APM), otherwise the error PowerNotSupported is returned.
-Notification Order
- Device Drivers
- Application Programs
- Disable Power Management Function
Indicates that the Advanced Power Management BIOS request for power management assistance is being disabled, either for the entire system or a particular device or device class.
-Parameters
SubId(USHORT) = 0004H DevId(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,0)
DevId is the ID of the device whose power management assistance is being disabled. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
Note: When running with APM version 1.0, DevId must be 0 or 1 (specifying all devices managed by APM), otherwise the error PowerNotSupported is returned.
-Notification Order
- Application Programs
- Device Drivers
- Restore BIOS Defaults
Indicates that the Advanced Power Management BIOS Restore BIOS Power-On Defaults request is being processed.
-Parameters
SubId(USHORT) = 0005H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Application Programs
- Device Drivers
- Set Power State
Indicates that an Advanced Power Management BIOS Set Power State function request is being processed.
-Parameters
SubId(USHORT) = 0006H DevId(USHORT) = (See below) PwrState(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,PwrState)
DevId is the ID of the device whose power state is being set. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
PwrState is the state to which the device is to be set. The set of power states supported by the Advanced Power Management Specification is listed in #Power Management States.
-Notification Order
- Application Programs
- Device Drivers
- Battery Low Event
Indicates that the Advanced Power Management BIOS has detected and notified the operating system that a Battery Low situation is occurring.
-Parameters
SubId(USHORT) = 0007H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Application Programs
- Device Drivers
- Normal Resume Event
Indicates that the Advanced Power Management BIOS has entered and exited a normal System Suspend situation and is notifying the operating system on the suspend exit.
-Parameters
SubId(USHORT) = 0008H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Device Drivers
- Application Programs
- Critical Resume Event
Indicates that the Advanced Power Management BIOS has entered and exited a critical System Suspend situation and is notifying the operating system on the suspend exit.
-Parameters
SubId(USHORT) = 0009H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Device Drivers
- Application Programs
- Standby Resume Event
Indicates that the Advanced Power Management BIOS has entered and exited a System Standby state and is notifying the operating system on the standby exit.
-Parameters
SubId(USHORT) = 000AH ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Device Drivers
- Application Programs
- Engage Power Management Function
Indicates that cooperative power management between BIOS and the operating system has been requested, either for the entire system or a particular device or device class.
-Parameters
SubId(USHORT) = 000BH DevId(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,0)
DevId is the ID of the device whose cooperative power management is being engaged. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
-Notification Order
- Device Drivers
- Application Programs
- Disengage Power Management Function
Indicates that BIOS will be automatically performing power management without operating system cooperation, either for the entire system or a particular device or device class.
-Parameters
SubId(USHORT) = 000CH DevId(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,0)
DevId is the ID of the device whose cooperative power management is being disengaged. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
-Notification Order
- Application Programs
- Device Drivers
- Power Status Change Event
Indicates that the system's power status has changed. A query power status call can be issued to obtain the system's current power status.
-Parameters
SubId(USHORT) = 000DH ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Device Drivers
- Application Programs
- Update Time Event
Indicates that the operating system may need to update its time by reading the hardware clock. This event is issued in cases where APM BIOS actions may have prevented the timer tick from being serviced.
-Parameters
SubId(USHORT) = 000EH ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0)
-Notification Order
- Device Drivers
- Application Programs
- OEM Defined APM Event
Indicates that the APM BIOS has raised an OEM defined event which is specific to the system currently being used.
-Parameters
SubId(USHORT) = 000FH EvtCode(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(EvtCode,0)
EvtCode is the OEM defined event code. The Advanced Power Management Specification defines the range of OEM defined events to be 0200H - 02FFH.
-Notification Order
- Device Drivers
- Application Programs
- Query Power State
Issued to query the power state of a device. This message is only sent to ring 0 device drivers who have registered to receive it through the IDC interface. It is not supported for ring 3 tasks using the IOCTL interface. It is generated by the APM Subsystem in order to determine the power state of a device from its device driver. This is particularly useful for devices which are not directly power managed by the machine's BIOS. Refer to the RegisterDDRtn function under #Power Management IDC Functions for more details on this event.
-Parameters
SubId(USHORT) = 0010H DevId(USHORT) = (See below) PwrState(USHORT) = (See below) ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(DevId,PwrState)
DevId is the ID of the device whose power state is being queried. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.
PwrState is the power state of the specified device. This field is an output parameter filled in by the device driver receiving the event. The set of power states supported by the Advanced Power Management Specification is listed in #Power Management States.
-Notification Order
- Device Drivers
MAKEULONG
In the previous descriptions, a C language-defined macro called MAKEULONG is sometimes used in the definition of the parameters. MAKEULONG is defined in OS2DEF.H and has the following syntax:
MAKEULONG(Low, High) /* Low and High are both 16-bit parameters. */
Leaving out the type-casting for simplicity, MAKEULONG translates to:
( (Low) | (High) << 16 )
An example is:
ULONG ulParm; ulParm = MAKEULONG(0x5678, 0x1234);
/* The statement above sets ulParm equal to 0x12345678 */
The first parameter to MAKEULONG becomes the low-order word, and the second parameter becomes the high-order word in the resulting 32-bit value.
Power Management IDC Interfaces
In the OS/2 operating system, there is an interface layer between the low-level subsystems and device driver clients. The mechanism for achieving this interface is based on IDC. For the OS/2 Power Management Services Layer, there are five IDC functions. The IDC functional interfaces and how they map to the Advanced Power Management BIOS Interfaces are defined in the following table:
| Advanced Power Management 1.1 BIOS Functions | OS/2 Power Management IDC Functions |
|---|---|
| Installation Check (00h) | QueryPowerInfo (0004h) |
| Interface Connect (01h) | N/A |
| Protect-Mode Connect 16-Bit (02h) | N/A |
| Protect-Mode Connect 32-Bit (03h) | N/A |
| Interface Disconnect (04h) | N/A |
| CPU Idle (05h) | N/A |
| CPU Busy (06H) | N/A |
| Set Power State (07h) | SendPowerEvent (0002h) |
| Enable/Disable Pwr Mgt Fcns (08h) | SendPowerEvent (0002h) |
| Restore BIOS Defaults (09h) | SendPowerEvent (0002h) |
| Get Power Status (0Ah) | QueryPowerStatus (0003h) |
| Get Pwr Mgt Event (0Bh) | RegisterDDRtn/DeregisterDDRtn (0000h)/(0001h) |
| Get Power State (0Ch) | QueryPowerState (0006h) |
| Enable/Disable Device Pwr Mgt (0Dh) | SendPowerEvent (0002h) |
| APM Driver Version (0Eh) | N/A |
| Engage/Disengage Pwr Mgt (0Fh) | SendPowerEvent (0002h) |
| OEM APM Function (80h) | OEMAPMFunction (0007h) |
An OS/2 physical device driver (PDD) accesses the power management services by calling the power management device driver's IDC entry point. This address is obtained using the DevHlp_AttachDD interface. The name "APM$", (APM$, followed by four blank characters) is passed to AttachDD as the power management device driver name.
Before calling the power management device driver, the client device driver must create a data structure and fill in the appropriate parameters. The first member of the structure is a WORD that identifies the function being requested. The rest of the data structure contains the parameters for that function.
The client then loads a Selector:Offset pointer to the structure into ES:BX and calls the Power Management IDC interface. There is no need to set the Power Management Data Selector before the call.
On entry to the Power Management IDC routine, ES:BX points to a data structure of the following format:
Function WORD ; IDC function code, as defined below.
Parameters BYTE(?) ; Parameter packet, as defined below.
; A different parameter packet is defined
; for each IDC service.
These IDC interfaces are only available at task time. They are not available at initialization or interrupt time. The Power Management device driver processes the call and returns the Return Code in AX. AX is set to 0 and the Carry flag is cleared on a successful call. On error, AX is guaranteed to be nonzero and the Carry flag is set.
Power Management IDC functions are callable only in kernel-context mode.
Power Management IDC Functions
The OS/2 Power Management IDC function codes are the values in the first WORD of the data structures submitted to the Power Management device driver. The codes are defined as follows:
| Length | Value | Function |
|---|---|---|
| WORD | 0 | RegisterDDRtn |
| 1 | DeregisterDDRtn | |
| 2 | SendPowerEvent | |
| 3 | QueryPowerStatus | |
| 4 | QueryPowerInfo | |
| 6 | QueryPowerState | |
| 7 | OEMAPMFunction | |
| All other values are reserved. | ||
The OS/2 Power Management IDC functional descriptions are defined as follows:
Power Management IDC Function 0 - RegisterDDRtn
The RegisterDDRtn function is used by a Power-Management-sensitive device driver so that it will be notified of Power Management events. These Power Management events are synchronous messages. The caller provides the following parameter information:
-Parameters
| Field | Type | Length |
|---|---|---|
| Handle | USHORT | WORD |
| EventHandler | PRM | DWORD |
| NotificationMask | ULONG | DWORD |
| ClientDS | SEL | WORD |
| DeviceID | USHORT | WORD |
Where the fields are interpreted as follows:
--Handle
Output parameter. The unique handle value for the registered event-handler routine information. When registered, a device driver is required to perform a DeregisterDDRtn request to disconnect the registered routine.
--EventHandler
Input parameter. The calling device driver's Selector:Offset value of the calling device driver's Event Handler routine.
--NotificationMask
Input parameter. The bit mask indicating the power management events on which the calling device driver is to receive notifications. A set bit ( value = 1) indicates power management event notification selection. The Notification Mask bit definitions are as follows:
BIT # MEANING
- 3 Enable Power Management
- 4 Disable Power Management
- 5 Restore BIOS defaults
- 6 Set power state
- 7 Battery Low event
- 8 Normal Resume event
- 9 Critical Resume event
- 10 Standby Resume event
- 11 Engage Power Management
- 12 Disengage Power Management
- 13 Power Status Change event
- 14 Update Time event
- 15 OEM Defined APM event
- 16 Query Power State
- All other bits are reserved.
Events associated with bits 10 through 16 are supported by APM version 1.1, but not APM version 1.0. Selecting to receive notification for events not supported under the current version of APM will not cause an error. See Power Management Event Messages for more details on the Power Management Events previously described.
--ClientDS
Input parameter. The calling device driver's Data Segment Selector value. This value is loaded into the DS register when the Event Handler Routine is invoked.
--DeviceID
Input parameter. The ID of the device. The set of device types supported by the Advanced Power Management Specification is listed in Power Management Devices. This parameter can be used to restrict the notification of power state changes. The parameter normally is set to 0001H, which selects all BIOS-managed devices. However, if the parameter is set to some other value that selects a particular device type, the client receives notification on power transitions only on that particular device. For example, the driver registers with DeviceID set to 02FF (all disk devices). The Event Handler routine is called at the following times:
-When the entire system is entering or exiting Standby or Suspend mode
-When only a disk is entering or exiting Standby or Suspend modes.
The Event Handler routine is not invoked, however, when, for example, only a display is entering Standby.
-Event Handler Calling Conventions
When a Power Management Event is triggered, the Power Management device driver formats an Event Handler Packet (as defined below), stores a 16:16 pointer to the packet in ES:BX, sets the client's DS selector, then calls the client device driver.
Registered device-driver Event Handler routines are called with the following power management event-related information and conditions:
| Field | Type | Length |
|---|---|---|
| Function | USHORT | WORD |
| ulParm1 | ULONG | DWORD |
| ulParm2 | ULONG | DWORD |
Where the fields are interpreted as follows:
--Function
Input parameter. Must be the following value:
-Event Notification = 0000H. All other values are reserved.
--ulParm1
Input parameter. See
the previous figure "Power Management Event Messages and Parameter Values" and Power Management Event Messages for value descriptions.
--ulParm2
Input/Output parameter. See the previous figure "Power Management Event Messages and Parameter Values" and Power Management Event Messages for value descriptions.
The Power Management device driver loads the DS register and calls the Event Handler routine address with the values established using the RegisterDDRtn function.
The Event Handler routine is guaranteed to be called only in kernel-context mode by the Power Management device driver.
On return from the Event Handler routine, the AX register is used to indicate whether or not the notification request was accepted or rejected. An accepted request is noted by an AX register value of zero. A rejected request is noted by a nonzero AX register value. If a notification request cannot be supported due to pending device activity or an indeterminate device state it is valid for the device driver to fail the request.
All other register values are preserved across the call by the Event Handler routine.
The OS/2 APM Subsystem performs special processing of the return values for the following events.
--Set Power State to Suspend
If a device driver fails a Suspend Event request (indicated by returning a nonzero value in AX), the APM Subsystem will generate an artificial Resume Event to reset the device drivers that have already processed, and accepted , the failed Suspend Event request. Those registered device drivers that did not see the Suspend Event would also not see the Resume Event.
--Query Power State
When this event is received, the device driver should determine whether or not it supports the device specified by the DevId parameter. If so, and the power state of the device is known, it should report the power state by updating the PwrState field in the event message packet, and return success by setting AX to 0. Otherwise, it should fail the query by setting AX to a nonzero return code.
Power Management IDC Function 1 - DeregisterDDRtn
The DeregisterDDRtn function is used by an APM-aware device driver to disconnect a registered event-handler routine. Disconnection is necessary for proper cleanup in cases where a device driver de-installs itself after registration has occurred.
-Parameters
| Field | Type | Length |
|---|---|---|
| Handle | USHORT | WORD |
Where the field is interpreted as follows:
--Handle
Input parameter. The unique handle value for the device driver's registered event-handler routine. This value is returned from a successful request to the RegisterDDRtn function.
-Remarks
None.
Power Management IDC Function 2 - SendPowerEvent
The SendPowerEvent function enables an APM-aware device driver to send a power management event message to Power Management Services. Power Management Services process power management event messages sent by the device driver in the same manner as power management BIOS and user interface requests. This function might not return to the caller until the request and associated activities are completed.
The caller provides the following parameter information:
-Parameters
| Field | Type | Length |
|---|---|---|
| ulParm1 | ULONG | DWORD |
| ulParm2 | ULONG | DWORD |
See the previous figure "Power Management Event Messages and Parameter Values" for the parameter values. All unused parameter fields should be set to a value of 0. Refer to Category OCh, Function 40h, "Send Power Event" in the OS/2 Physical Device Driver Reference for more information.
This function must not be called if the caller is running under the context of the IDC-registered device driver event-handler routine. In addition, this function must not be called when running in an interrupt context.
Power Management IDC Function 03h - QueryPowerStatus
The QueryPowerStatus function is used by an APM-aware device driver to determine the current power source status.
-Parameters
| Field | Type | Length |
|---|---|---|
| ParmLength | USHORT | WORD |
| PowerFlags | USHORT | WORD |
| ACStatus | BIT 8 | BYTE |
| BatteryStatus | BIT 8 | BYTE |
| BatteryLife | BIT 8 | BYTE |
| BatteryTimeForm | BIT 8 | BYTE |
| BatteryTime | USHORT | WORD |
| BatteryFlags | BIT 8 | BYTE |
-Remarks
None.
Refer to Category OCh, Function 60h, "Query Power Status" in the OS/2 Physical Device Driver Referencefor more information.
Power Management IDC Function 04h - QueryPowerInformation
The QueryPowerInfo function is used by an APM-aware device driver to determine the power configuration and revision-level information.
-Parameters
| Field | Type | Length |
|---|---|---|
| ParmLength | USHORT | WORD |
| BIOSFlags | USHORT | WORD |
| BIOSVersion | USHORT | WORD |
| SubsysVersion | USHORT | WORD |
| APMVersion | USHORT | WORD |
-Remarks
None.
Power Management IDC Function 06h - QueryPowerState
The QueryPowerState function is used by an APM-aware device driver to determine the current power state of a device, class of devices, or the entire system.
-Parameters
| Field | Type | Length |
|---|---|---|
| ParmLength | USHORT | WORD |
| DeviceId | USHORT | WORD |
| PowerState | USHORT | WORD |
-Remarks
This function is not supported under APM version 1.0.
Refer to Category OCh, Function 63h, "Query Power State" in the OS/2 Physical Device Driver Referencefor more information.
This function must not be called if the caller is running under the context of the IDC-registered device driver event-handler routine. In addition, this function must not be called when running in an interrupt context.
Power Management IDC Function 07h - OEMAPMFunction
The OEMAPMFunction provides access to hardware dependant OEM defined APM functions. Since BIOS APM functions use a register passing interface, the parameter packet structure for this function facilitates general purpose register passing.
-Parameters
| Field | Type | Length |
|---|---|---|
| ParmLength | USHORT | WORD |
| Flags | USHORT | WORD |
| EAX | ULONG | DWORD |
| EBX | ULONG | DWORD |
| ECX | ULONG | DWORD |
| EDX | ULONG | DWORD |
| ESI | ULONG | DWORD |
| EDI | ULONG | DWORD |
| DS | USHORT | WORD |
| ES | USHORT | WORD |
| FS | USHORT | WORD |
| GS | USHORT | WORD |
-Remarks
This function is not supported under APM version 1.0.
Refer to Category OCh, Function 45h, "OEM APM Function" in the OS/2 Physical Device Driver Reference for more information.
IDC Error Codes
In addition to the error codes listed under the IOCtl return errors (see Power Management IOCtl Interfaces), the following error codes pertain to IDC functions:
| Decimal Value | Name (Hex Value) and Description |
|---|---|
| 128 | PowerIDC_InvalidFunction (0080h). IDC function code out of range. |
| 129 | PowerIDC_InvalidHandle (0081h). IDC handle invalid. |
| 130 | PowerIDC_TooManyClients (0082h). Maximum number of IDC clients exceeded. |
| 131 | PowerIDC_Busy (0083h). The request cannot be serviced at this time due to pending activity that must be completed. The caller must determine whether to wait and reissue the request, proceed anyway, or end the activity. |
Power Management IOCtl Interfaces
The OS/2 operating system contains an interface layer between the low-level subsystems and the user interface environment. A typical mechanism for bridging these layers when device drivers are involved is the generic IOCtl interface. For the OS/2 Power Management Services Layer, the generic IOCtl category value of OCh (12) is used for this interface. The function codes supported are defined with the following common descriptions:
- Set/Send functions = 0100xxxxB
- Get/Query functions = 0110xxxxB
The generic IOCtl interfaces and how they are mapped to the Advanced Power Management BIOS Interfaces are defined in the following table:
| Advanced Power Management 1.1 BIOS Functions | OS/2 Power Management IOCtls |
|---|---|
| Installation Check (00h) | Query Power Info (Function 62h)*** |
| Interface Connect (01h) | N/A |
| Protect-Mode Connect 16-Bit (02h) | N/A |
| Protect-Mode Connect 32-Bit (03h) | N/A |
| Interface Disconnect (04h) | N/A |
| CPU Idle (05h) | N/A |
| CPU Busy (06h) | N/A |
| Set Power State (07h) | Send Power Event (Function 40h) |
| Enable/Disable Pwr Mgt Fcns (08h) | Send Power Event (Function 40h) |
| Restore BIOS Defaults (09h) | Send Power Event (Function 40h) |
| Get Power Status (0Ah) | Query Power Status (Function 60h) |
| Get Pwr Mgt Event (0Bh) | Query Power Event (Function 61h) |
| N/A | Set Power Event Resources (Function 41h) |
Note:
- Some of the information available in the Installation Check function is made available in the Query Power Information IOCtl. Refer to the OS/2 Physical Device Driver Referencefor descriptions of the IOCtls.
The possible error codes returned by the Power Management IOCtl Interfaces are defined in the following table:
| Decimal Value | Name | Description |
|---|---|---|
| 0 | PowerNoError | No error. |
| 1 | PowerBadSubId | Invalid SubId specified for Send Power Event. |
| 2 | PowerBadReserved | Reserved field not set to 0. |
| 3 | PowerBadDevId | Invalid or unsupported device ID. |
| 4 | PowerBadPwrState | Invalid power state specified. |
| 5 | PowerSemAlreadySetup | Set Power Event semaphore already set up. |
| 6 | PowerBadFlags | Invalid Set Power Event request flags. |
| 7 | PowerBadSemHandle | Semaphore doesn't match the one used to setup event queue. |
| 8 | PowerBadLength | Invalid ParmLength field value. |
| 9 | PowerDisabled | Power management is disabled. |
| 10 | PowerNoEventQueue | Attempt to query event with no event queue. |
| 11 | PowerTooManyQueues | Unable to create event queue (reached limit). |
| 12 | PowerBiosError | BIOS returned an error. |
| 13 | PowerBadSemaphore | Set Power Event invalid semaphore. |
| 14 | PowerQueueOverflow | Event queue overflow occurred. |
| 15 | PowerStateChangeReject | The requested power state cannot be entered. |
| 16 | PowerNotSupported | Attempt to use a function not supported by current APM version. |
| 17 | PowerDisengaged | Power management is disengaged. |
APM-Aware Device Drivers
APM-aware device drivers provide the device-specific knowledge for managing power management events for their device. Typically, device drivers understand what activities are pending in their device queues and know what effects a given power state has on their device. An APM-aware device driver can choose among several schemes to manage the device. The following are some of the most common device management schemes for access requests (read/write) when the device is powered-off:
- Queue up the request
- Fail the request
- Change the current power state and process the request
An OS/2 APM-aware device driver must be written as an OS/2 physical device driver (PDD). The PDD can be defined as a level-3 device driver by setting Bit 4 (value=1) in the Capabilities Bit Strip of the device driver header. By using the level-3 PDD support APM-aware device drivers can simplify CONFIG.SYS ordering problems and utilize the INIT_COMPLETE (1Fh) command. All OS/2 APM-aware device drivers must form an IDC interface link with the OS/2 APM Subsystem in order to get notifications of power events. (See #Power Management IDC Functions for more details.)
There are numerous ways an APM-aware device driver can be optimized for size, speed, maintenance, and so on, which also applies to the driver initialization phase. For instance, a common initialization scenario for APM-aware device drivers is:
- During the INIT command (00h) processing, the driver issues the DevHelp_ AttachDD call to determine if the APM System is present.
- If present, the driver sets up to support power management activities ( such as locking power management code segments).
- If not present, the driver may streamline itself (such as discarding power management code/data areas) for non-power managed environments.
- During the INIT_COMPLETE command (1Fh) processing the driver issues a Far Call to the APM Subsystem IDC entry point to register itself as an APM- aware device driver. (See #Power Management IDC Functions for more details.)
Note:The above scenario has a driver ordering dependency in the CONFIG. SYS file such that the APM Subsystem (APM.SYS) must be loaded first.
An APM-aware device driver can have accompanying user interface requirements for the device specific functions and features. The typical OEM APM-Aware device driver scenario includes:
- The APM-aware device driver, which exports user-defined generic IOCtls for GUI/application level interactions and utilizes the APM Subsystem IDC interface for power event interactions.
- A Dynamic Link Library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls.
- An installation program to copy the files into an OS/2 environment and form the execution linkages (such as device driver, Power object DLL subclassing, and so on).
Be sure to note that not all devices can be or should be managed by an APM-aware device driver. For example, device IDs not supported by the Advanced Power Management Specification are also not supported in OS/2 as being power manageable. In addition, some common devices (internally powered) are completely managed by the vast majority of available APM BIOS implementations so that APM-aware device drivers are not needed. There are three key elements that help define whether an APM-aware device driver should be developed for a given device. These three elements are:
- APM device IDs, which are defined by the Advanced Power Management Specification.
- Power supply, which is defined by the device environment and determines if the APM BIOS is aware of the device existence. It also determines whether the device draws current internally or externally.
- Effects of power management states on the device, (power supply and device capabilities).
Power Management Devices
The device types supported by the Advanced Power Management Specification are:
- System BIOS (0000h)
Device ID for Advanced Power Management BIOS - System BIOS-managed devices (0001h)
Generic device ID for all devices managed by Advanced Power Management BIOS. - Display devices (01xxh)
Generic device ID for display devices - Secondary storage devices (02xxh)
Generic device ID for secondary storage devices - Parallel ports (03xxh)
Generic device ID for parallel ports - Serial ports (04xxh)
Generic device ID for serial ports - Network adapters (05xxh)
Generic device ID for network adapters - PCMCIA sockets (06xxh)
Generic device ID for PCMCIA sockets - OEM defined power device IDs (E000h - EFFFh)
Range of IDs to be used by OEM devices
Note:
- XXindicates the physical device number (0-based)
- All other device-type values are reserved
- Devices powered with external system unit power supplies are not supported
- Device IDs 05xxh and higher are only supported by version 1.1 or higher of APM
Internal/External Power
An internally powered deviceis one that draws current from the system unit 's power supply and has a direct line from the power supply that can be independently and uniquely controlled. An externally powered deviceis one that draws current from either a power supply outside the system unit's power supply or from an internal device that has no independent or unique control over the power line. For example, an asynchronous serial port (COM) is an internally powered device, whereas the mouse connected to a COM port is considered an externally powered device because the current supply is not unique to the mouse.
Power Management States
OS/2 device drivers should support, with appropriate device actions, the following set of power states supported by the Advanced Power Management Specification.
- Ready (0000h)
This state indicates that the system or device is operating at full power. Ready state responsibilities include:- Enter State
Actions to enter this state are more accurately defined by the prior state involved in the state transition, particularly for externally powered devices. - State Operations
Operates at maximum throughput for device performance. - Exit State
Actions to exit this state are more accurately defined by the next state involved in the state transition, particularly for externally powered devices.
- Enter State
- Standby (0001h)
This state indicates that the system or device is operating at a partial power level that permits energy conservation without noticeable delays in restoring power for reestablished operation.
Standby state responsibilities include:- Enter State
The current device state can be saved in RAM for most devices (both internal and external). - State Operations
The device is isolated from unnecessary commands and status activities that would consume power by bringing the device out of Standby. Useful commands can be processed by changing the state saved in RAM rather than programming the device immediately. - Exit State
If a RAM-saved state is available and the saved information is modified during the Standby period, the saved values can be activated as delayed commands. As a rule, internally powered devices need not have additional support for this state. However, externally powered devices (for example, those that draw power from a port) must have device-state Save and Restore support.
Note: There is no explicit Resume notification for the Standby state. The implicit Standby Resume is based on the next time the associated code is invoked.
- Enter State
- Suspend (0002h)
This state indicates that the system or device is operating at a partial power level that permits substantial energy conservation with accepted noticeable delays in restoring power for reestablished operation.
The Advanced Power Management Specification defines the Suspend power state as system-wide and does not currently support it as device-specific. The OS/2 architecture supports both system and device levels of usage as a desired deviation from the public standard. Suspend state responsibilities include:- Enter State
All externally powered devices must have their device-state information saved in a RAM data area. Similarly, all internally powered devices must have their device-state information saved when the Suspend is on a device level rather than on a system/BIOS level. Because no processing is permitted in the System Suspended state, internally powered devices can be saved by the Advanced Power Management BIOS. - State Operations
Because processing is not performed during this state, there are no in-state operation requirements for system/BIOS requests. However, for a Device Suspend (versus a system/BIOS Suspend), the device driver must provide the isolation layer between the device and the applications. - Exit State
All externally powered devices that had their former state information saved are reconfigured to bring them back to the pre-Suspend operating mode. Internally powered devices are also brought back to the pre-Suspend operating mode when a device-level Suspend exits.
- Enter State
- Off (0003H)
This state indicates that the system or device is not operating or receiving any amount of power. OFF state responsibilities include:- Enter State
Actions to enter this state include complete device shutdown and disconnection from application environments. Because the device is not recoverable when this state is entered, all parameters used for reconnection must be saved to disk if needed and applicable. - State Operations
The device is now completely unavailable, and there is no operational activity. - Exit State
Actions to exit this state are currently defined only as a restart of the entire system environment (both hardware and software).
- Enter State
- OEM Defined System State (0020h - 03Fh)
This range of states may be used to define OEM system states. - OEM Defined Device State (0040h - 07Fh)
This range of states may be used to define OEM device states.
All other power state values are reserved.
APM BIOS
The APM BIOS is the single most important piece of the OS/2 Power Management Architecture because all higher layers of software components are dependent upon its presence and function. The APM BIOS interfaces are significant because they define basic parameters values utilized in the higher software layers as well as the ability for the APM Subsystem to locate and connect to the APM BIOS support. There are two basic parameters (Power Management Device IDs and Power Management States) defined by the APM BIOS interfaces which are utilized within the APM Subsystem IDC and IOCtl interfaces. The details for both the Power Management Device IDs and Power Management States are defined in APM-Aware Device Drivers.
The OS/2 Power Management Architecture allows the traditional APM ROM BIOS support to be built as an OS/2 physical device driver (PDD). This construction facilitates a field upgrade capability for computer manufacturers which may have the desire to supplement existing support or even the ability to add APM BIOS to systems which were not built with it initially. Details for the APM Subsystem interactions and dependencies on these two APM BIOS implementation options are defined later in this document.
The following table defines whether or not the Industry Standard APM BIOS 1.1 Interface functions are used or required by the OS/2 APM Subsystem.
| APM 1.1 BIOS Functions | Required for OS/2 |
|---|---|
| Installation Check (00h) | Yes |
| Interface Connect (01h) | No |
| Protect-Mode Connect 16-Bit (02h) | Yes** |
| Protect-Mode Connect 32-Bit (03h) | Yes** |
| Interface Disconnect (04h) | No |
| CPU Idle (05h) | Yes |
| CPU Busy (06h) | Yes |
| Set Power State (07h) | Yes |
| Enable/Disable Pwr Mgt Fcns (08h) | Yes |
| Restore BIOS Defaults (09h) | Yes |
| Get Power Status (0Ah) | Yes |
| Get Pwr Mgt Event (0Bh) | Yes |
| Get Power State (0Ch) | Yes |
| Enable/Disable Device Pwr Mgmt (0Dh) | Yes |
| APM Driver Version (0Eh) | Yes |
| Engage/Disengage Pwr Mgmt (0Fh) | Yes |
| OEM APM Function (80h) | Yes |
Note:** Only one of these functions is required per BIOS implementation.
ROM BIOS
During OS/2 system initialization processing, the APM ROM BIOS support is queried. The BIOS query is performed using the INT 15h, APM Installation Check Function (AH=53h AL=00h). The returned information is saved and made available to device drivers by way of the DevHelp_GetDOSVar function call (index parameter value = 16). The returned data is checked (if an APM BIOS is present) for the types of interface connections supported (real mode, protect-mode 16 bit, or protect-mode 32 bit). OS/2 will attempt to connect to the APM BIOS using the protect-mode 16-bit interface, if available. If the protect-mode 16-bit interface is not available then OS/2 will try to connect to the APM BIOS using the protect-mode 32-bit interface. If neither of the protect-mode options are available then OS/2 will end the connection processing.
When the APM Subsystem (APM.SYS PDD) loads (with either a /B option or a failed /D option) it issues the DevHelp_GetDOSVar (index = 16) request to determine if the APM ROM BIOS is available. If so, APM.SYS will check which interface connection mechanism was established with the APM BIOS and begin using it to setup the OS/2 environment variables. See the OS/2 Required APM BIOS functions defined in the previous table.
BIOS Device Driver
When the APM Subsystem (APM.SYS PDD) loads (with either a /D option or a failed /B option) it attempts to locate and connect to a device driver implementation of APM BIOS. This connection is performed by issuing a DevHelp_AttachDD function call specifying a device name of "APMBIOS$". A successful function return provides APM.SYS with the protect-mode 16-bit IDC interface, which APM.SYS will treat as the standard APM BIOS protect- mode 16-bit connected interface. (See the OS/2 Required APM BIOS Functions defined in APM BIOS). An APM BIOS Device Driver must be an OS/2 physical device driver (PDD) with a device name of "APMBIOS$" defined in the Device Driver Header.
There are some differences between the APM BIOS Device Driver implementation and the APM ROM BIOS implementation for supported APM BIOS interfaces. These differences are:
- Protect-mode 16-bit interface is the only mode supported.
- No protect-mode 16-bit connection request needed. It is the default interface mode as opposed to the real mode default of ROM BIOS implementations.
- The Installation Check function will be issued in protect-mode 16-bit to determine BIOS driver capabilities. (As opposed to the real-mode definition for ROM BIOS implementations.)
All other calling conventions, register usage, and parameter definitions are preserved as defined by the Advanced Power Management Specification. The APM BIOS device driver interfaces are based upon the BIOS conventions rather than OS/2 IDC conventions. For instance, the APM BIOS device driver must set up its own DS register value when invoked rather than assuming it is done by the caller. All register values, except those identified as having return values, must be preserved across function request as is normal practice with BIOS requests.
It is quite probable that APM BIOS extensions implemented as device drivers will have accompanying user interface requirements for the added functions and features. The typical OEM APM BIOS Extension scenario includes:
- The APM BIOS device driver, which exports user-defined generic IOCtls for GUI/application level interactions and emulates the APM 1.1 BIOS interface (by way of IDC) for the APM Subsystem interactions.
- A dynamic link library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls.
- An installation program to copy the pieces into an OS/2 environment and form the execution linkages (such as device driver, Power object DLL subclassing, and so on).