NeXTSTEPDRIVERKIT:Chapter4 5

Debugging a Driver

드라이버 디버깅(Debugging a Driver)

You have two choices for creating debugging messages: the IOLog() function and the Driver Debugging Module (DDM). Most drivers just use IOLog() until a need arises for the more powerful and complex DDM functions.

Another debugging tool, gdb, is described in NEXTSTEP Development Tools and Techniques. You can run the driver with gdb from Project Builder--the example located in /NextLibrary/Documentation/NextDev/Examples/DriverKit/TestDriver shows how to do this. NEXTSTEP Development Tools and Techniques also describes Project Builder.

Using the IOLog Function

Using IOLog() is similar to using printf() to print error or debug messages. You can output strings and parameters, just as for printf(). One difference is that output is placed in the /usr/adm/messages file instead of the console window. Place a call to IOLog() anywhere in your driver where you want to get information about the driver state--or to indicate that the driver reached that point during execution.

IOLog() is useful both for status messages and as a basic debugging tool. Although IOLog() is useful for debugging, it can affect the timing of the driver. When timing is important, you should use DDM instead.

See "Functions" in Chapter 5, "Driver Kit Reference", for more information about IOLog().

Using the Driver Debugging Module (DDM)

The Driver Debugging Module (DDM) provides support for viewing debugging information without disturbing the timing of the kernel. By using the DDMViewer application (in /NextDeveloper/Demos), you can specify which information should be stored in the event buffer and display debugging information from this buffer.

The core of DDM is a circular event buffer that stores the debugging information sent to it by drivers. Each entry in the buffer is timestamped (to the microsecond) and consists of a printf-style format string and up to five arguments associated with the format string. A call to the function that timestamps and stores one entry takes about 10 microseconds.

Gathering DDM Events

The function IOAddDDMEntry() adds an event to the DDM buffer. An event consists of a character string and several integer values. The IODEBUG() macro is provided to call IOAddDDMEntry(): A driver typically doesn't call IOAddDDMEntry() directly. Instead, the driver should define its own macros using the IODEBUG() macro, as in this example:

#define ddm_exp(x, a, b, c, d, e)      \
    IODEBUG(A7770_DDM_INDEX, DDM_EXPORTED, x, a, b, c, d, e)
#define ddm_him(x, a, b, c, d, e)      \
    IODEBUG(A7770_DDM_INDEX, DDM_HIM, x, a, b, c, d, e)

These macros can then be called like this:

ddm_him("abort_channel chan %d\n", channel, 2,3,4,5);

ddm_him("scb_int_preempt: scb 0x%x index %d haStat %s\n",
    scb_ptr, scb_index,
    IOFindNameForValue(compstat, scbHaStatValues),
    4,5);

A word of mask bits controls the collection of DDM entries. All calls to IODEBUG() don't add data to DDM's circular buffer--only those events whose mask bits are enabled are added. The mask bits are enabled and disabled by a user-level tool like DDMViewer. A driver isn't (and shouldn't be) concerned about which mask bits are enabled. Typically you turn on one or two bits of the mask word to study the trace information for a particular module.

See the SCSI example driver in /NextDeveloper/Examples/DriverKit/Adaptec1542B, which illustrates all aspects of using DDM.

Viewing DDM Events with DDMViewer

You can examine DDM traces at the user-level with the DDMViewer application, which is located in /NextDeveloper/Demos. You can also specify DDM mask bits with this application. DDMViewer can be run on any computer running NEXTSTEP, not just the machine being tested.

The DDMViewer window contains the following controls:

• Device Name field. Enter the name of the target to which you want to attach. The name is determined by the driver.
  
• Host Name field. Enter the name of the host on which the target is running. Leave it empty if you are debugging a driver or kernel on the current machine.
  
• List button. Click this button to start and stop the display of DDM entries. Entries are displayed starting from the last event in time and scrolling backward.
  
• Set Mask button. Click this button to send the mask defined in the Mask window (see below) to the target.
  
• Disable button. Click this button to freeze the state of the DDM buffer at the target. Click again to reenable.
  
• Clear Window button. Click this button to clear the display area.
  
• Clear Buffer button. Click this button to clear the target's circular DDM buffer.
  

You can specify the value of the DDM mask bits by name if you open a .ddm file that specifies the names of the mask bits. You create .ddm files with an editor such as Edit. Here's an example of a .ddm file:

#
#  DDMViewer data file for kernel devices.
#
Index : 0 : "Kernel Devices"
#
#  Common fields.
#
0x0001 : "Device Object"
0x0002 : "Disk Object"
0x0004 : "Net"
0x0020 : "DMA"
#
#  SCSI.
#
0x0100 : "SCSI Control"
0x0400 : "SCSI Disk"

Comments start with "#". The line that starts with "Index" defines which DDM Mask word is being defined (there are currently four mask words). The Index line also defines the name of the window associated with this set of mask bits. All other lines define one bit in the mask word, specifying the value of the bit and an ASCII name equivalent. The SCSI example driver in /NextDeveloper/Examples/DriverKit/Adaptec1542B has a sample .ddm file.