ADF Structure and Syntax

ADF Format
ADF Syntax
Keywords

Content by Peter H. Wendt (original HERE). Edited by Tomáš Slavotínek.


ADF Format

  • File names are @xxxx.ADF where xxxx is Adapter ID
  • The file is an editable ASCII-Text
  • The file is not case-sensitive,
    Keywords can be uppercase, lowercase or mixed
    The case is preserved for explicitly marked text-strings
  • Blanks, tabs and new lines are ignored, except for text-strings
    The file should not include Tab-spaces at all
  • All lines beginning with a semicolon (;) are comments and are ignored

ADF Syntax

SymbolMeaning
{ }an optional item
{ }*0, 1, 2 ... items allowed
{ }+1, 2, 3 ... items allowed
x | yeither x or y allowed
x {n}n numbers of x required
[0-9]+one or more decimal digits

The above table shows the meaning of special symbols used in the following explanation of the ADFs syntax. Values shown as hexadecimal can be specified as decimal or as hex using the Intel format. Values shown as binary must be specified as binary.


Keywords

adf_file =card_id card_name nbytes {fixed resources} {system_memory} {initial_program} {lock_enable} {adress_width} {programmed_io} {items}*
This statement defines the content of an ADF.
The following definitions describe each parameter in detail.
 
card_id =AdapterId number
Each ADF must contain the card_id parameter. The character string AdapterId is a keyword and must be present. The Set Configuration program looks for this ID, which matches the ID used in the filename.
AdapterId 0E001h
 
card_name =AdapterName string
Each ADF must contain the card_name parameter. The character string AdapterName is a keyword and must be present. The string following the AdapterName keyword is displayed as the adapter name in the Change Configuration and View Configuration screens The length of the AdapterName string is limited to 66 characters.
AdapterName "IBM Token Ring Adapter 16/4 /A"
 
nbytes =NumBytes number
Each ADF must contain the nbytes parameter. It defines the number of POS bytes used by the adapter. The number of POS bytes used includes all bytes from POS[0] to the last POS byte used. Even if the card defines and uses only POS[3] the number for NumBytes must be 4.
NumBytes 4
 
fixed_resources =FixedResources pos_setting resource_setting
The fixed_resource parameter is optional. It defines those resources required by an adapter and the corresponding POS data. The character string FixedResource is a keyword and must be present if the adapter has a specific system resource it must use, such as hardwired I/O adresses or interrupt level.
FixedResource POS[1]=XXXX010Xb int 3
 
system_memory =SysMem granularity {adress_size}
The system_memory parameter is required for adapters that use an ADP to configure their system memory. The character string SysMem is the keyword.
The granularity field is required and specifies the smallest block of memory, which can be disabled on the adapter. The block size must be divisible by 4KB. The value used in this field specifies the number of 1KB blocks.
The adress_size field specifies the number of adress bits supported by the adapter. It can be either 24 or 32 bits. The default is 24.
SysMem 1024 32
Note: This keyword requires an ADP!
 
initial_program =InitProg attribute
The initial_program parameter is required for adapters that have an initialization program associated with them. The character string InitProg is the keyword. The initialization programs are loaded onto the fixed disk and executed before the operating system is booted from the fixed disk.
The attribute is a number from 0 to 127 and determines the order in which the init programs are run. The lower numbers are run first. Values outside the range from 30 to 80 are reserved.
InitProg 30
Note: This keyword requires an Init Program!
 
lock_enable =Lock
The lock_enable parameter is optional. The keyword Lock enables the Lock function.
An adapter that wishes to communicate with other masters through the memory semaphore protocol (an invisible test and set operation, such as an Exchange instruction) must indicate this to the Set Configuration program by the Lock keyword.
Lock
 
items ={{named_item | input_item} | {begin_device}}*
The items parameter is optional and can be any combination of the named_item and input_item parameters or it can be any number of begin_device parameters.
 
named_item =NamedItem prompt {named_choice}+ help
The Named_Item parameter is optional and it defines a field that provides a choice of one or more resources. Each Choice field sets specified POS bits to a unique setting used to identify resources assigned to the adapter.
The character string NamedItem is a keyword and must be present if the adapter can be configured to use different resources. The adapter determines the resources to which it is configured by how the POS bytes are set.
When a NamedItem is defined, it must be accompanied by a prompt, at least one named_choice and a help field.
To provide flexibility during configuration, each named_item should contain more than one choice.

Note: Each ADF is limited to 10 named_items per adapter!
NamedItem

   Prompt "SCSI Parity Checking On/Off"
      Choice "On"  pos[2]=xxx1xxxxb
      Choice "Off" pos[2]=xxx0xxxxb

   Help
       "The host adapter will check SCSI Parity if 'On'.
        (Default On)"
 
input_item =Input prompt pos_byte_setting range help
The input_item parameter is optional. It defines a field that accepts data from user input to initialize a single POS byte or define specific bits with this byte.
The character string Input is the keyword. The user can enter up to a 3-digit positive integer (0 - 255). The bits to be altered are defined using 0 or 1. The X specifies bits that remain unchanged by the input. The input is aligned with the least-significant bit of the pos_byte_setting not defined as X. The two values are merged using a logically OR function before the new mask is applied and the result is stored. The range defines the limits of the accepted input values. The first number listed in the range will be used as input for the adapter during automatic configuration.
Input

   Prompt "Enter value" pos[0]=XXXX1111b 0 - 15

   Help "Enter a value from 0 - 15"
 
prompt =Prompt string
The prompt is required when a named_item or input_item is defined. The prompt is used to define a title for a NamedItem or an Input field.
The character string Prompt is a keyword and must be present when a NamedItem or Input parameter is present. The string following the Prompt keyword appears after the adapter name in the Change Configuration or View Configuration screens.
Following the prompt string is a field that can be toggled in Change Configuration screen if two or more named_choices are defined. The length of the prompt cannot exceed 38 characters.
Prompt "SCSI Parity Checking On/Off"
 
named_choice =Choice {valid_check} choice_name pos_setting resource_setting
At least one named_choice is required when a Named_Item is defined.
The character string Choice is a keyword and must be present when a NamedItem is present. The named_choice field is specified after the prompt. Each choice must contain the choice_name, which describes the current choice. The choice_name string must not exceed 28 characters. Each Choice must define a pos_setting for at least one POS byte that uniquely identifies the resource_setting defined in the named_choice.
Choice "IO 3F8h" POS[0]=XXXX01XXb io 03f8h - 03fbh
 
valid_check =Vcheck
The valid_check parameter invokes an ADP that checks the specified choice for validity.
The character string Vcheck is the keyword. The ADP ensures, that the choice is valid for the system configuration. If the Set Configuration program is unable to load the ADP, the choice is treated as invalid. If all the choices within a named_item are invalid, the Set Configuration program deletes the named_items from the list of items for that adapter.

Note: This keyword requires an ADP!
 
help =Help string
The help field is a string of text used to give the user assistance at a prompt. The text is displayed in the Change Configuration screens when the cursor is at the associated prompt and the F1 key is pressed.
The character string Help is a keyword and must be present when the NamedItem or Input parameter is present. The string following the Help keyword is the text that describes the prompt. The length of the help string is limited to 1.000 characters.
The help string begins and ends with a double-quote. Additional double quotes inside the help string are not allowed.
Help
       "The host adapter will check SCSI Parity if 'On'.
        (Default On)"
 
pos_setting ={pos_byte_setting}+
The pos_setting parameter must contain at least one pos_byte_setting.
See the definition of pos_byte_setting below.
 
pos_byte_setting =POS[number]=pos_bit{8}b
Each pos_byte_setting field defines one POS byte.
The character string POS is a keyword and precedes each POS byte defined. The number of the POS bytes is specified in brackets and refers to the POS bytes as shown below:
number = 0, POS byte 0 at port 102h
number = 1, POS byte 1 at port 103h
number = 2, POS byte 2 at port 104h
number = 3, POS byte 3 at port 105h
The closing bracket must be followed by an equal sign, and then a bit definition of the POS byte as described in pos_bit below. The bit definition must define all 8 bits of the POS byte.
Bit 0 of pos[0] and bit 7 of pos[3] should always be defined as X to leave them unchanged.
pos[0]=XXX1001Xb
 
pos_bit =x | X | 0 | 1
A pos_bit can be defined as "unchange" mask bit (x or X), a clear bit (0) or a set bit (1).
pos[0]=XXX1001Xb
 
resource_setting ={ioblock_list} {interrupt_list} {arb_list} {memaddr_list} {exec_adp}
The resource_setting parameter defines a list of system resources.
The resources can be fixed resources required by the adapter, or they can resources the adapter uses when configuring to a specific choice in a named_item. The resources can consist of the following:
Range of I/O adresses       (limited to 16 ranges)
List of interrupt levels    (limited to 16)
List of arbitration levels  (limited to 16)
Range of memory adresses    (Limited to 2 ranges)
An ADP call for a nonsystem memory allocation
For details see the specific resource definitions below.
 
ioblock_list =IO {range}+
The ioblock_list parameter is a list of one or more ranges of I/O adresses. The character string IO is a keyword and must be present in a ioblock_list.
IO 3F8h - 3FBh
 
interrupt_list =Int {number}+
The interrupt_list parameter is a list of one or more ranges of interrupt levels that are used concurrently. The character string Int is a keyword and must be present in a interrupt_list.
Int 3 4
 
arb_list =Arb {shared_arb} {number}+
The arb_list parameter is a list of one or more arbitration levels that are used concurrently. The character string Arb is a keyword and must be present in a arb_list.
Arb 1
 
shared_arb =SharedArb
The character string SharedArb is the keyword and indicates that, in a controlled environment, the arbitration levels in the named_item parameter can be shared with the arbitration level of other devices that support sharing of arbitration levels.
Arb SharedArb 1
 
memaddr_list =Mem {range}+
The memaddr_list parameter is a list of one or more ranges of RAM or ROM addresses. The character string Mem is a keyword and must be present in a memaddr_list. This keyword is used to allocate the memory address space in the hex 000C0000 through hex 000DFFFF and the nonsystem memory above 1MB. Include the address for each Choice in the choice_name field so that the address is also displayed during Change Configuration.
Mem 0CC000h - 0CDFFFh 0E00000 - 0EFFFFFh
Note: Because of the limited space available, each adapter should limit the address space used in segments 0C000 and 0D000 to 16KB.
 
exec_adp =Exec
The exec_adp parameter is required for adapters containing nonsystem memory that can be initialized by an ADP. The character string Exec is the keyword that defines the ADP and should be the last Choice in the list of named_choices.
The Exec keyword indicates to the Set Configuration program that the adapter has an ADP.
Exec
Note: This keyword requires an ADP!
 
address_width =Address 24 | 32
The address_width field specifies the number of address bits supported by the adapter, 24 or 32 bits. The character string Address is the keyword and the default size is 24
Address 32
 
programmed_I/O =PIO
The programmed_I/O parameter is used to specify whether an adapter includes address bits 24 through 31 in its address decode. If this parameter is not specified, the adapter does respond to these address bits.
PIO
Note: A device is address limited if the ADF does not have the PIO parameter and the slot or the adapter is address limited.
 
begin_device =Begin
{device} {rs422} {DMA_not_used}
{named_item | input_item}*
End
The begin_device parameter is optional and is used to define a device block on an adapter. A device block is a series of items that define POS settings for lor like devices on an adapter, but are not associated with any other device that might be on the adapter.
 
device =Device device_id {implement_id {revision_level}}
{device} {rs422} {DMA_not_used}
{named_item | input_item}*
End
The device parameter is optional and defines the device types in ABIOS for the individual devices on an adapter or the system board.
The character string Device is the keyword. The device_id parameter is the ABIOS device ID, which is described in the IBM Personal System /2 and Personal Computer BIOS Interface Technical Reference.

The implement_id parameter is the implementation identifier, and the revision_level parameter is the implementation revision level.
The implementation identifier and revision level are optional and default to 0 if not specified; however, the revision level cannot be specified without the implementation identifier.
Device 2 1
 
rs422 =RS422
The rs422 parameter is optional, and indicates that the serial device uses a RS422-type interface. The character string rs422 is the keyword.
RS422
 
DMA_not_used =NoDMA
The DMA_not_used parameter indicates that arbitration levels for the named_items within the begin_device do not require a DMA channel. The character string NoDMA is the keyword.
If this parameter is specified, the Set Configuration program does not indicate that a DMA channel is required when an arbitration level is used. If this parameter is not specified, the Set Configuration program indicates that a DMA channel is required when an arbitration level is used
NoDMA
Note: Bus masters should use the NoDMA keyword.
 
range =number - number
 
number =[0-9]+ {d} | [0-9 a-f]+ h | [0-9 A-F]+ H
Note: The definition above is not correct! Valid syntax for IBM POS is:
number =[0-9]+ {d|D} | [0-9][0-9 a-f A-F]+ h|H
This means that decimal numbers can have optional suffix "d" or "D". Hexadecimal number MUST start with digit 0-9. Lower and upper case characters a-f and A-F can be mixed. Hexadecimal numbers must have either "h" or "H" suffix. NCR POS is different and the implementation seems to be based on the original definition - so it will accept hexadecimal numbers starting with a-f or A-F!
 
string =" [any ascii except for (") ]+ "
The string field is a set of ASCII characters beginning with a double quote (") and ending with a double quote.
"This is the I/O Port of the host adapter.  Conflicting
 assignments are marked with an asterisk and must be
 changed to use the host adapter. (Default 330h)"

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: 24 Mar 2024 - Changelog | About | Legal & Contact