View Source: isapnp.conf(5) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
ISAPNP.CONF
!!!ISAPNP.CONF
NAME
SYNOPSIS
DESCRIPTION
FILE FORMAT
SECTIONS
INITIALISATION
CONFIGURATION
TIDY UP
LIST OF KEYWORDS
KEYWORDS
BUGS
AUTHOR
AVAILABILITY
REFERENCES
SEE ALSO
----
!!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
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:


(ISOLATE) (VERBOSITY 2) (CONFLICT (__IO__ FATAL))
(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 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 --


(CONFIGURE DFX0000/1493 (LD 0 (IO 0 (SIZE 8)(BASE 0x3e8))
(INT 0 (IRQ 11 (MODE +E))) (NAME
!!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 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
''-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


(CONFLICT (DMA WARNING)(MEM WARNING)(IO WARNING)(IRQ
WARNING))


__(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 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:


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 __ACT__ivated. 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.
!!BUGS


Check http://www.roestock.demon.co.uk/isapnptools/ for
latest information and FAQ.


If you think you have found a problem not mentioned in the
latest version, please send a report to
isapnp@roestock.demon.co.uk.
!!AUTHOR


__isapnp.conf__ has been written by Peter Fox
__
!!AVAILABILITY


The latest version of the sources may be obtained by ftp
from ftp://ftp.demon.co.uk/pub/unix/linux/utils
Or follow one of the pointers to various ftp sites carrying
isapnptools from my web page at
http://www.roestock.demon.co.uk/
!!REFERENCES


Plug and Play ISA Specification, Version 1.0a, May 5, 1994.
Available from
ftp://ftp.microsoft.com/developr/drg/Plug-and-Play/Pnpspecs
!!SEE ALSO


pnpdump(8), isapnp(8)
----
3 pages link to isapnp.conf(5):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Monday, June 3, 2002 6:55:57 pm by "perry"
Edit PageHistory Diff Info LikePages