Device Driver Tutorial

Device Driver Testing Tips

Testing a device driver can cause the system to panic and can harm the kernel.

The following tips can help you avoid problems when testing your driver:

Install the driver in a temporary location.

Install drivers in the /tmp directory until you are finished modifying and testing the _info(), _init(), and attach() routines. Copy the driver binary to the /tmp directory. Link to the driver from the kernel driver directory.

If a driver has an error in its _info(), _init(), or attach() function, your machine could get into a state of infinite panic. The OS automatically reboots itself after a panic and loads any drivers it can during boot. If you have an error in your attach() function that panics the system when you load the driver, then the system will panic again when it tries to reboot after the panic. The system will continue the cycle of panic, reboot, panic as it attempts to reload the faulty driver every time it reboots after panic.

To avoid an infinite panic, keep the driver in the /tmp area until it is well tested. Link to the driver in the /tmp area from the kernel driver area. The OS removes all files from the /tmp area every time the system reboots. If your driver causes a panic, the OS reboots successfully because the driver has been removed automatically from the /tmp area. The link in the kernel driver area points to nothing. The faulty driver did not get loaded, so the system does not go back into a panic. You can modify the driver, copy it again to the /tmp area, and continue testing and developing. When the driver is well tested, copy it to the /usr/kernel/drv area so that it will remain available after a reboot.

The following example shows you where to link the driver for a 32-bit platform. For other architectures, see the instructions in Installing a Driver.
# cp mydriver /tmp # ln -s /tmp/mydriver /usr/kernel/drv/mydriver
Enable the deadman feature to avoid a hard hang.

If your system is in a hard hang, then you cannot break into the debugger. If you enable the deadman feature, the system panics instead of hanging indefinitely. You can then use the kmdb(1) kernel debugger to analyze your problem.

The deadman feature checks every second whether the system clock is updating. If the system clock is not updating, then you are in an indefinite hang. If the system clock has not been updated for 50 seconds, the deadman feature induces a panic and puts you in the debugger.
1. Make sure you are capturing crash images with dumpadm(1M).
2. Set the snooping variable in the /etc/system file.
```
set snooping=1
```
3. Reboot the system so that the /etc/system file is read again and the snooping setting takes effect.
Note that any zones on your system inherit the deadman setting as well.

If your system hangs while the deadman feature is enabled, you should see output similar to the following example on your console:
```
panic[cpu1]/thread=30018dd6cc0: deadman: timed out after 9 seconds of
clock inactivity

panic: entering debugger (continue to save dump)
```
Inside the debugger, use the ::cpuinfo command to investigate why the clock interrupt was not able to fire and advance the system time.
Use a serial connection to control your test machine from a separate host system.

This technique is explained in Testing With a Serial Connection in Writing Device Drivers.
Use an alternate kernel.

Booting from a copy of the kernel and the associated binaries rather than from the default kernel avoids inadvertently rendering the system inoperable.
Use an additional kernel module to experiment with different kernel variable settings.

This approach isolates experiments with the kernel variable settings. See Setting Up Test Modules in Writing Device Drivers.
Make contingency plans for potential data loss on a test system.

If your test system is set up as a client of a server, then you can boot from the network if problems occur. You could also create a special partition to hold a copy of a bootable root file system. See Avoiding Data Loss on a Test System in Writing Device Drivers.
Capture system crash dumps if your test system panics.
Use fsck(1M) to repair the damaged root file system temporarily if your system crashes during the attach(9E) process so that any crash dumps can be salvaged. See Recovering the Device Directory in Writing Device Drivers.
Install drivers in the /tmp directory until you are finished modifying and testing the _info(), _init(), and attach() routines.

Keep a driver in the /tmp directory until the driver has been well tested. If a panic occurs, the driver will be removed from /tmp directory and the system will reboot successfully.