Driver testing and debugging

Coding the driver for debugging

Debugging code in the driver source code is one of the most valuable tools when testing and debugging a driver. Many of these facilities require that the driver code has a #include <sys/debug.h> statement.

Conditional compiler statements

Calculations, cmn_err( ) statements and other code that are only for debugging and other testing should be coded within conditional compiler statements in the driver. This saves you the task of removing extraneous code when you release the driver for production, and makes that debugging code readily available should you need to troubleshoot the driver after it is in the field.

SCO recommends the following:

All debugging #define statements should use strings that are prefixed. For example, for the my driver, you might have sections marked MY_DEBUG and MY_PERFORM. This prevents conflicts with debugging types that are defined for other drivers and for the kernel itself.
Provide separate code for different types of testing to which the driver will be subjected. For instance, you might use MY_TEST for functionality testing, MY_PERFORM for minimal performance testing, and MY_FULLPERF for full performance monitoring. Each of the testing options is then defined in the code as either 0 (turned off) or 1 (turned on), using standard C language coding practices.
The testing procedure can be refined further by using flags within the conditionally-compiled code. Then, when MY_TEST is turned on, you can specify the exact sort of testing without recompiling and reinstalling the driver. The flags should use the driver prefix. For instance, the following code sets three flags for testing the intr(D2) interrupt routine, the biostart(D2) routine, and driver performance:
```
   #if MY_TEST
   int my_intpr, my_biostpr, my_perfpr;
   #endif
```
You can change the flags by recompiling and reinstalling the driver, or you can change them in the running system either with a kernel debugger or by writing a small program to use /dev/kmem with the SVR5 getksym system call or the SCO OpenServer 5 nm(CP) command. You can also use scodb -w to change these flags.

Putting debug statements in a driver

Use the cmn_err(D3) function to put debugging comments in the driver code; when the driver executes, you can use these to tell what part of the driver is executing. The cmn_err(D3) function is similar to the SVR5 printf library routine and the SCO OpenServer 5 printf(S) system call but it executes from inside the kernel.

cmn_err( ) statements for debugging are written to the putbuf where they can be viewed using a crash command such as:

   od -h putbuf 500 ! more

Be sure to code newlines in the cmn_err( ) messages to ensure that the full text is written to the putbuf. Because they are written by the kernel, they cannot be redirected to a file or to a remote terminal (see ``Setting up a remote console for debugging''. On the other hand, as long as the system stays up, putbuf messages are copied to disk files by a user-level daemon. On SVR5 systems, the messages are copied to the /etc/.osm file; on SCO OpenServer 5 systems, the messages are copied to the /usr/adm/messages file. You can also write cmn_err( ) statements to the console, but massive amounts of statements to the console will severely slow system speed.

On older operating systems, a common practice is to code cmn_err( ) calls with the CE_PANIC level within #ifdef DEBUG sections, to force the debugger to be called when certain conditions occurred. Production drivers should never use the CE_PANIC level, even within DEBUG sections. The next section discusses other methods that should be used to force a call to the debugger.