'\" te
.\" Copyright (c) 2009 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER,
.\" with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SD 4D "September 12, 2020"
.SH NAME
sd \- SCSI disk and ATAPI/SCSI CD-ROM device driver
.SH SYNOPSIS
.nf
\fBsd@target,lun:partition\fR
.fi

.SH DESCRIPTION
To open a device without checking if the vtoc is valid, use the O_NDELAY flag.
When the device is opened using O_NDELAY, the first read or write to the device
that happens after the open results in the label being read if the label is not
currently valid. Once read, the label remains valid until the last close of the
device. Except for reading the label, O_NDELAY has no impact on the driver.
.SS "SPARC"
The \fBsd\fR \fBSCSI\fR and \fBSCSI/ATAPI\fR driver supports embedded
\fBSCSI\fR-2 and \fBCCS\fR-compatible \fBSCSI\fR disk and CD-ROM drives,
\fBATAPI \fR 2.6 (SFF-8020i)-compliant CD-ROM drives, SFF-8090-compliant
\fBSCSI/ATAPI\fR DVD-ROM drives, IOMEGA \fBSCSI/ATAPI\fR ZIP drives, \fBSCSI
JAZ\fR drives, and USB mass storage devices (refer to \fBscsa2usb\fR(4D)).
.sp
.LP
To determine the disk drive type, use the \fBSCSI/ATAPI\fR inquiry command and
read the volume label stored on block 0 of the drive. (The volume label
describes the disk geometry and partitioning and must be present for the disk
to be mounted by the system.) A volume label is not required for removable,
re-writable or read-only media.
.SS "x86 Only"
The \fBsd\fR driver supports embedded \fBSCSI\fR-2 and \fBCCS\fR-compatible
\fBSCSI \fRdisk and CD-ROM drives, \fBATAPI \fR2.6 (SFF-8020i)-compliant CD-ROM
drives, SFF-8090-compliant \fBSCSI/ATAPI\fR DVD-ROM drives, IOMEGA
\fBSCSI/ATAPI\fR ZIP drives\fB, and SCSI JAZ\fR drives.
.sp
.LP
The x86 BIOS legacy requires a master boot record (MBR) and \fBfdisk\fR table
in the first physical sector of the bootable media. If the x86 hard disk
contains a Solaris disk label, it is located in the second 512-byte sector of
the FDISK partition.
.SH DEVICE SPECIAL FILES
Block-files access the disk using normal buffering mechanism and are read-from
and written-to without regard to physical disk records. A \fBraw\fR interface
enables direct transmission between the disk and the user's read or write
buffer. A single \fBread\fR or \fBwrite\fR call usually results in a single I/O
operation, therefore raw I/O is more efficient when many bytes are transmitted.
Block files names are found in \fB/dev/dsk\fR; raw file names are found in
\fB/dev/rdsk\fR.
.sp
.LP
I/O requests to the raw device must be aligned on a 512-byte (\fBDEV_BSIZE\fR)
boundary and all I/O request lengths must be in multiples of 512 bytes.
Requests that do not meet these requirements will trigger an \fBEINVAL\fR
error. There are no alignment or length restrictions on I/O requests to the
block device.
.SH CD-ROM DRIVE SUPPORT
A CD-ROM disk is single-sided and contains approximately 640 megabytes of data
or 74 minutes of audio. When the CD-ROM is opened, the eject button is disabled
to prevent manual removal of the disk until the last \fBclose()\fR is called.
No volume label is required for a CD-ROM. The disk geometry and partitioning
information are constant and never change. If the CD-ROM contains data recorded
in a Solaris-aware file system format, it can be mounted using the appropriate
Solaris file system support.
.SH DVD-ROM DRIVE SUPPORT
DVD-ROM media can be single or double-sided and can be recorded upon using a
single or double layer structure. Double-layer media provides parallel or
opposite track paths. A DVD-ROM can hold from between 4.5 Gbytes and 17 Gbytes
of data, depending on the layer structure used for recording and if the DVD-ROM
is single or double-sided.
.sp
.LP
When the DVD-ROM is opened, the eject button is disabled to prevent the manual
removal of a disk until the last \fBclose()\fR is called. No volume label is
required for a DVD-ROM. If the DVD-ROM contains data recorded in a
Solaris-aware file system format, it can be mounted using the appropriate
Solaris file system support.
.SH ZIP/JAZ DRIVE SUPPORT
\fBZIP/JAZ\fR media provide varied data capacity points; a single \fBJAZ
\fRdrive can store up to 2 GBytes of data, while a ZIP-250 can store up to
250MBytes of data. \fBZIP/JAZ\fR drives can be read-from or written-to using
the appropriate drive.
.sp
.LP
When a \fBZIP/JAZ\fR drive is opened, the eject button is disabled to prevent
the manual removal of a disk until the last \fBclose()\fR is called. No volume
label is required for a \fBZIP/JAZ\fR drive. If the \fBZIP/JAZ\fR drive
contains data recorded in a Solaris-aware file system format, it can be mounted
using the appropriate Solaris file system support.
.SH DEVICE STATISTICS SUPPORT
Each device maintains I/O statistics for the device and for partitions
allocated for that device. For each device/partition, the driver accumulates
reads, writes, bytes read, and bytes written. The driver also initiates
hi-resolution time stamps at queue entry and exit points to enable monitoring
of residence time and cumulative residence-length product for each queue.
.sp
.LP
Not all device drivers make per-partition IO statistics available for
reporting. \fBsd\fR and \fBssd\fR(4D) per-partition statistics are enabled by
default but may be disabled in their configuration files.
.SH IOCTLS
Refer to \fBdkio\fR(4I), and \fBcdio\fR(4I)
.SS "ERRORS"
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
Permission denied
.RE

.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
The partition was opened exclusively by another thread
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The argument features a bad address
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
Invalid argument
.RE

.sp
.ne 2
.na
\fB\fBENOTTY\fR\fR
.ad
.RS 10n
The device does not support the requested ioctl function
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
During opening, the device did not exist. During close, the drive unlock failed
.RE

.sp
.ne 2
.na
\fB\fBEROFS\fR\fR
.ad
.RS 10n
The device is read-only
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
Resource temporarily unavailable
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
A signal was caught during the execution of the \fBioctl()\fR function
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Insufficient memory
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 10n
Insufficient access permission
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
An I/O error occurred. Refer to notes for details on copy-protected DVD-ROM
media.
.RE

.SH CONFIGURATION
The \fBsd\fR driver can be configured by defining properties in the
\fBsd.conf\fR file. The \fBsd\fR driver supports the following properties:
.sp
.ne 2
.na
\fB\fBenable-partition-kstats\fR\fR
.ad
.RS 27n
The default value is 1, which causes partition IO statistics to be maintained.
Set this value to zero to prevent the driver from recording partition
statistics. This slightly reduces the CPU overhead for IO, minimizes the amount
of \fBsar\fR(1) data collected and makes these statistics unavailable for
reporting by \fBiostat\fR(8) even though the \fB-p\fR/\fB-P\fR option is
specified. Regardless of this setting, disk IO statistics are always
maintained.
.RE

.sp
.ne 2
.na
\fB\fBqfull-retries\fR\fR
.ad
.RS 27n
The supplied value is passed as the \fBqfull-retries\fR capability value of the
HBA driver. See \fBscsi_ifsetcap\fR(9F) for details.
.RE

.sp
.ne 2
.na
\fB\fBqfull-retry-interval\fR\fR
.ad
.RS 27n
The supplied value is passed as the \fBqfull-retry interval\fR capability value
of the HBA driver. See \fBscsi_ifsetcap\fR(9F) for details.
.RE

.sp
.ne 2
.na
\fB\fBallow-bus-device-reset\fR\fR
.ad
.RS 27n
The default value is 1, which allows resetting to occur. Set this value to
\fB0\fR (zero) to prevent the \fBsd\fR driver from calling \fBscsi_reset\fR(9F)
with a second argument of \fBRESET_TARGET\fR when in error-recovery mode. This
\fBscsi_reset\fR(9F) call may prompt the HBA driver to send a SCSI Bus Device
Reset message. The \fBscsi_reset\fR(9F) call with a second argument of
\fBRESET_TARGET\fR may result from an explicit request via the \fBUSCSICMD\fR
\fBioctl\fR. Some high-availability multi-initiator systems may wish to
prohibit the Bus Device Reset message; to do this, set the
\fBallow-bus-device-reset\fR property to \fB0\fR.
.RE

.sp
.ne 2
.na
\fBoptical-device-bind\fR
.ad
.RS 27n
Controls the binding of the driver to non self-identifying SCSI target optical
devices. (See \fBscsi\fR(5)). The default value is 1, which causes \fBsd\fR to
bind to DTYPE_OPTICAL devices (as noted in \fBscsi\fR(5)).  Setting this value
to 0 prevents automatic binding. The default behavior for the SPARC-based
\fBsd\fR driver prior to Solaris 9 was not to bind to optical devices.
.RE

.sp
.ne 2
.na
\fB\fBpower-condition\fR\fR
.ad
.RS 27n
Boolean type, when set to \fBFalse\fR, it indicates that the disk does not
support \fBpower condition\fR field in the \fBSTART STOP UNIT\fR command.
.RE

.sp
.LP
In addition to the above properties, some device-specific tunables can be
configured in \fBsd.conf\fR using the \fBsd-config-list\fR global property. The
value of this property is a list of duplets. The formal syntax is:
.sp
.in +2
.nf
sd-config-list = <duplet> [, <duplet> ]* ;

where

<duplet>:= "<vid+pid>" , "<tunable-list>"

and

<tunable-list>:= <tunable>  [, <tunable> ]*;
<tunable> = <name> : <value>

The <vid+pid> is the string that is returned by the target device
on a SCSI inquiry command.

The <tunable-list> contains one or more tunables to apply to
all target devices with the specified <vid+pid>.

Each <tunable> is a <name> : <value> pair. Supported
tunable names are:

   delay-busy: when busy, nsecs of delay before retry.

   retries-timeout: retries to perform on an IO timeout.
.fi
.in -2

.sp
.ne 2
.na
\fB\fBmmc-gesn-polling\fR\fR
.ad
.RS 20n
For optical drives compliant with \fBMMC-3\fR and supporting the \fBGET EVENT
STATUS NOTIFICATION\fR command, this command is used for periodic media state
polling, usually initiated by the \fBDKIOCSTATE\fR \fBdkio\fR(4I) ioctl. To
disable the use of this command, set this boolean property to \fBfalse\fR. In
that case, either the \fBTEST UNIT READY\fR or zero-length \fBWRITE(10)\fR
command is used instead.
.RE

.SH EXAMPLES
.in +2
.nf
The following is an example of a global sd-config-list property:

   sd-config-list =
      "SUN     T4", "delay-busy:600, retries-timeout:6",
      "SUN     StorEdge_3510", "retries-timeout:3";
.fi
.in -2

.SH FILES
.ne 2
.na
\fB\fB/kernel/drv/sd.conf\fR\fR
.ad
.RS 23n
Driver configuration file
.RE

.sp
.ne 2
.na
\fB\fB/dev/dsk/cntndnsn\fR\fR
.ad
.RS 23n
Block files
.RE

.sp
.ne 2
.na
\fB\fB/dev/rdsk/cntndnsn\fR\fR
.ad
.RS 23n
Raw files
.RE

.sp
.LP
Where:
.sp
.ne 2
.na
\fBcn\fR
.ad
.RS 6n
controller n
.RE

.sp
.ne 2
.na
\fBtn\fR
.ad
.RS 6n
SCSI target id n (0-6)
.RE

.sp
.ne 2
.na
\fBdn\fR
.ad
.RS 6n
SCSI LUN n (0-7 normally; some HBAs support LUNs to 15 or 32. See the specific
manpage for details)
.RE

.sp
.ne 2
.na
\fBsn\fR
.ad
.RS 6n
partition n (0-7)
.RE

.SS "x86 Only"
.ne 2
.na
\fB\fB/dev/rdsk/cntndnpn\fR\fR
.ad
.RS 22n
raw files
.RE

.sp
.LP
Where:
.sp
.ne 2
.na
\fBpn\fR
.ad
.RS 6n
Where \fIn\fR=0 the node corresponds to the entire disk.
.RE

.SH SEE ALSO
.BR sar (1),
.BR close (2),
.BR ioctl (2),
.BR lseek (2),
.BR read (2),
.BR write (2),
.BR scsa2usb (4D),
.BR ssd (4D),
.BR hsfs (4FS),
.BR pcfs (4FS),
.BR udfs (4FS),
.BR cdio (4I),
.BR dkio (4I),
.BR driver.conf (5),
.BR scsi (5),
.BR filesystem (7),
.BR cfgadm_scsi (8),
.BR fdisk (8),
.BR format (8),
.BR iostat (8),
.BR scsi_ifsetcap (9F),
.BR scsi_reset (9F)
.sp
.LP
\fIANSI Small Computer System Interface-2 (SCSI-2)\fR
.sp
.LP
\fIATA Packet Interface for CD-ROMs, SFF-8020i\fR
.sp
.LP
\fIMt.Fuji Commands for CD and DVD, SFF8090v3\fR
.SH DIAGNOSTICS
.in +2
.nf
Error for Command:\fI<command name>\fR
Error Level: Fatal
Requested Block: \fI<n>\fR
Error  Block: \fI<m>\fR
Vendor:'\fI<vendorname>\fR\&'
Serial Number:'\fI<serial number>\fR\&'
Sense Key:\fI<sense key name>\fR
.fi
.in -2
.sp

.sp
.ne 2
.na
\fBASC: 0x<a> (<ASC name>), ASCQ: 0x<b>, FRU: 0x<c>\fR
.ad
.sp .6
.RS 4n
The command indicated by <command name> failed. The Requested Block is the
block where the transfer started and the Error Block is the block that caused
the error. Sense Key, \fBASC\fR, and \fBASCQ\fR information is returned by the
target in response to a request sense command.
.RE

.sp
.ne 2
.na
\fBCaddy not inserted in drive\fR
.ad
.sp .6
.RS 4n
The drive is not ready because no caddy has been inserted.
.RE

.sp
.ne 2
.na
\fBCheck Condition on REQUEST SENSE\fR
.ad
.sp .6
.RS 4n
A REQUEST SENSE command completed with a check condition. The original command
will be retried a number of times.
.RE

.sp
.ne 2
.na
\fBLabel says <m> blocks Drive says <n> blocks\fR
.ad
.sp .6
.RS 4n
There is a discrepancy between the label and what the drive returned on the
\fBREAD CAPACITY\fR command.
.RE

.sp
.ne 2
.na
\fBNot enough sense information\fR
.ad
.sp .6
.RS 4n
The request sense data was less than expected.
.RE

.sp
.ne 2
.na
\fBRequest Sense couldn't get sense data\fR
.ad
.sp .6
.RS 4n
The \fBREQUEST SENSE\fR command did not transfer any data.
.RE

.sp
.ne 2
.na
\fBReservation Conflict\fR
.ad
.sp .6
.RS 4n
The drive was reserved by another initiator.
.RE

.sp
.ne 2
.na
\fBSCSI transport failed: reason \fB\&'xxxx'\fR: {retrying|giving up}\fR
.ad
.sp .6
.RS 4n
The host adapter has failed to transport a command to the target for the reason
stated. The driver will either retry the command or, ultimately, give up.
.RE

.sp
.ne 2
.na
\fBUnhandled Sense Key<\fIn\fR>\fR
.ad
.sp .6
.RS 4n
The REQUEST SENSE data included an invalid sense.
.RE

.sp
.ne 2
.na
\fBUnit not ready. Additional sense code 0x\fR
.ad
.sp .6
.RS 4n
\fI<n>\fR The drive is not ready.
.RE

.sp
.ne 2
.na
\fBCan't do switch back to mode 1\fR
.ad
.sp .6
.RS 4n
A failure to switch back to read mode 1.
.RE

.sp
.ne 2
.na
\fBCorrupt label - bad geometry\fR
.ad
.sp .6
.RS 4n
The disk label is corrupted.
.RE

.sp
.ne 2
.na
\fBCorrupt label - label checksum failed\fR
.ad
.sp .6
.RS 4n
The disk label is corrupted.
.RE

.sp
.ne 2
.na
\fBCorrupt label - wrong magic number\fR
.ad
.sp .6
.RS 4n
The disk label is corrupted.
.RE

.sp
.ne 2
.na
\fBDevice busy too long\fR
.ad
.sp .6
.RS 4n
The drive returned busy during a number of retries.
.RE

.sp
.ne 2
.na
\fBDisk not responding to selection\fR
.ad
.sp .6
.RS 4n
The drive is powered down or died
.RE

.sp
.ne 2
.na
\fBFailed to handle UA\fR
.ad
.sp .6
.RS 4n
A retry on a Unit Attention condition failed.
.RE

.sp
.ne 2
.na
\fBI/O to invalid geometry\fR
.ad
.sp .6
.RS 4n
The geometry of the drive could not be established.
.RE

.sp
.ne 2
.na
\fBIncomplete read/write - retrying/giving up\fR
.ad
.sp .6
.RS 4n
There was a residue after the command completed normally.
.RE

.sp
.ne 2
.na
\fBNo bp for direct access device format geometry\fR
.ad
.sp .6
.RS 4n
A bp with consistent memory could not be allocated.
.RE

.sp
.ne 2
.na
\fBNo bp for disk label\fR
.ad
.sp .6
.RS 4n
A bp with consistent memory could not be allocated.
.RE

.sp
.ne 2
.na
\fBNo bp for fdisk\fR
.ad
.sp .6
.RS 4n
A bp with consistent memory could not be allocated.
.RE

.sp
.ne 2
.na
\fBNo bp for rigid disk geometry\fR
.ad
.sp .6
.RS 4n
A bp with consistent memory could not be allocated.
.RE

.sp
.ne 2
.na
\fBNo mem for property\fR
.ad
.sp .6
.RS 4n
Free memory pool exhausted.
.RE

.sp
.ne 2
.na
\fBNo memory for direct access device format geometry\fR
.ad
.sp .6
.RS 4n
Free memory pool exhausted.
.RE

.sp
.ne 2
.na
\fBNo memory for disk label\fR
.ad
.sp .6
.RS 4n
Free memory pool exhausted.
.RE

.sp
.ne 2
.na
\fBNo memory for rigid disk geometry\fR
.ad
.sp .6
.RS 4n
The disk label is corrupted.
.RE

.sp
.ne 2
.na
\fBNo resources for dumping\fR
.ad
.sp .6
.RS 4n
A packet could not be allocated during dumping.
.RE

.sp
.ne 2
.na
\fBOffline\fR
.ad
.sp .6
.RS 4n
Drive went offline; probably powered down.
.RE

.sp
.ne 2
.na
\fBRequeue of command fails\fR
.ad
.sp .6
.RS 4n
Driver attempted to retry a command and experienced a transport error.
.RE

.sp
.ne 2
.na
\fBsdrestart transport failed()\fR
.ad
.sp .6
.RS 4n
Driver attempted to retry a command and experienced a transport error.
.RE

.sp
.ne 2
.na
\fBTransfer length not modulo\fR
.ad
.sp .6
.RS 4n
Illegal request size.
.RE

.sp
.ne 2
.na
\fBTransport of request sense fails()\fR
.ad
.sp .6
.RS 4n
Driver attempted to submit a request sense command and failed.
.RE

.sp
.ne 2
.na
\fBTransport rejected()\fR
.ad
.sp .6
.RS 4n
Host adapter driver was unable to accept a command.
.RE

.sp
.ne 2
.na
\fBUnable to read label\fR
.ad
.sp .6
.RS 4n
Failure to read disk label.
.RE

.sp
.ne 2
.na
\fBUnit does not respond to selection\fR
.ad
.sp .6
.RS 4n
Drive went offline; probably powered down.
.RE

.SH NOTES
DVD-ROM media containing DVD-Video data may follow/adhere to the requirements
of content scrambling system or copy protection scheme. Reading of
copy-protected sector will cause I/O error. Users are advised to use the
appropriate playback software to view video contents on DVD-ROM media
containing DVD-Video data.