ADP Internals

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.

00hADP FunctionSlot
02hOffset to System Memory (<16MB)
04hSegment to System Memory (<16MB)
06hOffset to System Board Memory (<16MB)
08hSegment to System Board Memory (<16MB)
0AhOffset to POS Array
0ChSegment to POS Array
0EhOffset to POS Mask
10hSegment to POS Mask
12hOffset to Adapter ID List
14hSegment to Adapter ID List
16hOffset to ADP Function Call Entry
18hSegment to ADP Function Call Entry
1AhOffset to Resource Query Parameters
1ChSegment to Resource Query Parameters
1EhOffset to System Memory (16MB to 4G8)
20hSegment to System Memory (16MB to 46GB)
22hOffset of System Board Memory (16MB to 46GB)
24hSegment 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.

00h02h04h10h
SystemSlot 1Slot 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
01Configure the adapter in the given slot.
02Configure all adapters corresponding to the ADP.
03Deallocate resources for the adapter in the given slot.
04Deallocate resources for all adapters corresponding to the ADP.
05Deduce the configuration of the adapter in the given slot.
06Disable a block of system memory.
07Remap the system memory to above the 16MB address.
08Remap the system memory to below the 16MB address.
09Configure the system memory on the adapter in the given slot.
0AConfigure system memory on all adapters corresponding to the ADP.
0BDeallocate the system memory on the adapter in the given slot.
0CDeallocate system memory on alt adapters corresponding to the ADP.
0DDeduce configuration of system memory on adapter in the given slot.
80Check 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.

00hHex 80Hex 00
02hStarting Address of the First I/0 Address Range
   (0 if no I/0 Address Range)
04hFirst Interrupt Level
   (0 if no Interrupt Level)
06hFirst Arbitration Level
   (Hex 0FFFF if no Arbitration Level)
08hStarting Address of the First Memory Address Range
   (0 if no Memory Address Range)
0ChOffset of the Adapter IDs List.
0EhSegment of the Adapter IDs List.
10hOffset of the ADP Function Call Entry Point
12hSegment of the ADP Function Call Entry Point
14hOffset of the Resource Query Parameters
16hSegment 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
00Request Memory Block
01Check Memory Block
02De-allocate Memory Block
03Enable an Adapter
04Disable an Adapter
05Enable Memory with a Prompt
06Get Number of Slots
07Get 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.

00hFunctionSlot
02hStart_add_high
04hStart_add_low
06hEnd_add high
08hEnd_add_low
0AhSize_high
0ChSize_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
01The slot number specified was not valid.
02The size specified is not valid.
03The resource is already allocated to an adapter.
04Attempted to deallocate resources that were not allocated.
05A list value is not valid.
06The memory range specified is not valid.
07The function passed by the ADP is not valid.
08Cannot allocate any more memory blocks to this adapter.
09All memory for this adapter has already been disabled.
FFOperation 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).

Content created and/or collected by:
Louis F. Ohland, Peter H. Wendt, David L. Beem, William R. Walsh, Tatsuo Sunagawa, Tomáš Slavotínek, Jim Shorney, Tim N. Clarke, Kevin Bowling, and many others.

Ardent Tool of Capitalism is maintained by Tomáš Slavotínek.
Last update: 20 Jan 2024 - Changelog | About | Legal & Contact