The isapnp.conf file is a configuration file for isapnp.
isapnp.conf provides instructions for isapnp. This includes
how to identify the cards present, and configuration information for
each one.
FILE FORMAT
The file consists of comments and instructions.
Comments start with a # character, and continue to
the end of the line.
Instructions consist of keywords and parameters, enclosed
in pairs of parentheses, with nesting as appropriate to show
context. For example:
Instructions can be spread across many lines, and include
comments if required.
SECTIONS
The file conceptually has three sections:
Initialisation
Which is the set of keywords associated with identifying the
Plug-and-Play cards. These usually come at the beginning
of the configuration file.
Configuration
Which is the set of keywords used to select a card and write
values to its configuration registers.
Tidy up
Which is the set of keywords used to finish the Plug and Play
configuration process.
There are also some keywords for debugging purposes.
INITIALISATION
There are two ways to initialise the configuration
mechanism, corresponding to using pnpdump with
and without the two optional parameters.
BIOS does ISOLATION
This method assumes the BIOS has already carried out the isolation
process, and allocated Card Select Numbers (CSNs) to each card.
The configuration file specifies the number of cards and the readport
address, and then isapnp reads the serial identifier from
the beginning of the resource data to find out the identity of each card.
A configuration file using this method will start like:
(READPORT 0x3bb)
(CSN 2)
(IDENTIFY *)
Using this method, and PEEK instructions instead of the configuration
setting instructions, it is possible to examine the configuration of the
Plug-and-Play cards, without upsetting normal system operation.
This can be useful for example to check how the BIOS has configured the
hardware. (If you want to get really fancy, you could pipe the output
through a script to configure the kernel driver(s) to match).
Note that some cards appear to be broken in that they don't follow the
requirement in the second paragraph of section 4.5 of the PnP ISA Spec.
(They start returning resource data immediately when entering the
Config state from the Sleep state, rather than the 9 byte
serial identifier).
These cards may not be able to use this method.
Due to the difficulty of determining the correct READPORT address
to use (which must be the same as the one the BIOS used), this method
may be tricky to get working.
isapnp does ISOLATION
With this method, isapnp carries out the isolation process.
This will be required for example on those systems without a Plug and Play
BIOS, or with a broken BIOS.
The configuration file simply includes the line
(ISOLATE)
which will scan for a suitable readport address and identify all the devices.
You may still want to include (IDENTIFY *) however, as it will printout
the names of the devices found. Putting a (READPORT xxx) before the (ISOLATE)
will prevent the scanning process.
Note that as of the 1.12 release of isapnptools, ISOLATE can now take
an optional parameter which determines whether the existing hardware
configuration settings are preserved or not. The default is now to
preserve the settings.
CONFIGURATION
This is the core of the process. For each card to be configured (not all
need to be), it is first selected using the CONFIGURE keyword. (Cards
can be selected using the CSN keyword, but the CSN numbers will change
when Plug and Play cards are added and removed, which could result in
configuration register settings going to the wrong card).
After this, each logical device on the card is selected in turn using
the LD keyword. The registers for that device are programmed using the
IO, INT, DMA, MEM keywords and their subwords. Finally the logical
device is enabled using the ACT keyword.
For debugging purposes, or to access non-standard configuration
registers or vendor specific registers, the REG keyword may be used to directly access the
configuration registers by address.
A couple of examples of this part of the configuration file look like
this:
# Card 1: (serial identifier 13 0e 1e 37 b4 19 01 89 14)
# EDI0119 Serial No 236861364 [checksum 13]
# Version 1.0, Vendor version 1.0
# ANSI string -->PLUG & PLAY ETHERNET CARD<--
# Logical device id EDI0119
# Device support I/O range check register
(CONFIGURE EDI0119/236861364 (LD 0
# Compatible device id PNP80d6
# Logical device decodes 10 bit IO address lines
# Minimum IO base address 0x0240
# Maximum IO base address 0x03e0
# IO base alignment 32 bytes
# Number of IO addresses required: 32
(IO 0 (BASE 0x0340))
# IRQ 3, 4, 5, 9, 10, 11, 12 or 15.
# High true, edge sensitive interrupt
(INT 0 (IRQ 10 (MODE +E)))
# Memory is non-writeable (ROM)
# Memory is non-cacheable
# Memory decode supports high address
# memory is 8-bit only
# memory is shadowable
# memory is an expansion ROM
# Minimum memory base address 0x0c0000
# Maximum memory base address 0x0dc000
# Range base alignment mask 0xff4000 bytes
# Range length 16384 bytes
# Choose UPPER = Range, or UPPER = Upper limit to suit hardware
# (MEM 0 (BASE 0x0c0000) (MODE bu) (UPPER 0x0c4000))
# (MEM 0 (BASE 0x0c0000) (MODE br) (UPPER 0x004000))
(ACT Y)))
# End tag... Checksum 0x00 (OK)
This is just the keyword WAITFORKEY, which returns the Plug and Play
configuration mechanism to the Wait for Key state.
The configuration file thus ends with
(WAITFORKEY)
LIST OF KEYWORDS
The following is a complete list of the keywords, showing the heirarchy
of validity.
CONFIGURE (or CSN)
LD
ACT
PEEK
DMA
CHANNEL
PEEK
INT
IRQ
MODE
PEEK
IO
BASE
SIZE
PEEK
CHECK
NAME
MEM
BASE
MODE
PEEK
UPPER
REG
PEEK
POKE
CONFLICT
IO
IRQ
DMA
MEM
DEBUG
IDENTIFY
IDENTIFY-FORMAT
ISOLATE
IGNORECRC
READPORT
VERBOSITY
VERIFYLD
WAITFORKEY
KEYWORDS
In alphabetical order.
The ... in the parentheses implies that the instruction is merely a selector
of some sort, and further instructions are required to do something useful.
(ACT arg)
Context: within (LD ...).
arg can be Y or N.
Y will cause the logical device to be activated and respond to accesses.
N will cause the logical device to be deactivated and isolated from the bus.
If a NAME has been specified, and VERBOSITY is greater than 1, a
status message will be output to stdout, summarising the device configuration
settings.
(BASE arg)
Context: within (IO ...) or (MEM ...).
arg specifies the base address of the region.
Prefix a hex address with 0x.
(CHANNEL arg)
Context: within (DMA ...).
arg specifies the DMA channel to use.
Valid settings are 0..7.
Channel 4 means no DMA used.
Channels 0..3 are for 8 bit DMA,
Channels 5..7 are for 16 bit DMA.
(CHECK)
Context: within (IO ...).
Carry out an IO range check to ensure no bus contention with any
other device. Only valid if the device supports it, and the device
is not already activated.
(CONFIGURE arg ...)
Context: Global.
arg specifies the card Vendor Id and serial number in the form
[A-Z][A-Z][A-Z][0-9A-F][0-9A-F][0-9A-F][0-9A-F]/[-#]?[1-9][0-9]*. For
example "DFX0000/1493". The serial number -1 implies that the
device does not have a serial number; in this case, only one card
can of this type can be supported in the system. Some cards appear
to include an underscore character as one of the initial three
letters of the Vendor ID, this is outside the specification, though
supported.
To allow the same configuration files on multiple machines, two
additional features have been added from release 1.12:
If the specified device is not found, the device is skipped.
Rather than the script aborting.
The serial number of the device may be specified as #n, meaning
the nth device found with the given Vendor Id, independent of
its actual serial number. Each card must still have a unique
serial number to be separately identified.
(CONFLICT ...)
Context: Global.
This keyword is used to select whether resource conflicts for each
of DMA, MEM, IO or IRQ are a Warning
or Fatal. Resource conflicts will cause a message to be output,
but if the resource is set as Fatal on conflict, the program will
immediately abort.
The default is equivalent to
Context: Global.
arg specifies the Card Select Number of the card to select
for access. isapnp assumes you know what you are doing
if you use this instruction, and will assume the card exists (and
all the cards with lower CSNs). arg must be in the range
1..32, this is a compiled in limit.
(DEBUG)
Context: Global.
This turns on debugging immediately. Diagnostic messages will
be produced as soon as this instruction is read in.
(DMA arg ...)
Context: within (LD ...).
arg specifies the DMA register to configure, in the range 0..1.
Each logical device can use up to 2 DMA channels.
Note there is another DMA described in CONFLICT.
(IDENTIFY arg)
Context: Global.
arg specifies the Card Select Number of the card to identify.
Identification consists of reading the card's resource data, updating
internal tables so that CONFIGURE can find the card, and
printing the results (the format of the results can be changed using
IDENTIFY-FORMAT). arg must be in the range of valid CSNs
(ie number of boards found), or can be specified as * to operate
on each card in turn.
Note:VERBOSITY must be greater than 2 to see the results on
stdout.
(IDENTIFY-FORMAT arg)
Context: Global.
arg specifies the format string to be used by IDENTIFY
when outputting the data for each card, it must be a string enclosed
in double quotes. The IDENTIFY-FORMAT command must precede
IDENTIFY if it going to have any effect.
The default format string is:
"Board %b has Identity %8 %7 %6 %5 %4 %3 %2 %1 %0: %v Serial No %s [checksum %8]\n"
The following format escapes are recognised:
%b - Card Select (board) Number [Decimal number]
%s - Board serial number [Decimal number]
%v - Board vendor Id [7 character string]
%x - where x is 0..8 - Identification byte x, 8 is the checksum [2 Hex digits]
(IGNORECRC)
Context: Global.
Normally, cards which have a CRC error during the reading of the
serial identifier in the isolation process are not counted, and the
READPORT is assumed bad.
Setting this flag means they will be treated as good, and you have
to hope that IDENTIFY will fix the identifier.
This must therefore come before ISOLATE if it is to
have any effect.
(INT arg ...)
Context: within (LD ...).
arg specifies the INT register set to configure, in the range 0..1.
Each logical device can use up to two interrupt lines.
(IO arg ...)
Context: within (LD ...).
arg specifies the IO register set to configure, in the range 0..7.
Each logical device can use up to eight IO regions. The size of the IO
region should be specified using the SIZE keyword.
The size of the IO region can be found by examining the output of
pnpdump.
Note there is another IO described in CONFLICT.
(IRQ arg ...)
Context: within (INT ...).
arg specifies the interrupt line to use for the interrupt, in the
range 0..15. No interrupt is specified using 0. To use interrupts a
value in the range 1..15 must be specified. Note that not all interrupt
lines are connected, so the resource data must be consulted to get a
list of valid settings.
Note there is another IRQ described in CONFLICT.
(ISOLATE arg)
Context: Global.
This carries out the full isolation protocol. First it resets all
the Card Serial Numbers, then isolates them one by one, allocating
each one a Card Select Number. If a READPORT hasn't already
been specified, it will also search for a valid readport address.
The optional arg may be PRESERVE, the default, in which case
the existing configuration settings are preserved, or it may be
CLEAR, in which case all the Plug and Play devices are reset
to their power-on default configurations.
(LD arg ...)
Context: within (CONFIGURE ...) or (CSN ...).
arg specifies the logical device to configure, in the range 0..n,
where n is one less than the number of logical devices on the card.
After setting the register to select the logical device, it is read
back and checked; an error is generated if there is a mismatch.
This behaviour can be changed using the global command VERIFYLD.
The number of logical devices on a card can be found by examining the
output of pnpdump.
(MEM arg ...)
Context: within (LD ...).
arg specifies the memory register set to configure, in the range 0..3.
The memory register sets are the normal range (24 bit addresses).
Each logical device can support up to 4 memory regions.
There is no direct support for the 32 bit memory descriptors, though POKE
could be used if required.
Note there is another MEM described in CONFLICT.
(MODE arg)
Context: within (IRQ ...) or (MEM ...).
Within IRQ, arg specifies the interrupt line polarity and sensitivity
using two characters [+-][EL] for [positive|negative][Edge|Level] sensitivity.
In most ISA situations this will be +E.
Within MEM, arg specifies memory width and the meaning of the value
written to the UPPER register. arg is of the form [BW][RU] for
[Byte|Word][Range|Upper]. Note that often these values cannot be set, but they are
checked with the hardware value and an error is generated if they don't match.
(NAME arg)
Context: within (LD ...).
arg specifies the name of the logical device to be output when
the device is ACTivated. The arg is a string in double quotes.
(PEEK)
Context: within most register access keywords.
This instruction causes the register value to be read and a suitable
message output to stdout. VERBOSITY must be greater than 0 to
see the output.
(POKE arg)
Context: within (REG ...).
arg specifies the value to write to the selected register in the
range 0..255.
(READPORT arg)
Context: Global.
arg specifies the address of the readport register to use in the
range 0x203..0x3ff. The address chosen must be unused by any other
hardware. The bottom two bits are set to ensure the port is on the
correct address boundary. This should be the first instruction if
used (except perhaps for DEBUG).
The Plug and Play specification specifies three registers. Two of them
are write only, at images of the printer status port (so were
previously read only), at addresses 0x279 and 0xA79. However, the
protocol requires a single readable register. The location of this
register cannot be standardised due to the impossibility of finding a
single unused address which is common to all systems.
For this reason the address of the readable register is specified in
one of the configuration registers, and an algorithm specified to find
a suitable non-conflicting location. If you know a good value to use,
it can be specified with this command to prevent having to try to
discover it.
(REG arg ...)
Context: within (LD ...).
arg specifies the address of the register to configure, in the range 0..255.
This may be used to access the various reserved and vendor defined registers on
a logical device.
(SIZE arg)
Context: within (IO ...).
arg specifies the size of the region in bytes.
Prefix a hex size with 0x. This keyword does not affect any PnP
configuration registers, it is simply information for resource conflict
checking. If the SIZE is unspecified, 8 will be assumed.
(UPPER arg)
Context: within (MEM ...).
arg specifies the memory range the device can use. The value is either
an upper address, or a range (offset) value, depending on the device.
Consult the resource data as dumped by pnpdump to find out what the
device supports.
(VERBOSITY arg)
Context: Global.
arg is a number from 0 to 3, which represents the amount of status
output the program should provide. 0 is mininum, 3 is maximum. The default
is 3 for backwards compatibility.
(VERIFYLD arg)
Context: Global.
Normally, isapnp attempts to verify the logical device exists by
reading back the the value in the logical device register after setting it.
The standard seems rather vague on whether this is a requirement, and it
would appear that some hardware fails to read back correctly, so this
instruction allows the verification to be turned on and off.
Within VERIFYLD, arg may be [Y|N] to turn verification on
and off respectively. If no parameter is supplied, verification will
be turned on.
(WAITFORKEY)
Context: Global.
Returns all cards to the Wait for Key state, as required by the
specification.
