Installation instructions for the PCMCIA cardmgr

Build the programs with "make".  I've included a sample config file
(config.sample) and a sample script for setting up a network adapter
(network.sample).  You will probably want to start cardmgr from your
/etc/rc.d/rc.M file.  "make install" will copy cardmgr to /usr/sbin,
and put the configuration files in /etc/pcmcia.

Normally, "cardmgr" requires no command line options.  By default,
cardmgr reads card descriptions from /etc/pcmcia/config.  You can use
the "-c" option to specify another file.  It will look for loadable
modules in /usr/src/linux/modules; you can use the "-m" option to
specify another directory.  Status information will be written to the
system log.

The "status" utility displays some information about currently active
cards.  If a card is not recognized (and is not configured), it will
not be displayed.

PCMCIA configuration file format

There are three kinds of entries in cardmgr config files: resource
descriptions, driver descriptions, and card descriptions.  These may
occur in any order, however, a card can only be defined after all its
drivers are defined.

1.  Resource descriptions

There are three kinds of resource entries: "include", "exclude", and
"reserve".  "Including" a resource enables Card Services to allocate
that resource for client drivers.  Part of a resource that is under
Card Services control can be "excluded" if a specific device in the
system uses that resource.  And, a resource can be "reserved", so that
it will only be assigned to a client if that client specifically asks
for that resource, or no other suitable resources are available.

There are three resource types: ports, memory, and irq's.  By default,
Card Services assumes that it can use any interrupt that is not bound
by another device driver.  However, it makes no assumptions about port
and address ranges, because many Linux drivers do not register their
resource usage.  So, port and memory ranges must be explicitly made
available for use by PCMCIA devices.

So, here is a portion of a config file:

	include port 0x300-0x3ff, memory 0xd0000-0xdffff
        reserve irq 3
	exclude irq 4

This says that Card Services can reserve ports in the range 0x300 to
0x3ff, and memory in the range 0xd0000 to 0xdffff.  It should not use
irq 4 (even if it is currently available).  And irq 3 should only be
allocated if a client specifically asks for it.

Card Services will never reserve resources actually reserved by
another device driver.  The "include/exclude/reserve" mechanism just
provides a way of controlling what resources it will try to use, to
accomodate devices that are not registered with the Linux resource
manager.

2.  Device driver declarations

All Card Services client drivers are identified by a 16-character tag.
"Device" entries in the config file describe client drivers.  The only
required field is the device tag.  Additional fields can specify
kernel modules that need to be loaded to make the device available,
and system commands to be executed to enable and disable instances of
a device.  When an instance of a driver is assigned to a socket, it
gives cardmgr a device name by which this device will be known by the
system (for example, eth0 for a net device, or ttyS1 for a modem).
This name will be substituted for "%d%" embedded in the start and stop
commands.  For example:

	device "de650_cs"
	  module "8390", "de650_cs"
	  start "/etc/pcmcia/network %d% start"
	  stop  "/etc/pcmcia/network %d% stop"

This says that the "de650_cs" device requires two loadable modules.
When an appropriate card is inserted and initialized, the "start"
command will be executed, after substituting the ethernet interface
name for "%d%".

3.  Card declarations

Card declarations map PCMCIA cards to their client drivers.  A card
declaration consists of a descriptive name, a method for identifying
the card when it is inserted, and driver bindings.  There are two
identification methods: the "version" method matches a card using its
VERSION_1 id strings, and the "tuple" method matches a card using any
string embedded in any arbitrary CIS tuple.  For example:

	card "Linksys Ethernet Card"
	  tuple 0x40, 0x0009, "E-CARD PC Ethernet Card"
	  bind "de650_cs"

This card is identified by a string at offset 0x0009 in tuple 0x40,
and will be bound to the "de650_cs" driver (which must be already
declared in a "driver" declaration).

	card "D-Link DE-650 Ethernet Card"
	  version "D-Link", "DE-650", "*", "*"
	  bind "de650_cs"

This card will be identified using its VERSION_1 tuple, and will also
be bound to the de650_cs driver.
