4.8 Power Management Services

The following subsections describe the Plug and Play support for allowing interaction with Advanced Power Management (APM) 1.1 and greater.

4.8.1 Function 0Bh - Get APM ID Table

Synopsis:


int FAR (*entryPoint)(Function, Bufsize, ApmIdTable, BiosSelector);     
int Function;               /* PnP BIOS Function 0Bh */
unsigned int FAR *BufSize;  /* Size of buffer to copy APM ID table to */
unsigned char FAR *ApmIdTable; /* Address of caller's buffer for*/
                               /*the table */
unsigned int BiosSelector;     /* PnP BIOS readable/writable selector */

Description:

Required for Power Management. This function will copy the table of APM 1.1 (or greater) device identifier to Plug and Play device identifier mappings to the buffer specified by the caller. This allows the operating system to use the APM interface to perform power management on individual devices controlled by the system BIOS. If BufSize indicates that the buffer is not large enough to contain the entire table, the system BIOS will return BUFFER_TOO_SMALL and the size of the buffer required to contain the entire table will be returned in the caller's BufSize parameter. Therefore, the caller can call this function with BufSize equal to 0 to determine the size of the buffer it needs to allocate for the APM identifier table. The apmIDTable argument contains the pointer to the caller's memory buffer. If the buffer is large enough, on return apmIDTable will contain the APM identifier table. Each entry in the table will be specified in the following format:

Field

Length

Value

Device identifier

DWORD

Varies

APM 1.1 identifier (version 1.1 or greater)

WORD

Varies


Device Identifier:

This field is the Plug and Play device identifier. The Logical Device ID provides a mechanism for uniquely identifying multiple logical devices embedded in a single physical board. The format of the logical device ID is composed of three character compressed ASCII EISA ID and a manufacturer specific device code.

APM identifier:

This element specifies the corresponding APM device identifier.

An APM identifier table with multiple entries would be described as follows:

Field

Device identifier #1

APM identifier #1

Device identifier #2

APM identifier #2

:

:

Device identifier #n

APM identifier #n


This call supports APM version 1.1 or greater. The APM interface INT 2Fh supports a get version call.

The BiosSelector parameter enables the system BIOS, if necessary, to update system variables that are contained in the system BIOS memory space. If this function is called from protected mode the caller must create a data segment descriptor using the 16-bit Protected Mode data segment base address specified in the Plug and Play Installation Check data structure, a limit of 64K, and the descriptor must be read/write capable. If this function is called from real mode, BiosSelector should be set to the Real Mode 16-bit data segment address as specified in the Plug and Play Installation Check structure. Refer to section 4.4 above for more information on the Plug and Play Installation Check Structure and the elements that make up the structure.

This function is available in real mode and 16-bit protected mode.

Example scenario: An operating system provides a device driver level-interface to both the Plug and Play BIOS as well as the APM 1.1 (or greater) interface. An OEM or third party wishes to write a Plug and Play device driver for a device built into the system in order to provide enhancements available through operating-system services. However, he also wishes to power manage the device using support already available in the machine's APM 1.1 implementation. This function provides a means for the device driver to determine which Plug and Play identifiers have corresponding power management support through an APM 1.1 device identifier.

Returns:

0 if successful - SUCCESS
!0 if an error (Bit 7 set) or a warning occurred - error code (The function return codes are described in Appendix C)

The FLAGS and registers will be preserved, except for AX which contains the return code.

Example:

The following example illustrates how the 'C' style call interface could be made from an assembly language module:


          .
          .
          .
     push    Bios Selector     
     push    segment/selector of APM Id table       ; pointer to APM Id
                                                    ; table buffer
     push    offset of APM Id table     
     push    segment/selector of table buffer size  ; pointer to APM Id
                                                    ; table buffer size 
     push    offset of APM Id table buffer size
     push    GET_APM_TABLE                          ; Function 0Bh
     call    FAR PTR entryPoint      
     add     sp,12                                  ; Clean up stack
     cmp     ax,SUCCESS                             ; Function completed
                                                    ; successfully?
     jne     error                                  ; No-handle error
                                                    ; condition
          .
          .
          .