CD Actual 13/CDA13.ISO/DOC/HOWTO/OTHER_FO/SGML/PCMCIA_H.GZ/PCMCIA-HOWTO.sgml

SGML Document | 1996-08-25 | 66.2 KB | 1,604 lines

<!doctype linuxdoc system>

<article>

<title>Linux PCMCIA HOWTO
<author>David Hinds, <tt/[e-mail]/
<date>v1.87, 28 July 1996
<abstract>
This document describes how to install and use PCMCIA Card Services
for Linux, and answers some frequently asked questions.
The latest version of this document can always be found at
<tt/hyper.stanford.edu/ in <tt>/pub/pcmcia/doc</tt>.  An HTML
version is at
<tt>http://hyper.stanford.edu/~dhinds/pcmcia/pcmcia.html</tt>
</abstract>

<toc>

<sect>General information and hardware requirements

<sect1>Introduction

<p>
Card Services for Linux is a complete PCMCIA support package.  It
includes a set of loadable kernel modules that implement a version of
the PCMCIA Card Services applications program interface, a set of
client drivers for specific cards, and a card manager daemon that can
respond to card insertion and removal events, loading and unloading
drivers on demand.  It supports ``hot swapping'' of PCMCIA cards, so
cards can be inserted and ejected at any time.

This software is still under development.  It probably contains bugs,
and should be used with caution.  I'll do my best to fix problems that
are reported to me, but if you don't tell me, I may never know.  If
you use this code, I hope you will send me your experiences, good or
bad!

If you have any suggestions for how this document could be improved,
please let me know (<tt/[e-mail]/).

<sect1>Copyright notice and disclaimer
<p>
Copyright (c) 1996 David A. Hinds

This document may be reproduced or distributed in any form without my
prior permission.  Modified versions of this document, including
translations into other languages, may be freely distributed, provided
that they are clearly identified as such, and this copyright is
included intact.

This document may be included in commercial distributions without my
prior consent.  While it is not required, I would like to be informed
of such usage.  If you intend to incorporate this document in a
published work, please contact me to make sure you have the latest
available version.

This document is provided ``as is'', with no explicit or implied
warranties.  Use the information in this document at your own risk.

<sect1>What is the latest version, and where can I get it?<label id="where">

<p>
The current major release of Card Services is version 2.8, and minor
updates or bug fixes are numbered 2.8.1, 2.8.2, and so on.

Source code for the latest version is available from
<tt/hyper.stanford.edu/ in the <tt>/pub/pcmcia</tt> directory, as
<tt/pcmcia-cs-2.8.?.tar.gz/.  There will usually be several versions
here.  I generally only keep the latest minor release for a given
major release.  New major releases may contain relatively untested
code, so I also keep the latest version of the previous major release
as a relatively stable fallback; the current fallback is 2.7.6.  It is
up to you to decide which version is more appropriate, but the
<tt/CHANGES/ file will summarize the most important differences.

<tt/hyper.stanford.edu/ is mirrored at <tt/sunsite.unc.edu/ in
<tt>/pub/Linux/kernel/pcmcia</tt>.
I'll also try to upload major releases to <tt/tsx-11.mit.edu/ under
<tt>/pub/linux/packages/laptops/pcmcia</tt> now and then.

If you do not feel up to compiling the PCMCIA drivers from scratch,
pre-compiled drivers are included with current releases of most of the
major Linux distributions, including Slackware, Red Hat, Caldera, and
Yggdrasil, among others.

<sect1>What systems are supported?

<p>
This code should run on almost any Linux-capable laptop.  All common
PCMCIA controllers are supported, including Intel, Cirrus, Vadem,
VLSI, Ricoh, and Databook chips.  Custom controllers used in IBM and
Toshiba laptops are also supported.  Several people use the package on
desktop systems with PCMCIA card adapters.

The Motorola 6AHC05GA controller used in some Hyundai laptops is not
supported.  The custom PCMCIA controller in the HP Omnibook 600 is
also unsupported.

<sect1>What PCMCIA cards are supported?

<p>
The current release includes drivers for a variety of ethernet cards,
a driver for modem and serial port cards, several SCSI adapter
drivers, a driver for ATA/IDE drive cards, and memory card drivers
that should support most SRAM cards and some flash cards.  The
<tt/SUPPORTED.CARDS/ file included with each release of Card Services
lists all cards that are known to work in at least one actual system.

The likelihood that a card not on the supported list will work depends
on the type of card.  Essentially all modems should work with the
supplied driver.  Some network cards may work if they are OEM versions
of supported cards.  Other types of IO cards (GPS, frame buffers,
sound cards, etc) will not work until someone writes the appropriate
drivers.

<sect1>When will card X be supported?

<p>
Unfortunately, they do not pay me to write device drivers, so if you
would like to have a driver for your favorite card, you are probably
going to have to do at least some of the work.  The
<tt/SUPPORTED.CARDS/ file mentions some cards for which driver work is
currently in progress.  I will try to help where I can.

<sect1>Mailing list

<p>
I maintain a database and mailing list of Linux PCMCIA users.  This is
used to announce new releases of the PCMCIA package.  To be included,
send me the following:

<itemize>
<item>Your name and email address
<item>What kind of laptop are you using?
<item>What PCMCIA controller is reported by the <tt/probe/ command?
<item>What PCMCIA cards are you using?
<item>Any special settings you use: compilation options, irq and port
settings, <tt>/etc/pcmcia/config.opts</tt> changes, <tt/insmod/ options,
etc.
</itemize>

You can also register via the WWW: see
<tt>http://hyper.stanford.edu/~dhinds/pcmcia/pcmcia.html</tt> for
instructions.

There is also a Linux mailing list devoted to laptop issues, the
``linux-laptop'' list.  For more information, send a message
containing the word ``help'' to <tt/[e-mail]/.

<sect>Compilation, installation, and configuration

<sect1>Prerequisites and kernel setup<label id="prereq">

<p>
The following things should be installed on your system before you
start installing PCMCIA:
<itemize>
<item>
One of the following kernels: 1.2.8 through 1.2.13, 1.3.30, 1.3.37,
1.3.39 through 1.3.99, 1.99.* (i.e., pre-2.0), or 2.0.*.
<item>
A current set of module utilities.
<item>
(Optional) the ``Forms'' X11 user interface toolkit.
</itemize>

The latest version requires a kernel version 1.2.8 or higher, or a
development kernel 1.3.30 or higher.  1.3.38 is definitely broken, and
1.3.31 to 1.3.36 are untested.  It also requires a relatively recent
set of module utilities.  There are no kernel patches specifically for
PCMCIA.

You need to have a complete linux source tree for your kernel, not
just an up-to-date kernel image, to compile the PCMCIA package.  The
PCMCIA modules contain some references to kernel source files.  While
you may want to build a new kernel to remove unnecessary drivers,
installing PCMCIA does not require you to do so.

Current ``stable'' kernel sources and patches are available from
<tt/sunsite.unc.edu/ in <tt>/pub/Linux/kernel/v1.2</tt>, or from
<tt/tsx-11.mit.edu/ in <tt>/pub/linux/sources/system/v1.2</tt>.
Current module utilities can be found in the same place, in
<tt/modules-1.2.8.tgz/.  Development kernels can be found in the
corresponding <tt/v1.3/ subdirectories.  Some recent development
kernels and compiler releases interact badly with older sets of module
tools.  The latest versions of the module utilities can be found at
<tt><http://www.pi.se/blox/modules></tt>.

When configuring your kernel, if you plan on using a PCMCIA ethernet
card, you should turn on networking support but turn off the normal
Linux network card drivers, including the ``pocket and portable
adapters''.  The PCMCIA network card drivers are all implemented as
loadable modules.  Any drivers compiled into your kernel will only
waste space.

If you want to use SLIP, PPP, or PLIP, you do need to either configure
your kernel with these enabled, or use the loadable module versions of
these drivers.  There is an unfortunate deficiency in the kernel
config process in 1.2.X kernels, in that it is not possible to set
configuration options (like SLIP compression) for a loadable module,
so it is probably better to just link SLIP into the kernel if you
need it.

If you want to use a PCMCIA token ring adapter, your kernel needs to
be configured with ``Token Ring driver support'' (<tt/CONFIG_TR/)
enabled, though you should leave <tt/CONFIG_IBMTR/ off.

If you will be using a PCMCIA SCSI adapter, you should enable
<tt/CONFIG_SCSI/ when configuring your kernel.  Also, enable any top
level drivers (SCSI disk, tape, cdrom, generic) that you expect to
use.  All low-level drivers for particular host adapters should be
disabled, as they will just take up space.

If you want to modularize a driver that is needed for a PCMCIA device,
you must modify <tt>/etc/pcmcia/config</tt> to specify what modules
need to be loaded for what card types.  For example, if the serial
driver is modularized, then you could change the serial device
definition to:

<tscreen><verb>
device "serial_cs"
  class "serial" module "serial", "serial_cs"
</verb></tscreen>

If your kernel is compiled with <tt/CONFIG_MODVERSIONS/ enabled, for
kernel symbol version checking, the configure script will check for
the existence of <tt>/usr/include/linux/modversions.h</tt>, the symbol
version database.  This is created by running ``make dep'' in the
kernel source tree.

This package includes an X-based card status utility called
<tt/cardinfo/.  This utility is based on a public domain user
interface toolkit called the Forms Library, which you will need to
install before building <tt/cardinfo/.  A binary distribution is on
<tt/hyper.stanford.edu/ in <tt>/pub/pcmcia/extras</tt>: there are both
a.out and ELF versions of the library.

<sect1>Installation

<p>

Here is a synopsis of the installation process:

<itemize>
<item>
Unpack pcmcia-cs-2.8.?.tar.gz in /usr/src.
<item>
Run ``<tt/make config/'' in the new <tt/pcmcia-cs-2.8.?/ directory.
<item>
Run ``<tt/make all/'', then ``<tt/make install/''.
<item>
Customize <tt>/etc/rc.d/rc.pcmcia</tt> and the option files in
<tt>/etc/pcmcia</tt> for your site.
</itemize>

Running ``<tt/make config/'' prompts for a few configuration options,
and checks out your system to verify that it satisfies all
prerequisites for installing PCMCIA support.  In most cases, you'll be
able to just accept all the default configuration options.  Be sure to
carefully check the output of this command in case there are problems.

If you are compiling the PCMCIA stuff for installation on another
machine, specify an alternate target directory when prompted by the
configure script.  This should be an absolute path.  All the PCMCIA
tools will be installed relative to this directory.  You will then be
able to <tt/tar/ this directory tree and copy to your target machine,
and unpack relative to its root directory to install everything in the
proper places.

If you are cross compiling on another machine, you may want to specify
alternate names for the compiler and linker.  This may also be helpful
on mixed a.out and ELF systems.  The script will also prompt for
additional compiler flags for debugging.

There are a few kernel configuration options that affect the PCMCIA
tools.  The configuration script can deduce these from the running
kernel (the most common case).  Alternatively, if you are compiling
for installation on another machine, it can read the configuration
from a kernel source tree, or each option can be set interactively.

Running ``<tt/make all/'' followed by ``<tt/make install/'' will build
and then install the kernel modules and utility programs.  Kernel
modules are installed under <tt>/lib/modules/<version>/pcmcia</tt>.
The <tt/cardmgr/ and <tt/cardctl/ programs are installed in
<tt>/sbin</tt>.  If <tt/cardinfo/ is built, it is installed in
<tt>/usr/bin/X11</tt>.

Configuration files will be installed in the <tt>/etc/pcmcia</tt>
directory.  If you are installing over an older version, your old
config scripts will be backed up before being replaced.  The saved
scripts will be given extensions like <tt/*.~1~/, <tt/*.~2~/, and so
on.

If you don't know what kind of PCMCIA controller chip you have, you
can use the <tt/probe/ utility in the <tt>cardmgr/</tt> subdirectory to
determine this.  There are two major types: the Databook TCIC-2 type
and the Intel i82365SL-compatible type.

A user-level daemon processes card insertion and removal events.  This
is called <tt/cardmgr/.  It is similar in function to Barry Jaspan's
<tt/pcmciad/ in earlier PCMCIA releases.  <tt/Cardmgr/ reads a
configuration file describing known PCMCIA cards from
<tt>/etc/pcmcia/config</tt>.  This file also specifies what resources
can be allocated for use by PCMCIA devices, and may need to be
customized for your system.  See the <tt/pcmcia/ man page for more
information about this file.

The script <tt/rc.pcmcia/, installed in <tt>/etc/rc.d</tt>, controls
starting up and shutting down the PCMCIA system.
``<tt/make install/'' will use the <tt/probe/ command to determine
your controller type and modify <tt/rc.pcmcia/ appropriately.  You
should add a line to your system startup file <tt>/etc/rc.d/rc.M</tt>
to invoke this:

<tscreen><verb>
/etc/rc.d/rc.pcmcia start
</verb></tscreen>

In a few cases, the <tt/probe/ command will be unable to determine
your controller type automatically.  The Tadpole P1000 and some other
PCI-based laptops have a special Cirrus PCI-to-PCMCIA bridge chip that
can't be detected by <tt/probe/.  If you have one of these systems,
you'll need to edit <tt/rc.pcmcia/ by hand to load the <tt/i82365/
module.  If you have a Halikan NBD 486 system, it has a TCIC-2
controller at an unusual location: you'll need to edit <tt/rc.pcmcia/
to load the <tt/tcic/ module, as well as setting the <tt/PCIC_OPTS/
parameter to ``<tt/tcic_base=0x02c0/''.

<sect1>Site-specific configuration options<label id="timing">

<p>
Card Services should automatically avoid allocating IO ports and
interrupts already in use by other standard devices.  It will also
attempt to detect conflicts with unknown devices, but this is not
completely reliable.  In some cases, you may need to explicitly
exclude resources for a device in <tt>/etc/pcmcia/config.opts</tt>.

Here are some resource settings for specific laptop types.

<itemize>
<item>
On the AMS SoundPro, exclude irq 10.
<item>
On some AMS TravelPro 5300 models, use memory 0xc8000-0xcffff.
<item>
On the BMX 486DX2-66, exclude irq 5, irq 9.
<item>
On the Chicony NB5, use memory 0xda000-0xdffff.
<item>
On the HP Omnibook 4000C, exclude port 0x300-0x30f.
<item>
On the NEC Versa M, exclude irq 9, port 0x2e0-2ff.
<item>
On the NEC Versa P/75, exclude irq 5, irq 9.
<item>
On the NEC Versa S, exclude irq 9, irq 12.
<item>
On the ProStar 9200, Altima Virage, and Acquiline Hurricane DX4-100,
exclude irq 5, port 0x330-0x35f.  Maybe use memory 0xd8000-0xdffff.
<item>
On the TI TravelMate 5000, use memory 0xd4000-0xdffff.
<item>
On the Toshiba T4900 CT, exclude irq 5, port 0x2e0-0x2e8, port
0x330-0x338.
<item>
On the Twinhead 5100, HP 4000, Sharp PC-8700 and PC-8900, exclude
irq 9 (sound), irq 12.
<item>
On an MPC 800 Series, exclude irq 5, port 0x300-0x30f for the CD-ROM.
</itemize>

Some PCMCIA controllers have optional features that may or may not be
implemented in a particular system.  It is generally impossible for a
socket driver to detect if these features are implemented.  Check the
man page for your driver to see what optional features may be enabled.

The low level socket drivers, <tt/tcic/ and <tt/i82365/, have numerous
bus timing parameters that may need to be adjusted for systems with
particularly fast processors.  Symptoms of timing problems include
card recognition problems, lock-ups under heavy loads, high error
rates, or poor device performance.  Check the corresponding man pages
for more details, but here is a brief summary:

<itemize>
<item>
Cirrus controllers have numerous configurable timing parameters.  The
most important is the <tt/freq_bypass/ flag which changes the
multiplier for the PCMCIA bus clock to slow down all operations.
<item>
The Cirrus PD6729 PCI controller has the <tt/fast_pci/ flag, which
should be set if the PCI bus speed is greater than 25 MHz.
<item>
For Vadem VG-468 controllers and Databook TCIC-2 controllers, the
<tt/async_clock/ flag changes the relative clocking of PCMCIA bus and
host bus cycles.  Setting this flag adds extra wait states to some
operations.  However, I have yet to hear of a laptop that needs this.
<item>
The <tt/pcmcia_core/ module has the <tt/cis_speed/ parameter for
changing the memory speed used for accessing a card's Card Information
Structure (CIS).  On some systems with fast bus clocks, increasing
this parameter (i.e., slowing down card accesses) may be beneficial.
<item>
This isn't a timing issue, but if you have more than one PCMCIA
controller in your system or extra sockets in a docking station,
the <tt/i82365/ module should be loaded
with the <tt/extra_sockets/ parameter set to 1.
</itemize>

All these options should be configured by modifying the top of
<tt>/etc/rc.d/rc.pcmcia</tt>.  For example:

<tscreen><verb>
# Should be either i82365 or tcic
PCIC=i82365
# Put socket driver timing parameters here
PCIC_OPTS="cmd_time=12"
# Put pcmcia_core options here
CORE_OPTS="cis_speed=500"
</verb></tscreen>

Here are some timing settings for specific systems:

<itemize>
<item>On the ARM Pentium-90 or Midwest Micro Soundbook Plus, use
``<tt/freq_bypass=1 cmd_time=8/''.
<item>On a Midwest Micro Soundbook Elite, use ``<tt/cmd_time=12/''.
<item>On a Gateway Liberty, try ``<tt/cmd_time=16/''.
</itemize>

On some systems using Cirrus controllers, including the NEC Versa M,
the BIOS puts the controller in a special suspended state at system
startup time.  On these systems, the <tt/probe/ command will fail to
find any known PCMCIA controller.  If this happens, edit
<tt>/etc/rc.d/rc.pcmcia</tt> by hand as follows:

<tscreen><verb>
# Should be either i82365 or tcic
PCIC=i82365
# Put socket driver timing parameters here
PCIC_OPTS="wakeup=1"
</verb></tscreen>

<sect1>Problems loading kernel modules

<p>
The configure script will normally ensure that the PCMCIA modules are
compatible with your kernel.  So, module loading problems generally
indicate that the user has interfered with the normal installation
process in some way.  Some module loading errors are sent directly to
the Linux console.  Other errors are recorded in the system log file,
normally <tt>/usr/adm/messages</tt> or <tt>/var/log/messages</tt>.  To
track down a problem, be sure to check both locations, to pin down
which module is actually causing trouble.

Some of the PCMCIA modules require kernel services that may or may not
be present, depending on kernel configuration.  For instance, the SCSI
card drivers require that the kernel be configured with SCSI support,
and the network drivers require a networking kernel.  If a kernel
lacks a necessary feature, <tt/insmod/ may report undefined symbols
and refuse to load a module.

If <tt/insmod/ reports ``wrong version'' errors, it means that the
module was compiled for a different kernel version than your system is
actually running.  This might occur if modules compiled on one machine
are copied to another machine with a different configuration, or if
the kernel is reconfigured after PCMCIA is installed.

Another source of module loading errors is when the modules and kernel
were compiled with different settings of <tt/CONFIG_MODVERSIONS/.  If
a module with version checking is loaded against a kernel without
version checking, <tt/insmod/ will complain about undefined symbols.

Finally, relatively recent binutils releases are incompatible with
older versions of the module utilities, and can cause module version
incompatibilities to be reported.  The most common symptom is
complaints about ``<tt/gcc_compiled/'' being undefined.  If you get
these errors, upgrade to the latest module utilities, available from
<tt><http://www.pi.se/blox/modules></tt>.

<sect1>Problems with the card status change interrupt

<p>
In most cases, the socket driver (<tt/i82365/ or <tt/tcic/) will
automatically probe and select an appropriate interrupt to signal card
status changes.  The automatic interrupt probe doesn't work on some
Intel-compatible controllers, including Cirrus chips and the chips
used in some IBM ThinkPads.  If a device is inactive at probe time,
its interrupt may also appear to be available.  In these cases, the
socket driver may pick an interrupt that is used by another device.

With the <tt/i82365/ and <tt/tcic/ drivers, the <tt/irq_mask/ option
can be used to limit the interrupts that will be tested.  This mask
limits the set of interrupts that can be used by PCMCIA cards as well
as for monitoring card status changes.  The <tt/cs_irq/ option can
also be used to explicitly set the interrupt to be used for monitoring
card status changes.

If you can't find an interrupt number that works, there is also a
polled status mode: both <tt/i82365/ and <tt/tcic/ will accept a
<tt/poll_interval=100/ option, to poll for card status changes once
per second.  This option should also be used if your system has a
shortage of interrupts available for use by PCMCIA cards.  Especially
for systems with more than one PCMCIA controller, there is little
point in dedicating interrupts for monitoring card status changes.

All these options should be set in the <tt/PCIC_OPTS=/ line in either
<tt>/etc/rc.d/rc.pcmcia</tt> or <tt>/etc/sysconfig/pcmcia</tt>,
depending on your site setup.

The most common problem of this type seems to be a conflict with a
PS/2 pointer device on interrupt 12.  In this case, edit
<tt/rc.pcmcia/ so the <tt/PCIC_OPTS=/ line reads:

<tscreen><verb>
PCIC_OPTS="irq_mask=0xefff"
</verb></tscreen>

<sect1>Memory window configuration problems

<p>
By default, the PCMCIA drivers use the address region 0xd0000-0xdffff
to access PCMCIA devices.  This memory window is specified in
<tt>/etc/pcmcia/config.opts</tt>.  If this address region is used by
other devices in your system, cards may not be identified correctly.
With chipsets that support it, conflicts can also result from memory
shadowing in this region.  If you find that all your cards are always
misidentified as memory cards, verify that shadowing is disabled in
your system's hardware setup.  As there is no reliable way to
automatically identify memory window conflicts, finding a good window
may require some experimentation.  Some alternative windows to try are
0xd8000-0xdffff, 0xc0000-0xcffff, and 0xc8000-0xcffff.

If you have DOS PCMCIA drivers, you may be able to deduce what memory
region those drivers use.  Note that DOS memory addresses are often
specified in ``segment'' form, which leaves off the final hex digit
(so an absolute address of 0xd0000 would be given as 0xd000).  Be sure
to add the extra digit back when making changes to
<tt>/etc/pcmcia/config.opts</tt>.

<sect1>What about installation on Red Hat and Caldera?

<p>
Red Hat and Caldera have a System V-ish arrangement for system startup
files.  The PCMCIA installation scripts will automatically detect this
and adjust accordingly.  The <tt/rc.pcmcia/ script will be installed as
<tt>/etc/rc.d/init.d/pcmcia</tt>.  There is no need to edit any of the
Caldera startup scripts to enable PCMCIA: it will happen
automatically.

A separate configuration file, <tt>/etc/sysconfig/pcmcia</tt>, will
be created for startup options.  If you need to change any module
options (like the <tt/PCIC=/ or <tt/PCIC_OPTS=/ settings), edit this config
file rather than the actual PCMCIA startup script.  This file will not
be overwritten by subsequent installs.

Previous releases used the <tt>/etc/sysconfig/pcmcia-scripts</tt>
directory in place of <tt>/etc/pcmcia</tt> on these platforms.  The
current release instead uses <tt>/etc/pcmcia</tt> for all systems, and
will move an existing <tt>/etc/sysconfig/pcmcia-scripts</tt> to
<tt>/etc/pcmcia</tt>.

<sect1>Why don't you distribute PCMCIA binaries?

<p>
For me, distributing binaries is a significant hassle.  It is
complicated because some features can only be selected at compile
time, and because the PCMCIA modules are somewhat dependent on having
the ``right'' kernel configuration.  So, I would probably need to
distribute precompiled modules along with matching kernels.  Beyond
this, the greatest need for precompiled modules is when installing
Linux on a clean system.  This typically requires setting up PCMCIA so
that it can be used in the installation process for a particular Linux
distribution.  Each Linux distribution has its own procedures, and it
is not feasible for me to provide boot and root disks for even just
the common combinations of drivers and distributions.

PCMCIA is now a part of many of the major Linux distributions,
including Red Hat, Caldera, Slackware, Yggdrasil, Craftworks, and
Nascent Technology.

<sect1>Why is the PCMCIA package so darned big?

<p>
Well, first of all, it isn't actually that large.  All the driver
modules together take up about 200K of disk space.  The utility
programs add up to about 70K, and the stuff in /etc/pcmcia is about
30K.  When running, the core PCMCIA modules take up 48K of system
memory.  The cardmgr daemon will generally be swapped out except when
cards are inserted or removed.  The total package size is not much
different from DOS Card Services implementations.

Compared to DOS ``point enablers'', this may still seem like a lot of
overhead, especially for people that don't plan on using many of the
features of PCMCIA, such as power management or hot swapping.  Point
enablers can be tiny because they generally support only one or a
small set of cards, and also generally support a restricted set of
PCMCIA controllers.  If someone were to write a genuinely ``generic''
modem enabler, it would end up incorporating much of the functionality
of Card Services, to handle cards from different vendors and the full
range of PCMCIA controller variants.

<sect>Usage and features

<sect1>How do I tell if it is working?

<p>
The <tt/cardmgr/ daemon normally beeps when a card is inserted, and
the tone of the beeps indicates the status of the newly inserted card.
Two high beeps indicate the card was identified and configured
successfully.  A high beep followed by a lower beep indicates that the
card was identified, but could not be configured for some reason.  One
low beep indicates that the card could not be identified.

If you are running X, the new <tt/cardinfo/ utility produces a slick
graphical display showing the current status of all PCMCIA sockets.

If the modules are all loaded correctly, the output of the <tt/lsmod/
command should look like the following, with no cards inserted:

<tscreen><verb>
Module:        #pages:  Used by:
ds                 2
i82365             3
pcmcia_core        7    [ds i82365]
</verb></tscreen>

All the PCMCIA modules and the <tt/cardmgr/ daemon send status
messages to the system log.  This will usually be
<tt>/var/log/messages</tt> or <tt>/usr/adm/messages</tt>.
This file should be the first place to
look when tracking down a problem.  When submitting a bug report,
always include the contents of this file.  <tt/Cardmgr/ also records
some current device information for each socket in <tt>/var/run/stab</tt>.
Here is a sample <tt>/var/run/stab</tt> listing:

<tscreen><verb>
Socket 0: Adaptec APA-1460 SlimSCSI
0    scsi    aha152x_cs    0    sda    8    0
0    scsi    aha152x_cs    1    scd0    11    0
Socket 1: Serial or Modem Card
1    serial    serial_cs    0    cua1    5    65
</verb></tscreen>

For the lines describing devices, the first field is the socket, the
second is the device class, the third is the driver name, the fourth
is used to number multiple devices associated with the same driver,
the fifth is the device name, and the final two fields are the major
and minor device numbers for this device.

<sect1>Overview of the PCMCIA configuration scripts

<p>
Each PCMCIA device has an associated ``class'' that describes how it
should be configured and managed.  Classes are associated with device
drivers in <tt>/etc/pcmcia/config</tt>.  There are currently five IO
device classes (network, SCSI, cdrom, fixed disk, and serial) and
three memory device classes (FTL, memory, and pcmem).  For each class,
there are two
scripts in <tt>/etc/pcmcia/config</tt>: a main configuration script
(i.e., <tt>/etc/pcmcia/scsi</tt> for SCSI devices), and an options
script (i.e., <tt>/etc/pcmcia/scsi.opts</tt>).  The main script for a
device will be invoked to configure that device when a card is
inserted, and to shut down the device when the card is removed.  For
cards with several associated devices, the script will be invoked for
each device.

The config scripts start by extracting some information about a device
from <tt>/var/run/stab</tt>.  Each script constructs a ``device address'',
that uniquely describes the device it has been asked to configure, in
the <tt/ADDRESS/ variable.  This is passed to the <tt/*.opts/ script,
which should return information about how a device at this address
should be configured.  For some devices, the device address is just
the socket number.  For others, it includes extra information that may
be useful in deciding how to configure the device.  For example,
network devices pass their hardware ethernet address as part of the
device address, so the <tt/network.opts/ script could use this to
select from several different configurations.

The first part of all device addresses is the current PCMCIA
``scheme''.  This parameter is used to support multiple sets of device
configurations based on a single external user-specified variable.
One use of schemes would be to have a ``home'' scheme, and a ``work''
scheme, which would include different sets of network configuration
parameters.  The current scheme is selected using the <tt/cardctl/
command.  The default if no scheme is set is ``default''.

As a general rule, when configuring Linux for a laptop, PCMCIA devices
should only be configured from the PCMCIA device scripts.  Do not try
to configure a PCMCIA device the same way you would configure a
permanently attached device.

<sect1>How do I use my PCMCIA network card?

<p>
Linux ethernet-type network interfaces normally have names like
<tt/eth0/, <tt/eth1/, and so on.  Token-ring adapters are handled
similarly, however they are named <tt/tr0/, <tt/tr1/, and so on.
The <tt/ifconfig/ command is used to
view or modify the state of a network interface.  A peculiarity of
Linux is that network interfaces do not have corresponding device
files under <tt>/dev</tt>, so don't be surprised when you can't find
them.

When a PCMCIA ethernet card is detected, it will be assigned the first
free interface name, which will probably be <tt/eth0/.  <tt/Cardmgr/
will run the <tt>/etc/pcmcia/network</tt> script to configure the
interface.

Do not configure your PCMCIA ethernet card in
<tt>/etc/rc.d/rc.inet1</tt>, since the card may not be present when
this script is executed.  Comment out everything except the loopback
stuff in <tt/rc.inet1/.
If your system has an automatic network configuration procedure, you
should indicate that you do not have a network card installed.
Instead, edit the
<tt>/etc/pcmcia/network.opts</tt> file to match your local network setup.
The <tt/network/ and <tt/network.opts/ scripts will be executed only
when your ethernet card is actually present.

The device address passed to <tt/network.opts/ consists of three
comma-separated fields: the scheme, the socket number, the device
instance, and the card's hardware ethernet address.  The device
instance is used to
number devices for cards that have several network interfaces, so it
will usually be 0.  If you have several network cards used for
different purposes, one option would be to configure the cards based
on socket position, as in:

<tscreen><verb>
case "$ADDRESS" in
*,0,*,*)
    # definitions for network card in socket 0
    ;;
*,1,*,*)
    # definitions for network card in socket 1
    ;;
esac
</verb></tscreen>

Alternatively, they could be configured using their hardware
addresses, as in:

<tscreen><verb>
case "$ADDRESS" in
*,*,*,00:80:C8:76:00:B1)
    # definitions for a D-Link card
    ;;
*,*,*,08:00:5A:44:80:01)
    # definitions for an IBM card
esac
</verb></tscreen>

To automatically mount and unmount NFS filesystems, first add all
these filesystems to <tt>/etc/fstab</tt>, but include <tt>noauto</tt>
in the mount options.  In <tt>network.opts</tt>, list the filesystem
mount points in the <tt>MOUNTS</tt> variable.  It is especially
important to use either <tt/cardctl/ or <tt/cardinfo/ to shut down a
network card when NFS mounts are configured this way.  It is not
possible to cleanly unmount NFS filesystems if a network card is
simply ejected without warning.

<sect1>How do I use my PCMCIA modem card?

<p>
Linux serial devices are accessed via the <tt>/dev/cua*</tt> and
<tt>/dev/ttyS*</tt> special device files.  The <tt/ttyS*/ devices are
for incoming connections, such as directly connected terminals.  The
<tt/cua*/ devices are for outgoing connections, such as modems.  The
configuration of a serial device can be examined and modified with the
<tt/setserial/ command.

When a PCMCIA serial or modem card is detected, it will be assigned to
the first available serial device slot.  This will usually be
<tt>/dev/cua1</tt> or <tt>/dev/cua2</tt>, depending on the number of
built-in serial ports.  The default serial device option script,
<tt>/etc/pcmcia/serial.opts</tt>, will link the appropriate device
file to <tt>/dev/modem</tt> as a convenience.

Do not try to use <tt>/etc/rc.d/rc.serial</tt> to configure a PCMCIA
modem.  This script should only be used to configure non-removable
devices.  Modify <tt>/etc/pcmcia/serial.opts</tt> if you want to do
anything special to set up your modem.

The device address passed to <tt/serial.opts/ has three comma-separated
fields: the first is the scheme, the second  is the socket number, and
the third is the device
instance.  The device instance may take several values for cards that
support multiple serial ports, but for single-port cards, it will
always be 0.  If you commonly use more than one PCMCIA modem, you may
want to specify different settings based on socket position, as in:

<tscreen><verb>
case "$ADDRESS" in
*,0,*)
    # Options for modem in socket 0
    ;;
*,1,*)
    # Options for modem in socket 1
    ;;
esac
</verb></tscreen>

If a PCMCIA modem is already configured when Linux boots, it may be
incorrectly identified as an ordinary built-in serial port.  This is
harmless, however, when the PCMCIA drivers take control of the modem,
it will be assigned a different device slot.  It is best to either
parse <tt>/var/run/stab</tt> or use <tt>/dev/modem</tt>, rather than
expecting a PCMCIA modem to always have the same device assignment.

If you configure your kernel to load the basic Linux serial port
driver as a module, you must edit <tt>/etc/pcmcia/config</tt> to
indicate that this module must be loaded.  Edit the serial device
entry to read:

<tscreen><verb>
device "serial_cs"
  class "serial" module "char/serial", "serial_cs"
</verb></tscreen>

<sect1>How do I use my PCMCIA SCSI card?

<p>
All the currently supported PCMCIA SCSI cards are work-alikes of one
of the following ISA bus cards: the Qlogic, the Adaptec AHA-152X, or
the Future Domain TMC-16x0.  The PCMCIA drivers are built by linking
some PCMCIA-specific code (in <tt/qlogic_cs.c/, <tt/toaster_cs.c/, or
<tt/fdomain_cs.c/) with the normal Linux SCSI driver.

When a new SCSI host adapter is detected, the SCSI drivers will probe
for devices.  Check the system log to make sure your devices are
detected properly.  New SCSI devices will be assigned to the first
available SCSI device files.  The first SCSI disk will be
<tt>/dev/sda</tt>, the first SCSI tape will be <tt>/dev/st0</tt>, and
the first CD-ROM will be <tt>/dev/scd0</tt>.

With 1.3.X kernels, the PCMCIA core drivers are able to find out from
the kernel which SCSI devices are connected to a card.  They will be
listed in <tt>/var/run/stab</tt>, and the SCSI configuration script,
<tt>/etc/pcmcia/scsi</tt>, will be called once for each attached
device, to either configure or shut down that device.  The default
script does not take any actions to configure SCSI devices, but will
properly unmount filesystems on SCSI devices when a card is removed.

With 1.2.X kernels, the PCMCIA drivers cannot automatically deduce
which devices are associated with a particular SCSI adapter.  Instead,
if you have one normal SCSI device configuration, you may list these
devices in <tt>/etc/pcmcia/scsi.opts</tt>.  For example, if you
normally have a SCSI disk and a CD-ROM, you would use:

<tscreen><verb>
# For 1.2 kernels: list of attached devices
SCSI_DEVICES="sda scd0"
</verb></tscreen>

The device addresses passed to <tt/scsi.opts/ are complicated, because
of the variety of things that can be attached to a SCSI adapter.
Addresses consist of either six or seven comma-separated fields: the
current scheme, the
device type, the socket number, the SCSI channel, ID, and logical unit
number, and optionally, the partition number.  The device type will be
``sd'' for disks, ``st'' for tapes, ``sr'' for CD-ROM devices, and
``sg'' for generic SCSI devices.  For most setups, the SCSI channel
and logical unit number will be 0.  For disk devices with several
partitions, <tt/scsi.opts/ will first be called for the whole device,
with a five-field address.  The script should set the <tt/PARTS/
variable to a list of partitions.  Then, <tt/scsi.opts/ will be called
for each partition, with the longer seven-field addresses.  For example,
here is a script for configuring a disk device at SCSI ID 3, with two
partitions, and a CD-ROM at SCSI ID 6:

<tscreen><verb>
case "$ADDRESS" in
*,sd,*,0,3,0)
    # This device has two partitions...
    PARTS="1 2"
    ;;
*,sd,*,0,3,0,1)
    # Options for partition 1:
    #  update /etc/fstab, and mount an ext2 fs on /usr1
    DO_FSTAB="y" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="ext2"
    OPTS=""
    MOUNTPT="/usr1"
    ;;
*,sd,*,0,3,0,2)
    # Options for partition 2:
    #  update /etc/fstab, and mount an MS-DOS fs on /usr2
    DO_FSTAB="y" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="msdos"
    OPTS=""
    MOUNTPT="/usr2"
    ;;
*,sr,*,0,6,0)
    # Options for CD-ROM at SCSI ID 6
    PARTS=""
    DO_FSTAB="y" ; DO_FSCK="n" ; DO_MOUNT="y"
    FSTYPE="iso9660"
    OPTS="ro"
    MOUNTPT="/cdrom"
    ;;
esac
</verb></tscreen>

If your kernel does not have a top-level driver (disk, tape, etc) for
a particular SCSI device, then the device will not be configured by
the PCMCIA drivers.  As a side effect, the device's name in
<tt>/var/run/stab</tt> will be something like ``sd#nnnn'' where ``nnnn''
is a four-digit hex number.  This happens when <tt/cardmgr/ is unable
to translate a SCSI device ID into a corresponding Linux device name.

It is possible to modularize the top-level SCSI drivers so that they
are only loaded when a PCMCIA SCSI adapter is detected.  To do so, you
need to edit <tt>/etc/pcmcia/config</tt> to tell <tt/cardmgr/ which
extra modules need to be loaded when your adapter is configured.
For example:

<tscreen><verb>
device "aha152x_cs"
  class "scsi" module "scsi/scsi_mod", "scsi/sd_mod", "aha152x_cs"
</verb></tscreen>

would say to load the core SCSI module and the top-level disk driver
module before loading the regular PCMCIA driver module.

Always turn on SCSI devices before powering up your laptop, or before
inserting the adapter card, so that the SCSI bus is properly
terminated when the adapter is configured.  Also be very careful about
ejecting a SCSI adapter.  Be sure that all associated SCSI devices are
unmounted and closed before ejecting the card.  The best way to ensure
this is to use either <tt/cardctl/ or <tt/cardinfo/ to request card
removal before physically ejecting the card.  For now, all SCSI
devices should be powered up before plugging in a SCSI adapter, and
should stay connected until after you unplug the adapter and/or power
down your laptop.

There is a potential complication when using these cards that does not
arise with ordinary ISA bus adapters.  The SCSI bus carries a
``termination power'' signal that is necessary for proper operation of
ordinary passive SCSI terminators.  PCMCIA SCSI adapters do not supply
termination power, so if it is required, an external device must
supply it.  Some external SCSI devices may be configured to supply
termination power.  Others, such as the Zip Drive and the Syquest
EZ-Drive, use active terminators that do not depend on it.  In some
cases, it may be necessary to use a special terminator block such as
the APS SCSI Sentry 2, which has an external power supply.  When
configuring your SCSI device chain, be aware of whether or not any of
your devices require or can provide termination power.

The Adaptec APA-460 SlimSCSI adapter is not supported.  This card was
originally sold under the Trantor name, and when Adaptec merged with
Trantor, they continued to sell the Trantor card with an Adaptec
label.  The APA-460 is not compatible with any existing Linux driver.
I'm not sure how hard it would be to write a driver; I don't think
anyone has been able to obtain the technical information from Adaptec.

The (unsupported) Trantor SlimSCSI can be identified by the following:

<tscreen><verb>
Trantor / Adaptec APA-460 SlimSCSI
FCC ID: IE8T460
Shipped with SCSIworks! driver software
</verb></tscreen>

The (supported) Adaptec SlimSCSI can be identified by the following:

<tscreen><verb>
Adaptec APA-1460 SlimSCSI
FCC ID: FGT1460
P/N: 900100
Shipped with EZ-SCSI driver software
</verb></tscreen>

<sect1>How do I use my PCMCIA memory card?

<p>
The default memory card startup script will create block and character
devices for accessing each partition on a memory card.  There are two
memory card drivers... <tt/pcmem_cs/, the older driver, works well for
simple static RAM cards.  The newer driver, <tt/memory_cs/, is mostly
for direct access to flash memory cards.  Check the man pages for a
detailed description of how devices are named.  Both block and
character devices are created.  The block device is used for disk-like
access (creating and mounting filesystems, etc).  The character device
is for "raw" reads and writes at arbitrary locations.

To use a flash memory card as an ordinary disk-like block device,
first create a ``flash translation layer'' partition on the device
with the <tt/ftl_format/ command:

<tscreen><verb>
ftl_format -i /dev/mem0c0c
</verb></tscreen>

Note that this command accesses the card through the ``raw'' memory
card interface.  Once formatted, the card can be accessed as an
ordinary block device via the <tt/ftl_cs/ driver.  For example:

<tscreen><verb>
mke2fs /dev/ftl0
mount -t ext2 /dev/ftl0 /mnt
</verb></tscreen>

With the FTL and ``new'' memory drivers, the device address passed to
<tt/ftl.opts/ and <tt/memory.opts/ consists of two fields: the socket
number, and the partition number.  Common memory partitions are
numbered before attribute memory partitions.  Generally, the only
interesting partition is partition 0 (the main common-memory
partition, where data is stored).  Here is an example of a script that
will automatically mount flash memory cards based on which socket they
are inserted into:

<tscreen><verb>
case "$ADDRESS" in
*,0,0)
    # Mount filesystem, but don't update /etc/fstab
    DO_FSTAB="n" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="ext2" ; OPTS=""
    MOUNTPT="/ftl0"
    ;;
*,1,0)
    # Mount filesystem, but don't update /etc/fstab
    DO_FSTAB="n" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="ext2" ; OPTS=""
    MOUNTPT="/ftl1"
    ;;
esac
</verb></tscreen>

There are two major formats for flash memory cards: the ``flash
translation layer'' style, and the Microsoft Flash File System.  The
FTL format is generally more flexible because it allows any ordinary
high-level filesystem (ext2, ms-dos, etc) to be used on a flash card
as if it were an ordinary disk device.  The FFS is a complete new
filesystem type.  Linux cannot currently handle cards formated with
FFS.

<sect1>How do I use my ATA/IDE card drive?

<p>
ATA/IDE drive support requires a 1.3.72 or higher kernel.  The
PCMCIA-specific part of the driver is <tt/fixed_cs/.  Be sure to use
<tt/cardctl/ or <tt/cardinfo/ to shut down an ATA/IDE card before
ejecting it, as the driver has not been made ``hot-swap-proof''.

The device addresses passed to <tt/fixed.opts/ consist of either two
or three fields: the current scheme, the socket number, and an
optional partition number.  As with SCSI devices, <tt/fixed.opts/ is
first called for the entire device.  If <tt/fixed.opts/ returns a list
of partitions in the <tt/PARTS/ variable, the script will then be
called for each partition.

Here is an example <tt/fixed.opts/ file to mount the first partition
of any ATA/IDE card on <tt>/mnt</tt>.

<tscreen><verb>
case "$ADDRESS" in
*,*)
    PARTS="1"
    ;;
*,*,1)
    DO_FSTAB="y" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="msdos"
    OPTS=""
    MOUNTPT="/mnt"
    ;;
esac
</verb></tscreen>

<sect1>How do I tell <tt/cardmgr/ how to identify a new card?<label id="new-card">

<p>
Assuming that your card is supported by an existing driver, all
that needs to be done is to add an entry to
<tt>/etc/pcmcia/config</tt> to tell <tt/cardmgr/ how to identify the card,
and which driver(s) need to be linked up to this card.  Check the man
page for <tt/pcmcia/ for more information about the config file format.
If you insert an unknown card, <tt/cardmgr/ will normally record some
identification information in the system log that can be
used to construct the config entry.

Here is an example of how cardmgr will report an unsupported card in
<tt>/usr/adm/messages</tt>.

<tscreen><verb>
cardmgr[460]: unsupported card in socket 1
cardmgr[460]: version info: "MEGAHERTZ", "XJ2288", "V.34 PCMCIA MODEM"
</verb></tscreen>

The corresponding entry in <tt>/etc/pcmcia/config</tt> would be:

<tscreen><verb>
card "Megahertz XJ2288 V.34 Fax Modem"
  version "MEGAHERTZ", "XJ2288", "V.34 PCMCIA MODEM"
  bind "serial_cs"
</verb></tscreen>

You can use ``*'' to match strings that don't need to match exactly,
like version numbers.  When making new config entries, be careful
to copy the strings exactly, preserving case and blank spaces.
Also be sure that the config entry has the same number of strings as
are reported in the log file.

After editing <tt>/etc/pcmcia/config</tt>, you can signal <tt/cardmgr/
to reload the file with:

<tscreen><verb>
kill -HUP `cat /var/run/cardmgr.pid`
</verb></tscreen>

If you do set up an entry for a new card, please send me a copy so
that I can include it in the standard config file.

<sect1>How do I control which interrupts and ports are used by a device?

<p>
In theory, it should not really matter which interrupt is allocated to
which device, as long as two devices are not configured to use the
same interrupt.  In <tt>/etc/pcmcia/config.opts</tt> you'll find
a place for excluding interrupts that are used by non-PCMCIA devices.

Note that the interrupt used to monitor card status changes is chosen
by the low-level socket driver module (<tt/i82365/ or <tt/tcic/)
before <tt/cardmgr/ parses <tt>/etc/pcmcia/config</tt>, so it is not
affected by changes to this file.  To set this interrupt, use the
<tt/irq_mask/ or <tt/cs_irq/ options when the socket driver is loaded,
in <tt>/etc/rc.d/rc.pcmcia</tt>.

All the client card drivers have a parameter called <tt/irq_mask/ for
specifying which interrupts they may try to allocate.  Each bit of
irq_mask corresponds to one irq line: bit 0 is irq 0, bit 1 is irq 1,
and so on.  So, a mask of 0x1200 would correspond to irq 9 and irq 12.
To limit a driver to use only one specific interrupt, its irq_mask
should have only one bit set.  These driver options should be set in
your <tt>/etc/pcmcia/config</tt> file.  For example:

<tscreen><verb>
device "serial_cs"
  module "serial_cs" opts "irq_mask=0x1100"
  ...
</verb></tscreen>

would specify that the serial driver should only use irq 8 or irq 12.
Note that Card Services will never allocate an interrupt that is
already in use by another device, or an interrupt that is excluded
in the config file.

There is no way to directly specify the I/O addresses for a PCMCIA
card to use.  The <tt>/etc/pcmcia/config.opts</tt> file allows you
to specify ranges of ports available for use by all PCMCIA devices.

After modifying <tt>/etc/pcmcia/config</tt>, you can restart
<tt/cardmgr/ with ``<tt/kill -HUP/''.

<sect1>When is it safe to insert or eject a PCMCIA card?

<p>
In theory, you can insert and remove PCMCIA cards at any time.
However, it is a good idea not to eject a card that is currently being
used by an application program.  Kernels older than 1.1.77 would often
lock up when serial/modem cards were ejected, but this should be fixed
now.

<sect1>How do I unload PCMCIA drivers?

<p>
To unload the entire PCMCIA package, invoke <tt/rc.pcmcia/ with:

<tscreen><verb>
/etc/rc.d/rc.pcmcia stop
</verb></tscreen>

This script will take several seconds to run, to give all client
drivers time to shut down gracefully.  If a PCMCIA device is currently
in use, the shutdown will be incomplete, and some kernel modules may
not be unloaded.  To avoid this, use ``<tt/cardctl eject/'' to shut
down all sockets before invoking <tt/rc.pcmcia/.  The exit status of
the <tt/cardctl/ command will indicate if any sockets could not be
shut down.

<sect1>How does Card Services deal with suspend/resume?

<p>
Card Services can be compiled with support for APM (Advanced Power
Management) if you've installed this package on your system.  APM is
incorporated into 1.3.46 and later kernels.  It is currently being
maintained by Rick Faith ([e-mail]), and APM tools can be
obtained from <tt/ftp.cs.unc.edu/ in <tt>/pub/users/faith/linux</tt>.
The PCMCIA modules will automatically be configured
for APM if a compatible version is detected on your system.

Without resorting to APM, you can do ``<tt/cardctl suspend/'' before
suspending your laptop, and ``<tt/cardctl resume/'' after resuming, to
properly shut down and restart your PCMCIA cards.  This will not work
with a PCMCIA modem that is in use, because the serial driver isn't
able to save and restore the modem operating parameters.

APM seems to be unstable on some systems.  If you experience trouble
with APM and PCMCIA on your system, try to narrow down the problem to
one package or the other before reporting a bug.

<sect1>How do I turn off a PCMCIA card without ejecting it?

<p>
Use either the <tt/cardctl/ or <tt/cardinfo/ command.
``<tt/cardctl suspend #/'' will suspend one socket, and turn off
its power.  The corresponding <tt/resume/ command will wake up the
card in its previous state.

<sect1>How can I have separate device configurations for home and work?

<p>
This is trivial using PCMCIA ``scheme'' support.
Use two configuration schemes, called ``home'' and ``work''.  Here is
an example of a <tt/network.opts/ script with scheme-specific
settings:

<tscreen><verb>
case "$ADDRESS" in
work,*,*,*)
    # definitions for network card in work scheme
    ;;
home,*,*,*|default,*,*,*)
    # definitions for network card in home scheme
    ;;
esac
</verb></tscreen>

The first part of a PCMCIA device address is always the configuration
scheme.  In this example, the second ``case'' clause will select for
both the ``home'' and ``default'' schemes.  So, if the scheme is unset
for any reason, it will default to the ``home'' setup.

Now, to choose between the two sets of settings, run either:

<tscreen><verb>
cardctl scheme home
</verb></tscreen>

or

<tscreen><verb>
cardctl scheme work
</verb></tscreen>

The <tt/cardctl/ command does the equivalent of shutting down all your
cards and restarting them.  The command can be safely executed whether
or not the PCMCIA system is loaded, but the command may fail if you
are using other PCMCIA devices at the time (even if their
configurations are not explicitly dependant on the scheme setting).

To find out the current PCMCIA scheme setting, run:

<tscreen><verb>
cardctl scheme
</verb></tscreen>

<sect>Problems with specific cards

<sect1>Why doesn't my modem work?

<p>
That's a broad question, but here's a quick troubleshooting guide.

<itemize>
<item>
Is your card recognized as a modem?  Check the system log and
make sure that <tt/cardmgr/ identifies the card correctly and starts up the
<tt/serial_cs/ driver.  If it doesn't, you may need to add a new entry to
your <tt>/etc/pcmcia/config</tt> file so that it will be identified properly.
See section <ref id="new-card" name="3.6"> for details.
<item>
Is the modem configured successfully by serial_cs?  Again, check
the system log and look for messages from the serial_cs driver.  If
you see ``register_serial() failed'', you may have an I/O port conflict
with another device.  Another
tip-off of a conflict is if the device is reported to be an 8250; most
modern PCMCIA modems should be identified as 16550A UART's.  If you
think you're seeing a port conflict, edit <tt>/etc/pcmcia/config.opts</tt>
and exclude the port range that was allocated for the modem.
<item>
Is there an interrupt conflict?  If the system log looks good,
but the modem just doesn't seem to work, try using <tt/setserial/ to
change the irq to 0, and see if the modem works.  This causes the
serial driver to use a slower polled mode instead of using interrupts.
If this seems to fix the problem, it is likely that some other device
in your system is using the interrupt selected by serial_cs.  You
should add a line to <tt>/etc/pcmcia/config.opts</tt> to exclude this
interrupt.
<item>
If the modem seems to work only really, really slowly, this is an
almost certain indicator of an interrupt conflict.
<item>
Make sure your problem is really a PCMCIA one.  It may help to see
if the card works under DOS with the vendor's drivers.  Also, don't
test the card with something complex like SLIP until you are sure you
can make simple connections.  If simple things work but SLIP does not,
your problem is most likely with SLIP, not with PCMCIA.
</itemize>

<sect1>Why doesn't my network adapter card work?

<p>
Here's another quick troubleshooting guide.

<itemize>
<item>
Is your card recognized as an ethernet card?  Check the system log and
make sure that <tt/cardmgr/ identifies the card correctly and starts
up one of the network drivers.  If it doesn't, your card might still
be usable if it is compatible with a supported card.  This will be
most easily done if the card claims to be ``NE2000 compatible''.
<item>
Is the card configured properly?  If you are using a supported card,
and it was recognized by <tt/cardmgr/, but still doesn't work, there
might be an interrupt or port conflict with another device.  Find out
what resources the card is using (from the system log),
and try excluding these in <tt>/etc/pcmcia/config.opts</tt> to force
the card to use something different.
<item>
If your card seems to be configured properly, but sometimes locks up,
particularly under high load, you may need to try changing your socket
driver timing parameters.  See section <ref id="timing" name="2.3">
for more information.
<item>
If you get messages like ``network unreachable'' when you try to
access the network, then you have probably set up
<tt>/etc/pcmcia/network.opts</tt> incorrectly.  On the other hand,
mis-configured cards will usually fail silently.
<item>
To diagnose problems in <tt>/etc/pcmcia/network.opts</tt>, start by
trying to ping other systems on the same subnet using their IP
addresses.  Then try to ping your gateway, and then machines on other
subnets.  Ping machines by name only after trying these simpler tests.
<item>
Make sure your problem is really a PCMCIA one.  It may help to see see
if the card works under DOS with the vendor's drivers.  Double check
your modifications to the <tt>/etc/pcmcia/network.opts</tt> script.
Make sure your drop cable, ``T'' jack, terminator, etc are working.
</itemize>

Here are some comments about specific cards:

<itemize>
<item>
With IBM CCAE and Socket EA cards, you need
to pick the transceiver type (10base2, 10baseT, AUI) when the network
device is configured.  Make sure that the transceiver type reported in
the system log matches your connection.
<item>
The drivers for SMC, Megahertz, Ositech, and 3Com cards should
autodetect the attached network type (10base2 or 10baseT).  Setting
the transceiver type when the driver is loaded serves to define the
card's ``first guess''.
<item>
The Farallon EtherWave is actually based on the 3Com 3c589, with a
special transceiver.  Though the EtherWave uses 10baseT-style
connections, its transceiver requires that the 3c589 be configured in
10base2 mode.
<item>
If you have trouble with an IBM CCAE, NE4100, Thomas Conrad, or
Kingston adapter, try increasing the memory access
time with the <tt/mem_speed=#/ option to the <tt/pcnet_cs/ module.
An example of how to do this is given in the standard <tt/config.opts/
file.  Try speeds of up to 1000 (in nanoseconds).
<item>
For the New Media Ethernet adapter, on some systems, it may be
necessary to increase the IO port access time with the
<tt/io_speed=#/ option when the <tt/pcmcia_core/ module is loaded.
Edit <tt/CORE_OPTS/ in <tt>/etc/rc.d/rc.pcmcia</tt> to set this option.
<item>
The driver used by the IBM and 3Com token ring adapters
seems to behave very badly if the cards are not connected to a ring
when they get initialized.  Always connect these cards to the net
before they are powered up.
</itemize>

<sect1>How do I select the transceiver type for a network card?

<p>
The transceiver type can be selected in <tt/network.opts/ using the
<tt/IF_PORT/ setting.  This can either be a numeric value as in
previous PCMCIA releases, or a keyword identifying the transceiver
type.  All the network drivers default to either autodetect the
interface if possible, or 10baseT otherwise.  The <tt/ifport/ command
can be used to check or set the current transceiver type.  For
example:

<tscreen><verb>
# ifport eth0 10base2
#
# ifport eth0
eth0    2 (10base2)
</verb></tscreen>

Current releases of the 3c589 driver attempt to autodetect the network
connection, but this doesn't seem to be completely functional yet.
For autodetection to work, the network cable should be connected to the
card when the card is configured.  Alternatively, once the network is
connected, you can force the driver to check the connection with:

<tscreen><verb>
ifconfig eth0 down up
</verb></tscreen>

<sect1>How do I add support for an NE2000-compatible ethernet card?

<p>
First, see if the card is already recognized by <tt/cardmgr/.  Some
cards not listed in <tt/SUPPORTED.CARDS/ are actually OEM versions of
cards that are supported.  If you find a card like this, let me know
so I can add it to the list.

If your card is not recognized, follow the instructions in section
<ref id="new-card" name="3.6"> to create a config entry for your card,
but bind the card to the memory card driver, <tt/pcmem_cs/ for now.
Restart <tt/cardmgr/ to use the new updated config file.

You will need to know your card's hardware ethernet address.  This
address is a series of six two-digit hex numbers, often printed on the
card itself.  If it is not printed on the card, you may be able to use
a DOS driver to display the address.  In any case, once you know it,
run:

<tscreen><verb>
dd if=/dev/pcmem0a count=20 | od -Ax -t x1
</verb></tscreen>

and search the output for your address.  Record the hex offset of the
first byte of the address.  Now, edit <tt>modules/pcnet_cs.c</tt> and
find the <tt/hw_info/ structure.  You'll need to create a new entry
for your card.  The first field is a descriptive name.  The next field
is the offset multiplied by two.  The
next three fields are the first three bytes of the hardware address.
The final field contains some flags for specific card features; to
start, try setting it to 0.

After editing <tt/pcnet_cs.c/, compile and install the new module.
Edit <tt>/etc/pcmcia/config</tt> again, and change the card binding
from <tt/pcmem_cs/ to <tt/pcnet_cs/.  Follow the instructions for
reloading the config file, and you should be all set.  Please send me
copies of your new <tt/hw_info/ and config entries.

If you can't find your card's hardware address in the hex dump, as a
method of last resort, it is possible to ``hardwire'' the address when
the <tt/pcnet_cs/ module is initialized.  Edit
<tt>/etc/pcmcia/config</tt> and add a <tt/hw_addr=/ option, like so:

<tscreen><verb>
module "pcnet_cs" opts "hw_addr=0x00,0x80,0xc8,0x01,0x02,0x03"
</verb></tscreen>

Substitute your own card's hardware address in the appropriate spot,
of course.

<sect1>Multifunction cards such as the 3Com 3c562

<p>
Starting with the 1.3.73 Linux kernel, a single interrupt can be
shared by several drivers, such as the serial driver and an ethernet
driver.  When using a multifunction card under a newer kernel, all
card functions can be used simultaneously.

Earlier kernels do not support interrupt sharing between different device
drivers, so it is not possible for the PCMCIA drivers to configure
this card for simultaneous ethernet and modem access.  The ethernet
and serial drivers are both loaded automatically.  However, the
ethernet driver ``owns'' the card interrupt by default.  To use the
modem, you can unload the ethernet driver and reconfigure the serial
port by doing something like:

<tscreen><verb>
ifconfig eth0 down
rmmod 3c589_cs
setserial /dev/modem autoconfig auto_irq
setserial /dev/modem
</verb></tscreen>

The second <tt/setserial/ should verify that the port has been
configured to use the interrupt previously used by the ethernet
driver.

<sect1>How do I use my PCMCIA floppy interface?

<p>
The PCMCIA floppy interface used in the Compaq Aero and a few other
laptops is not yet supported by this package.  The snag in supporting
the Aero floppy is that the Aero seems to use a customized
PCMCIA controller to support DMA to the floppy.  Without
knowing exactly how this is done, there isn't any way to implement
support under Linux.

If the floppy adapter card is present when an Aero is booted, the Aero
BIOS will configure the card, and Linux will identify it as a normal
floppy drive.  When the Linux PCMCIA drivers are loaded, they will
notice that the card is already configured and attached to a Linux
driver, and this socket will be left alone.  So, the drive can be used
if it is present at boot time, but the card is not hot swappable.

<sect1>What's up with support for Xircom cards?

<p>
Xircom does not share technical information about its cards without a
non-disclosure agreement.  This means that it is not really possible
to develop freely distributable drivers for Xircom cards without doing
legally dubious things like reverse engineering DOS drivers.

Recently, Xircom seems to have had a change of heart about their
non-disclosure policy, and it now seems that this information will be
more readily available in the future.  However, please do not pester
me with questions about Xircom cards: drivers will be announced when
they become available, and I will not try to guess when that will be.

The Xircom CreditCard Ethernet+Modem II card can be used as a modem
under Linux, with no special configuration.

<sect>Debugging tips and programming information

<sect1>How can I submit a helpful bug report?

<p>
Here are some things that should be included in all bug reports:

<itemize>
<item>Your system type, and the output of the <tt/probe/ command
<item>What PCMCIA cards you are using
<item>Your Linux kernel version, and PCMCIA version
<item>The contents of the <tt/config.out/ file
<item>Any changes you've made to the startup files in
<tt>/etc/pcmcia</tt>, or to <tt/rc.pcmcia/
<item>All PCMCIA-related stuff in your system log file
</itemize>

Before submitting a bug report, please check to make sure that you are
using an up-to-date copy of the driver package.  While it is somewhat
gratifying to read bug reports for things I've already fixed, it isn't
a particularly constructive use of my time.

If your problem involves a kernel fault, the register dump from the
fault is only useful if you can track down the fault address, EIP.  If
it is in the main kernel, look up the address in <tt/System.map/ to
identify the function at fault.  If the fault is in a loadable module,
it is a bit harder to trace.  With the current module tools,
``<tt/ksyms -m/'' will report the base address of each loadable
module.  Pick the module that contains the EIP address, and subtract
its base address from EIP to get an offset inside that module.  Then,
run <tt/gdb/ on that module, and look up the offset with the <tt/list/
command.  This will only work if you've compiled that module with
<tt/-g/ to include debugging information.

Send bug reports to <tt/[e-mail]/.  I prefer to handle
bug reports by email -- please avoid calling me at home or at work.
You can also submit bug reports via the WWW: see
<tt>http://hyper.stanford.edu/~dhinds/pcmcia/pcmcia.html</tt> for
details.

<sect1>Low level PCMCIA debugging aids

<p>
The PCMCIA modules contain a lot of conditionally-compiled debugging
code.  Most of this code is under control of the <tt/PCMCIA_DEBUG/
preprocessor define.  If this is undefined, debugging code will
not be compiled.  If set to 0, the code is compiled but inactive.
Larger numbers specify increasing levels of verbosity.  Each module
built with <tt/PCMCIA_DEBUG/ defined will have an integer parameter,
<tt/pc_debug/, that controls the verbosity of its output.  This
can be adjusted when the module is loaded, so output can be controlled
on a per-module basis without recompiling.

There are a few debugging tools in the <tt>debug_tools/</tt>
subdirectory of the PCMCIA distribution.  The <tt/dump_tcic/ and
<tt/dump_i365/ utilities generate complete register dumps of the
PCMCIA controllers, and decode a lot of the register information.
They are most useful if you have access to a datasheet for the
corresponding controller chip.  The <tt/dump_tuples/ utility lists a
card's CIS (Card Information Structure), and decodes some of the
important bits.  And the <tt/dump_cisreg/ utility displays a card's
local configuration registers.

The <tt/pcmem_cs/ memory card driver is also sometimes useful for
debugging.  It can be bound to any PCMCIA card, and does not interfere
with other drivers.  It can be used to directly access any card's
attribute memory or common memory.

<sect1>How do I write a Card Services driver for card X?

<p>
The Linux PCMCIA Programmer's Guide is the best documentation for the
Linux PCMCIA interface.  The latest version is always available from
<tt/cb-iris.stanford.edu/ in <tt>/pub/pcmcia/doc</tt>.

For devices that are close relatives of normal ISA devices, you'll
probably be able to use parts of existing Linux drivers.  In some
cases, the biggest stumbling block will be modifying an existing
driver so that it can handle adding and removing devices after boot
time.  Of the current drivers, the memory card driver is the only
``self-contained'' driver that does not depend on other parts of the
Linux kernel to do most of the dirty work.

I've written a skeleton driver with lots of comments that explains a
lot of how a driver communicates with Card Services; you'll find this
in the PCMCIA source distribution in <tt>modules/skeleton.c</tt>.

</article>