4.6 Event Notification Interface

Certain classes of systems may provide the capability for the addition or removal of system devices while the system unit is powered on, such as inserting a Notebook unit into a Docking Station. System BIOS support is necessary for providing Event Notification accessible to system software so that when devices are added or removed the system software will comprehend the use or release of system resources by those devices. Event Notification can be implemented as either a polled method or as asynchronous events. System software can check the Control Word, which is located in the BIOS Plug and Play Header structure, to determine the Event Notification method supported on the system. Refer to the Plug and Play Installation Check section for more information on the BIOS Plug and Play Header and the Control Word. The Control Word has bits defined that indicate the type of Event Notification. The BIOS Plug and Play Header structure also contains the Event notification flag address, which specifies the physical location of the Event Flag for polling. The Event Flag is the event polling location. When a system event occurs bit 0 of the Event Flag will be set to indicate a pending event. Therefore, if the method for Event Notification is through polling, system software should monitor the Event Flag to determine when a configuration event has occurred.

The asynchronous method of Event Notification allows system software to install an interrupt handler as a means for notification. The system BIOS will specify a system device node, which can be obtained from the Get Node runtime function, that will specify the requirements for handling asynchronous events. The system device node for asynchronous event management will be identified through the device identifier field in the device node data structure, and will specify the interrupt number and an I/O port address. This event system device node can be defined in one of two ways. First, the device node can follow the generic implementation in which the device identifier is PNP0C03 and the interrupt number and I/O address assigned are system specific. The only requirement with the generic implementation is that the I/O address bit used for detecting the source of the interrupt and clearing the interrupt line is bit 0. If bit 0 of this I/O address is set to 1, then the interrupt was generated due to a system event. The interrupt service routine should reset the interrupt line by clearing bit 0 at the specified I/O address. All other bits read from the I/O address should not be modified. The second way the event system device node can be defined is implementation specific where the system vendor must supply their own device identifier and whatever resources are required for servicing the event interrupt. This method will require a specific device driver associated with the device node identifier to support the event notification interface.

When the system software is notified of an event by either mechanism, it can then call the BIOS runtime function to get the event which will return a message specifying the type of event. These events are specific to the system and do not represent events that can occur on the various expansion busses, such as PCMCIA insertion and removal events. The following table describes the types of events that are reported through this BIOS interface:

Event Identifier	Value	Description
ABOUT_TO_CHANGE_CONFIG	0001h	This message provides the system with a mechanism whereby system software can obtain notification from the system BIOS when a change is about to be made to the system. This notification encompasses initiating a docking, or undocking, sequence. For systems that support this message, the docking sequence will be suspended until the system software issues a Send_Message() to the system BIOS with either an OK message indicating that it's OK to dock/undock the system, or an ABORT message that signals the BIOS to halt the event. (Refer to Send Message function description below for more information.)
DOCK_CHANGED	0002h	This message indicates that new devices have either been successfully added or removed from the system, such as docking to, or undocking from, a docking station. This message will be used to indicate that a convenience base has been added/removed from the system.
SYSTEM_DEVICE_CHANGED	0003h	This message indicates that removable ("pluggable") system devices have been removed or inserted into the base unit.
CONFIG_CHANGE_FAILED	0004h	This message indicates that the system detected an error when attempting to add or remove devices to/from the system, such as attempting to dock to the docking station, or failing to successfully undock from the docking station. An error code will be returned in the return status for the Get_Event Plug and Play BIOS function if the system is able to determine the cause of the CONFIG_CHANGE_FAILED. Appendix C contains a complete list of return codes.
UNKNOWN_SYSTEM_EVENT	FFFFh	An unknown system event has occurred. The system BIOS is not able to determine the type of event.
OEM_DEFINED_EVENTS	8000h thru FFFEh	OEM defined events allow OEM to define events specific to their system implementation. These events are only comprehended by the OEM. These events are identified by the upper bit of the event message being set (bit 7=1).

To properly support event management, a PnP BIOS should implement the PNP_OS_ACTIVE and PNP_OS_INACTIVE messages, as well as their associated event timing requirements and PnP-OS-Active states as described in section 4.6.2.

4.6.1 Function 3 - Get Event

Synopsis:

int FAR (*entryPoint)(Function, Message, BiosSelector);     
int Function;               /* PnP BIOS Function 3 */
unsigned int FAR *Message;  /* Storage for the event message */
unsigned int BiosSelector;  /* PnP BIOS readable/writable selector */

Description:

Required for Dynamic Event Management. This function will allow system software to retrieve a message specifying the type of event that has occurred on the system. This function is supported for either event notification by polling or for asynchronous event notification, if the system BIOS provides event notification. It is the responsibility of this function to clear the event flag when called if the event notification method implemented is through polling.

If a system event has occurred this call will return the appropriate event notification message in the memory location specified by the Message argument. Message will be set to one of the following event notification messages:

ABOUT_TO_CHANGE_CONFIG
DOCK_CHANGED
SYSTEM_DEVICE_CHANGED
CONFIG_CHANGE_FAILED
UNKNOWN_SYSTEM_EVENT
OEM_DEFINED_EVENT

The event notification messages are defined in the table at the start of Event Notification Interface section. If Message is CONFIG_CHANGE_FAILED and the system is able to determine the cause of the error, then the appropriate error should be returned in AX. This will allow system software the ability notify the user of the cause of the failure. Refer to Appendix C for a description of the error codes associated with the CONFIG_CHANGE_FAILED event message.

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.

Returns:

0 if successful - SUCCESS
!0 if an error (Bit 7 set) or a warning occurred or no pending events - 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 Message     ; pointer to Message
     push    offset of Message     
     push    GET_EVENT               ; Function 3
     call    FAR PTR entryPoint     
     add     sp,8                    ; Clean up stack
     cmp     ax,SUCCESS              ; Function completed successfully?
     jne     error                   ; No-handle error condition
          .
          .
          .

4.6.2 Function 4 - Send Message

Synopsis:

int FAR (*entryPoint)(Function, Message, BiosSelector);     
int Function;              /* PnP BIOS Function 4 */
unsigned int Message;      /* Docking Message */
unsigned int BiosSelector; /* PnP BIOS readable/writable selector */

Description:

Required for Dynamic Event Management. This function will provide system software with a mechanism for interacting with the system while handling system events. There are three classes of messages that are supported by this interface: Response Messages, Control Messages, and OEM Defined Messages. The Response Messages are used as a means whereby the system BIOS will not proceed with a particular event until the system software provides a response instructing the system BIOS to continue or abort the processing of that event. Message values 0 through 3Fh are reserved for Response Messages. Control Messages provide system software with the ability to cause a particular event to happen. Message values 40h through 7Fh are reserved for Control Messages. OEM Defined Messages are specific to the OEM's system implementations and are only understood by the OEM. Message values 8000h through FFFFh identify OEM Defined Messages. The following table describes the event messages that system software can send to the system BIOS, where Message has one of the following meanings:

Response Messages 00h through 3Fh:

Message Identifier	Value	Description
OK	00h	Instructs the system to continue with the sequence which initiated the event. This message is only valid when the Get Event function has returned one of the ABOUT_TO_XXXXX events. When the system software is notified with an ABOUT_TO_XXXXX message, the appropriate actions will not take place until the Send Message BIOS Function is called with OK.
ABORT	01h	Abort the action which initiated the ABOUT_TO_XXXXX event. This message instructs the system BIOS to prevent the event from occurring. For instance, if the event is an undocking sequence, then the system will not be allowed to undock. It is assumed that it is the responsibility of the system software to communicate to the user the reason for not allowing the system to carry out the action for the event. This message is only valid when Get Event has returned one of the ABOUT_TO_XXXXX messages.

Control Messages 40h through 7Fh:

Message Identifier	Value	Description
UNDOCK_DEFAULT_ACTION	40h	This message provides a mechanism for system software to soft eject the system and instructs the system BIOS to take the default action when ejecting the system.
POWER_OFF	41h	This message instructs the system BIOS to power off the system. It is assumed that the system software will perform the necessary actions to shut the system down before sending this message.
PNP_OS_ACTIVE	42h	This message allows the PnP BIOS to track whether a PnP OS is active and defines event timing. The PnP BIOS may default to either a PnP-OS-Inactive or PnP-OS-Active state as needed. However, upon initial OS load, a PnP OS will register with the PnP BIOS by sending the PNP_OS_ACTIVE message to the PnP BIOS. When the PNP_OS_ACTIVE message is received, the PnP BIOS will operate in the PnP-OS-Active state. In this state, the PnP BIOS will wait forever after signaling a system event. This will allow the PnP OS to execute a Plug and Play BIOS Function Get Event call and handle the event (See Section 4.6). Although a PnP BIOS is not required to support the PNP_OS_ACTIVE message, support is recommended in systems that generate events. If this message is unsupported, then MESSAGE_NOT _SUPPORTED should be returned.
PNP_OS_INACTIVE	43h	This message complements the PNP_OS_ACTIVE message. A PnP OS will send the PNP_OS_INACTIVE message to the PnP BIOS upon OS termination. When the PNP_OS_INACTIVE message is received, the PnP BIOS will operate in the PnP-OS-Inactive state. In this state, no PnP event timing constraints exist. The PnP BIOS does not have to wait for the PnP OS to execute a Plug and Play BIOS Function Get Event call (See Section 4.6) and can handle event timing in the manner it best determines. Although a PnP BIOS is not required to support the PNP_OS_INACTIVE message, support is recommended in systems that generate events. If this message is unsupported, then MESSAGE_NOT _SUPPORTED should be returned.

OEM Defined Messages 8000h through FFFFh:

Message Identifier	Value	Description
OEM_DEFINED_MESSAGES	8000h thru FFFFh	This message allows OEMs to define messages specific to their system implementation. These messages are only comprehended by the OEM. These messages are identified by the upper bit of the message.

If the system BIOS does not support one of the specified messages, this function will return MESSAGE_NOT_SUPPORTED.

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 64KB, 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.

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    Message           ; Message
     push    SEND_MSG          ; Function 4
     call    FAR PTR entryPoint
     add     sp,6              ; Clean up stack
     cmp     ax,SUCCESS        ; Function completed successfully?
     jne     error             ; No-handle error condition
          .
          .
          .

4.6.3 Function 5 - Get Docking Station Information

Synopsis:

int FAR (*entryPoint)(Function, DockingStationInfo, BiosSelector);     
int Function;                           /* PnP BIOS Function 5 */
unsigned char FAR *DockingStationInfo;  /* Pointer to docking station*/
                                        /*info structure */
 unsigned int BiosSelector;             /* PnP BIOS readable/writable*/
                                        /*selector */

Description:

Required for Dynamic Event Management. This function will allow system software to get information which specifies the type of docking device, either expansion or convenience base, the system is connected to, as well as the capabilities of the docking device. The docking station information will be returned in the memory buffer pointed to by DockingStationInfo in the following format:

Field	Offset	Length	Value
Docking station location identifier	00h	DWORD	Varies
Serial number	04h	DWORD	Varies
Capabilities	08h	WORD	Varies

Docking station location identifier:

This field is the docking device location identifier. The identifier should follow the EISA device identifier format. The docking device location identifier will allow system software to differentiate between the types of docking stations and convenience bases that the base system unit can be connected to. This enables the system software to better determine the various docked and undocked configuration states. LocationId will be set to UNKNOWN_DOCKING_IDENTIFIER (0xFFFFFFFF) for docking stations and/or convenience bases that do not have a product identifier.

Serial number:

SerialNum is not required; however, if the docking station does not have a serial number, then 0 should be returned in this parameter.

Capabilities:

The Docking Capabilities bit field is defined as follows:

	Bits 15:3 Reserved (0)
	Bit 2:1 -	00=System should be powered off to dock or undock (Cold Docking)
		01=System supports Warm Docking/Undocking, system must be in suspend
		10=System supports Hot Docking/Undocking, not required to be in suspend
		11=Reserved
	Bit 0 -	0=Docking station does not provide support for controlling the docking/undocking sequence (Surprise Style).
		1=Docking station provides support for controlling the docking/undocking
		sequence (VCR Style).

If the system supports docking and is unable to determine the docking station capabilities, this function will return UNABLE_TO_DETERMINE_DOCK_CAPABILITIES. All other relevant information, such as the docking station identifier, will be returned in the data structure.

If the system does not support docking, this function will return FUNCTION_NOT_SUPPORTED. If the system supports docking, but is not currently docked, this function will return SYSTEM_NOT_DOCKED and will not return any information about a docking station.

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 64KB, 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.

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

Returns:

0 if successful - SUCCESS

!0 if an error (Bit 7 set) or a warning occurred or the system is not currently docked (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 DockingStationInfo     ; pointer to
                                         ;docking station info
                                         ;data structure
     push   offset of DockingStationInfo     
     push   GET_DOCK_INFO                ; Function 5
     call   FAR PTR entryPoint     
     add    sp,8                         ; Clean up stack
     cmp    ax,SUCCESS                   ; Function completed
                                         ;successfully?
     jne    error                        ; No-handle error condition
          .
          .

4.6.4 Function 6 - Reserved

This function has been reserved for future implementations and should return FUNCTION_NOT_SUPPORTED.

4.6.5 Function 7 - Reserved

This function has been reserved for future implementations and should return FUNCTION_NOT_SUPPORTED.

4.6.6 Function 8 - Reserved

This function has been reserved for future implementations and should return FUNCTION_NOT_SUPPORTED.