2. Compilation and installation

2.1 Prerequisites and kernel setup

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:

• A 2.0, 2.2, 2.4, or 2.6 series kernel source tree.
• An appropriate set of module utilities.
• (Optional) the ``XForms'' X11 user interface toolkit.

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.

2.2 Kernel PCMCIA support

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.

2.3 Installation

Here is a synopsis of the installation process:

• Unpack pcmcia-cs-3.2.?.tar.gz in /usr/src.
• Run ``make config'' in the new pcmcia-cs-3.2.? directory.
• Run ``make all'', then ``make install''.
• Customize the startup script and the option files in /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:

Linux kernel source directory?

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).

Build 'trusting' versions of card utilities?

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.

Include 32-bit (CardBus) card support?

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.

Include PnP BIOS resource checking?

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.

Module install directory?

The directory that new kernel modules will be installed into. Normally this should be the subdirectory of /lib/modules that matches your kernel version.

How to set kernel-specific options?

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''.

2.4 Startup options

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:

PCMCIA

This 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.

PCIC

This 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_OPTS

This 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_OPTS

This specifies options for the pcmcia_core module, which implements the core PC Card driver services. See ``man pcmcia_core'' for more information.

CARDMGR_OPTS

This specifies options to be passed to the cardmgr daemon. See ``man cardmgr'' for more information.

SCHEME

If 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:

• ISA-bus Cirrus controllers have numerous configurable timing parameters. The most important seems to be the 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.
• The Cirrus PD6729 PCI controller has the fast_pci flag, which should be set if the PCI bus speed is greater than 25 MHz.
• For Vadem VG-468 controllers, the 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.
• The 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.
• Another 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.
• This is not a timing issue, but if you have more than one ISA-to-PCMCIA controller in your system or extra sockets in a laptop docking station, the 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:

• On the ARM Pentium-90 or Midwest Micro Soundbook Plus, use ``freq_bypass=1 cmd_time=8''.
• On a Compaq Presario 1220, try ``setup_time=1''.
• On a Midwest Micro Soundbook Elite, use ``cmd_time=12''.
• On a Gateway Liberty, try ``cmd_time=16''.
• On a Samsung SENS 810, use ``fast_pci=1''.

Card readers for desktop systems

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.

• The Linksys ProConnect PCMRDWR and Antec DataChute ISA card readers are ``ISA Plug and Play'' devices. To use these, you must first activate them with the Linux isapnp tools. See the man pages for pnpdump and isapnp for more information.
• For Chase CardPORT and Altec ISA card readers using the Cirrus PD6722 ISA-to-PCMCIA bridge, the i82365 driver should be loaded with a ``has_ring=0'' parameter to prevent irq 15 conflicts.
• For Elan P-series PCI card readers based on the Cirrus PD6729 PCI-to-PCMCIA bridge chip, the i82365 driver requires a ``irq_mode=1'' parameter.
• For the Sycard PCChost1200 host adapter, the i82365 driver requires a ``p2cclk=1'' parameter.
• For the Alex Electronics PCICBI host adapter based on the TI 1221 bridge, the i82365 driver requires ``p2cclk=1 irq_mode=0'' as well as PCMCIA driver release 3.1.23 or later.
• With SCM Microsystems SBP series PCI card readers (which are also being distributed with Lucent WaveLAN IEEE cards), and for the Synchrotech PCM-CR-PC2IF and PCM-CR-PC2IR, it is necessary to specify ``irq_mode=0'' for the i82365 module, to force use of PCI interrupts.
• For the ActionTec PC 750 card reader, and for the Antec Datachute PCI card reader, the i82365 driver requires a ``irq_list=0'' parameter, to indicate that ISA interrupts are unavailable.
• The PLX Technologies PCI9052 (also sold as the Linksys WDT11) is not a general purpose PCMCIA card reader at all: it is a PCI interface card for use with certain wireless adapters, that makes them look like ordinary PCI devices. These devices are not supported.

2.5 System resource settings

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 the AMS SoundPro, exclude irq 10.
• On some AMS TravelPro 5300 models, use memory 0xc8000-0xcffff.
• On the BMX 486DX2-66, exclude irq 5, irq 9.
• On the Chicony NB5, use memory 0xda000-0xdffff.
• On the Compaq Presario 900Z, exclude port 0x3b0-0x3bb.
• On the Compaq Presario 1020, exclude port 0x2f8-0x2ff, irq 3, irq 5.
• On the Compaq Presario 2120EA, exclude irq 10.
• On the Dell Inspiron 7000, exclude irq 3, irq 5.
• On the Dell Inspiron 8000, exclude port 0x800-0x8ff.
• On the Fujitsu C series, exclude port 0x200-0x27f.
• On the HP Omnibook 4000C, exclude port 0x300-0x30f.
• On the HP Omnibook 4100, exclude port 0x220-0x22f.
• On the IBM ThinkPad 380, and maybe the 385 and 600 series, exclude port 0x230-0x233, and irq 5.
• On IBM ThinkPad 600 and 770 models with internal modems, exclude port 0x2f8-0x2ff.
• On the IBM ThinkPad 600E and 770Z, change the high memory window to 0x60000000-0x60ffffff.
• On the Micron Millenia Transport, exclude irq 5, irq 9.
• On the NEC Versa M, exclude irq 9, port 0x2e0-2ff.
• On the NEC Versa P/75, exclude irq 5, irq 9.
• On the NEC Versa S, exclude irq 9, irq 12.
• On the NEC Versa 6000 series, exclude port 0x2f8-0x33f, irq 9, irq 10.
• On the NEC Versa SX, exclude port 0x300-0x31f.
• On the ProStar 9200, Altima Virage, and Acquiline Hurricane DX4-100, exclude irq 5, port 0x330-0x35f. Maybe use memory 0xd8000-0xdffff.
• On the Siemens Nixdorf SIMATIC PG 720C, use memory 0xc0000-0xcffff, port 0x300-0x3bf.
• On the TI TravelMate 5000, use memory 0xd4000-0xdffff.
• On the Toshiba Satellite 4030CDS, exclude irq 9.
• On the Toshiba T4900 CT, exclude irq 5, port 0x2e0-0x2e8, port 0x330-0x338.
• On the Toshiba Tecra 8000, exclude irq 3, irq 5, irq 9.
• On the Twinhead 5100, HP 4000, Sharp PC-8700 and PC-8900, exclude irq 9 (sound), irq 12.
• On an MPC 800 Series, exclude irq 5, port 0x300-0x30f for the CD-ROM.

PowerBook specific settings

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

2.6 Notes about specific Linux distributions

This section is incomplete. Corrections and additions are welcome.

Debian

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.

Red Hat, Caldera, Mandrake

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

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

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.