This section describes some of the mechanisms that can be used to debug drivers at runtime. Runtime debugging is typically performed during driver development; this process is substantially simplified if you have followed the coding practices described in the previous section. Although the kadb debugger is a runtime debugging tool, it is treated at length in a separate section, The kadb Kernel Debugger.
The /etc/system file serves several purposes, but for driver development, the most important is that it allows you to set the value of kernel variables at boot time. This can be used to toggle different behaviors in a driver, or to enable certain debugging features made available by the kernel.
/etc/system is read only once, while the kernel is booting. After this file is modified, the system must be rebooted for the changes to take effect. If a change in the file causes the system not to work, boot with the ask (-a) option and specify /dev/null as the system file.
The set command is used to change the value of module or kernel variables:
To set module variables, specify the module name and the variable:
set module_name:variable=value
For example, to set the variable test_debug in the driver test, use the following set command:
set test:test_debug=1
To set a variable exported by the kernel itself, omit the module name. Other assignments are also supported, such as bitwise OR'ing a value into an existing value:
set moddebug | 0x80000000
See the system(4) man page for more information.
Most kernel variables are not guaranteed to be present in subsequent releases.
moddebug is a kernel variable that controls the module loading process. The possible values are:
0x80000000 |
Prints messages to the console when loading or unloading modules. |
0x40000000 |
Gives more detailed error messages. |
0x20000000 |
Prints more detail when loading or unloading (such as including the address and size). |
0x00001000 |
No auto-unloading drivers: the system will not attempt to unload the device driver when the system resources become low. |
0x00000080 |
No auto-unloading streams: the system will not attempt to unload the streams module when the system resources become low. |
0x00000010 |
No auto-unloading of kernel modules of any type. |
0x00000001 |
If running with kadb, moddebug causes a breakpoint to be executed and a return to kadb immediately before each module's _init(9E) routine is called. Also generates additional debug messages when the module's _info and _fini routines are executed. |
kmem_flags is a kernel variable used to enable debugging features in the kernel's memory allocator. Setting kmem_flags to 0xf enables the allocator's debugging features. These include runtime checks to find:
Code that writes to a buffer after it is freed
Code using memory before it is initialized
Code that writes past the end of a buffer
The “Debugging With the Kernel Memory Allocator” section of the Solaris Modular Debugger Guide describes how the kernel memory allocator can be used to determine the root cause of these problems.
Testing and developing with kmem_flags set to 0xf is extremely valuable because it can detect latent memory corruption bugs. Because setting kmem_flags to 0xf changes the internal behavior of the kernel memory allocator, you should thoroughly test without kmem_flags as well.
The kernel automatically loads needed modules and unloads unused ones, so modload(1M), modunload(1M), and modinfo(1M) are not very useful for system administration. However, they can be useful when debugging and stress testing driver load/unload scenarios.
modload can be used to force a module into memory. The kernel might subsequently unload the module, but modload can be used to verify that the driver has no unresolved references when loaded. Keep in mind that loading a driver does not mean that the driver will attach. A driver that loads successfully will have its _info(9E) entrypoint called, but will not necessarily attach.
You can use modinfo to confirm that your driver is loaded. Here is an example:
$ modinfo Id Loadaddr Size Info Rev Module Name 6 101b6000 732 - 1 obpsym (OBP symbol callbacks) 7 101b65bd 1acd0 226 1 rpcmod (RPC syscall) 7 101b65bd 1acd0 226 1 rpcmod (32-bit RPC syscall) 7 101b65bd 1acd0 1 1 rpcmod (rpc interface str mod) 8 101ce8dd 74600 0 1 ip (IP Streams module) 8 101ce8dd 74600 3 1 ip (IP Streams device) ... $ modinfo | grep mydriver 169 781a8d78 13fb 0 1 mydriver (Test Driver 1.5)
The number in the info field is the major number chosen for the driver. modunload can be used to unload a module, given a module ID (which can be found in the leftmost column of modinfo output). A common bug is that a driver refuses to unload, even after a modunload is issued. Note that a driver will not unload if the system thinks the driver is busy. This occurs when the driver fails detach(9E), either because the driver really is busy, or because the detach entry point is implemented incorrectly.
To remove all currently unused modules from memory, run modunload with a module ID of 0:
# modunload -i 0