Kernel Print Statements
There are, of course, limitations in debugging and testing device drivers.
In the absence of a Kernel debugging tool, print statements inside the driver are the primary method used. PrintfO calls made inside the Kernel will appear on the UNIX System V /386 monitor (fdev /console). Note that this printfO is not the same printf in section 3 of the Programmer's Reference Manual. It has identical syntax to printf(3}, but it only supports print options byte, hexadecimal, character, decimal, unsigned decimal, octal, hexadecimal and string (option variables b, c, d, u, 0, x, and s). The use of printfO is men-tioned for historical purposes. A new general kernel error utility called cmILerrO should be used in newly written drivers. See the Device Driver Reference Manual.
Since the print statements are written by the Kernel, there is no way to redirect the output to a file or to remote terminal. Using print statements also modifies the timing of driver code execution, which may change the behavior of problems you are investigating.
Print statements in the driver can be made more efficient by using an ioctl to set one or more levels of debugging output. This way you can write a sim-ple user program to tum the print output on or off as needed. The game port driver in Appendix B shows how to do this.
Sometimes kernel print statements scroll by too quickly to read. There is a limited kernel buffer called putbuf that records all kernel printf's. There are several ways to later retrieve this data:
1. Use the crash command. Try the following command after executing /etc/crash:
od -a Plt:l:nf 2000
You can examine the crash(lM} manual page in the User's/System Administrator's Reference Manual for more information.
3·70 ISDG
2. Use the built-in kernel console monitor /dev/osm. Since the base system does not have preconfigured /dev /osm device nodes, you should make one:
o
Create a file named /etc/conf/node.d/osm that contains the fol-lowing:osm osmO c 0
o
Execute the /etc/conf/bin/idmknod command.o
Use cat or tail to examine /dev /osmO.The cmlLerrO has an option of putting the character data only in putbuf and not having the data appear on the console at all. This is done by preced-ing the text strpreced-ing with a "!". For example:
aRLerr(CEUVl'E," Ithis driver print statement will only go :into pItI:Juf, not onto the screen.");
The Trace Driver
Another useful way to observe driver behavior is by using a trace driver.
Such a driver can be called by your driver to log data. A user program can then be written to read the trace driver either in real-time or as a postmortem analysis. Appendix C provides the source code for such a driver which logs data presented to it by trsaveO calls made from other drivers. The trace driver uses clists (see the earlier section "Clists") to save these traces. Although this driver isn't delivered with the base UNIX System V /386, you can compile and link edit the driver into your system from the source code presented in Appendix C. Not only will /dev/traceO be useful for your debugging, but it may help you better understand how the ID works before you actually write your driver. The game port driver in Appendix B has some calls to trsaveO so you can see how it is used.
System Panics
If the programmer expects that the driver could enter a state that is illegal, the driver can halt the system by using the panicO function. For example, if the driver expects one of three specific cases in a switch statement, the driver can add a fourth default case that calls the panicO function. The argument to
DEVICE DRIVERS 3-71
the panicO function is a string that will appear on the UNIX System V /386 monitor:
panic( "Your system has panic'ed, DE.V_NAME error I ") ;
The system will dump an image of memory for later analysis. If the error is recoverable, the driver should not call panicO. As with printfO, new drivers should use cmIL.errO for all panics as described in the Device Driver Reference Manual. In the example above the correct syntax would be as follows:
Taking a System Dump
In the event a panicO occurs, there may be some value in examining the dump produced by the system. Since UNIX System V /386 uses the same physical hard disk partition for both "swap" and "dump, II it is important that you do not reboot to the multi-user state before examining the dump. If the system reaches multi-user state, the dump may be overwritten by system paging. To examine the dump you must save the dump image. Since the sys-tem detects an improper shutdown, you will receive a message as follows on the next reboot:
There may be a system dump memory :image an the swap device.
Do JIOl want to save it? (yin»
Answer 'y'. When given a selection list of what media to use for the dump say 'q' for quad density 1.2 Megabyte floppy disks. (You will need a number of blank formatted floppy disks). Follow the instructions concerning floppy insertion and removal. When the image is written to a floppy disk, you will see a message reporting that /etc/ldsysdump can be used to copy the dump off the disk. First, however, you must let the reboot continue its checking and remounting of the file systems.
3-72 ISDG
When you see the Console Login: prompt, log in and execute fetcfldsysdump to take the dump off the floppy diskettes.
1. First do a df to determine a file system that has at least 8000 free disk blocks.
2. Execute ulimit 8000.
3. Execute ldsysdump file, where file is a file name to hold the dump image. It should be in the file system with ample room as found in step l.
4. Follow the instructions and specify "q" for quad density disks. Insert the floppy disks as directed.
Finally, you can use the crash command to examine the dump as follows:
crash -d file
Consult the crash(lM) manual page in the User'sjSystem Administrator's Refer-ence Manual for information on how to use crash to examine the UNIX Operating System kernel and user process status at the time of the panicO.
One useful piece of information might be to retrieve the panicO printout and any other kernel messages that have made their way into putbuf. Use the crash command "od -a putbuf count" where count is the length of the putbuf data you wish to examine.
Note that the procedures to examine a memory dump only apply to UNIX Systems that have completed the dump sequence, usually in response to a panicO. The prompt that you may see after an improper shutdown only indi-cates that the system was not properly brought down and a dump "may"
exist. If the system is inadvertently powered down or reset, or if your device driver causes the kernel to hang or go berserk without ever executing a
"panic," no dump will have been taken, and the above procedures will yield a large memory image that crash will not be able to interpret. Remember, the following message applies only when you have properly detected an error and executed the panicO function inside your driver or when your driver has caused a system error detected by the kernel or some other driver causing it to panicO:
DEVICE DRIVERS 3· 73
There may be a system dunp menory :image an the swap d~ce.
Ik> you want to save it? (yin»
At this point, it might be well to repeat the advice stated in the introduction:
Writing a device driver carries a heavy responsibility.
As part of the UNIX Operating System
kernel it is assumed to always take the correct action.
Few limits are placed on the driver by the other parts of the kernel, and the driver must be written
to never compromise the system's stability.