Chapter 15 Debugging

Overview of Debugging Facilities

Thischapter describes some of the tools available to assist in debugging STREAMS-based applications.

The basic categories available for debugging can be broken into these areas:

• Kernel debug printing - kernel facilities for printing from inside drivers

• STREAMS error logging - a STREAMS-supported model of generating error messages and allowing them to be received by one of three different types of loggers

• Kernel-examination tools - which include the tools bundled with the operating system

Kernel Debug Printing

Console Messages

The kernel routine cmn_err(9F) allows printing of formatted strings on a system console. It displays a specified message on the console and/or stores it in the putbuf that is a circular array in the kernel and contains output from cmn_err(9F). Its format is:

#include <sys/cmn_err.h>

void cmn_err (int level, char *fmt, int ARGS)

where level can take the following values:

• CE_CONT - may be used as simple printf(3S). It is used to continue another message or to display an informative message not associated with an error.

• CE_NOTE - report system events. It is used to display a message preceded by NOTICE:. This message is used to report system events that do not necessarily require user action, but may interest the system administrator. For example, a sector on a disk needing to be accessed repeatedly before it can be accessed correctly.

• CE_WARN - system events that require user action. This is used to display a message preceded by WARNING:. This message is used to report system events that require immediate attention, such as those where, if an action is not taken, the system may panic. For example, when a peripheral device does not initialize correctly, this level should be used.

• CE_PANIC - system panic. This is used to display a message preceded with PANIC:. Drivers should specify this level only under the most severe conditions. A valid use of this level is when the system cannot continue to function. If the error is recoverable and not essential to continued system operation, do not panic the system. This level halts all processing.

  fmt and ARGS are passed to the kernel routine printf that runs at splhi and should be used sparingly. If the first character of fmt is ! (an exclamation point), output is directed to putbuf. putbuf can be accessed with the crash(1M) command. If the destination character begins with ^ (a caret) output goes to the console. If no destination character is specified, the message is directed to both the putbuf array and the console.

  cmn_err(9F) appends each fmt with "\n", except for the CE_CONT level, even when a message is sent to the putbuf array. ARGS specifies a set of arguments passed when the message is displayed. Valid specifications are %s (string), %u (unsigned decimal), %d (decimal), %o (octal), and %x (hexadecimal). cmn_err(9F) does not accept length specifications in conversion specifications. For example, %3d is ignored.

STREAMS Error Logging

Error and Trace Logging

STREAMS error and trace loggers are provided for debugging and for administering STREAMS modules and drivers. This facility consists of log(7D), strace(1M), strclean(1M), strerr(1M), and strlog(9F).

Any module or driver in any Stream can call the STREAMS logging function strlog(9F) (see also log(7D)). strlog(9F) sends formatted text to the error logger strerr(1M), the trace logger strace(1M), or the console logger.

strerr(1M) runs as a daemon process initiated at system startup. A call to strlog(9F) requesting an error to be logged causes an M_PROTO message to be sent to strerr(1M), which formats the contents and places them in a daily file. strclean(1M) purges daily log files that have not been modified for three days.

strlog(9F) also sends a similar M_PROTO message to strace(1M), which places it in a user designated file. strace(1M) is initiated by a user. The user designates the modules and drivers and the severity level of the messages accepted for logging by strace(1M).

A user process can submit its own M_PROTO messages to the log driver for inclusion in the logger of its choice through putmsg(2). The messages must be in the same format required by the logging processes and are switched to the loggers requested in the message.

The output to the log files is formatted, ASCII text. The files can be processed by standard system commands such as grep(1) or by developer-provided routines.

Kernel Examination Tools

crash(1M) Command

crash(1M) examines kernel structures interactively. It can be used on a system dump and on an active system. The following crash functions are related to STREAMS:

• dbfree - Print data block header free list

• dblock - Print allocated STREAMS data block headers

• linkblk - Print the linkblk(9S) table

• mbfree - Print free STREAMS message block headers

• mblock - Print allocated STREAMS message block headers

• pty - Print pseudo ttys now configured. The l option gives information on the line discipline module ldterm(7M), the h option provides information on the pseudo-tty emulation module ptem(7M). The s option gives information on the packet module pckt(7M).

• qrun - Print a list of scheduled queues

• queue - Print the STREAMS queues

• stream - Print the stdata table

• strstat - Print STREAMS statistics

• tty - Print the tty table. The l option prints details about the line discipline module.

  The crash(1M) functions dblock, linkblk, mblock, queue, and stream take an optional table entry argument or address that is the address of the data structure. The strstat command gives information about STREAMS event cells and linkblks in addition to message blocks, data blocks, queues, and streams. On the output report, the CONFIG column represents the number of structures currently configured. It may change because resources are allocated as needed.

adb(1) Command

adb(1) is an interactive general-purpose debugger. It can be used to examine files and provides a controlled environment for the execution of programs. It has no support built in for any STREAMS functionality.

kadb(1M) Command

kadb(1M) is an interactive debugger with a user interface similar to adb(1), but runs in the same virtual address space as the program begin debugged. It also has no specific STREAMS support.