Card Services for Linux is a complete PCMCIA or ``PC Card'' support package. It includes a set of loadable kernel modules that implement a version of the 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 most card types, so cards can be safely inserted and ejected at any time.

This software is a work in progress. It 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 (dahinds@users.sourceforge.net).

Copyright (c) 1998-2002 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 express or implied warranties. Use the information in this document at your own risk.

The current major release of Card Services is version 3.2, and minor updates or bug fixes are numbered 3.2.1, 3.2.2, and so on.

Source code for the latest version is available on the web at http://pcmcia-cs.sourceforge.net, as pcmcia-cs-3.2.?.tar.gz. You may find more than one release number here. It is up to you to decide which version is more appropriate, but the CHANGES file will summarize the most important differences.

Pre-compiled drivers are included with current releases of essentially all major Linux distributions, including Slackware, Debian, Red Hat, Caldera, and SuSE, among others. So generally there is no need to compile the drivers from scratch.

This package should run on almost Intel-based Linux-capable laptop. It also runs on some Alpha, PowerPC, ARM, and MIPS platforms. Most common socket controllers are supported. Card docks for desktop systems should work as long as they use a supported controller, and are plugged directly into the ISA or PCI bus, as opposed to SCSI-to-PCMCIA or IDE-to-PCMCIA adapters. The following controllers are recognized by the supplied socket drivers:

Other controllers that are register compatible with the Intel i82365sl will generally work, as well.

Due to the rapid pace of technological change for laptop hardware, new controllers appear frequently, and there may be delays between when a new model appears on the market, and when driver support becomes available.

Support for Toshiba's ToPIC bridges was hindered for a long time by a lack of sufficiently detailed technical documentation. While some datasheets have been available, a few idiosyncracies of the ToPIC chips were not adequately explained. Toshiba has given some direct technical help on some of these issues, and I think the major ones have been resolved. However, with the introduction of kernel PCMCIA support in 2.4.* and later kernels, some new Toshiba bugs may have cropped up in the new socket driver code.

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

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 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 (frame buffers, sound cards, etc) will not work until someone writes the appropriate drivers.

Unfortunately, they usually don't 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. Ideally, I'd like to work towards a model like the Linux kernel, where I would be responsible mainly for the ``core'' driver code and other authors would contribute and maintain client drivers for specific cards. The SUPPORTED.CARDS file mentions some cards for which driver work is currently in progress. I will try to help where I can, but be warned that debugging kernel device drivers by email is not particularly effective.

The Linux PCMCIA information page is at http://pcmcia-cs.sourceforge.net, and has bug tracking, support and feature requests, and a variety of PCMCIA related message forums. Users can request email notification of new responses to particular questions, or notification for all new messages in a given category. I hope that this will become a useful repository of information, for questions that go beyond the scope of the HOWTO.

The Linux Laptop Page at http://www.linux-on-laptops.com has links to a vast number of sites that have information about configuring specific types of laptops for Linux. There is also a searchable database of system configuration information, and pointers to a variety of laptop-related mailing lists.

Before starting, you should think about whether you really need to compile the PCMCIA package yourself. All common Linux distributions come with pre-compiled driver packages. Generally, you only need to install the drivers from scratch if you need a new feature of the current drivers, or if you've updated and/or reconfigured your kernel in a way that is incompatible with the drivers included with your Linux distribution. While compiling the package is not technically difficult, it does require some general Linux familiarity.

The following things should be installed on your system before you begin:

You need to have a complete linux source tree for your kernel, not just an up-to-date kernel image. The driver 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 ftp://ftp.kernel.org/pub/linux/kernel/v2.4. Current module utilities can be found in the same locations.

In the Linux kernel source tree, the Documentation/Changes file describes the versions of all sorts of other system components that are required for that kernel release. You may want to check through this and verify that your system is up to date, especially if you have updated your kernel. If you are using a development kernel, be sure that you are using the right combination of shared libraries and module tools.

On x86 based systems, if you plan to use 16-bit PC Card devices, you should also enable CONFIG_ISA, for recent kernels. These cards behave much like ISA devices, and the PCMCIA drivers use CONFIG_ISA to judge whether a platform supports ISA bus interrupts.

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.

In order to use a PCMCIA token ring adapter, your kernel should be configured with ``Token Ring driver support'' (CONFIG_TR) enabled, though you should leave CONFIG_IBMTR off.

If you want to use a PCMCIA IDE adapter, your kernel should be configured with CONFIG_BLK_DEV_IDE_PCMCIA enabled, for 2.0.* kernels. Newer kernels do not require a special configuration setting.

If you will be using a PCMCIA SCSI adapter, then enable 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.

This package includes an X-based card status utility called cardinfo. This utility is based on a freely distributed user interface toolkit called the XForms Library. This library is available as a separate package with most Linux distributions. If you would like to build cardinfo, you should install XForms and all the normal X header files and libraries before configuring the PCMCIA package. This tool is completely optional.

PCMCIA driver support is included in the 2.4 and later linux kernel trees. While it shares most of the same code with the standalone PCMCIA driver package, there are some important differences. The kernel PCMCIA support is also still evolving.

The kernel PCMCIA code has the same functionality as the driver side of the pcmcia-cs package. It does not eliminate the need to install the pcmcia-cs package, since it requires the same user tools (cardmgr, cardctl, /etc/pcmcia/* files). The drivers in pcmcia-cs can still be built for 2.4 kernels, so you have a choice of using either the in-kernel PCMCIA drivers, or the drivers included in pcmcia-cs. With 2.5 and later kernels, the standalone drivers cannot be used.

To use the kernel PCMCIA drivers, configure the kernel with CONFIG_HOTPLUG, CONFIG_PCMCIA, and usually CONFIG_CARDBUS enabled. On x86 based systems, CONFIG_ISA should also be enabled. The drivers can either be built into the kernel or built as modules. PCMCIA client driver options are listed in their regular driver categories; thus, PCMCIA network drivers are in a submenu of network drivers, and PCMCIA serial drivers are in a submenu of character drivers.

In the standalone pcmcia-cs drivers, the i82365 module supports both ISA-to-PCMCIA, PCI-to-PCMCIA, and PCI-to-CardBus bridges. The CardBus socket driver in the 2.4 tree is the yenta_socket driver. It is selected by the CONFIG_CARDBUS option. In your PCMCIA startup options, this driver should be specified in place of the i82365 driver. The kernel version of the i82365 driver, selected by CONFIG_I82365, only supports ISA-to-PCMCIA bridges. PCI-to-PCMCIA bridges that are not CardBus capable, like the Cirrus PD6729, are not supported at all by the kernel PCMCIA drivers.

When compiling the standalone PCMCIA package, the Configure script decides whether or not to build any kernel modules by looking at the value of the CONFIG_PCMCIA option in your kernel configuration. If CONFIG_PCMCIA is enabled, then by default, no driver components are built. If CONFIG_PCMCIA is disabled, then all the modules will be built and installed. It is safe to compile the user tools (cardmgr, cardctl, etc) in a PCMCIA package whose version number differs from the PCMCIA version number in the kernel source tree. The kernel PCMCIA header files take precedence over the ones included in the PCMCIA package, if CONFIG_PCMCIA is enabled.

Here is a synopsis of the installation process:

If you plan to install any contributed client drivers not included in the core PCMCIA distribution, unpack each of them in the top-level directory of the PCMCIA source tree. Then follow the normal build instructions. The extra drivers will be compiled and installed automatically.

Running ``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. The following options are available:

The Configure script can also be executed non-interactively, for automatic builds or to quickly reconfigure after a kernel update. Some additional less-frequently-used options can be only be set from the command line. Running ``Configure --help'' lists all available options.

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

Configuration files will be installed in the /etc/pcmcia 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 an *.O extension.

If you don't know what kind of host controller your system uses, you can use the pcic&lowbar;probe utility in the cardmgr/ subdirectory to determine this. There are several major types: the Databook TCIC-2 type and the Intel i82365SL-compatible type. With the kernel PCMCIA subsystem, Intel compatible controllers are further subdivided into ISA-bus 16-bit bridges, and PCI-based CardBus bridges.

In a few cases, the pcic&lowbar;probe command will be unable to determine your controller type automatically. If you have a Halikan NBD 486 system, it has a TCIC-2 controller at an unusual location: you'll need to edit rc.pcmcia to load the tcic module, and also set the PCIC&lowbar;OPTS parameter to ``tcic&lowbar;base=0x02c0''.

On some old pre-PCI 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 pcic&lowbar;probe command will fail to find any known host controller. If this happens, edit rc.pcmcia and set PCIC to i82365, and PCIC&lowbar;OPTS to ``wakeup=1''.

The PCMCIA startup script recognizes several groups of startup options, set via environment variables. Multiple options should be separated by spaces and enclosed in quotes. Placement of startup options depends on the Linux distribution used. They may be placed directly in the startup script, or they may be kept in a separate option file. See the Notes about specific Linux distributions

The low level socket drivers, tcic and i82365, have various bus timing parameters that may need to be adjusted for certain systems with unusual bus clocking. Symptoms of timing problems can include card recognition problems, lock-ups under heavy loads, high error rates, or poor device performance. Only certain host bridges have adjustable timing parameters: check the corresponding man page to see what options are available for your controller. Here is a brief summary:

Here are some timing settings for a few old systems:

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 /etc/pcmcia/config.opts.

Here are some resource settings for specific laptop types. View this list with suspicion: it may give useful hints for solving problems, but it is inevitably out of date and certainly contains mistakes. Corrections and additions are welcome.

include port 0x100-0x4ff, port 0x1000-0x17ff
include memory 0x80000000-0x80ffffff

This section is incomplete. Corrections and additions are welcome.

if [ -f /etc/sysconfig/network-scripts/ifcfg-$2 ] ; then
    start_fn () {
	. /etc/sysconfig/network-scripts/ifcfg-$1
	if [ "$ONBOOT" = "yes" ] ; then /sbin/ifup $1 ; fi
    }
    stop_fn () {
	/sbin/ifdown $1
    }
fi

Symptoms:

Kernel modules contain version information that is checked against the current kernel when a module is loaded. The type of checking depends on the setting of the CONFIG&lowbar;MODVERSIONS kernel option. If this is false, then the kernel version number is compiled into each module, and insmod checks this for a match with the running kernel. If CONFIG&lowbar;MODVERSIONS is true, then each symbol exported by the kernel is given a sort of checksum. These codes are all compared against the corresponding codes compiled into a module. The intent was for this to make modules less version-dependent, because the checksums would only change if a kernel interface changed, and would generally stay the same across minor kernel updates. In practice, the checksums have turned out to be even more restrictive, because many kernel interfaces depend on compile-time kernel option settings. Also, the checksums turned out to be an excessively pessimistic judge of compatibility.

The practical upshot of this is that kernel modules are closely tied to both the kernel version, and the setting of many kernel configuration options. Generally, a set of modules compiled for one 2.2.19 kernel will not load against some other 2.2.19 kernel unless special care is taken to ensure that the two were built with similar configurations. This makes distribution of precompiled kernel modules a tricky business.

You have several options:

Symptoms:

Some of the driver 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, insmod may report undefined symbols and refuse to load a particular module. Note that insmod error messages do not distinguish between version mismatch errors and missing symbol errors.

Specifically:

There are two ways to proceed:

The /etc/pcmcia/config file can specify that additional modules need to be loaded for a particular client. For example, for the serial driver, one would use:

device "serial_cs"
  class "serial" module "misc/serial", "serial_cs"

Module paths are specified relative to the top-level module directory for the current kernel version; if no relative path is given, then the path defaults to the pcmcia subdirectory.

Symptoms:

After identifying the host controller type, the socket driver probes for free ISA bus interrupts. The probe involves programming the controller for each apparently free interrupt, then generating a ``soft'' interrupt, to see if the interrupt can be detected correctly. In some cases, probing a particular interrupt can interfere with another system device.

The reason for the probe is to identify interrupts which appear to be free (i.e., are not reserved by any other Linux device driver), yet are either not physically wired to the host controller, or are connected to another device that does not have a driver.

In the system log, a successful probe might look like:

Intel PCIC probe:
  TI 1130 CardBus at mem 0x10211000, 2 sockets
  ...
  ISA irqs (scanned) = 5,7,9,10 status change on irq 10

There are two ways to proceed:

In either case, the probe options can be specified using the PCIC&lowbar;OPTS definition in the PCMCIA startup script, for example:

PCIC_OPTS="irq_list=5,9,10"

It should be noted that /proc/interrupts is completely useless when it comes to diagnosing interrupt probe problems. The probe is sensible enough to never attempt to use an interrupt that is already in use by another Linux driver. So, the PCMCIA drivers are already using all the information in /proc/interrupts. Depending on system design, an inactive device can still occupy an interrupt and cause trouble if it is probed for PCMCIA.

Symptoms:

When cardmgr processes IO port ranges listed in /etc/pcmcia/config.opts, the kernel probes these ranges to detect latent devices that occupy IO space but are not associated with a Linux driver. The probe is read-only, but in rare cases, reading from a device may interfere with an important system function, resulting in a lock-up.

Your system user's guide may include a map of system devices, showing their IO and memory ranges. These can be explicitly excluded in config.opts.

Alternatively, if the probe is unreliable on your system, it can be disabled by setting CORE&lowbar;OPTS to ``probe&lowbar;io=0''. In this case, you should be very careful to specify only genuinely available ranges of ports in config.opts, instead of using the default settings.

Symptoms:

Or alternately:

The core modules perform a memory scan at the time of first 16-bit card insertion. This scan can potentially interfere with other memory mapped devices. Also, pre-3.0.0 driver packages perform a more aggressive scan than more recent drivers. The memory window is defined in /etc/pcmcia/config.opts. The default window is large, so it may help to restrict the scan to a narrower range. Reasonable ranges to try include 0xd0000-0xdffff, 0xc0000-0xcffff, 0xc8000-0xcffff, or 0xd8000-0xdffff.

If you have DOS or Windows 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 might be given as 0xd000). Be sure to add the extra digit back when making changes to config.opts.

Changing BIOS settings affecting how devices are mapped can sometimes be useful. Try changing settings for BIOS shadowing, or "Plug and Play OS support".

In unusual cases, a memory probe failure can indicate a timing register setup problem with the host controller. See the Startup options

CardBus bridges can allocate memory windows outside of the 640KB-1MB ``memory hole'' in the ISA bus architecture. It is generally a good idea to configure CardBus bridges to use high memory windows, because these are unlikely to conflict with other devices. Also, CardBus cards may require large memory windows, which may be difficult or impossible to fit into low memory. Card Services will preferentially allocate windows in high memory for CardBus bridges, if both low and high memory windows are defined in config.opts. The default config.opts includes several candidate high memory windows, one of which will work in most cases.

Symptoms:

In most cases, the socket driver (i82365 or 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 i82365 and tcic drivers, the irq&lowbar;list option can be used to limit the interrupts that will be tested. This list limits the set of interrupts that can be used by PCMCIA cards as well as for monitoring card status changes. The cs&lowbar;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 i82365 and tcic will accept a poll&lowbar;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 host controller, there is little point in dedicating interrupts for monitoring card status changes.

All these options should be set in the PCIC&lowbar;OPTS= line in either /etc/rc.d/rc.pcmcia or /etc/sysconfig/pcmcia, depending on your site setup.

Symptoms:

The most simple interrupt delivery problems are due to conflicts with other system devices. These can generally be resolved by excluding problem interrupts in /etc/pcmcia/config.opts. To test, just exclude interrupts one by one until either the problem is fixed or you run out of interrupts. If no interrupts work, then device conflicts are probably not the problem.

For CardBus bridges, a variety of other interrupt delivery issues may come into play. For a complete discussion, see PCI interrupt delivery problems

Symptoms:

Interrupt starvation often indicates a problem with the interrupt probe (see ISA interrupt scan failures

If the interrupt probe is not working properly, the socket driver may allocate an interrupt for monitoring card insertions, even when interrupts are too scarce for this to be a good idea. You can switch the controller to polled mode by setting PCIC&lowbar;OPTS to ``poll&lowbar;interval=100'. Or, if you have a CardBus controller and an older version of the PCMCIA drivers, try ``pci&lowbar;csc=1'', which selects a PCI interrupt (if available) for card status changes.

In some cases, kernel misconfiguration can also produce an apparent interrupt shortage. On 2.4 and later kernels, if CONFIG&lowbar;ISA is not enabled, then the PCMCIA drivers will assume no ISA bus interrupts are available.

IO port starvation is fairly uncommon, but sometimes happens with cards that require large, contiguous, aligned regions of IO port space, or that only recognize a few specific IO port positions. The default IO port ranges in /etc/pcmcia/config.opts are normally sufficient, but may be extended. If this is the problem, try uncommenting the ``include port 0x1000-0x17ff'' line in config.opts. In rare cases, starvation may indicate that the IO port probe failed (see IO port scan failures

Memory starvation is also uncommon with the default memory window settings in config.opts. CardBus cards may require larger memory regions than typical 16-bit cards. Since CardBus memory windows can be mapped anywhere in the host's PCI address space (rather than just in the 640K-1MB ``hole'' in PC systems), it is helpful to specify large memory windows in high memory, such as 0xa0000000-0xa0ffffff.

Symptoms:

This usually indicates a resource conflict with a system device that Linux does not know about. PCMCIA devices are dynamically configured, so, for example, interrupts are allocated as needed, rather than specifically assigned to particular cards or sockets. Given a list of resources that appear to be available, cards are assigned resources in the order they are configured. In this case, the card configured last is being assigned a resource that in fact is not free.

Check the system log to see what resources are used by the non-working card. Exclude these in /etc/pcmcia/config.opts, and restart the cardmgr daemon to reload the resource database.

Symptoms:

This indicates that the card was identified successfully, however, cardmgr has been unable to complete the configuration process for some reason. The most likely reason is that a step in the card setup script has blocked. A good example would be the network script blocking if a network card is inserted with no actual network hookup present.

To pinpoint the problem, you can manually run a setup script to see where it is blocking. The scripts are in the /etc/pcmcia directory. They take two parameters: a device name, and an action. The cardmgr daemon records the configuration commands in the system log. For example, if the system log shows that the command ``./network start eth0'' was the last command executed by cardmgr, the following command would trace the script:

sh -x /etc/pcmcia/network start eth0

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

Module                  Size  Used by
ds                      5640   2 
i82365                 15452   2 
pcmcia_core            30012   3  [ds i82365]

The system log should also include output from the socket driver describing the host controller(s) found and the number of sockets detected.

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	ttyS1	5	65

Socket 0:
  not configured
Socket 1:
  Vcc = 5.0, Vpp1 = 0.0, Vpp2 = 0.0
  Card type is memory and I/O
  IRQ 3 is dynamic shared, level mode, enabled
  Speaker output is enabled
  Function 0:
    Config register base = 0x0800
      Option = 0x63, status = 0x08
    I/O window 1: 0x0280 to 0x02bf, auto sized
    I/O window 2: 0x02f8 to 0x02ff, 8 bit

Socket 0:
  no product info available
Socket 1:
  product info: "LINKSYS", "PCMLM336", "A", "0040052D6400"
  manfid: 0x0143, 0xc0ab
  function: 0 (multifunction)

/etc/rc.d/rc.pcmcia stop

The following information applies to cards that are managed by cardmgr. In 2.4 and later kernels, if the kernel PCMCIA subsystem is active, then CardBus cards are managed by the hotplug subsystem and the PCMCIA scripts are not used.

Each PCMCIA device has an associated ``class'' that describes how it should be configured and managed. Classes are associated with device drivers in /etc/pcmcia/config. There are currently five IO device classes (network, SCSI, cdrom, fixed disk, and serial) and two memory device classes (memory and FTL). For each class, there are two scripts in <cdx>/etc/pcmcia</cdx>: a main configuration script (i.e., /etc/pcmcia/scsi for SCSI devices), and an options script (i.e., /etc/pcmcia/scsi.opts). 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 the stab file. Each script constructs a ``device address'', that uniquely describes the device it has been asked to configure, in the ADDRESS shell variable. This is passed to the *.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 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 ``cardctl scheme'' command. The default if no scheme is set is ``default''.

There are a few additional shell variables that can be used in *.opts files in addition to ADDRESS:

As the *.opts files are just shell scripts, it is not required that they follow the form of the examples, which just return settings based on ADDRESS.

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. However, some Linux distributions provide PCMCIA packages that are hooked into those distributions' own device configuration tools. In that case, some of the following sections may not apply; ideally, this will be documented by the distribution maintainers.

Linux ethernet-type network interfaces normally have names like eth0, eth1, and so on. Token-ring adapters are handled similarly, however they are named tr0, tr1, and so on. The 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 /dev, so do not be surprised when you do not find them.

When an ethernet card is detected, it will be assigned the first free interface name, which will normally be eth0. Cardmgr will run the /etc/pcmcia/network script to configure the interface, which normally reads network settings from /etc/pcmcia/network.opts. The network and network.opts scripts will be executed only when your ethernet card is actually present. If your system has an automatic network configuration facility, it may or may not be PCMCIA-aware. Consult the documentation of your Linux distribution and the Notes about specific Linux distributions

The device address passed to network.opts consists of four 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:

case "$ADDRESS" in
*,0,*,*)
    # definitions for network card in socket 0
    ;;
*,1,*,*)
    # definitions for network card in socket 1
    ;;
esac

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

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

case "$ADDRESS" in
*,*,*,*)
    IF_PORT="10base2"
    BOOTP="n"
    IPADDR="10.0.0.1"
    NETMASK="255.255.255.0"
    NETWORK="10.0.0.0"
    BROADCAST="10.0.0.255"
    GATEWAY="10.0.0.1"
    DOMAIN="domain.org"
    DNS_1="dns1.domain.org"
    ;;
esac

# ifport eth0 10base2
# 
# ifport eth0
eth0    2 (10base2)

Linux serial devices are accessed via the /dev/ttyS* and /dev/cua* special device files. In pre-2.2 kernels, the ttyS* devices were for incoming connections, such as directly connected terminals, and the cua* devices were for outgoing connections, such as modems. Use of cua* devices is deprecated in current kernels, and ttyS* can be used for all applications. The configuration of a serial device can be examined and modified with the setserial command.

When a serial or modem card is detected, it will be assigned to the first available serial device slot. This will usually be /dev/ttyS1 (cua1) or /dev/ttyS2 (cua2), depending on the number of built-in serial ports. The ttyS* device is the one reported in stab. The default serial device option script, /etc/pcmcia/serial.opts, will link the device file to /dev/modem as a convenience. For pre-2.2 kernels, the link is made to the cua* device.

Do not try to use /etc/rc.d/rc.serial to configure a PCMCIA modem. This script should only be used to configure non-removable devices. Modify /etc/pcmcia/serial.opts if you want to do anything special to set up your modem. Also, do not try to change the IO port and interrupt settings of a serial device using setserial. This would tell the serial driver to look for the device in a different place, but would not change how the card's hardware is actually configured. The serial configuration script allows you to specify other setserial options, as well as whether a line should be added to /etc/inittab for this port.

The device address passed to 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 modem, you may want to specify different settings based on socket position, as in:

case "$ADDRESS" in
*,0,*)
    # Options for modem in socket 0
    LINK=/dev/modem0
    ;;
*,1,*)
    # Options for modem in socket 1
    LINK=/dev/modem1
    ;;
esac

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 stab or use /dev/modem, 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 /etc/pcmcia/config to indicate that this module must be loaded. Edit the serial device entry to read:

device "serial_cs"
  class "serial" module "misc/serial", "serial_cs"

case "$ADDRESS" in
*,*,*)
    LINK="/dev/modem"
    SERIAL_OPTS=""
    INITTAB="/sbin/getty"

The Linux parallel port driver is layered so that several high-level device types can share use of the same low level port driver. Printer devices are accessed via the /dev/lp* special device files. The configuration of a printer device can be examined and modified with the tunelp command.

The parport&lowbar;cs module depends on the parport and parport&lowbar;pc drivers, which may be either compiled into the kernel or compiled as modules. The layered driver structure means that any top-level parallel drivers (such as the plip driver, the printer driver, etc) must be compiled as modules. These drivers only recognize parallel port devices at module startup time, so they need to be loaded after any PC Card parallel devices are configured.

The device address passed to parport.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 parallel ports, but for single-port cards, it will always be 0. If you commonly use more than one such card, you may want to specify different settings based on socket position, as in:

case "$ADDRESS" in
*,0,*)
    # Options for card in socket 0
    LINK=/dev/printer0
    ;;
*,1,*)
    # Options for card in socket 1
    LINK=/dev/printer1
    ;;
esac

case "$ADDRESS" in
*,*,*,*)
    LINK="/dev/printer"
    LP_OPTS=""

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 qlogic&lowbar;cs.c, aha152x&lowbar;cs.c, or fdomain&lowbar;cs.c) with the normal Linux SCSI driver, pulled from the Linux kernel source tree. The Adaptec APA1480 CardBus driver is based on the kernel aic7xxx PCI driver. Due to limitations in the Linux SCSI driver model, only one removable card per driver is supported.

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 /dev/sda, the first SCSI tape will be /dev/st0, and the first CD-ROM will be /dev/scd0.

A list of SCSI devices connected to this host adapter will be shown in stab, and the SCSI configuration script, /etc/pcmcia/scsi, 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.

The device addresses passed to 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, scsi.opts will first be called for the whole device, with a five-field address. The script should set the PARTS variable to a list of partitions. Then, scsi.opts will be called for each partition, with the longer six-field addresses.

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 stab will be something like ``sd&num;nnnn'' where ``nnnn'' is a four-digit hex number. This happens when 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 loaded on demand. To do so, you need to edit /etc/pcmcia/config to tell cardmgr which extra modules need to be loaded when your adapter is configured. For example:

device "aha152x_cs"
  class "scsi" module "scsi/scsi_mod", "scsi/sd_mod", "aha152x_cs"

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 cardctl or 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.

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

The memory&lowbar;cs driver handles all types of memory cards, as well as providing direct access to the PCMCIA memory address space for cards that have other functions. When loaded, it creates a combination of character and block devices. See the man page for the module for a complete description of the device naming scheme. Block devices are used for disk-like access (creating and mounting filesystems, etc). The character devices are for "raw" unbuffered reads and writes at arbitrary locations.

The device address passed to memory.opts consists of two fields: the scheme, and the socket number. The options are applied to the first common memory partition on the corresponding memory card.

Some flash memory cards, and most simple static RAM cards, lack a ``Card Information Structure'' (CIS), which is the system PCMCIA cards use to identify themselves. Normally, cardmgr will assume that any card that lacks a CIS is a simple memory card, and load the memory&lowbar;cs driver. Thus, a common side effect of a general card identification problem is that other types of cards may be misdetected as memory cards.

There is another issue to consider when handling memory cards that do not have CIS information. At startup time, the PCMCIA package tries to use the first detected card to determine what memory regions are usable for PCMCIA. The memory scan can be fooled if that card is a simple memory card. If you plan to use memory cards often, it is best to limit the memory windows in /etc/pcmcia/config.opts to known-good regions.

The memory&lowbar;cs driver uses a heuristic to guess the capacity of these cards. The heuristic does not work for write protected cards, and may make mistakes in some other cases as well. If a card is misdetected, its size should then be explicitly specified when using commands such as dd or mkfs. The memory&lowbar;cs module also has a parameter for overriding the size detection. See the man page.

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="/mem0"
    ;;
*,1,0)
    # Mount filesystem, but don't update /etc/fstab
    DO_FSTAB="n" ; DO_FSCK="y" ; DO_MOUNT="y"
    FSTYPE="ext2" ; OPTS=""
    MOUNTPT="/mem1"
    ;;
esac

ftl_format -i /dev/mem0c0c

mke2fs /dev/ftl0c0
mount -t ext2 /dev/ftl0c0 /mnt

ATA/IDE drive support is based on the regular kernel IDE driver. This includes SmartMedia and CompactFlash devices: these flash memory cards are set up so that they emulate an IDE interface. The PCMCIA-specific part of the driver is ide&lowbar;cs. Be sure to use cardctl or 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 ide.opts consist of either three or four fields: the current scheme, the socket number, the drive's serial number, and an optional partition number. The ide&lowbar;info command can be used to obtain an IDE device's serial number. As with SCSI devices, ide.opts is first called for the entire device. If ide.opts returns a list of partitions in the PARTS variable, the script will then be called for each partition.

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

A single interrupt can be shared by several drivers, such as the serial driver and an ethernet driver: in fact, the PCMCIA specification requires all card functions to share the same interrupt. Normally, all card functions are available without having to swap drivers. All Linux kernels support this kind of interrupt sharing.

Simultaneous use of two card functions is ``tricky'' and various hardware vendors have implemented interrupt sharing in their own incompatible (and sometimes proprietary) ways. The drivers for some cards (Ositech Jack of Diamonds, 3Com 3c562 and related cards, Linksys cards) properly support simultaneous access, but others (older Megahertz cards in particular) do not. If you have trouble using a card with both functions active, try using each function in isolation. That may require explicitly doing an ``ifconfig down'' to shut down a network interface and use a modem on the same card.

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 /etc/pcmcia/config.opts you'll find a place for excluding interrupts that are used by non-PCMCIA devices.

Similarly, there is no way to directly specify the I/O addresses for a card to use. The /etc/pcmcia/config.opts file allows you to specify ranges of ports available for use by any card, or to exclude ranges that conflict with other devices.

After modifying /etc/pcmcia/config.opts, you can reinitialize cardmgr with ``kill -HUP''.

The interrupt used to monitor card status changes is chosen by the low-level socket driver module (i82365 or tcic) before cardmgr parses /etc/pcmcia/config, so it is not affected by changes to this file. To set this interrupt, use the cs&lowbar;irq= option when the socket driver is loaded, by setting the PCIC&lowbar;OPTS variable in /etc/rc.d/rc.pcmcia.

All the client card drivers have a parameter called irq&lowbar;list for specifying which interrupts they may try to allocate. These driver options should be set in your /etc/pcmcia/config file. For example:

device "serial_cs"
  module "serial_cs" opts "irq_list=8,12"
  ...

would specify that the serial driver should only use irq 8 or irq 12. Regardless of irq&lowbar;list settings, 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.

Most of the following discussion applies to 2.2 and earlier kernels. With 2.4 and later kernels, the PCI subsystem has more complete responsibility for PCI interrupt management. The following tips may help diagnose a problem, though some workarounds described here may not be available.

PCI slot 1 INTA --> router PIRQ1 --> CPU irq 9
PCI slot 1 INTB --> router PIRQ2 --> CPU irq 10

PCI slot 2 INTA --> router PIRQ2 --> CPU irq 10
PCI slot 2 INTB --> router PIRQ1 --> CPU irq 9

Linux PCMCIA Card Services 3.1.18
  kernel build: 2.2.14-5.0 #1 Tue May 9 10:44:24 PDT 2000 
  options:  [pci] [cardbus] [apm] [pnp]
PCI routing table version 1.0 at 0xfdf30
Intel PCIC probe:
  TI 1125 rev 02 PCI-to-CardBus at slot 00:07, mem 0x20000000
    host opts [0]: [ring] [serial pci & irq] [pci irq 11] ...
    host opts [0]: [ring] [serial pci & irq] [pci irq 11] ...
  ISA irqs (scanned) = 3,4,7 PCI status changes

This is fairly easy using ``scheme'' support. Use two configuration schemes, called ``home'' and ``work''. Here is an example of a network.opts script with scheme-specific settings:

case "$ADDRESS" in
work,*,*,*)
    # definitions for network card in work scheme
    ...
    ;;
home,*,*,*|default,*,*,*)
    # definitions for network card in home scheme
    ...
    ;;
esac

The first part of a 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 select between the two sets of settings, run either:

cardctl scheme home

or

cardctl scheme work

The 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 scheme setting, run:

cardctl scheme

By default, the scheme setting is persistent across boots. This can have undesirable effects if networking is initialized for the wrong environment. Optionally, you can set the initial scheme value with the SCHEME startup option (see Startup options

To save even more keystrokes, schemes can be specified in lilo's configuration file. For instance, you could have:

root = /dev/hda1
read-only
image = /boot/vmlinuz
  label  = home
  append = "SCHEME=home"
image = /boot/vmlinuz
  label  = work
  append = "SCHEME=work"

Typing ``home'' or ``work'' at the boot prompt would then boot into the appropriate scheme.

Having the root filesystem on a PCMCIA device is tricky because the Linux PCMCIA system is not designed to be linked into the kernel. Its core components, the loadable kernel modules and the user mode cardmgr daemon, depend on an already running system. The kernel's ``initrd'' facility works around this requirement by allowing Linux to boot using a temporary ram disk as a minimal root image, load drivers, and then re-mount a different root filesystem. The temporary root can configure PCMCIA devices and then re-mount a PCMCIA device as root.

The initrd image absolutely must reside on a bootable device: this generally cannot be put on a PCMCIA device. This is a BIOS limitation, not a kernel limitation. It is useful here to distinguish between ``boot-able'' devices (i.e., devices that can be booted), and ``root-able'' devices (i.e., devices that can be mounted as root). ``Boot-able'' devices are determined by the BIOS, and are generally limited to internal floppy and hard disk drives. ``Root-able'' devices are any block devices that the kernel supports once it has been loaded. The initrd facility makes more devices ``root-able'', not ``boot-able''.

Some Linux distributions will allow installation to a device connected to a PCMCIA SCSI adapter, as an unintended side-effect of their support for installs from PCMCIA SCSI CD-ROM devices. However, at present, no Linux installation tools support configuring an appropriate ``initrd'' to boot Linux with a PCMCIA root filesystem. Setting up a system with a PCMCIA root thus requires that you use another Linux system to create the ``initrd'' image. If another Linux system is not available, another option would be to temporarily install a minimal Linux setup on a non-PCMCIA drive, create an initrd image, and then reinstall to the PCMCIA target.

The Linux Bootdisk-HOWTO has some general information about setting up boot disks but nothing specific to initrd. The main initrd document is included with recent kernel source code distributions, in linux/Documentation/initrd.txt. Before beginning, you should read this document. A familiarity with lilo is also helpful. Using initrd also requires that you have a kernel compiled with CONFIG&lowbar;BLK&lowbar;DEV&lowbar;RAM and CONFIG&lowbar;BLK&lowbar;DEV&lowbar;INITRD enabled.

This is an advanced configuration technique, and requires a high level of familiarity with Linux and the PCMCIA system. Be sure to read all the relevant documentation before starting. The following cookbook instructions should work, but deviations from the examples will quickly put you in uncharted and ``unsupported'' territory, and you will be on your own.

This method absolutely requires that you use a PCMCIA driver release of 2.9.5 or later. Older PCMCIA packages or individual components will not work in the initrd context. Do not mix components from different releases.

pcinitrd -v initrd pcmcia/i82365.o pcmcia/aha152x_cs.o

mount -o loop -t ext2 initrd /mnt

mke2fs /dev/fd0
mount /dev/fd0 /mnt
mkdir /mnt/etc /mnt/boot /mnt/dev
cp -a /dev/fd0 /dev/sda1 /mnt/dev
cp [kernel-image] /mnt/vmlinuz
cp /boot/boot.b /mnt/boot/boot.b
gzip < [initrd-image] > /mnt/initrd

boot=/dev/fd0
compact
image=/vmlinuz
    label=linux
    initrd=/initrd
    read-only
    root=/dev/sda1

lilo -r /mnt

LOADLIN <kernel> initrd=<initrd-image>

mount /dev/hda1 /mnt
mkdir /mnt/linux
cp [kernel-image] /mnt/linux/vmlinuz
cp [initrd-image] /mnt/linux/initrd

boot=/dev/hda
map=/mnt/linux/map
compact
image=/mnt/linux/vmlinuz
	label=linux
	root=/dev/sda1
	initrd=/mnt/linux/initrd
	read-only
other=/dev/hda1
	table=/dev/hda
	label=windows

lilo -C lilo.conf

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

Here is an example of how cardmgr will report an unsupported card in the system log:

cardmgr[460]: unsupported card in socket 1
cardmgr[460]: product info: "MEGAHERTZ", "XJ2288", "V.34 PCMCIA MODEM"
cardmgr[460]: manfid: 0x0101, 0x1234  function: 2 (serial)

The corresponding entry in /etc/pcmcia/config would be:

card "Megahertz XJ2288 V.34 Fax Modem"
  version "MEGAHERTZ", "XJ2288", "V.34 PCMCIA MODEM"
  bind "serial_cs"

or using the more compact product ID codes:

card "Megahertz XJ2288 V.34 Fax Modem"
  manfid 0x0101, 0x1234
  bind "serial_cs"

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.

Beware that you can specify just about any driver for a card, but if you're just shooting in the dark, there is not much reason to expect this to be productive. You may get lucky and find that your card is supported by an existing driver. However, the most likely outcome is that the driver won't work, and may have unfortunate side effects like locking up your system. Unlike most ordinary device drivers, which probe for an appropriate card, the probe for a PCMCIA device is done by cardmgr, and the driver itself may not do much validation before attempting to communicate with the device.

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

kill -HUP `cat /var/run/cardmgr.pid`

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.

Before you begin: this procedure will only work for simple 16-bit ethernet cards. Multifunction cards (i.e., ethernet/modem combo cards) have an extra layer of complexity regarding how the two functions are integrated, and generally cannot be supported without obtaining some configuration information from the card vendor. Using the following procedure for a multifunction card will not be productive.

First, see if the card is already recognized by cardmgr. Some cards not listed in 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 the Configuring unrecognized cards

If the pcnet&lowbar;cs driver says that it is unable to determine your card's hardware ethernet address, then edit your new config entry to bind the card to the memory card driver, memory&lowbar;cs. Restart 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:

dd if=/dev/mem0a count=20 | od -Ax -t x1

and search the output for your address. Only the even bytes are defined, so ignore the odd bytes in the dump. Record the hex offset of the first byte of the address. Now, edit clients/pcnet&lowbar;cs.c and find the hw&lowbar;info structure. You'll need to create a new entry for your card. The first field is the memory offset. 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 pcnet&lowbar;cs.c, compile and install the new module. Edit /etc/pcmcia/config again, and change the card binding from memory&lowbar;cs to pcnet&lowbar;cs. Follow the instructions for reloading the config file, and you should be all set. Please send me copies of your new hw&lowbar;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 ``hard-wire'' the address when the pcnet&lowbar;cs module is initialized. Edit /etc/pcmcia/config.opts and add a hw&lowbar;addr= option, like so:

module "pcnet_cs" opts "hw_addr=0x00,0x80,0xc8,0x01,0x02,0x03"

Substitute your own card's hardware address in the appropriate spot, of course. Beware that if you've gotten this far, it is very unlikely that your card is genuinely NE2000 compatible. In fact, I'm not sure if there are any cards that are not handled by one of the first two methods.

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.

The best way to submit reports is to use the online pcmcia-cs forums or the bug tracker at SourceForge. That way, other people can see current problems (and fixes or workarounds, if available). Here are some things that should be included in all bug reports:

All the PCMCIA modules and the cardmgr daemon send status messages to the system log. These will usually end up somewhere like /var/log/messages or /var/log/daemon.log. These files should be the first place to look when tracking down a problem. When submitting a bug report, always include the relevant contents of these files. If you are having trouble finding your system messages, check /etc/syslog.conf to see how different classes of messages are handled.

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 you do not have web access, bug reports can be sent to me at dahinds@users.sourceforge.net. However, I prefer that bug reports be posted to the pcmcia-cs SourceForge site, so that they can be seen by others.

If your problem involves a kernel fault, the register dump from the fault is only useful if you can translate the fault address, EIP, to something meaningful. Recent versions of klogd attempt to translate fault addresses based on the current kernel symbol map, but this may not work if the fault is in a module, or if the problem is severe enough that klogd cannot finish writing the fault information to the system log.

If a fault is in the main kernel, the fault address can be looked up in the System.map file. This may be installed in /System.map or /boot/System.map. If a fault is in a module, the nm command gives the same information, however, the fault address has to be adjusted based on the module's load address. Let's say that you have the following kernel fault:

Unable to handle kernel NULL pointer dereference
current->tss.cr3 = 014c9000, %cr3 = 014c9000
*pde = 00000000
Oops: 0002
CPU:    0
EIP:    0010:[<c2026081>]
EFLAGS: 00010282

The fault address is 0xc2026081. Looking at System.map, we see that this is past the end of the kernel, i.e., is in a kernel module. To determine which module, check the output of ``ksyms -m &verbar; sort'':

Address   Symbol                            Defined by
c200d000  (35k)                             [pcmcia_core]
c200d10c  register_ss_entry                 [pcmcia_core]
c200d230  unregister_ss_entry               [pcmcia_core]
          ...
c2026000  (9k)                              [3c574_cs]
c202a000  (4k)                              [serial_cs]

So, 0xc2026081 is in the 3c574&lowbar;cs module, and is at an offset of 0x0081 from the start of the module. We cannot look up this offset in 3c574&lowbar;cs.o yet: when the kernel loads a module, it inserts a header at the module load address, so the real start of the module is offset from the address shown in ksyms. The size of the header varies with kernel version: to find out the size for your kernel, check a module that exports symbols (like pcmcia&lowbar;core above), and compare a symbol address with nm output for that symbol. In this example, register&lowbar;ss&lowbar;entry is loaded at an offset of 0xc200d10c - 0xc200d000 = 0x010c, while ``nm pcmcia&lowbar;core.o'' shows the offset as 0x00c0, so the header size is 0x010c - 0x00c0 = 0x004c bytes.

Back to 3c574&lowbar;cs, our fault offset is 0x0081, and subtracting the 0x004c header, the real module offset is 0x0035. Now looking at ``nm 3c574&lowbar;cs.o &verbar; sort'', we see:

0000002c d if_names
0000002c t tc574_attach
00000040 d mii_preamble_required
00000041 d dev_info

So, the fault is located in tc574&lowbar;attach().

In this example, the fault did not cause a total system lockup, so ksyms could be executed after the fault happened. In other cases, you may have to infer the module load addresses indirectly. The same sequence of events will normally load modules in the same order and at the same addresses. If a fault happens when a certain card is inserted, get the ksyms output before inserting the card, or with a different card inserted. You can also manually load the card's driver modules with insmod and run ksyms before inserting the card.

For more background, see ``man insmod'', ``man ksyms'', and ``man klogd''. In the kernel source tree, Documentation/oops-tracing.txt is also relevant. Here are a few more kernel debugging hints:

The PCMCIA modules contain a lot of conditionally-compiled debugging code. Most of this code is under control of the PCMCIA&lowbar;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 PCMCIA&lowbar;DEBUG defined will have an integer parameter, pc&lowbar;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.

Your default configuration for syslogd may discard kernel debugging messages. To ensure that they are recorded, edit /etc/syslog.conf to ensure that ``kern.debug'' messages are recorded somewhere. See ``man syslog.conf'' for details.

There are a few register-level debugging tools in the debug&lowbar;tools/ subdirectory of the PCMCIA distribution. The dump&lowbar;tcic and dump&lowbar;i365 utilities generate register dumps for ISA-to-PCMCIA controllers. In 3.1.15 and later releases, dump&lowbar;i365 is replaced by dump&lowbar;exca, which is similar but also works for PCI-to-CardBus bridges. Also new in 3.1.15 for CardBus bridges is the dump&lowbar;cardbus tool, which interprets the CardBus-specific registers. These are all most useful if you have access to a datasheet for the corresponding controller chip. The dump&lowbar;cis utility (dump&lowbar;tuples in pre-3.0.2 distributions) lists the contents of a card's CIS (Card Information Structure), and decodes most of the important bits. And the dump&lowbar;cisreg utility displays a card's local configuration registers.

The memory&lowbar;cs memory card driver is also sometimes useful for debugging problems with 16-bit PC Cards. It can be bound to any card, and does not interfere with other drivers. It can be used to directly access any card's attribute memory or common memory. Similarly for CardBus cards, the memory&lowbar;cb driver can be bound to any 32-bit card, to give direct access to that card's address spaces. See the man pages for more information.

On 2.2 and later kernels, the PCMCIA package will create a tree of status information under <cdx>/proc/bus/pccard</cdx>. Much of the information can only be interpreted using the data sheets for the PCMCIA host controller. Its contents may depend on how the drivers were configured, but may include all or some of the following:

The Linux PCMCIA Programmer's Guide is the best documentation for the client driver interface. The latest version is always available from projects.sourceforge.net in /pub/pcmcia-cs/doc, or on the web at http://pcmcia-cs.sourceforge.net.

For devices that are close relatives of normal ISA devices, you will 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.

In many cases, the largest barrier to supporting a new card type is obtaining technical information from the manufacturer. It may be difficult to figure out who to ask, or to explain exactly what information is needed. However, with a few exceptions, it is very difficult if not impossible to implement a driver for a card without technical information from the manufacturer.

I have written a dummy driver with lots of comments that explains a lot of how a driver communicates with Card Services; you will find this in the PCMCIA source distribution in clients/dummy&lowbar;cs.c.

I have decided that it is not really feasible for me to distribute all PCMCIA client drivers as part of the PCMCIA package. Each new driver makes the main package incrementally harder to maintain, and including a driver inevitably transfers some of the maintenance work from the driver author to me. Instead, I will decide on a case by case basis whether or not to include contributed drivers, based on user demand as well as maintainability. For drivers not included in the core package, I suggest that driver authors adopt the following scheme for packaging their drivers for distribution.

Driver files should be arranged in the same directory scheme used in the PCMCIA source distribution, so that the driver can be unpacked on top of a complete PCMCIA source tree. A driver should include source files (in ./modules/), a man page (in ./man/), and configuration files (in ./etc/). The top level directory should also include a README file.

The top-level directory should include a makefile, set up so that ``make -f ... all'' and ``make -f ... install'' compile the driver and install all appropriate files. If this makefile is given an extension of .mk, then it will automatically be invoked by the top-level Makefile for the all and install targets. Here is an example of how such a makefile could be constructed:

# Sample Makefile for contributed client driver
FILES = sample_cs.mk README.sample_cs \
	modules/sample_cs.c modules/sample_cs.h \
	etc/sample.conf etc/sample etc/sample.opts \
	man/sample_cs.4
all:
	$(MAKE) -C modules MODULES=sample_cs.o
install:
	$(MAKE) -C modules install-modules MODULES=sample_cs.o
	$(MAKE) -C etc install-clients CLIENTS=sample
	$(MAKE) -C man install-man4 MAN4=sample_cs.4
dist:
	tar czvf sample_cs.tar.gz $(FILES)

This makefile uses install targets defined in 2.9.10 and later versions of the PCMCIA package. This makefile also includes a ``dist'' target for the convenience of the driver author. You would probably want to add a version number to the final package filename (for example, sample&lowbar;cs-1.5.tar.gz). A complete distribution could look like:

sample_cs.mk
README.sample_cs
modules/sample_cs.c
modules/sample_cs.h
etc/sample.conf
etc/sample
etc/sample.opts
man/sample_cs.4

With this arrangement, when the contributed driver is unpacked, it becomes essentially part of the PCMCIA source tree. It can make use of the PCMCIA header files, as well as the machinery for checking the user's system configuration, and automatic dependency checking, just like a ``normal'' client driver.

In this example, etc/sample and etc/sample.opts would be the new driver's configuration scripts (if needed), and etc/sample.conf would contain any additions to the PCMCIA card configuration file. Starting with the 3.1.6 release, cardmgr will automatically process any *.conf files installed in /etc/pcmcia, so installation of contributed drivers should no longer require hand editing configuration files.

I will accept client drivers prepared according to this specification and place them in the /pub/pcmcia-cs/contrib directory on projects.sourceforge.net. The README in this directory will describe how to unpack a contributed driver.

The client driver interface has not changed much over time, and has almost always preserved backwards compatibility. A client driver will not normally need to be updated for minor revisions in the main package. I will try to notify authors of contributed drivers of changes that require updates to their drivers.

If your distribution has system configuration tools that you would like to be PCMCIA-aware, please use the *.opts files in /etc/pcmcia for your ``hooks.'' These files will not be modified if a user compiles and installs a new release of the PCMCIA package. If you modify the main configuration scripts, then a fresh install will silently overwrite your custom scripts and break the connection with your configuration tools. Contact me if you are not sure how to write an appropriate option script, or if you need additional capabilities.

It is helpful for users (and for me) if you can document how your distribution deviates from the PCMCIA package as described in this document. In particular, please document changes to the startup script and configuration scripts. If you send me the appropriate information, I will include it in the Notes about specific Linux distributions

When building PCMCIA for distribution, consider including contributed drivers that are not part of the main PCMCIA package. For reasons of maintainability, I am trying to limit the core package size, by only adding new drivers if I think they are of particularly broad interest. Other drivers will be distributed separately, as described in the previous section. The split between integral and separate drivers is somewhat arbitrary and partly historical, and should not imply a difference in quality.