Previous Next Contents

6. Debugging tips and programming information

6.1 How can I submit a helpful bug report?

The best way to submit bug reports is to use the HyperNews message lists on the Linux PCMCIA information site. 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:

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

If your problem involves a kernel fault, the register dump from the fault is only useful if you can track down the fault address, EIP. If it is in the main kernel, look up the address in System.map to identify the function at fault. If the fault is in a loadable module, it is a bit harder to trace. With the current module tools, ``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.

If you do not have web access, bug reports can be sent to me at dhinds@hyper.stanford.edu. However, I prefer that bug reports be posted to my web site, so that they can be seen by others.

6.2 Low level PCMCIA debugging aids

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

There are a few debugging tools in the 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 memory_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.

6.3 How do I write a Card Services driver for a new card?

The Linux PCMCIA Programmer's Guide is the best documentation for the Linux PCMCIA interface. The latest version is always available from hyper.stanford.edu in /pub/pcmcia/doc, or on the web at http://hyper.stanford.edu/HyperNews/get/pcmcia/home.html.

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.

6.4 Guidelines for PCMCIA client driver authors

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

I will accept client drivers prepared according to this specification and place them in the /pub/pcmcia/contrib directory on my FTP server, hyper.stanford.edu. The README in this directory will describe how to unpack a contributed driver.

The PCMCIA 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 PCMCIA package. I will try to notify authors of contributed drivers of changes that require updates to their drivers.


Previous Next Contents