.\" Copyright (c) 1996, 1997 Peter Fox <fox@roestock.demon.co.uk>
.\" This program is distributed according to the Gnu General Public License.
.\" See the file COPYING in the isapnptools source distribution.
.\"
.\" $Id: pnpdump.8,v 0.10 1999/12/02 22:38:21 fox Exp $
.\"
.TH PNPDUMP 8 "30 Nov 1999" "isapnptools"
.SH NAME
pnpdump \- Dump ISA Plug-And-Play devices resource information
.SH SYNOPSIS
\fBpnpdump\fP [ \-\-help ] [ \-\-config ] [ \-\-script[=outputfile] ] [ \-\-reset ] [ \-\-ignorecsum ] [ \-\-masks ] [ \-\-dumpregs ] [ \-\-max-realtime=\fIt\fP ] [ \-\-version ] [ \-\-debug-isolate ] [ [ \fIdevs\fP ] \fIreadport\fP ]
.SH DESCRIPTION
\fBpnpdump\fP will scan all the ISA PnP cards, dumping
their resource data to \fIstdout\fP. The resource data is
supposed to be a description of the resources (IO ports,
interrupts, DMA channels) that the card would like, or needs,
to use to work. It is stored in a small ROM on the card, which
can be read as part of the Plug and Play configuration process.

.br
Note that some manufacturers are rather lax about the contents of this
ROM, particularly if the card is not required for booting, so the
resource data may not be accurate. As they also typically provide a
DOS/Windows driver for the card, they really only need to be able to
recognise it, as the driver can then complete the configuration.

.br
The output of \fBpnpdump\fP is in a form that can be used by \fBisapnp\fP,
except that the actual configuration statements are commented
out. See \fBisapnp.conf(5)\fP for details of the format.

.br
By default, \fBpnpdump\fP will reset all the Card Serial Numbers,
then ISOLATE each one and allocate it
a handle (Card Select Number). This process will include
trying different \fIreadport\fP addresses until a suitable
one is found avoiding conflicts with other hardware.
For a description of what the \fIreadport\fP is, see the
relevant entry in \fBisapnp.conf(5)\fP.
As of the isapnptools 1.12 release,
any existing configuration settings will be unaffected.

.br
If a single parameter is provided, this will be used as the
minimum \fIreadport\fP address to start scanning. This may
be chosen to avoid an unfortunate conflict.

.br
To skip the Isolation process, both
additional parameters may be supplied:
.SS Parameters
.TP
\fIdevs\fP is the \fInumber of PnP cards\fP that the BIOS has found,
ISOLATEd and allocated CSNs to in the system.  Note that if this is
greater than the actual number of cards in the system, pnpdump will
stop scanning when it receives a first serial identifier byte of 0xff
(this is what happens when there isn't a card with that CSN).

.br
If this parameter is provided, then \fBpnpdump\fP will not ISOLATE
each card and assign CSNs, however, the \fIreadport\fP provided must
be the same as the one the BIOS used. This could be difficult to
determine if it is not assigned via a BIOS setup screen.
.TP
\fIreadport\fP is the address of the \fIreadport\fP to use for the
Plug-And-Play access. The number base is determined by the format: a
leading \fI0x\fP implies hex, a leading \fI0\fP implies octal,
otherwise decimal is assumed.

.br
The address of the \fIreadport\fP must be chosen to avoid any
conflicts with existing (non Plug and Play) hardware, and must be in
the range 0x203..0x3ff.

.br
If the \fIreadport\fP is specified without \fIdevs\fP, then this is
the minimum \fIreadport\fP to use when scanning for a suitable one.
.PP
Note that for the two parameter option to work, you must have a PnP
BIOS which has already carried out the ISOLATION process correctly,
and you must know what \fIreadport\fP address the BIOS used.

.br
\fBpnpdump\fP will run with real-time scheduling if possible to
achieve the required IO timings. This will lock out all normal
programs while it executes. In version 1.19 and later of
\fBisapnptools\fP, \fBpnpdump\fP will only run in this mode for 5
seconds (or as set on the command line), it then reverts to standard
scheduling like any other program. Previous versions should only be
run from a standard console as ^C will kill it from there. If you run
the command remotely (and X counts as remote), you will not be able to
kill it as no other programs can run.

.SS Options
.br
Note that only the long form of the options are valid for the DOS
version.
.TP
.I "\-h, \-\-help"
Show a help summary.
.TP
.I "\-c, \-\-config"
attempt to determine safe settings to which the devices can be set,
and uncomment those settings in the output.  pnpdump will use
information in the /proc filesystem and the contents of the
/etc/isapnp.gone file to discover system resources that have already
been allocated, if these facilities are available on the system.

.br
Note that if the resource allocation is impossible, pnpdump is
not intelligent enough to realise this and may hang trying to find
a solution.
.TP
.I "\-d, \-\-dumpregs"
this will cause pnpdump will dump all the standard configuration
registers for each board.

.br
Note that this dump is dumping the physical registers, and will thus
show the settings that have been put in there by the BIOS, or some
cards will put a default setting in. Unused registers read back as 0.
.TP
.I "\-D, \-\-debug-isolate"
this will cause pnpdump to output loads of extra information, showing
the actual data received during the isolation process. You'll probably
need the ISAPnP spec to work out what it means.
.TP
.I "\-i, \-\-ignorecsum"
this will cause pnpdump will ignore checksum errors when deciding if
the readport address is good. Section 3.3.2 of the spec suggests that
a bad checksum should cause the \fIreadport\fP to be rejected. In
reality, it seems to be possible for the checksum to be bad for
reasons other than a \fIreadport\fP address conflict, and in this
situation all \fIreadport\fP addresses will be rejected resulting in
no boards found.

.br
Using this flag allows the boards to still be found. Boards with
a bad identifier checksum will have the identifier corrected by the
resource data if the resource data identifier has a good checksum.
.TP
.I "\-r, \-\-reset"
Carry out a full configuration reset, rather than just resetting the
CSNs. \fBDANGEROUS\fP as this could reset PnP boards in active use
by the kernel, resulting in a lockup or worse.
.TP
.I "\-m, \-\-masks"
Print the lists of acceptable interrupts and direct memory access
(DMA) channels as binary bitmasks.  For example, print "IRQ mask 0x03"
instead of "IRQ 1, 2, or 3".
.TP
.I "\-t \fIt\fP, \-\-max-realtime=\fIt\fP"
Set the maximum time the process can run at real-time priority to
\fIt\fP seconds. If \fIt\fP is set to 0, the timeout is disabled; in
this case you \fBmust\fP run the program from a normal text console to
allow it to be aborted via control-C if it hangs. The default timeout
is 5 seconds. After the timeout has expired, the process runs with
normal scheduling, which means it may go a lot slower, but will
prevent locking up the comupter (if it hangs while running under X
windows for example). This option is only available when compiled
with real time scheduling support.
.TP
.I "\-s, \-\-script[=outputscript]"
write a shell script to the specified file that can be used to
configure the system based on what ISA PnP boards were found and how
they were configured. Note that the script generated uses array variables,
so you need bash version 2 and later to run them. This option is not
available in the DOS version.

.br
If \-\-script is specified without an argument, then the script is
piped (using popen) directly into a shell (sh) process.  This is
really useful only with \-\-config.

.br
For each card, the script tries to execute the shell script
/etc/pnp/config-scripts/isa/PRODUCT_ID or, failing that,
/usr/share/pnp/config-scripts/isa/PRODUCT_ID.  The generated shell
script will try the compatible device ID's if any can any are in the
ISA PnP information and no script for the device itself can be found.

.br
The /usr/share directory contents are the standard location, while the
/etc directory is for you to put your customized versions of these
scripts.  You should write these shell scripts to generate the file
/etc/conf.modules.isapnp at boot time, and then do something like "cat
/etc/conf.modules.isapnp /etc/conf.modules.base > /etc/conf.modules",
so that you can automatically configure the modules for the devices
that you have.
.TP
.I "\-v, \-\-version"
Print the isapnptools version number on stderr.
.SH FILES
.TP
\fC/sbin/pnpdump\fR
The executable.
.TP
\fC/etc/isapnp.conf\fR
The resting place of the editted output.
\fC/etc/isapnp.gone\fR
The standard place for describing resources that are unavailable,
but not flagged as such in /proc/* etc. The format of this file
is explained in the example provided with \fBisapnptools\fP.
.SH BUGS
If the resource allocation is impossible, pnpdump -c is not
intelligent enough to realise this and may hang trying to find a
solution.

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

.br
If you think you have found one not mentioned in the latest version,
please send a report to isapnp@roestock.demon.co.uk.
.SH WARNING
This program can reset all your Plug-and-Play devices.
It can also lock up your machine.
Use at your own risk.
.SH AUTHOR
\fBpnpdump\fP has been written by Peter Fox <fox@roestock.demon.co.uk>,
the creator and maintainer of isapnptools.
.SH AVAILABILITY
The latest version of the sources may be obtained by ftp from
ftp://ftp.demon.co.uk/pub/unix/linux/utils
.br
Or follow the pointer from my web page at
http://www.roestock.demon.co.uk/isapnptools/
.SH REFERENCES
Plug and Play ISA Specification, Version 1.0a, May 5, 1994.
Available from ftp://ftp.microsoft.com/developr/drg/Plug-and-Play/Pnpspecs
.SH "SEE ALSO"
isapnp(8), isapnp.conf(5)