5 Debugging tips and programming information

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

• Your system type, and the output of the probe command
• What PCMCIA cards you are using
• Your Linux kernel version, and PCMCIA version
• Any changes you've made to the startup files in /etc/pcmcia
• Contents of /usr/adm/messages, even if you don't see anything that looks interesting.

The make.options file includes a few choices for building the kernel modules with various kinds of debugging code turned on. This may or may not be useful, depending on your problem. It is probably better to only turn on the really verbose debugging if I ask you to.

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

Send bug reports to dhinds@allegro.stanford.edu. I prefer to handle bug reports by email -- please avoid calling me at home or at work.

The PCMCIA modules contain a lot of conditionally-compiled debugging code. The make.options file shows how to enable this code. A module compiled with PCMCIA_DEBUG set will have a parameter, pc_debug, that controls the verbosity of debugging output. This can be adjusted when the module is loaded, so output can be controlled on a per-module basis without recompiling.

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

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

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

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

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