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.
There is also a mailing list for ongoing development of the kernel PCMCIA driver subsystem, at >
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:
make config'' in the new pcmcia-cs-3.2.? directory.make all'', then ``make install''./etc/pcmcia for your site, if needed.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:
This is the location of the source tree for the kernel you want to use
with PCMCIA. Often this is /usr/src/linux, but the default
location depends on what Linux distribution you're using (or on where
you've chosen to place your kernel source tree).
Some of the support utilities (cardctl and cardinfo) can be
compiled either in ``safe'' or ``trusting'' forms. The ``safe'' forms
prevent non-root users from modifying card configurations. The
``trusting'' forms permit ordinary users to issue commands to suspend
and resume cards, reset cards, and change the current configuration
scheme. The default is to build the safe forms.
This option must be selected if you wish to use 32-bit CardBus cards. It is not required for CardBus bridge support, if you only plan to use 16-bit PC Cards.
This builds additional code into the PCMCIA core module to communicate
with a system's PnP BIOS to obtain resource information for built-in
``motherboard'' devices (serial and parallel ports, sound, etc), to
help avoid resource conflicts. If enabled, some extra resource files
will be created under /proc/bus/pccard, and the lspnp
and setpnp tools can be used to view and manipulate PnP BIOS
devices. However, this setting causes problems on some laptops and is
not turned on by default.
The directory that new kernel modules will be installed into.
Normally this should be the subdirectory of /lib/modules that
matches your kernel version.
There are a few kernel configuration options that affect the PCMCIA tools. The configuration script can deduce these from the running kernel (the default and 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.
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_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_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_OPTS parameter to ``tcic_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_probe command will
fail to find any known host controller. If this happens, edit
rc.pcmcia and set PCIC to i82365, and PCIC_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 for specifics. The following variables can be set:
PCMCIAThis variable specifies whether PCMCIA support should be started up, or not. If it is set to anything other than ``yes'', then the startup script will be disabled.
PCICThis identifies the PC Card Interface Controller driver module. There are several options: ``tcic'', ``i82365'', and (for the kernel PCMCIA subsystem) ``yenta_socket''. Virtually all current controllers are in the ``i82365'' group for the standalone drivers, and ``yenta_socket'' for the kernel drivers. This is the only mandatory option setting.
PCIC_OPTSThis specifies options for the PCIC module. Some host controllers have optional features that may or may not be implemented in a particular system. In some cases, it is impossible for the socket driver to detect if these features are implemented. See the corresponding man page for a complete description of the available options.
CORE_OPTSThis specifies options for the pcmcia_core module, which
implements the core PC Card driver services. See ``man
pcmcia_core'' for more information.
CARDMGR_OPTSThis specifies options to be passed to the cardmgr daemon. See
``man cardmgr'' for more information.
SCHEMEIf set, then the PC Card configuration scheme will be initialized to this at driver startup time. See the Overview of the PCMCIA configuration scripts for a discussion of schemes.
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:
cmd_time flag,
which determines the length of PCMCIA bus cycles. Fast 486 systems
(i.e., DX4-100) seem to often benefit from increasing this from 6 (the
default) to 12 or 16.fast_pci flag, which
should be set if the PCI bus speed is greater than 25 MHz.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.pcmcia_core module has the cis_speed parameter for
changing the memory speed used for accessing a card's Card Information
Structure (CIS). On some systems, increasing this parameter (i.e.,
slowing down card accesses) may fix card recognition problems.pcmcia_core parameter, io_speed, can be used to slow
down accesses to IO cards. It may help in certain cases with systems
that have out-of-spec PCMCIA bus timing.i82365 module should be loaded with the extra_sockets
parameter set to 1. This should not be necessary for detection of
PCI-to-PCMCIA or PCI-to-CardBus bridges.Here are some timing settings for a few old systems:
freq_bypass=1 cmd_time=8''.setup_time=1''.cmd_time=12''.cmd_time=16''.fast_pci=1''.While almost all PCMCIA card readers and card docks work fine under
Linux, some require special startup options because they do not behave
exactly like laptop PCMCIA bridges. PCI card readers, in particular,
may handle interrupts differently. Some of the following parameter
settings are only available for the i82365 module in the
standalone drivers; the kernel's yenta_socket driver is not
configurable.
pnpdump and isapnp for more information.i82365 driver should be loaded with a
``has_ring=0'' parameter to prevent irq 15 conflicts.i82365 driver requires a
``irq_mode=1'' parameter.i82365 driver
requires a ``p2cclk=1'' parameter.i82365 driver requires ``p2cclk=1 irq_mode=0''
as well as PCMCIA driver release 3.1.23 or later.irq_mode=0'' for the i82365 module, to force use
of PCI interrupts.i82365 driver requires a ``irq_list=0''
parameter, to indicate that ISA interrupts are unavailable.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.
On PowerPC based PowerBook systems, the default system resources in
/etc/pcmcia/config.opts file are no good at all. Replace all
the IO port and window definitions with something like:
include port 0x100-0x4ff, port 0x1000-0x17ff
include memory 0x80000000-0x80ffffff
This section is incomplete. Corrections and additions are welcome.
Debian uses a System V boot script arrangement. The PCMCIA startup
script is installed as /etc/init.d/pcmcia. New packages use
/etc/default/pcmcia for startup options; older versions used
/etc/pcmcia.conf for this purpose. Debian's syslog
configuration will place kernel messages in /var/log/messages
and cardmgr messages in /var/log/daemon.log.
Debian distributes the PCMCIA system in two packages: the
``pcmcia-cs'' package contains cardmgr and other tools, man
pages, and configuration scripts; and the ``pcmcia-modules''
package contains the kernel driver modules.
Starting with 3.1.25, a clean PCMCIA install will identify Debian
systems and create a special network.opts file that, in the
absence of other network configuration settings, uses Debian's
ifup and ifdown commands to configure a network card based
on settings in /etc/network/interfaces.
These distributions use a System V boot script organization. The
PCMCIA startup script is installed as
/etc/rc.d/init.d/pcmcia, and boot options are kept in
/etc/sysconfig/pcmcia. Beware that installing the Red Hat
package may install a default boot option file that has PCMCIA
disabled. To enable PCMCIA, the ``PCMCIA'' variable should be
set to ``yes''. Red Hat's default syslogd configuration will
record all interesting messages in /var/log/messages.
Red Hat's PCMCIA package contains a replacement for the network setup
script, /etc/pcmcia/network, which meshes with the Red Hat
linuxconf configuration system. This is convenient for the case
where just one network adapter is used, with one set of network
parameters, but does not have the full flexibility of the regular
PCMCIA network script. Compiling and installing a clean PCMCIA source
distribution will overwrite the network script, breaking the link to
the Red Hat tools. If you prefer using the Red Hat tools, either use
only Red Hat RPM's, or replace /etc/pcmcia/network.opts with
the following:
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
Starting with the 3.1.22 release, the PCMCIA installation script will
automatically append a variant of this to the default
network.opts file, so this problem should no longer be an issue.
If you do use linuxconf (or netconf) to configure your
network interface, leave the ``kernel module'', ``I/O port'', and
``irq'' parameters blank. Setting these parameters may interfere with
proper operation of the PCMCIA subsystem.
At boot time, when the Red Hat network subsystem starts up, it may say ``Delaying eth0 initialization'' and ``[FAILED]''. This is actually not a failure: it means that this network interface will not be initialized until after the PCMCIA network device is configured.
Red Hat bundles their slightly modified PCMCIA source distribution
with their kernel sources, rather than as a separate source package.
When preparing to build a new set of PCMCIA drivers, you will
generally want to install Red Hat's kernel-source RPM
(kernel-source-*.i386.rpm), and not the kernel SRPM
(kernel-*.src.rpm). The SRPM is tailored for building their
kernel RPM files, which is not exactly what you want. With Red Hat
7.0, the kernel-source RPM also includes a mis-configured PCMCIA
source tree; if you want to use it, delete their PCMCIA config.out
file and re-do "make config".
Slackware uses a BSD boot script arrangement. The PCMCIA startup
script is installed as /etc/rc.d/rc.pcmcia, and boot options
are specified in rc.pcmcia itself. The PCMCIA startup script
is invoked from /etc/rc.d/rc.S.
SuSE uses a System V init script arrangement, with init scripts stored
under /etc/init.d. The PCMCIA startup script is installed as
/etc/init.d/pcmcia, and startup options are kept in
/etc/rc.config. Before release 7.0, init scripts were kept
under /sbin/init.d. In early SuSE releases (pre-5.3), the
PCMCIA startup script was somewhat limited and did not allow PCMCIA
startup variables to be overridden from the lilo boot prompt.
SuSE 8.0 includes both the standalone PCMCIA modules, and the 2.4
kernel PCMCIA subsystem modules. A new variable, PCMCIA_SYSTEM,
is available in /etc/sysconfig/pcmcia to choose between
these. It can be set to either ``kernel'' or ``external''.
To look up current PCMCIA issues in SuSE's support database, go to http://sdb.suse.de/cgi-bin/sdbsearch_en.cgi?stichwort=PCMCIA.