ISAPNP.CONF(5)                                     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)
        (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  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.
              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  (READ-
              PORT  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 configura-
              tion  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  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  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)

         (CONFIGURE  DFX0000/1493  (LD  0  (IO  0  (SIZE  8)(BASE
       0x3e8))  (INT 0 (IRQ 11 (MODE +E))) (NAME "DFX0000/1493[0]
       --- Modem and Fax") (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
               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 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.
              If  a  NAME  has  been  specified, and VERBOSITY is
              greater than 1, a status message will be output  to
              stdout,  summarising  the device configuration set-
              tings.

       (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.

       (CHECK)
              Context: within (IO ...).
              Carry out an IO range check to ensure no  bus  con-
              tention  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  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.
              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  WARN-
              ING)(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 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.
              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 IDEN-
              TIFY  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  iso-
              lates  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 descrip-
              tors, 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 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.

       (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. VER-
              BOSITY 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  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).
              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 regis-
              ter is specified in one of the configuration regis-
              ters, 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  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.

       (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 sim-
              ply 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 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.

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@roe-
       stock.demon.co.uk.

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 one of the pointers to various ftp sites carry-
       ing  isapnptools  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-
       opr/drg/Plug-and-Play/Pnpspecs

SEE ALSO
       pnpdump(8), isapnp(8)

isapnptools                11 Feb 1999                          1