|
Program Call
ADP Functions
Resource Query Functions
Error Codes
ADP Example
Source: IBM PS/2 Hardware Interface Reference Manual - Architectures 1st Ed., Oct 1990 (pp 27-53)
Program Call
When the Set Configuration program calls the ADP, the address of the ADP
parameter block is passed on the stack. This parameter block contains pointers
to data structures that are used by the ADP.
The Set Configuration program checks the parameter block before and on
return from the ADP, however, the ADP must maintain the integrity of these data
structures during its execution.
When the ADP is given control, the stack is set up as follows:
| .. |
| SS:SP → | Return Offset |
| Return Segment |
| Offset of Parameter Block |
| Segment of Parameter Block |
The ADP must preserve the contents of the DS, DI, SI, and BP registers as
well as the stack and stack pointers. The ADP ends using a Far Return with the
stack set up as shown.
| 00h | ADP Function | Slot |
| 02h | Offset to System Memory (<16MB) |
| 04h | Segment to System Memory (<16MB) |
| 06h | Offset to System Board Memory (<16MB) |
| 08h | Segment to System Board Memory (<16MB) |
| 0Ah | Offset to POS Array |
| 0Ch | Segment to POS Array |
| 0Eh | Offset to POS Mask |
| 10h | Segment to POS Mask |
| 12h | Offset to Adapter ID List |
| 14h | Segment to Adapter ID List |
| 16h | Offset to ADP Function Call Entry |
| 18h | Segment to ADP Function Call Entry |
| 1Ah | Offset to Resource Query Parameters |
| 1Ch | Segment to Resource Query Parameters |
| 1Eh | Offset to System Memory (16MB to 4G8) |
| 20h | Segment to System Memory (16MB to 46GB) |
| 22h | Offset of System Board Memory (16MB to 46GB) |
| 24h | Segment of System Board Memory (16MB to 46GB) |
Figure 4. ADP Parameter Block
Description of parameter block values and the data structures that are
pointed to.
ADP Function: This byte specifies the operation that the ADP will
perform. The functions are listed on page 28. The ADP uses this byte to return
the results of the operation, successful (0) or unsuccessful (not 0). The ADP
returns a hex 01 in this byte if the operation was not successfully completed,
and returns a hex FF if the function is not supported.
Slot: This is the slot number of the adapter to be configured. The
value is not required for all ADP functions.
System Memory Below 16MB: This is a pointer to the current count of
all system memory below 16MB. The count is a doubleword value and is the number
of 1KB blocks of memory below 16MB already allocated as system memory. (This
count includes the count in System Board Memory Below 16MB.) This value is
adjusted by ADPs as they map their system memory into the system address space.
The value is initially set to 0 before any configuring is started. An ADP
must not increase this value to the point that memory gets mapped beyond the
16MB address.
System Board Memory Below 16MB: This is a pointer to the count of
system memory on the system board below 16MB. The count is a doubleword value
and is the number of 1KB blocks of system board memory below 16MB. The memory
from 640KB to 1MB is included in this count. This value is set by the system
description program and must not be adjusted by any other program.
POS Array: This is a pointer to a table of the POS data for the
system board and the I/O slots. The ADP should initialize only those locations
that correspond to its adapters, and only the four POS data bytes from hex 0102
to 0105. The following is the format of the table and each entry.
| Reserved
(2 Bytes) | POS Data Starting at Port 102h
(28 Bytes) | Reserved
(4 Bytes) |
| System | | | |
| Slot 1 | | | |
| Slot 2 | | | |
| .. |
| Slot 8 | | | |
POS Mask: This is a pointer to the 32-byte field containing the POS
mask for adapter POS information. The POS mask data is initialized by an ADP,
and is applied to POS data for all slots with that adapter ID.
The mask bits are set to 1 for all POS bit positions that are initialized by
the ADP. The mask bits are set to 0 for those POS bits that are not used, or
that are initialized by statements in the ADF.
The following is the format of the POS mask data pointed to by this
field.
| 32 Bytes |
| POS Mask Starting at 102h |
Adapter ID List: This is a pointer to a list containing the system
and adapter IDs that are currently installed in the system. The adapter IDs are
stored as words at the following offsets.
| 00h | 02h | 04h | | 10h |
| System | Slot 1 | Slot 2 | .. | Slot 8 |
ADP Function Call Entry: This pointer is the program entry point for
calls by the ADP to the Set Configuration program when using the Resource Query
function calls (see “Resource Query Functions” on page 34). The ADP does a
Far Call when calling the Set Configuration program.
Resource Query Parameters: This pointer is the address for the
Resource Query parameter block that the ADP uses to pass parameters when
calling a Resource Query function. The address for this parameter block is
allocated by the Set Configuration program and should not be changed by the
ADP.
System Memory Between 16MB and 4GB: This is a pointer to the current
count of all system memory between 16MB and 4GB. The count is a doubleword
value and is the number of 1KB blocks from 16MB to below 4GB already allocated
as system memory. This value is adjusted by ADPs as they map their system
memory into the system address space.
The value is initially set to 0 before any configuring is started. An ADP
must not increase this value to the point that system memory gets mapped to the
4GB address (must be less than 4GB).
System Board Memory Between 16MB and 4GB: This is a pointer to the
count of system memory on the system board between 16MB and 4GB. The count is a
doubleword value and is the number of 1KB blocks of system memory on the system
board from 16MB to 4GB. This value is set by the system description program and
should not be adjusted by other description programs.
ADP Functions
When control is passed to an ADP, a function code is also passed. This
function code indicates the operation to be performed by the ADP. The ADPs do
not need to support all functions. If a function code is passed to an ADP that
is not supported, the ADP should return a hex FF in the Function byte.
The following functions are supported by the Set Configuration program.
Function
(Hex) | Description |
|---|
| 01 | Configure the adapter in the given slot. |
| 02 | Configure all adapters corresponding to the ADP. |
| 03 | Deallocate resources for the adapter in the given slot. |
| 04 | Deallocate resources for all adapters corresponding to the ADP. |
| 05 | Deduce the configuration of the adapter in the given slot. |
| 06 | Disable a block of system memory. |
| 07 | Remap the system memory to above the 16MB address. |
| 08 | Remap the system memory to below the 16MB address. |
| 09 | Configure the system memory on the adapter in the given slot. |
| 0A | Configure system memory on all adapters corresponding to the ADP. |
| 0B | Deallocate the system memory on the adapter in the given slot. |
| 0C | Deallocate system memory on alt adapters corresponding to the ADP. |
| 0D | Deduce configuration of system memory on adapter in the given slot. |
| 80 | Check the validity of an ADF choice |
Figure 5. ADP Functions
Configure the Adapter (func. 01h)
The ADP configures the adapter in the slot specified, and updates the
appropriate system memory and POS array values in the parameter table before
returning to the Set Configuration program.
All ADPs defined by the SysMem or Exec keywords must support this
function.
Configure All Adapters (func. 02h)
All adapters associated with that ADP are configured. !f more than one
adapter is being configured during this function, they are configured in the
ascending order of their slot number. The ADP updates the appropriate system
memory and POS array values in the parameter table before returning to
the Set Configuration program.
All ADPs defined by the SysMem keyword must support this function.
Deallocate Resources for an Adapter (func. 03h)
This function is indicated by 03 in the Function byte. The resources
allocated to the slot specified are deallocated. An ADP can deallocate only
those resources it has allocated. The ADP updates the appropriate system memory
and POS array values in the parameter table before returning to the Set
Configuration program.
All ADPs defined by the SysMem or Exec keywords must support this
function.
Note: The Set Configuration program can deallocate
memory space, previously allocated by an ADP, without calling the ADP.
Deallocate Resources for All Adapters (func. 04h)
The ADP deallocates all resources for all its adapters. The ADP can affect
only those resources and adapters that it changed during allocation. The ADP
updates the appropriate system memory and POS array values in the parameter
table before returning to the Set Configuration program.
All ADPs defined by the SysMem or Exec keywords must support this
function.
Deduce Adapter Configuration (func. 05h)
The ADP interprets the data in the POS array for the slot specified and
determines what memory space is allocated to the adapter.
If the ADP was defined by the Exec keyword, it uses the Request Memory Block
function to request the address space again. If the address space is not
allocated, the ADP leaves the POS data unchanged and returns with an error in
the Function byte.
If the ADP was defined by the SysMem keyword, the current top of memory is
checked to determine if this adapter was previously assigned the next address
space. If not, memory on another adapter may have been deallocated, and the ADP
should reconfigure its adapter to the current top of memory. The ADP then
updates the current count of system memory in the parameter block before
returning.
When the ADP detects a difference between the actual memory on the adapter
and its configuration, the ADP calls the Enable Memory Prompt function and
handles memory according to the user response.
All ADPs defined by the SysMem or Exec keywords must support this
function.
If the Set Configuration program is deducing the configuration of an adapter
and a match cannot be found between the data stored in CMOS/NVRAM and any of
the ADF choice POS definitions, the adapter will be configured to the first
choice in the list and the CMOS/NVRAM will be updated to reflect this. If the
adapter is in conflict with any other adapters when configured to the first
choice, the adapter will be disabled. The only indication that the user will
have of this change is by looking at the Change or View Configuration screen. A
message indicating that changes were made will also be displayed when the user
exits the Set Configuration menu.
Disable Block of System Memory (func. 06h)
The ADP disables the smallest amount of memory that it possibly can for the
specified slot. The ADP also decreases the current count of memory value
affected (either in the below 16MB value or the 16MB to 4GB value), and updates
the POS array to reflect the disabled memory.
The ADP can interpret the POS data to determine where its memory was
previously mapped. If its memory is not currently mapped as the top of memory,
the ADP does not change any values and indicates a successful operation. If its
memory is currently mapped as the top of memory, but the ADP cannot disable the
memory, the ADP returns a hex 01 in the ADP Function byte indicating the
operation was not successfully completed.
The ADP should support multiple calls to disable memory. For each call, an
additional block of memory should be disabled until all memory on the adapter
is disabled. If all memory has been disabled and the ADP is called again, the
ADP returns an error indicating that all memory for the slot specified is
already disabled.
All ADPs defined by the SysMem keyword must support this function.
Remap System Memory to Above 16MB (func. 07h)
All memory is remapped to the area above 16MB. The ADP updates its POS
values in the POS array and also updates both top of memory values to indicate
the changes. If its memory is not currently mapped as the top of memory, the
ADP does not change any values and indicates a successful operation.
All ADPs defined by the SysMem keyword must support this function; adapters
that have specified 24-bit addressing will not receive this request.
Remap System Memory to Below 16MB (func. 08h)
All memory for this adapter is remapped to the area below 16MB. The ADP
updates its POS values in the POS array and also updates both top of memory
values to reflect the changes. If its memory is not currently mapped as the top
of memory, the ADP does not change any values and indicates a successful
operation.
All ADPs defined by the SysMem keyword must support this function.
Configure System Memory on an Adapter (func. 09h)
This function is used only when the ADP is defined with both the SysMem and
Exec keywords. The ADP configures only the system memory on the adapter in the
slot specified. The ADP updates the appropriate system memory and POS array
values in the parameter table before returning to the Set Configuration
program.
Configure System Memory on All Adapters (func. 0Ah)
This function is used only when the ADP is defined with both the SysMem and
Exec keywords. The ADP configures only the system memory on all adapters
associated with the ADP. If more than one adapter is being configured, they are
configured in the ascending order of their slot number. The ADP updates the
appropriate system memory and POS array values in the parameter table before
returning to the Set Configuration program.
Deallocate System Memory on an Adapter (func. 0Bh)
This function is used only when the ADP is defined with both the SysMem and
Exec keywords. The system memory previously allocated to the adapter by the ADP
is deallocated. The ADP updates the appropriate system memory and POS array
values in the parameter table before returning to the Set Configuration
program.
Deallocate System Memory on All Adapters (func. 0Ch)
This function is used only when the ADP is defined with both the SysMem and
Exec keywords. The ADP deallocates system memory that it previously allocated
for all its adapters. The ADP updates the appropriate system memory and POS
array values in the parameter table before returning to the Set Configuration
program.
Deduce System Memory Configuration on an Adapter (func. 0Dh)
This function is used only when the ADP is defined with both the SysMem and
Exec keywords. The ADP checks the current top of memory to determine if the
adapter was previously assigned the next address space. If not, memory on
another adapter may have been deallocated and the ADP should reconfigure the
starting address of its adapter to the current top of memory. The ADP then
updates the current count of system memory in the parameter table before
returning.
When an ADP detects a difference between the actual memory on the adapter
and its configuration, the ADP uses the Enable Memory by Prompt function and
handles memory according to the user response.
Check Validity of Choice (func. 80h)
This function indicates whether the choice is valid or not for the current
system configuration. The parameter block for this function is different than
those defined previously. The following figure shows the parameter block for
this function.
| 00h | Hex 80 | Hex 00 |
| 02h | Starting Address of the First I/0 Address Range
(0 if no I/0 Address Range) |
| 04h | First Interrupt Level
(0 if no Interrupt Level) |
| 06h | First Arbitration Level
(Hex 0FFFF if no Arbitration Level) |
| 08h | Starting Address of the First Memory Address Range
(0 if no Memory Address Range) |
| 0Ch | Offset of the Adapter IDs List. |
| 0Eh | Segment of the Adapter IDs List. |
| 10h | Offset of the ADP Function Call Entry Point |
| 12h | Segment of the ADP Function Call Entry Point |
| 14h | Offset of the Resource Query Parameters |
| 16h | Segment of the Resource Query Parameters |
Figure 6. Check Validity of ADF Choice Function.
If the choice is valid, the ADP returns a 0 in the function byte. If the
choice is not valid, the named_item is not included in the list of available
settings during the configuration process.
All ADPs that use the Vcheck keyword must support this function.
Resource Query Functions
The Resource Query functions allows the ADP to communicate with the Set
Configuration program. The ADP can query the memory resource-allocation table
and request a block of addresses for an adapter. Before calling, the ADP loads
the specific values into the Resource Query parameter block for that function
and restores the DS register if it was changed.
A Resource Query function is initiated by making a far call to the program
entry point passed to the ADP in the parameter block. Most Resource Query
functions are designed to allocate address space for nonsystem memory. ADPs
configuring system memory are generally concerned with only the current top of
memory value.
Code
(Hex) | Description |
|---|
| 00 | Request Memory Block |
| 01 | Check Memory Block |
| 02 | De-allocate Memory Block |
| 03 | Enable an Adapter |
| 04 | Disable an Adapter |
| 05 | Enable Memory with a Prompt |
| 06 | Get Number of Slots |
| 07 | Get Slot Information |
Figure 7. Resource Query Function Calls.
The allocation of nonsystem is handled by the Set Configuration program. The
ADP simply requests a block of memory within a specified range. The ADP should
try to map its memory into the highest block possible.
Note: The block size and high end of the range
plus 1 must be divisible by 4KB.
The Set Configuration program responds with a return code that indicates
whether the request was successful or unsuccessful. If the request is
successful, the Set Configuration program has also returned the starting
address of the memory block allocated. The ADP then sets the appropriate bits
in the POS array.
The Set Configuration program attempts to allocate the highest block of
memory within the requested range. if the highest block is not available, the
starting address is decreased by the size of the block requested until either a
block of memory space is available, or the starting address is below the
requested range.
When the ADP returns control to the Set Configuration program, it must
indicate in the Function byte whether or not the configuration was
successful.
| 00h | Function | Slot |
| 02h | Start_add_high |
| 04h | Start_add_low |
| 06h | End_add high |
| 08h | End_add_low |
| 0Ah | Size_high |
| 0Ch | Size_low |
Figure 8. Resource Query Parameter Block
Request Memory Block (func. 00h)
This function is used to request a block of memory space for adapters with
nonsystem memory. The ADP provides the range where its memory can be mapped and
the number of bytes to be mapped.
The ADP can only allocate memory to an adapter with its ID. Once a memory
block has been allocated, it remains allocated until that ADP deallocates the
space, or until automatic configuration is run.
The following figure shows the values for the parameter passed between the
ADP and the Set Configuration program.
Function = 00
Slot = Slot number of adapter
Start_addr_high = Beginning of range (High Word)
Start_addr_low = Beginning of range (Low Word)
End_addr_high = End of range (High Word)
End_addr_low = End of range (Low Word)
Size_high = Requested block size in bytes (High Word)
Size_low = Requested block size in bytes (Low Word)
Return:
Successful:
Function = 00
Start_addr_high = Beginning of the block allocated
Start_addr_low = Beginning of the block allocated
Unsuccessful:
Function = Error code (01, 02, 03, 06, 08 or 09)
(refer to "Error Codes" on page 40)
All other values unchanged.
Figure 9. Request Memory Block Function
Check Memory Block (func. 01h)
This function allows the ADP to get the current memory block assigned to an
adapter in a given slot. An ADP can check the allocated memory blocks for any
slot.
Because a list of memory blocks can be allocated to an adapter, the ADP must
specify which block in the list to use. An ADP can check the entire list by
starting at number 0 and checking the next block until an error code is
returned.
Function = 01
Slot = Slot number of adapter
End_addr_high = Block number
Return:
Successful:
Function = 00
Start_addr_high = Beginning of block (High Word)
Start_addr_low = Beginning of block (Low Word)
Size_high = Allocated block size in bytes (High Word)
Size_low = Allocated block size in bytes (Low Word)
Unsuccessful:
Function = Error code (01, 05 or 09)
(refer to “Error Codes" on page 40)
All other values unchanged.
Figure 10. Check Memory Block Function
Deallocate Memory Block (func. 02h)
This function allows the ADP to deallocate a block of memory for a given
slot. The ADP can deallocate only the memory space assigned to adapters with
its ID. The ADP specifies only the beginning address of the memory block.
Function = 02
Slot = Slot number of adapter
Start_addr_high = Beginning of memory block (High Word)
Start_addr_low = Beginning of memory block (Low Word)
Return:
Successful:
Function = 00
Unsuccessful:
Function = Error code (01, 04 or 09)
(refer to "Error Codes" on page 40)
All other values unchanged.
Figure 11. Deallocate Memory Block Function
Enable an Adapter (func. 03h)
This function allows the ADP to enable and temporarily configure one of its
adapters. Because the data in the POS mask array is written when the adapter is
enabled, the ADP must initialize the POS mask before enabling the adapter.
Function = 03
Slot = Slot number of the adapter
Return:
Successful:
Function = 00
Unsuccessful:
Function = Error code (01)
(refer to "Error Codes” on page 40)
All other values unchanged.
Figure 12. Enable an Adapter Function
Disable an Adapter (func. 04h)
This function disables the adapter. Configuration information is not
required because only the adapter enable bit is changed.
Function = 04
Slot = Slot number of the adapter
Return:
Successful:
Function = 00
Unsuccessful:
Function = Error code (01)
(refer to "Error Codes" on page 40)
All other values unchanged.
Figure 13. Disable an Adapter Function
Enable Memory by Prompt (func. 05h)
This function allows an ADP to prompt the user for a decision when the
amount of memory on the adapter does not match configuration. When this
function is called, the Set Configuration program displays a message and waits
for the user to type a Y or N. The message asks the user if the memory should
be enabled and the adapter reconfigured. If a Y is typed, the Set Configuration
program returns a 01 in the Function byte and the ADP enables memory and
reconfigures the adapter. If an N is typed, the Set Configuration program
returns a 00 in the Function byte, the ADP disables the changed memory and does
not change the configuration.
This function should be used only when the ADP was called with a Deduce
function. An example of when this function is used is if memory was added to a
configured adapter.
Note: The return code specified in the Function
byte for Enable Memory by Prompt function is different from the error code
described in “Error Codes” on page 40.
Architecture Note: If the slot number specified in
the parameter block is not valid, the Set Configuration program also returns a
01 in the Function byte.
Function = 05
Slot = Slot number of the adapter
Return:
Enable memory:
Function = 01
Leave memory disabled:
Function = 00
Figure 14. Enable Memory by Prompt Function
Get Number of Slots (func. 06h)
This function allows the ADP to determine the number of channel connectors
in the system, which can be used to determine the size of the POS array,
adapter ID list, and other arrays.
Function = 06
Return:
Function = 00
Slot = Number of channel connectors in the system
Figure 15. Get Number of Slots Function
Get Slot Information (func. 07h)
This function requests information about a particular channel connector. The
ADP can use this information to determine the address size of the connector and
whether or not the connector has a video extension.
Function = 07
Slot = Slot number to get information about
Return:
Successful:
Function = 60
Slot = address size of slot
Start_addr_high:
bit 0 = 1, slot contains video extension
0, slot does not contain video extension
bits 1 - 15 = reserved (set to 6)
Unsuccessful:
Function = Error code (01)
(refer to "Error Codes” on page 40)
All other values unchanged.
Figure 16. Get Slot Information Function
Error Codes
The following is a list of the error codes used by the ADP and Set
Configuration program. The error codes are the same for the ADP functions and
the Resource Query functions.
Error
Code | Description |
|---|
| 01 | The slot number specified was not valid. |
| 02 | The size specified is not valid. |
| 03 | The resource is already allocated to an adapter. |
| 04 | Attempted to deallocate resources that were not allocated. |
| 05 | A list value is not valid. |
| 06 | The memory range specified is not valid. |
| 07 | The function passed by the ADP is not valid. |
| 08 | Cannot allocate any more memory blocks to this adapter. |
| 09 | All memory for this adapter has already been disabled. |
| FF | Operation is not supported. |
Figure 17. Error Codes
ADP Example
The HITR - Architectures
contains an example of an adapter description program that is defined by the
Exec keyword (spans across pp 45-53; poorly OCR'd).
|