Device Driver Debugging and Tuning Tips

The Oracle Solaris OS provides various tools for debugging and tuning your device driver:

• You might receive the following warning message from the add_drv(1M) command:

  Warning: Driver (driver_name) successfully added to system but failed to attach

  This message might have one of the following causes:

  • The hardware has not been detected properly. The system cannot find the device.

  • The configuration file is missing. See Writing a Configuration File for information on when you need a configuration file and what information goes into a configuration file. Be sure to put the configuration file in /kernel/drv or /usr/kernel/drv and not in the driver directory.

• Use the kmdb(1) kernel debugger for runtime debugging.

  The kmdb debugger provides typical runtime debugger facilities, such as breakpoints, watch points, and single-stepping. For more information, see Oracle Solaris Modular Debugger Guide.

• Use the mdb(1) modular debugger for postmortem debugging.

  Postmortem debugging is performed on a system crash dump rather than on a live system. With postmortem debugging, the same crash dump can be analyzed by different people or processes simultaneously. In addition, mdb enables you to create special macros called dmods to perform rigorous analysis on the dump. For more information, see Oracle Solaris Modular Debugger Guide.

• Use the kstat(3KSTAT) facility to export module-specific kernel statistics for your device driver.

• Use the DTrace facility to add instrumentation to your driver dynamically so that you can perform tasks such as analyzing the system and measuring performance. For information on DTrace, see the Dtrace wiki.

• If your driver does not behave as expected on a 64-bit platform, make sure you are using a 64-bit driver. By default, compilation on the Oracle Solaris OS yields a 32-bit result on every architecture. To obtain a 64-bit result, follow the instructions in Building a Driver.

  Use the file(1) command to determine whether you have a 64-bit driver.

  % file qotd_3 qotd_3: ELF 32-bit LSB relocatable 80386 Version 1

• If you are using a 64-bit system and you are not certain whether you are currently running the 64-bit kernel or the 32-bit kernel, use the -k option of the isainfo(1) command. The -v option reports all instruction set architectures of the system. The -k option reports the instruction set architecture that is currently in use.

  % isainfo -v 64-bit sparcv9 applications vis2 vis 32-bit sparc applications vis2 vis v8plus div32 mul32 % isainfo -kv 64-bit sparcv9 kernel modules

• If your driver seems to have an error in a function that you did not write, make sure you have called that function with the correct arguments and specified the correct include files. Many kernel functions have the same names as system calls and user functions. For example, read() and write() can be system calls, user library functions, or kernel functions. Similarly, ioctl() and mmap() can be system calls or kernel functions. The man mmap command displays the mmap(2) man page. To see the arguments, description, and include files for the kernel function, use the man mmap.9e command. If you do not know whether the function you want is in section 9E or section 9F, use the man -l mmap command, for example.