scsi(HW)

scsi -- small computer systems interface

Description

The Small Computer System Interface (SCSI) is a specification of a standard interface to peripherals such as hard disks, CD-ROMs, and tape drives connected via the SCSI bus. The specification also includes the command set to control the interface. From the point of view of the host computer SCSI provides device independent access to data; the SCSI interface handles the details of how the data is physically stored on peripheral devices.

The SCO OpenServer modular SCSI interface provides a number of standard device drivers for SCSI peripheral devices -- CD-ROM, tape, floptical, disk, and media changer devices (juke boxes) -- and for SCSI host adapter cards. The interface establishes a clearly defined protocol between the peripheral driver tier and the host adapter driver tier.

This description is primarily based on the SCSI-1 standard. Later SCSI standards maintain backward compatibility with SCSI-1 while allowing for increased data transfer rates, wider data buses, extended command sets, and a larger number of supported peripherals.

SCO OpenServer Release 5.0.6 supports SCSI-1, 2 and 3 tape devices.

Basic SCSI operation

The SCSI-1 bus is an 8-bit parallel I/O data bus with 9 control lines. Data transfer rates of up to 5 megabytes per second are possible using a synchronous handshaking protocol. The single-ended bus configuration allows a cable length of up to 6 meters; the differential configuration allows up to 25 meters.

A SCSI host adapter controller provides the interface between the host computer bus and the SCSI bus. It mediates requests from the host computer to access peripheral devices; it sends these in the form of Command Descriptor Blocks (CDBs). The host adapter also passes back data and status messages received from the peripherals. Several host adapters may be present on the same host computer; each adapter is identified by its host adapter number.

Usually, the host adapter acts as an initiator; it requests that a target controller perform an operation. While an initiator and target are communicating, the bus is unavailable to any other device.

A target can temporarily disconnect from an initiator if the operation will take some time (for example, rewinding a tape or moving a disk head). This allows the initiator to connect to a different target. When the first target has completed its task, it tries to reselect the initiator. As soon as the host adapter is free to respond, it arbitrates between the controllers that are requesting service from it. The adapter selects the controller with the highest priority as its new target.

Up to eight controllers can be connected to a SCSI 8-bit wide data bus, and up to sixteen controllers can be connected to a 16-bit bus. Each controller is assigned an ID number in the range 0-7 on an 8-bit data bus, or 0-15 on a 16-bit bus. The ID number is also referred to as a SCSI ID, target ID, or controller number. One of the controllers must be the host adapter which is usually assigned ID 7.

There are two types of controller other than host adapter controllers:

Bridge controllers can handle up to eight peripheral devices. These devices are addressed by their logical unit number or LUN in the range 0-7.
Embedded controllers within a single peripheral device; their LUN is usually 0, though they may choose to ignore any attempt to select a different LUN that is specified within a CDB.

SCSI addresses

A SCSI peripheral device is uniquely identified by its SCSI address:

the host adapter number of the SCSI host adapter to which the device is connected
the number of the bus (for host adapters that support more than one SCSI bus); the primary bus is bus 0, the secondary bus is bus 1, and so on
the controller ID on the bus
the device LUN

SCSI device drivers

The following peripheral device drivers are supported:

Driver name Device supported

Sdsk hard disk

Sflp floppy drive

Srom CD-ROM

Stp tape

Sjk media changer device (juke box)

Supported SCSI host adapter drivers are listed in the file /etc/default/scsihas.

Driver name	Device supported
Sdsk	hard disk
Sflp	floppy drive
Srom	CD-ROM
Stp	tape
Sjk	media changer device (juke box)

Configuration of SCSI host adapters and peripherals

SCSI host adapters are configured using entries in mdevice and /etc/conf/sdevice.d/xnamex (see the sdevice(F) manual page).

Any SCSI peripheral that you wish to access must be configured by an entry in the mscsi(F) file; the mkdev(ADM) options cdrom, flopti, hd,, tape and juke provide a means of doing this automatically for each host adapter.

Changes to mscsi, mdevice, and /etc/conf/sdevice.d/xnamex will only take effect if the kernel is relinked using link_unix(ADM) and the machine rebooted.

Boot time configuration of SCSI

The adapter= bootstring allows you to override the default kernel configuration for a given host adapter. Similarly, the periph= bootstring enables you to select a different boot device from the default (see boot(HW)).

Minor device numbering scheme

The minor device numbering scheme for SCSI hard disk drives is the same as the standard minor device number scheme for non-SCSI disk devices (see hd(HW)).

The minor device numbering scheme for SCSI tape drives is described on scsitape(HW).

The minor device numbering scheme for SCSI CD-ROM drives is described on cdrom(HW).

The minor device numbering scheme for SCSI floptical drives is described on Sflp(HW).

The minor device numbering scheme for SCSI juke boxes is described on jukebox(HW).

The SCSIUSERCMD ioctl request

The ioctl(S) request, SCSIUSERCMD, is used to pass any SCSI command to a target device; examples are mode sense, mode select, and block reallocation requests. The ioctl argument arg points to the scsicmd structure that holds the Command Descriptor Block for the request.

SCSIUSERCMD and the scsicmd structure are defined in <sys/scsicmd.h> as follows:

   #define SCSIUSERCMD     (('D'<<8)|64)   /* compare ioctl list in dio.h  */
   #define SCSICMDLEN      12
   
   struct scsicmd {
           faddr_t data_ptr;       /* pointer to user data read or written */
           ulong   data_len;       /* length of user data at data_ptr or 0 */
           ushort  is_write;       /* data i/o direction: 0 read, 1 write  */
           uchar_t cdb[SCSICMDLEN];/* command description block (0 padded) */
           uchar_t host_sts;       /* to be returned upon completion       */
           uchar_t target_sts;     /* to be returned upon completion       */
           uchar_t cdb_len;        /* used for vendor specific commands */
   };

SCSIUSERCMD requires that an effective user ID of 0 (zero) be set on the user process calling ioctl.

SCSIUSERCMD2 is a superset of SCSIUSERCMD; it also allows the user to retrieve sense information. SCSIUSERCMD2 is defined in <sys/scsicmd.h> as follows:

   #define SCSIUSERCMD2    (('D'<<8)|65)   /* New SCSIUSERCMD + sense      */
   
   struct scsicmd2 {
           struct scsicmd  cmd;    /* User-supplied SCSI command (see above) */
           int     sense_len;      /* Length of allocated data for sense info*/
           void    *sense_ptr;     /* Buffer for sense info (user provided)  */
   };

Note that the user must check for zero in the host_sts and target_sts fields for successful completion of the ioctl.

Diagnostics

The following error messages may be displayed on the console. See messages(M) for general information about kernel error messages, including a list of generic device driver errors. See also manual pages for individual SCSI drivers, such as: alad(HW), dptr(HW), eiad(HW), hf(HW), slha(HW), smad(HW), sumo(HW), tmcha(HW), and wdha(HW).

aha -- Adaptec AHA-1X40 SCSI host adapter driver

These messages may be produced if either the Adaptec AHA-1540 or AHA-1640 host adapter is installed.

WARNING: aha: Adapter m detected SCSI reset, status=0xn, intr=0xvector

An unexpected host adapter reset was detected.

WARNING: aha: Adapter m unexpected MBI status 0xn
AHA-1X40   cmd : o
AHA-1X40 sense : p

The incoming mailbox is in an unexpected state after an interrupt.

WARNING: aha: Port 0xm failed to go idle, status=0xn, cmd=0xo

Register m on the host adapter indicated that a command had still not been completed after R_LIMIT cycles in a spin loop.

WARNING: aha: Port 0xm internal failure 0xn

The host adapter failed to be recognized on initialization.

SCSI -- Small Computer Systems Interface driver

CONFIG: No Stype SCSI devices configured (unit n missing)

No configuration information existed for a given SCSI device.

CONFIG: Only m Stype SCSI devices configured (unit n missing)

No configuration information existed for a given SCSI device.

NOTICE: Stype: Error
on [reading|writing] SCSI device_type
[ dev major/minor ]
(ha=host_adapter id=controller lun=logical_unit)
[ block=block_number ]
NOTICE: Stype: sensemsg
NOTICE: Status: host=host_status target=target_status,
: Key: key code qualifier

The output sensemsg is one of the following sense error messages:

Command aborted: Command sent before previous one was completed Command aborted: Drive detected a SCSI parity error Command aborted: Drive received an 'initiator detected' error Command aborted: Drive received an illegal message Command aborted: Host sent abort message Command aborted: Message phase unexpected Command aborted: Phase sequence unexpected Command aborted: SCSI selection/reselection error occurred Command aborted: Unexpected command phase Command aborted: Unexpected data phase -possible DMA error

Copy aborted: Due to error on the source or destination device Copy aborted: Host cannot disconnect

Drive not ready: Being loaded Drive not ready: No media present Drive not ready: Offline

Error rate warning

Hardware error: Failure during write operation Hardware error: Media load/eject failed Hardware error: Moisture detected Hardware error: Track-following Hardware error: Unexpected internal error

Humidity warning

Illegal request: Invalid bits in identify message Illegal request: Invalid command Illegal request: Invalid field in CDB Illegal request: Invalid parameter list Illegal request: Logical unit not supported Illegal request: Parameter length error Illegal request: Parameter page not supported

Medium error: Append error during write Medium error: Blank tape - use tape erase command Medium error: EOP/M encountered Medium error: Incompatible medium installed Medium error: Positioning error detected Medium error: RAW retry limit exceeded Medium error: Unrecovered read error

Unit attention: Drive failed power-on self test Unit attention: Drive or bus reset Unit attention: Log parameters may have changed Unit attention: Mode parameters may have changed Unit attention: Possible media change - you may need to repeat command

Write error: Media is write protected

NOTICE: Status: host=n target=n,
: Key: unknown

The SCSI sense block was found to be empty.

WARNING: SCSI boot option(s) ignored : Invalid host adapter parameters
WARNING: SCSI boot option(s) ignored : Invalid id and/or lun
WARNING: SCSI boot option(s) ignored : Unknown host adapter driver
WARNING: SCSI boot option(s) ignored : Unknown peripheral driver

These errors are reported at I/O initialization when they are read from the SCSI bootstrings.

PANIC: Unacceptable value for Sha_last_registered (n), in Sharegister

Could not register a host adapter as a bootable device.

Warning

You should be familiar with the SCSI-1 standard and, if necessary, the SCSI-2 standard, before attempting to program the SCSI interface.

Files

/usr/include/sys/scsi.h
/usr/include/sys/scsicmd.h
/usr/include/sys/scsisup.h: SCSI interface header files

Standards conformance

The scsi interface is conformant with:

Draft proposed ANSI standard X3.131-198X, Small Computer System Interface -- 2 (SCSI-II), 1990.