	ISA PnP utilities Version 1.7
	=============================

These programs allow ISA Plug-And-Play devices to be configured
on a Linux machine.

This program is suitable for all systems, whether or not they
include a PnP BIOS. In fact, a PnP BIOS adds some complications
because it may already activate some cards so that the drivers
can find them, and these tools can unconfigure them, or change
their settings causing all sorts of nasty effects. If you have
(for example) plug and play network cards that already work, I
suggest you read section 4 on the format of the configuration
file below very carefully.

See the example for a dataflex voice fax modem.

The commands have been taken from the Plug and Play ISA
specification Version 1.0a, widely available on the net.
(ftp://developr/drg/Plug-and-Play/Pnpspecs/PNPISA.EXE -
this is a self-extracting DOS archive of PNPISA.DOC - a
word 6 document. If Word 6 not available, use the freely
redistributable viewer wordview which comes on the Win95 CD).

See CHANGES for a list of changes from the previous version.

Instructions for use
====================
1) Edit the makefile to select the appropriate compiler flags.

2) Compile the programs, and install in /sbin

3) Run pnpdump and capture the output in a file. Eg:

pnpdump > /etc/isapnp.conf

NOTE: pnpdump will unconfigure all ISA PnP cards, if this is
undesirable, give pnpdump two command line parameters, the
number of ISA PnP cards in the system, and the IO address to
use for the readport, eg:

pnpdump 1 0x3bb > /etc/isapnp.conf

If you say there are more cards than there are, the first missing
one will return all 0xff for their idents; pnpdump will ignore
this one, and any after this.

4) Edit the file to suit your hardware configuration:
a) All configuration information is commented out, so uncomment
the line beginning with '# (' that you want to use.
b) If the resource data specified a range of values, then only
the first will be put in the config entry. This should be editted
to suit.
c) DON'T FORGET to uncomment the (ACT Y) at the end of the logical
device entry if you want the device enabled !

5) Run isapnp giving it the editted configuration file as the
only argument. Eg:

isapnp /etc/isapnp.conf

6) If this is satisfactory, then edit your boot up scripts to
include the isapnp command.

7) Read the rest of the README, especially the bit about drivers.


Format of pnp configuration file:
=================================
1) # introduces a comment, which continues to the end of line:

# LD n      = Logical device, ie write to reg 7
# IO n      = IO descriptor n
# MEM n     = MEM descriptor n (24bit descriptors only for ISA)
# DMA n     = DMA descriptor n
# REG n     = Select register n
# POKE n    = Poke a value
# PEEK      = Read a value and print on stdout
# BASE n    = IO/Mem address n
# UPPER n   = Mem upper address/range n
# INT n     = Interrupt req n
# IRQ n     = Interrupt level n
# MODE      = IRQ line levels etc/Memory width etc
# CHANNEL n = DMA channel
# ACT       = Activate

2) Commands are nested within brackets as shown here:
Commands are case insensitive.

(DEBUG)           # Enable debugging
(IGNORECRC)       # Ignore CRC errors during isolation
(READPORT 0x207)  # Specify the READPORT, this can be an address 0x203..0x3ff, or *
(ISOLATE)         # Execute the isolation protocol and allocate CSNs to all boards
(CSN n)           # Specify the number of cards, without needing to ISOLATE.
(IDENTIFY n)      # Print out the identity of the board with CSN = n (* gives all)
                  # the identity is that from resetting the resource data, not that
                  # found during isolation.
(WAITFORKEY)      # End configuration and return all boards to the waitforkey state

3) The configuration command is well nested, note that whitespace is ignored:
Here are some examples, doing different things, the text after '#' is a description
of what is being done. Generally, multi-digit numbers may be specified in octal,
decimal or hex. Octal has leading 0, decimal doesn't, and hex has leading 0x.

(CONFIGURE DFX0000/1493 # Select a board by identifier/serialnumber
 (LD 0                  # Select a logical device within the board (0..255 - depends on board)
  (REG 0x42             # Select a register (0..0xff)
   (POKE 0x00)          # Write a value to the register (0..0xff)
   (PEEK))))            # Read the register and print it out with identification

(CONFIGURE DFX0000/1493 # Select a board
 (LD 0                  # and logical device on it
  (MEM 0                # Select a set of memory configuration registers (0..3)
   (BASE 0x400000)      # Set the base address, must fit in the mask 0x00ffff00
   (MODE wu)            # Set the mode [WB][UR] (Word/Byte) (Upper/Range)
   (UPPER 0x800000))    # Set the upper/range address, must fit in the mask 0x00ffff00
  (DMA 0                # Select a set of DMA configuration registers (0..1)
   (CHANNEL 1))))       # Set the DMA channel (0..7) (4 is don't use DMA)

(CONFIGURE DFX0000/1493 # Select a board
 (LD 0                  # and logical device on it
  (IO 0                 # Select a set of IO configuration registers (0..7)
   (BASE 0x3e8))        # Set the IO base address (0..0xffff)
  (INT 0                # Select a set of interrupt configuration registers
   (IRQ 12              # Select the interrupt line (1..15)
    (MODE +E)))         # and mode [+-][EL] (Active High/Low) (Edge/Level) +E is ISA standard
  (ACT Y)))             # Activate the logical device (or not N)

4) ISOLATE or NOT, that is the question.
The examples above use (ISOLATE) near the beginning. This resets the configuration
of all the ISA PnP cards, including those that may have been configured already
by the BIOS, and in use by the kernel (such as network cards).

This may be undesirable...

An alternative is to use (CSN x) where x is the number of PnP cards in the system,
assuming that the BIOS has already isolated them all and given them CSNs. Assuming
the cards comply with the specification, they can be identified using (IDENTIFY *),
and referred to by their device ident and serial number as above. Note however,
the READPORT must be specified before using CSN, IDENTIFY, or CONFIGURE, because
only the ISOLATion process can scan for READPORTs.

If you are really desparate, (CSN x (...)) can be used instead of
(CONFIGURE xxx/yyy (...)) to directly access cards by CSN, but this is, how shall
I say, unsafe !

5) isapnp for debugging.
As well as the (DEBUG) command, which allows debugging of the configuration script,
the PEEK command may now be used with the standard configuration settings to dump
the actual board configuration register settings, for example, the script:

#(DEBUG)
(READPORT 0x3bb)
#(READPORT 0x203)
(CSN 1) # Or as many cards as you have
(IDENTIFY *)
(CONFIGURE DFX0000/1493
        (LD 0
                (IO 0 (PEEK)) # Dump Port 0
                (IO 1 (PEEK)) # Dump Port 1
                (IO 2 (PEEK)) # Dump Port 2
                (INT 0 (PEEK)) # Dump INT 0
                (DMA 0 (PEEK)) # Dump DMA 0
                (DMA 1 (PEEK)) # Dump DMA 1
                (MEM 0 (PEEK)) # Dump MEM 0
                (REG 0x60 (PEEK)) (REG 0x61 (PEEK)) # Dump Port 0
                (REG 0x62 (PEEK)) (REG 0x63 (PEEK)) # Dump Port 1
                (REG 0x64 (PEEK)) (REG 0x65 (PEEK)) # Dump Port 2
                (REG 0x70 (PEEK)) (REG 0x71 (PEEK)) # Dump INT 0
                (REG 0x74 (PEEK)) # Dump DMA 0
                (REG 0x75 (PEEK)) # Dump DMA 1
))
(WAITFORKEY)

produces the following with my dataflex modem:

Board 1 has Identity 6e 00 00 05 d5 00 00 d8 10:  DFX0000 Serial No 1493 [checksum 6e]
Peek(DFX0000/1493)[0][0x60](IO  0) is 0x03E8, (3,232)
Peek(DFX0000/1493)[0][0x62](IO  1) is 0x0000, (0,0)
Peek(DFX0000/1493)[0][0x64](IO  2) is 0x0000, (0,0)
Peek(DFX0000/1493)[0][0x70](INT 0) is 0x0C02, (12,2)
Peek(DFX0000/1493)[0][0x74](DMA 0) is 0x04, (4)
Peek(DFX0000/1493)[0][0x74](DMA 0) is 0x04, (4)
Peek(DFX0000/1493)[0][0x40](MEM 0) is 0x0000000000000000, (0,0,0,0,0,0,0,0)
Peek(DFX0000/1493)[0][0x60](-REG-) is 0x03, (3)
Peek(DFX0000/1493)[0][0x61](-REG-) is 0xE8, (232)
Peek(DFX0000/1493)[0][0x62](-REG-) is 0x00, (0)
Peek(DFX0000/1493)[0][0x63](-REG-) is 0x00, (0)
Peek(DFX0000/1493)[0][0x64](-REG-) is 0x00, (0)
Peek(DFX0000/1493)[0][0x65](-REG-) is 0x00, (0)
Peek(DFX0000/1493)[0][0x70](-REG-) is 0x0C, (12)
Peek(DFX0000/1493)[0][0x71](-REG-) is 0x02, (2)
Peek(DFX0000/1493)[0][0x74](-REG-) is 0x04, (4)
Peek(DFX0000/1493)[0][0x75](-REG-) is 0x04, (4)

Drivers
=======
Note that boards first configured by isapnp are not visible to the kernel
during boot up. This means that drivers for the boards must be loaded
as modules after the board has been configured, so that they can
locate the board.

This doesn't apply to serial cards, because setserial can be used to
configure the serial ports after the kernel has booted.

If the kernel needs rebooting after configuration, because the drivers
are not modules, it may be possible to do this automatically in your
bootup scripts: use an isapnp.conf file which dumps the board
configuration registers and tests the the output.
If the board(s) haven't been configured, configure them with the
configuration isapnp.conf file and reboot.
If the boards have been configured, continue the boot normally.
You may want to take precautions to prevent the kernel continuously
rebooting if something goes wrong...

Bugs
====
I haven't tested the Memory setting stuff, as I haven't
got a card with suitable drivers. If it doesn't work, tell me,
and work around using poke, which I have tested.

Note
====
These programs must run as root, as they need unrestricted access
to the computer IO addresses. This could cause lots of problems,
so use with care. DO NOT MAKE THESE PROGRAMS SUID root !

Copyright
=========
These programs are copyright P.J.H.Fox (fox@roestock.demon.co.uk)
and distributed under the GPL (see COPYING).

If mailing patches, bug reports or comments, please put 'isapnp'
somewhere in the subject line, and mail to isapnp@roestock.demon.co.uk.

Warranty
========
There is NO WARRANTY for these programs.

These programs have been compiled on my machine using gcc 2.7.2,
flex 2.4.7 and linux 2.0.0, and they seem to work for me.

However, due to the nature of these programs, they are very likely
to completely screw up your computer: USE AT YOUR OWN RISK. But if
you find them useful, or have some suggestions for improvement,
please tell me.

Credits
=======
Thanks to the following for bug fixes and improvements to isapnptools.

Bob Clark (rlc@hrb.com)
Neal Sanche (neal@nsdev.ocunix.on.ca)
Karsten Keil (pnp@temic-ech.spacenet.de)
Jim Studt (jim@federated.com)

See also
========
Users of isapnptools may be interested in the pnp mailing list (pnp-list@redhat.com):
To subscribe to the mailinglist, simply send a message with the word "subscribe"
in the Subject: field to pnp-list-request@redhat.com.

Peter Fox
21-Jun-96
