Driver testing and debugging

Driver testing and debugging

This topic discusses the tools and practices that are available for testing and debugging the installed driver and gives tips for using them. This topic also discusses some of the common errors in drivers and some of the symptoms that might identify each. Debugging a driver is largely a process of analyzing the code to determine what could have caused a given problem. Testing a device driver consists of installing the driver on a working system and trying all of its functions under a variety of operating conditions. SVR5 and SCO OpenServer 5 include tools to help, but because the driver operates at the kernel level, these tools can only provide limited information.

Testing and debugging a driver is an iterative process, but the general steps are listed below.

You should test the functionality of the driver as you write it. If you are changing code from another driver, it is useful to install and test the driver after you have modified the initialization routines and the I/O routines. This testing could involve writing a short program that only reads and writes to the device to ensure that you can get into the device. When all the routines for the driver are written, you should install the hardware and perform full functionality testing.

Many of the steps that follow require you to modify files and directories owned by root. You must therefore be logged in as root or execute with the appropriate privileges to develop and debug device drivers.

Many of the most useful debugging techniques are implemented in the driver's code itself. See ``Coding the driver for debugging''.
Compile your driver without the optimizer (-O option) or symbolic debugging information (-g option). The disasembled code is easier to read if it is not optimized.
Install the operating system on the test machine. See ``Testing on a non-dedicated machine'' if you are debugging a driver on a machine that is not dedicated to testing.
If desired, set up a remote console for debugging. See ``Setting up a remote console for debugging'' for more information.
Create the required DSP files and copy them along with your Driver.o device driver module into the /tmp directory. (See ``DSP (Driver Software Package)''),
Enlarge the size of the putbuf buffer by setting the PUTBUFSZ parameter for either SVR5 or SCO OpenServer 5 to 10000. Driver debugging writes more data to the putbuf than normal operations, and you may lose important information if the putbuf is too small so that early data is overwritten by later data.
Link in the kernel debugger(s) you want to use. Both scodb and kdb are supported on SVR5, and both can be installed in the system at the same time; SCO OpenServer 5 uses the scodb debugger.
See ``Using crash and the kernel debuggers'' for more information.
Use the idinstall or idinstall(ADM) command with the -a option to install the new driver. You may also want to specify the -k option so that the DSP files are not deleted from the driver's private directory when they are installed in the appropriate system directories.
Load the driver into the kernel:
- For dynamically-loaded drivers on SVR5 systems, run the modadmin command with the -l option.
  If you get errors, run modadmin with the -U option to unload the driver (unless your kernel has been corrupted by the driver, in which case you may need to reboot the system). You can also use the -u option to unload the driver but generally -U is easier during the testing phase. Study the driver to find the error; the information in the /usr/adm/syslog and /var/adm/log/osmlog files may help you identify the errors. When you have fixed the code, recompile it and try to load the driver again.
  See ``Dynamically-loadable kernel modules (DLKM)'' for more information.
- For statically-linked DDI drivers and all ODDI drivers, use the idbuild or idbuild(ADM) command to rebuild the operating system kernel or just your driver.
  If the kernel built correctly, a new operating system image will have been created. Run shutdown or init 6 to cause the new kernel to be automatically copied to /stand/unix. On the next boot, the new kernel will execute, and upon entering init state 2, the new device nodes, inittab entries, and so on, will be installed.
When the system comes up, test your driver by exercising the board and using one of the kernel debuggers and the console error messages to study the state of the kernel.
If you get errors, study the driver to find the error, correct them, and repeat the above step. The information in the SCO OpenServer 5 /usr/adm/messages file or the SVR5 /usr/adm/syslog and /var/adm/log/osmlog files may help you find the error.
All error messages for DLKMs and many for static drivers are written to the kernel's putbuf message buffer; some of the messages are also written to the console. When a module fails to load and no detailed error message is displayed on the console, you can often determine the cause of the error by printing the messages in the putbuf using crash or one of the kernel debuggers. See ``Using crash and the kernel debuggers'' for more information.
It may be useful to divide your driver into separate sections and install each part separately until you find the problem. Fix the problem and install the driver. For a statically linked driver, you should then reset your system and boot your original kernel, assuming you saved it as recommended. To do this:
- Reset the system
- On SVR5 systems, when you see the boot logo, quickly press the keyboard space bar to interrupt the default boot.
- When the boot prompt appears, type the name of a backup copy of the kernel (for example, b /unix.old).
When the driver seems stable with manual testing procedures, use the appropriate test suites from those documented in the Section 1Mcert manual pages for more rigorous testing of the device and the driver.