Debugging
Debugging is the process of finding and eliminating faults from software. Almost every device driver writer will be faced with a difficult bug at some point in the development process. This chapter presents an overview of the tools available to make this process easier. This chapter provides information on the following subjects:
Machine Configuration
Before you begin developing a Solaris driver, set up your test platform for this purpose. Testing on a separate system is safest. This section explains how to set up a pair of machines for development, and how to prepare a test system for disaster recovery.
Setting Up a tip Connection
A serial connection can be made between a test system (the machine executing the code to be debugged) and a host system using tip(1). This connection enables a window on the host system, called a tip window, to be used as the console of the test machine. See the tip(1) man page for additional information.
Using a tip window confers the following advantages:
Interactions with the test system or kadb can be monitored. For example, the window can keep a log of the session for use if the driver crashes the test system.
The test machine can be accessed remotely by logging into a host machine (often called a tip host) and using tip(1) to connect to the test machine.
Note - A tip connection (and a second machine) is not required to debug a Solaris 9 device driver, but is recommended.
To Set Up the Host System
To set up the host system, do the following:
Connect the host system to the test machine using serial port A on both machines.
This connection must be made with a null modem cable.
On the host system, make an entry in /etc/remote for the connection if it is not already there (see the remote(4) man page for details).
The terminal entry must match the serial port being used. The Solaris 9 operating environment comes with the correct entry for serial port B, but a terminal entry must be added for serial port A:
debug:\ :dv=/dev/term/a:br#9600:el=^C^S^Q^U^D:ie=%$:oe=^D:Note - The baud rate must be set to 9600.
In a shell window on the host, run tip(1) and specify the name of the entry:
% tip debug connected
The shell window is now a tip window connected to the console of the test machine.
Caution - Do not use STOP-A for SPARC machines or F1-A for IA (Intel architecture) machines on the host machine to send a break to stop the test machine. This action actually stops the host machine. To send a break to the test machine, type ~#
in the tip window. Commands such as this are recognized only if they are the first characters on a line, so press the Return key or Control-U first if there is no effect.
Setting Up the Test System for SPARC Platforms
A quick way to set up the test machine is to unplug the keyboard before turning on the machine. The machine then automatically uses serial port A as the console.
Another way to set up the test machine is to use boot PROM commands to make serial port A the console. On the test machine, at the boot PROM ok prompt, direct console I/O to the serial line. To make the test machine always come up with serial port A as the console, set the environment variables input-device and output-device.
ok setenv input-device ttya ok setenv output-device ttya |
The eeprom command can also be used to make serial port A the console. As superuser, execute the following commands to make the input-device and output-device parameters point to serial port A.
# eeprom input-device=ttya # eeprom output-device=ttya |
Executing the eeprom commands causes the console to be redirected to serial port A at each subsequent system boot.
Setting Up the Test System for IA Platforms
On IA platforms, use the eeprom command to make serial port A the console. The procedure for this is the same as for SPARC platform and is discussed above. Executing the eeprom commands causes the console to switch to serial port A (COM1) during reboot.
Note - Unlike SPARC machines, where the tip connection maintains console control throughout the boot process, IA machines don't transfer console control to the tip connection until an early stage in the boot process.
Preparing for Disasters
Under certain circumstances, a driver can render the system incapable of booting. To avoid system reinstallation in this event, some advance work must be done.
Back Up Critical System Files
A number of driver-related system files are difficult, if not impossible, to reconstruct. Files such as /etc/name_to_major,/etc/driver_aliases, /etc/driver_classes, and /etc/minor_perm can be corrupted if the driver crashes the system during installation (see the add_drv(1M) man page).
To be safe, after the test machine is in the proper configuration, make a backup copy of the root file system. If you plan on modifying the /etc/system file, make a backup copy of the file before modifying it.
Prepare and Boot an Alternate Kernel
A good strategy to avoid rendering a system inoperable is to make a copy of the kernel and associated binaries, and to boot that instead of the default kernel. To do so, make a copy of the drivers in /platform/* as follows:
# cp -r /platform/`uname -i`/kernel /platform/`uname -i`/kernel.test |
When developing your driver, place it in /platform/`uname -i`/kernel.test/drv and boot that kernel instead of the default kernel:
# reboot -- kernel.test/unix |
or from the PROM:
ok boot kernel.test/unix |
This results in the test kernel and drivers being booted:
Rebooting with command: boot kernel.test/unix Boot device: /sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@0,0:a File and args: kernel.test/unix SunOS Release 5.9 Version Generic 32-bit Copyright 1983-2002 Sun Microsystems, Inc. All rights reserved. ... |
Alternately, the module path can be changed by booting with the ask (-a) option:
ok boot -a |
This results in a series of prompts which you can use to configure the way the kernel boots:
Rebooting with command: boot -a Boot device: /sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@0,0:a File and args: -a Enter filename [kernel/sparcv9/unix]: kernel.test/sparcv9/unix Enter default directory for modules [/platform/sun4u/kernel.test /kernel /usr/kernel]: <CR> Name of system file [etc/system]: <CR> SunOS Release 5.9 Version Generic 64-bit Copyright 1983-2002 Sun Microsystems, Inc. All rights reserved. root filesystem type [ufs]: <CR> Enter physical name of root device [/sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@0,0:a]: <CR> |
Prepare Other Backup Plans
If the system is attached to a network, the test machine can be added as a client of a server. If a problem occurs, the system can be booted off the network. The local disks can then be mounted and fixed. Alternatively, the system can be booted directly from the Solaris 9 CD-ROM.
Another way to recover from disaster is to have another bootable root file system. Use format(1M) to make a partition the exact size of the original, then use dd(1M) to copy it. After making a copy, run fsck(1M) on the new file system to ensure its integrity.
Later, if the system cannot boot from the original root partition, boot the backup partition and use dd(1M) to copy the backup partition onto the original one. If the system will not boot but the root file system is undamaged (just the boot block or boot program was destroyed), boot off the backup partition with the ask (-a) option, then specify the original file system as the root file system.