test

Writing Device Drivers

Machine Configuration

Setting Up a tip(1) 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 tip(1) for additional information.

Note -

A second machine is not required to debug a Solaris 7 device driver. It is only required for the use of tip(1).

Using a tip window confers the following advantages:

Setting Up the Host System

To set up the host system, do the following:

  1. 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.

  2. On the host system, make an entry in /etc/remote for the connection if it is not already there (see remote(4)).

    The terminal entry must match the serial port being used. The Solaris 7 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.

  3. In a shell window on the host, run tip(1) and specify the name of the entry:

    test% tip debugconnected

    The shell window is now a tip window connected to the console of the test machine.

    Caution - Caution -

    Do not use L1-A (for SPARC machines) or Control-ALT-D (for x86 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 the machine on. 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 ttyaok setenv output-device ttya

The eeprom command can also be used to make serial port A the console. As root user, 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 switch to serial port A during reboot.

Setting Up the Test System for x86 Platforms

On x86 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, x86 machines don't transfer console control to the tip connection until an early stage in the boot process.

Preparing for Disasters

It is possible for a driver to render the system incapable of booting. To avoid system reinstallation in this event, some advance work must be done.

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 add_drv(1M)).

To be safe, once 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.

Booting an Alternate Kernel

A kernel other than /platform/`uname -i`/kernel/unix can be booted by specifying it as the boot file. In fact, backup copies of all the system drivers in /platform/* can be made and used if the original drivers fail (this is probably more useful if more than one driver is being debugged). For example:

# cp -r /platform/sun4c/kernel /platform/sun4c/kernel.orig

To boot the original system, boot kernel.orig/unix.

Note -

During testing, the new driver should be placed in /platform/sun4c/kernel (and not in /kernel or /usr/kernel) so that, the driver is not loaded if the system is booted out of kernel.orig. Alternatively, the module path can be changed by booting with the ask (-a) option.

ok boot kernel.orig/unix
...

Rebooting with command: kernel.orig/unix
Boot device: /sbus/esp@0,800000/sd@1,0   File and args:kernel.orig/unix
SunOS Release 5.7 Version Generic [UNIX(R) System V Release 4.0]
Copyright (c) 1983-1998, Sun Microsystems, Inc.
...

For more complete control, boot with the ask (-a) option; this allows alternate boot parameters to be specified (such as /dev/null or /etc/system.orig if that is the saved original system file that was copied earlier).

ok boot -a
...

Rebooting with command: disk1 -a
Boot device: /sbus/esp@0,800000/sd@1,0   File and args: -a
Enter filename [/kernel/unix]: kernel.orig/unixEnter default directory for modules
[/platform/SUNW,Sun_4_75/kernel.orig /kernel /usr/kernel]:<CR>SunOS Release 5.7 Version Generic [UNIX(R) System V Release 4.0]
Copyright (c) 1983-1998, Sun Microsystems, Inc.
Name of system file [etc/system]: etc/system.origroot filesystem type [ufs]: <CR>Enter physical name of root device
[/sbus@1,f8000000/esp@0,800000/sd@1,0:a]: <CR>

Booting Off the Network or CD-ROM

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 7 CD-ROM.

Re-creating /devices and /dev

If the /devices or /dev directories are damaged--most likely to occur if the driver crashes during attach(9E))--they may be recreated by booting the system and running fsck(1M) to repair the damaged root file system. The root file system can then be mounted and /devices re-created by running drvconfig(1M) and specifying the /devices directory on the mounted disk. The /dev directory can be repaired by running devlinks(1M), disks(1M), tapes(1M), and ports(1M) on the dev directory of the mounted disk.

On SPARC, for example, if the damaged disk is /dev/dsk/c0t3d0s0, and an alternate boot disk is /dev/dsk/c0t1d0s0, do the following:

ok boot disk1
...
Rebooting with command: disk1
Boot device: /sbus/esp@0,800000/sd@1,0   File and args:
SunOS Release 5.7 Version Generic [UNIX(R) System V Release 4.0]
Copyright (c) 1983-1998, Sun Microsystems, Inc.
...
# fsck /dev/dsk/c0t3d0s0** /dev/dsk/c0t3d0s0
** Last Mounted on /
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
1478 files, 9922 used, 29261 free(141 frags, 3640 blocks, 0.4% fragmentation)
# mount /dev/dsk/c0t3d0s0 /mnt# drvconfig -r /mnt/devices# devlinks -r /mnt# disks -r /mnt# tapes -r /mnt# ports -r /mnt
Caution - Caution -

Fixing /devices and /dev may allow the system to boot, but other parts of the system may still be corrupted. This may only be a temporary fix to allow saving information (such as system core dumps) before reinstalling the system.

Booting Off a Backup Root Partition

One 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.