ISAPNP.CONF(5)
NAME
isapnp.conf - File format used by isapnp.
SYNOPSIS
/etc/isapnp.conf
DESCRIPTION
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 configura-
tion 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:
(ISOLATE)
(CONFIGURE DFX0000/1493 (LD 0 (IO 0 (BASE 0x3e8)) (ACT
Y)))
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 iden-
tifying 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 mecha-
nism, 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 pos-
sible to examine the configuration of the Plug-and-
Play cards, without upsetting normal system opera-
tion. 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.
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 (READ-
PORT xxx) before the (ISOLATE) will prevent the
scanning process.
CONFIGURATION
This is the core of the process. For each card to be con-
figured (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 configu-
ration 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)
(CONFIGURE DFX0000/1493 (LD 0 (IO 0 (BASE 0x3e8)) (INT 0
(IRQ 12 (MODE +E))) (ACT Y)))
TIDY UP
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
DMA
CHANNEL
PEEK
INT
IRQ
MODE
PEEK
IO
BASE
PEEK
MEM
BASE
MODE
PEEK
UPPER
REG
PEEK
POKE
DEBUG
IDENTIFY
ISOLATE
IGNORECRC
READPORT
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 use-
ful.
(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 iso-
lated from the bus.
(BASE arg)
Context: within (IO ...) or (MEM ...).
arg specifies the base address of the region. Pre-
fix a hex address with 0x.
(CHANNEL arg)
Context: within (DMA ...).
arg specifies the DMA channel to use. Valid set-
tings 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.
(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 sup-
ported 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 spec-
ification, though supported.
(CSN arg ...)
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 instruc-
tion 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.
(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. 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.
(IGNORECRC)
Context: Global.
Normally, cards which have a CRC error during the
reading of the serial identifier in the isolation
process are not counted. Setting this flag means
they will be counted anyway. 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. Note that there is no means to
specify the size of the IO region, unlike MEMory
regions. The size of the IO region can be found by
examining the output of pnpdump.
(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.
(ISOLATE)
Context: Global.
This carries out the full isolation protocol. First
it disables all the Plug and Play devices, 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.
(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 descrip-
tors, though POKE could be used if required.
(MODE arg)
Context: within (IRQ ...) or (MEM ...).
Within IRQ, arg specifies the interrupt line polar-
ity 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.
(PEEK) Context: within most register access keywords.
This instruction causes the register value to be
read and a suitable message output to stdout.
(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 cho-
sen must be unused by any other hardware. The bot-
tom 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).
(REG arg ...)
Context: within (LD ...).
arg specifies the address of the register to con-
figure, in the range 0..255. This may be used to
access the various reserved and vendor defined reg-
isters on a logical device.
(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.
(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 verifica-
tion 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.
AUTHOR
isapnp.conf has been written by Peter Fox <fox@roe-
stock.demon.co.uk>, the creator and maintainer of isap-
nptools.
AVAILABILITY
The latest version of the sources may be obtained by ftp
from ftp://ftp.demon.co.uk/pub/unix/linux/utils
Or follow the pointer from my web page at http://www.roe-
stock.demon.co.uk/
REFERENCES
Plug and Play ISA Specification, Version 1.0a, May 5,
1994. Available from ftp://ftp.microsoft.com/devel-
oper/drg/Plug-and-Play/Pnpspecs
SEE ALSO
pnpdump(8) isapnp(8)