WD(4)

NAME
wd - SSM SCSI disk controller

SYNOPSIS
device wd0 at ssm? bin 5 maps 200 target 0 unit 0 device wd1 at ssm? bin 5 maps 200 target 4 unit 0

DESCRIPTION
This device driver controls SCSI disk with embedded targets ("embedded SCSI" disks). It supports up to seven embedded SCSI disks per SSM board.

The lower 3 bits of the minor of the special file refers to partitions 0-7 while the next 8 bits refers to the drive number, the remaining 5 bits complete the partition number. Special files with minor partition numbers 0-15 and unit number 0 refer to partitions a-p on drive ``wd0'' (the first drive listed in the kernel configuration file), where n is the drive number and x is the partition name (a-h).

Block devices access the disk via the system's normal buffering mechanism, and may be read and written without regard to physical disk records. There is also a ``raw'' interface that provides for direct transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation, and therefore raw I/O is considerably more efficient when many words are transmitted. The names of the raw special files conventionally begin with an extra ``r'' — e.g., ``rwd0a''. Raw transfers are limited to a maximum of 256 512-byte sectors. In raw I/O, counts must be a multiple of 512 bytes, and must begin on 16-byte aligned memory addresses. Likewise, lseek calls should specify a multiple of 512 bytes.

BINARY CONFIGURATION
Before attempting to add a new disk or target adapter, read the disk and target adapter manuals thoroughly. The main information needed is how to set the target adapter number and drive-select cabling.

Table of disk units.
The ``wd_bconf'' array in the device driver binary configuration file (/sys/conf/conf_wd.c) must contain an entry for each drive that may be configured; the entries must be in the same order as the ``device'' entries in the kernel configuration file (kernel configuration files are described in the article ``Building DYNIX Systems with Config'' in Volume 2). When adding a new drive, make sure that the corresponding entry in ``wd_bconf'' points to the partition table for the appropriate drive type. (As installed, ``wd_bconf'' has entries for 7 drives, all using the same partition table. Superfluous entries are ignored; you must add more entries if you have more than 7 drives.)

Partition tables.
The binary configuration file contains one or more partition tables, defined as arrays of 8 ``wd_partition'' structures. Each partition table gives the starting address and size (in 512-byte sectors) of the 8 partitions on a particular type of disk. To support a new disk layout, add a new partition table to the binary configuration file, using an existing table as a template.

TUNING PARAMETERS
The following tuning parameters are defined for each drive in the ``wd_bconf'' array of the binary configuration file: (1) The number of IATs (indirect access table entries, used for scatter/gather I/O). The maximum number of IATs ever used is 64, since this will map 128K transfer.

IATs.
An indirect access table is used to map a contiguous I/O buffer in virtual memory to the corresponding pages scattered throughout physical memory. Each table entry (IAT) can map up to 2048 bytes. The number of IATs determines the maximum transfer size for each read/write request.

FILES
/dev/wd?[a-h]    block files
/dev/rwd?[a-h]    raw files
/sys/conf/conf_wd.c    binary configuration file

SEE ALSO
df(1), diskpart(8)

STAND-ALONE EQUIVALENCE
The convention for specifing a SCSI disk from stand-alone code is:
        wd(u,p)
where u refers to the unit number and p refers to the partition number. Each SCSI controller may have 8 unit numbers There may be 8 controllers on a SCSI bus. The assignment of unit number depends on whether the target adapter is embedded or not. The partition is a number 0-256, (partition 256 refers to the whole disk).
Separate target adapter:
	u = SCED board number x 512
		  + SCSI target adapter type x 64
	          + SCSI target number x 8
		  + SCSI unit number
	p = partition number.
Note that type is currently always 0, and the adapter starts at 6 and decreases to 0;
Embedded target adapter:
	u = SCED board number x 512
	          + SCSI target number x 8
	p = partition number.

DIAGNOSTICS

Embedded controller internal recovery and error reporting

    See the ANSI X3T9.2 (SCSI) specification.

Firmware and SCSI bus level errors (reported as HARD errors)

    Command Block Busy
    Bad Command Block
    No Target
    SCSI Bus Error

SCSI target adapter errors

    Recovered Error
    SOFT error message, for information only
    Unit Attention
    Totally ignored
    Medium Error
    Hardware Error
    Illegal Request
    Data Protect
    Blank Check
    Vendor Unique
    Copy Aborted
    Aborted Command
    Equal
    Volume Overflow
    Miscompare
    Unrecognized Completion Code
    Retried four times with soft error messages; fifth error produces Hard Error message

BUGS
In raw I/O, read(2) and write(2) truncate file offsets to 512-byte block boundaries, and lseek(2) should always deal in 512-byte multiples.

A program to analyze the logged error information (even in its present reduced form) is needed.

The partition tables for the file systems should be read from each disk, as they are never quite what any single installation would prefer, and this would make disks more portable.

The kernel ``milliseconds per seek'' statistic is not kept for this device; thus, iostat(1) always reports zero for this statistic.

When a request to the disk accesses past the end of media (for example, a non-existent block number), the device driver will report soft errors followed by a hard error in the same way that a bad block is treated. There is no special handling of the volume overflow sense error code for disks.