4.5 System Configuration Interface
The functions described in the following subsections define the System Configuration Interface for obtaining information about the systemboard devices and for setting the system resources utilized by the configurable devices.
4.5.1 Function 0 - Get Number of System Device Nodes
Synopsis:
int FAR (*entryPoint)(Function, NumNodes, NodeSize, BiosSelector);
int Function; /* PnP BIOS Function 0 */
unsigned char FAR *NumNodes; /* Number of nodes the BIOS will return */
unsigned int FAR *NodeSize; /* Size of the largest device node */
unsigned int BiosSelector; /* PnP BIOS readable/writable selector */
Description:
Required. This function will return the number of nodes that the system BIOS will return information for in NumNodes. These nodes represent only the systemboard devices. In addition to the number of nodes, the system BIOS will return the size, in bytes, of the largest System Device Node in NodeSize. This information can be utilized by the system software to determine the amount of memory required to get all of the System Device Nodes.
After an ISA warm/hot dock, the BIOS should be able to revise the mother board device node list to include any new devices that are discovered in the new docked environment. Conversely, at undock, device nodes that describe non-\revauth1 \revdttm1172972005 existent devices should be removed from the list. The Plug and Play operating system will re-enumerate all system devices, including mother board devices, each time it receives the "DOCK_CHANGED" message or "SYSTEM_DEVICE_CHANGED" message. The PnP OS may also re-enumerate each time the system resumes from sleep mode. The node number for each device should remain constant as there is no requirement for node numbers to be sequential. Plug and Play operating systems should be designed to handle devices that appear and disappear on the fly. The device node number sequence is not important, however, the BIOS should never change the node number of any existing device node. For example, an undocked system may report device nodes 0-11. When the system detects the hot-insertion of a modem it then reports device nodes 0-12. Later, when the system docks it can report more devices 0-12 and 20-22. If the modem is extracted the system reports device nodes 0-11 and 20-22.
The Number of Nodes variable was \revauth1 \revdttm1172972109 originally \revauth1 \revdttm1172972108 implemented as a WORD, then later it was changed to a CHAR. All new BIOSs should be implemented a CHAR according to the specification. All operating systems and utilities should expect a WORD then clear the upper byte \revauth1 \revdttm-2048248908 because it is \revauth1 \revdttm-2048248908 indeterminable. This will allow OS and utility vendors to be backwards compatible with earlier versions of plug and play BIOS.
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 - 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 NodeSize ; pointer to NodeSize
push offset of NodeSize
push segment/selector of NumNodes ; pointer to NumNodes
push offset of NumNodes
push GET_NUM_NODES ; Function 0
call FAR PTR entryPoint
add sp,12 ; Clean up stack
cmp ax,SUCCESS ; Function completed successfully?
jne error ; No-handle error condition
.
.
.
4.5.2 Function 1 - Get System Device Node
Synopsis:
int FAR (*entryPoint)(Function, Node, devNodeBuffer, Control, BiosSelector);
int Function; /* PnP BIOS Function 1 */
unsigned char FAR *Node; /* Node number/handle to retrieve */
struct DEV_NODE FAR *devNodeBuffer; /* Buffer to copy device node*/
/* data to */
unsigned int Control; /* Control Flag */
unsigned int BiosSelector; /* PnP BIOS readable/writable*/
/* selector */
Description:
Required. This function will copy the information for the specified System Device Node into the buffer specified by the caller. The Node argument is a pointer to the unique node number (handle). If Node contains 0, the system BIOS will return the first System Device Node. The devNodeBuffer argument contains the pointer to the caller's memory buffer. On return, Node will be updated with the next node number, or if there are no more nodes, it will contain FFh. The System Device Node data will be placed in the specified memory buffer.
The Control flag provides a mechanism for allowing the system software to request a node that indicates either how the specified systemboard device is currently configured or how it is configured for the next boot. Control is defined as:
| Bits 15:2: Reserved (0) | |
| Bit 1: | 0=Do not get the information for how the device will be configured for the next boot. |
| | 1=Get the device configuration for the next boot (static configuration). |
| Bit 0: | 0=Do not get the information for how the device is configured right now. |
| | 1=Get the information for how the device is configured right now. |
If Control flag is 0, neither bit 0 nor bit 1 is set, or if both bits are set, this function should return BAD_PARAMETER.
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 - 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 Control Flag
push segment/selector of devNodeBuffer ; pointer to
;devNodeBuffer
push offset of devNodeBuffer
push segment/selector of Node ; pointer to Node number
push offset of Node
push GET_DEVICE_NODE ; Function 1
call FAR PTR entryPoint
add sp,14 ; Clean up stack
cmp ax,SUCCESS ; Function completed
; successfully?
jne error ; No-handle error
; condition
.
.
.
4.5.3 Function 2 - Set System Device Node
Synopsis:
int FAR (*entryPoint)(Function, Node, devNodeBuffer, Control, BiosSelector);
int Function; /* PnP BIOS Function 2 */
unsigned char Node; /* Node number/handle to set */
struct DEV_NODE FAR *devNodeBuffer; /* Buffer containing device node data */
unsigned int Control; /* Control Flag */
unsigned int BiosSelector; /* PnP BIOS readable/writable selector */
Description:
Required. This function will allow system software to set the system resource configuration for the specified System Device Node. The Node argument will contain the unique node number (handle) for the device that is to be set, and devNodeBuffer contains the pointer to the node data structure that specifies the new resource allocation request. The node data structure must completely describe the resource settings for the device. A node data structure that contains partial settings will result in the improper set up of the device. It cannot be assumed that any previous resource allocations will remain when this call is made. It is important to note that the resource descriptors that define the resource allocation must be specified in the same order as listed in the allocated resource configuration block for the system device node to be set. The allocated resource configuration block should be used as a template for setting the new resources for the device to ensure that the descriptors are specified in the correct format. In fact, the devNodeBuffer can be a copy of the fetched System Device Node with its allocated resource configuration block modified to reflect the desired new device configuration. Therefore, this function must be implemented to extract and use only the relevant new resource configuration information while ignoring all other extraneous node information. This function will not validate the resource settings or the checksum passed by the caller, and may not return an error code.
To disable a device, all resource descriptors in the allocated resource configuration block of the System Device Node must be set to zero. The resource attribute information field and the tag fields are "Don't Care" and may be zeroed. A device with a single configuration option that can be enabled/disabled must include that single configuration option in the possible resource configuration options.
The Control flag provides a mechanism for allowing the system software to indicate whether the systemboard device configuration specified by this call is to take affect immediately or at the next boot. Control is defined as:
| Bits 15:2: | Reserved (0) |
| Bit 1: | 0=Do not set the device configuration for the next boot. |
| | 1=Set the device configuration for the next boot (static configuration). |
| Bit 0: | 0=Do not set the device configuration dynamically.
1=Set the device configuration right now (dynamic configuration). |
If Control flag is 0, neither bit 0 nor bit 1 is set and this function should return BAD_PARAMETER. If both bits are set, then the system BIOS will attempt to set the configuration of the device right now (dynamic configuration), as well as set the device configuration for the next boot (static configuration). When both bits are set, it is possible that the NOT_SET_STATICALLY warning could be generated. This indicates that the device was configured dynamically, but could not be configured statically (See Appendix C, Error Codes).
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.
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 - 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 Control ; Control flag
push segment/selector of devNodeBuffer ; pointer to devNodeBuffer
push offset of devNodeBuffer
push Node ; node number - only low 8-bits used
push SET_DEVICE_NODE ; Function 2
call FAR PTR entryPoint
add sp,12 ; Clean up stack
cmp ax,SUCCESS ; Function completed successfully?
jne error ; No-handle error condition
.
.
.