6 Administering Devices with Dynamic Device Recognition

This chapter describes the Dynamic Device Recognition (DDR) database, which you use to administer devices in the SCSI/CAM I/O subsystem. It explains how you use the ddr_config utility to manage the DDR database on your system. This chapter introduces DDR, then describes how you use the ddr_config utility to:

Add SCSI devices to the DDR database

Convert a customized cam_data.c file

This chapter also discusses adding pseudoterminals and disks and tapes that are not SCSI devices to the operating system.

6.1 Understanding Dynamic Device Recognition

Dynamic Device Recognition is a framework for describing the operating parameters and characteristics of SCSI devices to the SCSI CAM I/O subsystem. You can use DDR to include new and changed SCSI devices into your environment without having to reboot the operating system. You do not disrupt user services and processes, as happens with static methods of device recognition.

Beginning with Digital UNIX Version 4.0, DDR is preferred over the current, static method for recognizing SCSI devices. The current, static method, as described in Chapter 5, is to edit SCSI device customizations into the /sys/data/cam_data.c data file, reconfigure the kernel, and shut down and reboot the operating system.

Note
Support for the static method of recognizing SCSI devices will be retired in a future release of Digital UNIX .

Digital UNIX Version 4.0 supports both methods of recognizing SCSI devices. Both methods can be employed on the same system, with the restriction that the devices described by each method are exclusive to that method (nothing is doubly-defined).

The information DDR provides about SCSI devices is needed by SCSI drivers. You can supply this information using DDR when you add new SCSI devices to the system, or you can use the /sys/data/cam_data.c data file and static configuration methods. The information provided by DDR and the cam_data.c file have the same objectives. When compared to the static method of providing SCSI device information, DDR minimizes the amount of information that is supplied by the device driver or subsystem to the operating system and maximizes the amount of information that is supplied by the device itself or by defaults specified in the DDR databases.

6.1.1 Conforming to Standards

Devices you add to the system should conform to the SCSI-2 standard, as specified in SCSI-2, Small Computer System Interface-2 (X3.131-1994). If your devices do not comply with the standard, or if they require exceptions from the standard, you store information about these differences in the DDR database. If the devices comply with the standard, there is usually no need to modify the database.

6.1.2 Understanding DDR Messages

Following are the most common DDR message categories and the action, if any, that you should take.

Console messages are displayed during the boot sequence.
Frequently, these messages indicate that the kernel cannot read the DDR database. This error occurs when the system's firmware is not at the proper revision level. Upgrade to the correct revision level of the firmware.
Console messages warn about corrupted entries in the database. Recompile and regenerate the database.
Runtime messages generally indicate syntax errors that are produced by the ddr_config compiler. The compiler runs when you use the -c option to the ddr_config utility and does not produce an output database until all syntax errors have been corrected.

6.1.3 Getting Help with ddr_config Options

Use the -h option to the ddr_config command to display help on command options.

6.2 Changing the DDR Database

When you make a change to the operating parameters or characteristics of a SCSI device, you must describe the changes in the /etc/ddr.dbase file. You must compile the changes by using the ddr_config -c command.

Two common reasons for changes are:

Your device deviates from the SCSI standard or reports something different from the SCSI standard
You want to optimize device defaults, most commonly the TagQueueDepth parameter, which specifies the maximum number of active tagged requests the device supports

You use the ddr_config -c command to compile the /etc/ddr.dbase file and produce a binary database file, /etc/ddr.db. When it is notified that the file's state has changed, the kernel loads the new /etc/ddr.dbase file. In this way, the SCSI CAM I/O subsystem is dynamically updated with the changes that you made in the /etc/ddr.dbase file and the contents of the on-disk database are synchronized with the contents of the in-memory database.

Use the following procedure to compile the /etc/ddr.dbase database:

Log in as root or become the superuser.
Enter the ddr_config -c command, for example:
```
# /sbin/ddr_config -c 

# 
```

When the prompt is displayed, the compilation is complete. If there are syntax errors, they are displayed at standard output and no output file is compiled.

6.3 Converting Customized cam_data.c Information

You use the following procedure to transfer customized information about your SCSI devices from the /sys/data/cam_data.c file to the /etc/ddr.dbase text database. In this example, MACHINE is the name of your machine's system configuration file.

Log on as root or become the superuser.
To produce a summary of the additions and modifications that you should make to your /etc/ddr.dbase file, enter the ddr_config -x command. For example:
```
# /sbin/ddr_config -x MACHINE > output.file
```
The command uses as input the system configuration file that you used to build your running kernel. The procedure runs in multiuser mode and requires no input after it has been started. You should redirect output to a file in order to save the summary information. Compile errors are reported to standard error and the command terminates when the error is reported. Warnings are reported to standard error and do not terminate the command.
Edit the characteristics that are listed on the output file into the /etc/ddr.dbase file, following the syntax requirements of that file. Instructions for editing the /etc/ddr.dbase database are found in ddr.dbase(4).
Enter the ddr_config -c command to compile the changes.

See Section 6.2 for more information.

6.4 Adding Pseudoterminals and Devices without Using DDR

You can add pseudodevices, disks, and tapes statically, without using DDR, by using the methods described in the following sections.

6.4.1 Adding Pseudoterminals

Pseudoterminals enable users to use the network to access a system. A pseudoterminal is a pair of character devices that emulates a hardware terminal connection to the system. Instead of hardware, however, there is a master device and a slave device. Pseudoterminals, unlike terminals, have no corresponding physical terminal port on the system. Remote login sessions, window-based software, and shells use pseudoterminals for access to a system. Digital UNIX offers two implementations of pseudoterminals: BSD STREAMS and BSD clist.

For some installations, the default number of pty devices is adequate. However, as your user community grows, and each user wants to run multiple sessions of one or more timesharing machines in your environment, the machines may run out of available pty lines.

To add pseudoterminals to your system:

Edit the pseudodevice entry in the system configuration file. By default, the kernel supports 255 pseudoterminals. If you add more pseudoterminals to your system, you must edit the system configuration file entry and increment the number 255 by the number of pseudoterminals you want to add. The following examples show that 400 pseudoterminals have been added.
The pseudodevice entry for STREAMS-based pseudoterminals is as follows:
```
pseudo-device rpty 655
```
The pseudodevice entry for clist- based pseudoterminals is as follows:
```
pseudo-device pty 655
```
For more information on the configuration file and its its pseudodevice keywords, refer to
Chapter 5.
Rebuild and boot the new kernel. Use the information on rebuilding and booting the new kernel in Section 5.4.3.
When the system is first installed, the configuration file contains a pseudodevice entry with the default number of 255 pseudoterminals. If for some reason the number is deleted and not replaced with another number, the system defaults to supporting 80 pseudoterminals.
Log in as root and change to the /dev directory.
Create the device special files by using the MAKEDEV command, which has the following syntax:
./MAKEDEV pty#
The number sign (#) represents the set of pseudoterminals (0 to 101) you want to create. The first 51 sets (0 to 50) create 16 pseudoterminals for each set. The last 51 sets (51 to 101) create 46 pseudoterminals for each set. You can use the following syntax to create a large number of pseudoterminals:
./MAKEDEV PTY_#
The number sign (#) represents the set of pseudoterminals (1 to 9) you want to create. Each set creates 368 pseudoterminals, except the PTY_3 and PTY_9 sets, which create 356 and 230 pseudoterminals, respectively.
Refer to the Software Product Description (SPD) for the maximum number of supported pseudoterminals.
Note
By default, the installation software creates device special files for the first two sets of pseudoterminals, pty0 and pty1. The pty0 pseudoterminals have corresponding device special files named /dev/ttyp0 through /dev/ttypf. The pty1 pseudoterminals have corresponding device special files named /dev/ttyq0 through /dev/ttyqf.

If you add pseudoterminals to your system, the pty# variable must be higher than pty1 because the installation software sets pty0 and pty1. For example, to create device special files for a third set of pseudoterminals, enter:
```
# ./MAKEDEV pty2
```
The MAKEDEV command lists the device special files it has created. For example:
```
MAKEDEV: special file(s) for pty2:
ptyr0 ttyr0 ptyr1 ttyr1 ptyr2 ttyr2 ptyr3 ttyr3 ptyr4 ttyr4
ptyr5 ttyr5 ptyr6 ttyr6 ptyr7 ttyr7 ptyr8 ttyr8 ptyr9 ttyr9
ptyra ttyra ptyrb ttyrb ptyrc ttyrc ptyrd ttyrd ptyre ttyre
ptyrf ttyrf
```

If you want to allow root logins on all pseudoterminals, make sure an entry for ptys is present in the /etc/securettys file. If you do not want to allow root logins on pseudoterminals, delete the entry for ptys from the /etc/securettys file. For example (using the sample output shown in step 5), to add the entries for the new tty lines and to allow root login on all pseudoterminals, enter the following lines in the /etc/securettys file:

/dev/tty08     # direct tty

/dev/tty09     # direct tty

/dev/tty10     # direct tty

/dev/tty11     # direct tty

ptys

Refer to the securettys(4) reference page for more information.

The pty name space in SVR4 systems is defined as follows:

/dev/pts/N

The variable N is a number from 0-9999.

This name space allows for more scalability than the BSD pty name space (tty[a-zA-Z][0-9a-zA-Z]). The base system commands and utilities have been modified to support both SVR4 and BSD pty name spaces. For binary compatibility reasons, the default is the BSD name space. You can alter this behavior by using the SYSV_PTY(8) command. The invocation of the SVS_PTY command results in using the SVR4 name space as the default. To revert back to the original default behavior (BSD pty name space), create the BSD ptys as discussed in Section 6.4.1.

6.4.2 Adding Disk and Tape Drives

When you add new tape or disk drives to your system, you must physically connect the devices and then make the devices known to the system. There are two methods, one for static drivers and another for loadable drivers.

Note
You will need the documentation that came with your system's hardware. This includes such documentation as the owner's guide, the disk drive guide, and the options guide.

To add a device for a loadable driver, see Writing Device Drivers: Tutorial.

To add a device for a static driver, see Section 5.4.1.

Next, you make the device special files for the device, by following these steps:

Change to the /dev directory.
Create the device special files by using the MAKEDEV command. If you are configuring a RAID controller, follow the procedure described in the SCSI(8) reference page. Use the following syntax to invoke the MAKEDEV command:
./MAKEDEV device#
The device variable is the device mnemonic for the drive you are adding. Appendix A lists the device mnemonics for all supported disk and tape drives. The number sign (#) is the number of the device, 0 through 127 for SCSI disk and tape devices. For example, to create the device special files for two SCSI disk drives, enter the following command:
```
# ./MAKEDEV rz5 rz7
MAKEDEV: special file(s) for rz5:
rz5a rrz5a rz5b rrz5b rz5c rrz5c rz5d rrz5d rz5e rrz5e rz5f
rrz5f rz5g rrz5g rz5h rrz5h
MAKEDEV: special file(s) for rz7:
rz7a rrz7a rz7b rrz7b rz7c rrz7c rz7d rrz7d rz7e rrz7e rz7f
rrz7f rz7g rrz7g rz7h rrz7h
```
Stop system activity by using the shutdown command and then turn off the processor. Refer to Chapter 3 for more information.
Power up the machine. To ensure that all the devices are seen by the system, power up the peripherals before powering up the system box.
Boot the system with the new kernel. Refer to Chapter 3 for information on booting your processor.