ddr.dbase - Text database file of SCSI CAM device definitions
Dynamic Device Recognition (DDR) is a framework for describing the operating parameters and characteristics of SCSI devices to the SCSI CAM I/O subsystem. You use a utility, /sbin/ddr_config, and a text database, /etc/ddr.dbase, to make changes to the subsystem after installation and without rebooting.
This dynamic device recognition capability replaces the static methods of device recognition that have been employed by using the compiled-in device table, /sys/data/cam_data.c. SCSI devices in the /sys/data/cam_data.c file are supported for this release of the operating system, but support will be withdrawn in a future release.
The ddr.dbase file contains device specifications for the SCSI CAM devices. To manage these devices, you edit the ddr.dbase file to contain new or changed device information. After you have made changes to the ddr.dbase file, you run the ddr_config utility, which compiles a new version of the database, places the output in the /etc/ddr.db binary database file, and notifies the kernel that the device database has changed. Subsequently, the kernel synchronizes its in-memory device tables with the /etc/ddr.db binary database file.
The ddr.dbase file is an ASCII file and it is shipped on the distribution medium already populated with general syntax and entries for Digital-supported devices and templates for other devices.
Semantics, element definition, and formats conform to the specifications of SCSI-2, SMALL COMPUTER SYSTEM INTERFACE - 2 (X3.131-1994).
The following list contains the general syntax rules for entries in the ddr.dbase file: Comments: Text starting with the # character is a comment until the end of the line. Whitespace: Leading and separating whitespace is ignored. Identifiers: Identifiers must be fully specified; are case insensitive. Integers: Integers can be specified as decimal, hexadecimal (when preceded with 0x), or octal (when preceded with 0). Tokens: All tokens are case insensitive. All tokens must be fully specified, with the exception of Yes and No tokens, which are recognized by the first letter only. Strings: Strings are case sensitive when enclosed by quotes. Otherwise, strings are converted to lowercase.
There are three parts to the ddr.dbase file: A VERSION data section One or more GLOBAL data sections One or more SCSIDEVICE data sections
Each of these sections is identified by a keyword.
The VERSION data section defines which version of the ddr.dbase syntax the file conforms to. The syntax for the section keyword is: VERSION = version
The first line in the ddr.dbase file that is not a comment line must contain this version keyword and string.
The GLOBAL data section contains information used by the device data sections for two classes of attributes: disk partition sizes and tape density settings.
The object of the global partition information is to allow the kernel to create a default partition layout based on a disk's capacity and block size. You specify global information in this data section to change the defaults for disk devices.
The object of the global SCSI density code translation table for tapes is to define the density values (bpi) and blocking factors for the SCSI density codes that are obtained from tape devices.
You can use the strings defined in the density tables to specify SCSI density codes to the subsequent SCSIDEVICE subsections of this file instead of explicitly stating the integer values in the SCSIDEVICE subsections.
The GLOBAL data section syntax is as follows. The first data line in a global data section contains the GLOBAL keyword. The lines following the GLOBAL keyword line contain data lines. Each data line contains a single data element. Excepting as noted in the following discussion, data lines can be specified in any order, or omitted. The GLOBAL data section that contains the SCSI density code translation table must precede all SCSIDEVICE data section lines in the ddr.dbase file.
The PARTITION data line syntax is as follows.
Each PARTITION data line consists of an identity equated to a value.
In the /ddr.dbase file for VERSION 1, there are four data lines
and they are:
Partition_A_size = 64
Partition_B_size = 128
Partition_G_size = 400
min_partition_size = 50 If any of these values are not specified, they default to values compiled into the system.
The density code translation table syntax is as follows.
The first data line in a density code translation table must be
the specification for the size of the table, an identity equated to
For VERSION 1, this data line must be:
scsi_density_table_size = 0x30 There must be at least one subsequent entry in the table. These data lines are specified as an identifier and density code equated to a density name string, a bpi value, and a block size value (in bytes). The general format for these data lines is:
scsi_tape_density[density_code] = "name" bpi block_size The data lines can be specified in any order. If an element in a data line is not specified, it is assigned a NULL value. A block_size of zero indicates that the default blocking factor for the device is used and variable-size record blocking is allowed.
The first data line in a SCSI device data section must contain the SCSIDEVICE keyword. There must be a SCSIDEVICE data section for each device to be defined in the ddr.dbase file.
The next two data lines are also required: they define the vendor, product, and revision names that identify the device. Specifies one of the device types defined in the ddr.dbase file: disk tape printer processor worm rodirect cdrom scanner optical changer comm Specifies the SCSI vendor identification string, and optionally, the SCSI product identification string and product version string.
Each SCSI device data section is divided into subsections identified by the following keywords:
Entries in this subsection specify the operational parameters for SCSI devices. The syntax rules are:
The first line in the parameters section must contain the PARAMETERS: keyword.
The lines following the PARAMETERS: keyword contain data lines. Each data line contains a single data element. Data lines can be specified in any order, or omitted. Data lines that are not specified inherit the values of the default device entry for the device type. Specifies a subclass of the device type. Valid only for disks and tapes.
Some devices require mode selects to be sent to a device the first time that it is accessed so that the device can be placed in a known operational state. The CAM subsystem supports up to eight mode selects to be sent to the device.
The MODESELECT: subsection specifies the data for a single mode select. Only the 6-byte mode select command, the mode select header, (optionally) an 8-byte block descriptor, and a single page of data, is supported.
Up to eight mode select subsections can be specified for a device. The order in which the mode selects are sent to the device is based on the value of the ModeSelectNumber field (see below). Mode select number 0 will be sent first, followed by 1, and so on. The mode select number for each Mode Select subsection must be unique, and there must not be any holes (for example, you cannot define mode select numbers 1 and 3 without defining mode select number 2).
Each line in this subsection contains a single element of data.
The first line must contain the MODESELECT: keyword.
The following data lines must be specified, and must precede any optional data lines specified. These data lines may be specified in any order. Specifies the relative position that this mode select is to be issued to the device. Range is 0 to 7. The SP field (Byte 1 Bit 0) of the Mode Select Command. Specifies if the Mode Select data is to be saved by the device. The PF field (Byte 1 Bit 4) of the Mode Select Command. Identifies which Page format specification the mode select conforms to. Specify Yes to send an 8-byte block descriptor. Specify No to prevent an 8-byte block descriptor from being sent. The Parameter List Length field (byte 4) of the Mode Select Command. Specifies the length of mode select data to be transferred, in bytes. This value should include the size of the Mode Parameter Header, Block Descriptor, and the Page Data. Using this value, the subsystem calculates the Page Length entry for the Page data. Range is 0 to 255.
The following data lines are optional. If an entry is not specified, the device data inherits the value of zero for the entry. The data lines can be specified in any order. The Medium Type field (Byte 1) of the Mode Parameter Header. Range is 0 to 255. The Device-Specific Parameter field (Byte 2) of the Mode Parameter Header. This identifier is to be used whenever the device is not a tape or disk. Range is 0 to 255. The Speed field (Byte 2 Bits 0-3) of the Mode Parameter Header. Range is 0 to 15. Use this identifier only with tape devices. The Buffered Mode field (Byte 2 Bits 4-6) of the Mode Parameter Header. Range is 0 to 7. Use this identifier only with tape devices. The Density Code field (Byte 0) of the Block Descriptor. Specify this identifier only when the BlockDescriptor value is Yes. This identifier is accepted if the device type is specified as tape, cdrom, or optical. Range is 0 to 255. Note: for tape devices, the actual strings and values that are accepted are in the GLOBAL section, in the SCSI density code translation table.
The CAM subsystem support for tape devices allows specific densities (including the enabling of compression, and so on), to be selected when accessing the tape. When reading a tape, the device may override the density selected by autoselecting a density based on the media present The densities are selected based on the bits 1-3 of the minor device number for the tape device (/dev) node (bit 0 being the rewind/no-rewind indicator). Thus, eight different densities may be selected.
Currently, device nodes are made for only 4 of the 8 possible density values (0-3), which are reflected in the device node name by the suffixes (low), h (high), m (medium), and a (alternate) respectively.
This subsection specifies the density information that is sent to the device via a mode select (with the Device Configuration Page) in order to set the tape density. The assignment of density to minor bit values done via the DensityNumber field (see below). Up to eight density subsections may be specified for one device.
Each line within this subsection contains a single element of data.
The first data line in the density subsection must contain the DENSITY: keyword.
After the DENSITY: data line, the The following data line must be specified, and must precede any optional data lines Specifies the density bit values in the minor device number that this density subsection corresponds to. The values for this density subsection may apply to multiple minor device numbers by specifying each applicable number in a comma separated list. Range for integer is 0 to 7.
The following data lines are optional. If a data line is not specified, the device data inherits the value of zero for the entry. The data lines can be specified in any order. Specify Yes to write only one file mark when closing the device. Specify no to write two file marks when closing the device. The Speed field (Byte 2 Bits 0-3) of Mode Parameter Header sent to the device. Range is 0 to 15. The Buffered Mode field (Byte 2 Bits 4-6) of the Mode Parameter Header sent to the device. Range is 0 to 7. The Density Code field (Byte 0) of the Block Descriptor sent to the device. Range of integer is 0 to 255. The strings from the global section density table (tape only) are valid here for densitystring. The Number of Blocks field (Bytes 1-3) of the Block Descriptor that is sent to the device. A NULL value (zero) means variable size. Range is 0 to 16777215 (2^24 - 1). The Select Data Compression Algorithm field (Byte 14) of the Page data for Page Code 0x10 (Device Configuration Page). Range is 0 to 255.
The CAM subsystem now allows for device-specific attributes to be specified for a device. These attributes are not used by the CAM subsystem; they are provided as vendor-specific hooks for third party drivers.
This subsection specifies data for a single attribute. Any number of attribute subsections may be specified for a device.
Each line within this subsection contains a single element of data.
The first line of data in the attribute subsection must include the ATTRIBUTE: keyword.
After the ATTRIBUTE: keyword is specified, The following data lines must be specified, and must precede any optional data lines specified. These data lines may be specified in any order. A string specifying the name of the attribute. Strings are case sensitive when enclosed by quotes. Otherwise, strings are converted to lowercase. The length, in bytes, of the attribute data.
The following data lines are optional. If an entry is not specified, the attribute data inherits the value of zero for the entry. The data lines can be specified in any order. Used to set a byte quantity within the attribute data. Range for index is 0 to (<Length> - 1). Range for integer is 0 to 255. Used to set a short quantity within the attribute data. Range for index is 0 to ((<Length> - 1)/2). Range for integer is 0 to 65535. Used to set a int quantity within the attribute data. Range for index is 0 to ((<Length> - 1)/4). Range for integer is 0 to (2^32 - 1). Used to set a long quantity within the attribute data. Range for index is 0 to ((<Length> - 1)/8). Range for integer is 0 to (2^64 - 1). Used to set the contents of the attribute data to the contents of a text string. The length of the string must be no longer than (<Length> - 1). Any attribute data beyond the end of the string will be set to zero. Strings are case sensitive when enclosed in quotes. Otherwise, strings are converted to lowercase. [Note: the string contained in the attribute data will always be null-terminated).
See the /etc/ddr.dbase file for examples of use.
The binary database file of SCSI device definitions
The utility that compiles the /etc/ddr.dbase file into the
SCSI-2, SMALL COMPUTER SYSTEM INTERFACE - 2 (X3.131-1994) delim off