323 lines
9.2 KiB
Groff
323 lines
9.2 KiB
Groff
.\" Copyright (c) 1996
|
|
.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 2, 2003
|
|
.Dt DA 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm da
|
|
.Nd SCSI Direct Access device driver
|
|
.Sh SYNOPSIS
|
|
.Cd device da
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for all
|
|
.Tn SCSI
|
|
devices of the direct access class that are attached to the system
|
|
through a supported
|
|
.Tn SCSI
|
|
Host Adapter.
|
|
The direct access class includes disk, magneto-optical,
|
|
and solid-state devices.
|
|
.Pp
|
|
A
|
|
.Tn SCSI
|
|
Host
|
|
adapter must also be separately configured into the system
|
|
before a
|
|
.Tn SCSI
|
|
direct access device can be configured.
|
|
.Sh PARTITIONING
|
|
The
|
|
.Nm
|
|
driver allows the disk to have two levels of partitioning.
|
|
One layer, called the
|
|
.Dq slice layer ,
|
|
is used to separate the
|
|
.Fx
|
|
areas of the disk from areas used by other operating systems.
|
|
The second layer is the native
|
|
.Bx 4.4
|
|
partitioning scheme,
|
|
.Xr disklabel 5 ,
|
|
which is used to subdivide the
|
|
.Fx
|
|
slices into areas for individual file systems and swap spaces.
|
|
For more information, see
|
|
.Xr fdisk 8
|
|
and
|
|
.Xr disklabel 8 ,
|
|
respectively.
|
|
.Pp
|
|
If an uninitialized disk is opened, the slice table will be
|
|
initialized with a fictitious
|
|
.Fx
|
|
slice spanning the entire disk.
|
|
Similarly, if an uninitialized
|
|
(or
|
|
.No non- Ns Fx )
|
|
slice is opened, its disklabel will be initialized with parameters returned
|
|
by the drive and a single
|
|
.Sq Li c
|
|
partition encompassing the entire slice.
|
|
.Sh CACHE EFFECTS
|
|
Many direct access devices are equipped with read and/or write caches.
|
|
Parameters affecting the device's cache are stored in mode page 8,
|
|
the caching control page.
|
|
Mode pages can be examined and modified via the
|
|
.Xr camcontrol 8
|
|
utility.
|
|
.Pp
|
|
The read cache is used to store data from device-initiated read ahead
|
|
operations as well as frequently used data.
|
|
The read cache is transparent
|
|
to the user and can be enabled without any adverse effect.
|
|
Most devices
|
|
with a read cache come from the factory with it enabled.
|
|
The read cache can be disabled by setting the
|
|
.Tn RCD
|
|
(Read Cache Disable) bit in the caching control mode page.
|
|
.Pp
|
|
The write cache can greatly decrease the latency of write operations
|
|
and allows the device to reorganize writes to increase efficiency and
|
|
performance.
|
|
This performance gain comes at a price.
|
|
Should the device
|
|
lose power while its cache contains uncommitted write operations, these
|
|
writes will be lost.
|
|
The effect of a loss of write transactions on
|
|
a file system is non-deterministic and can cause corruption.
|
|
Most
|
|
devices age write transactions to limit vulnerability to a few transactions
|
|
recently reported as complete, but it is none-the-less recommended that
|
|
systems with write cache enabled devices reside on an Uninterruptible
|
|
Power Supply (UPS).
|
|
The
|
|
.Nm
|
|
device driver ensures that the cache and media are synchronized upon
|
|
final close of the device or an unexpected shutdown (panic) event.
|
|
This ensures that it is safe to disconnect power once the operating system
|
|
has reported that it has halted.
|
|
The write cache can be enabled by setting the
|
|
.Tn WCE
|
|
(Write Cache Enable) bit in the caching control mode page.
|
|
.Sh TAGGED QUEUING
|
|
The
|
|
.Nm
|
|
device driver will take full advantage of the SCSI feature known as tagged
|
|
queueing.
|
|
Tagged queueing allows the device to process multiple transactions
|
|
concurrently, often re-ordering them to reduce the number and length of
|
|
seeks.
|
|
To ensure that transactions to distant portions of the media,
|
|
which may be deferred indefinitely by servicing requests nearer the current
|
|
head position, are completed in a timely fashion, an ordered tagged
|
|
transaction is sent every 15 seconds during continuous device operation.
|
|
.Sh BAD BLOCK RECOVERY
|
|
Direct Access devices have the capability of mapping out portions of
|
|
defective media.
|
|
Media recovery parameters are located in mode page 1,
|
|
the Read-Write Error Recovery mode page.
|
|
The most important media
|
|
remapping features are 'Auto Write Reallocation' and 'Auto Read
|
|
Reallocation' which can be enabled via the AWRE and ARRE bits,
|
|
respectively, of the Read-Write Error Recovery page.
|
|
Many devices do not ship from the factory with these feature enabled.
|
|
Mode pages can be examined and modified
|
|
via the
|
|
.Xr camcontrol 8
|
|
utility.
|
|
.Sh KERNEL CONFIGURATION
|
|
It is only necessary to explicitly configure one
|
|
.Nm
|
|
device; data structures are dynamically allocated as disks are found
|
|
on the
|
|
.Tn SCSI
|
|
bus.
|
|
.Sh IOCTLS
|
|
The following
|
|
.Xr ioctl 2
|
|
calls apply to
|
|
.Tn SCSI
|
|
disks as well as to other disks.
|
|
They are defined in the header file
|
|
.In sys/disklabel.h .
|
|
.Pp
|
|
.Bl -tag -width DIOCSDINFO
|
|
.It Dv DIOCSBAD
|
|
Usually used to set up a bad-block mapping system on the disk.
|
|
.Tn SCSI
|
|
drives incorporate their own bad-block mapping so this command is not
|
|
implemented.
|
|
.It Dv DIOCGDINFO
|
|
Read, from the kernel, the in-core copy of the disklabel for the
|
|
drive.
|
|
This may be a fictitious disklabel if the drive has never
|
|
been initialized, in which case it will contain information read
|
|
from the
|
|
.Tn SCSI
|
|
inquiry commands.
|
|
.It Dv DIOCSDINFO
|
|
Give the driver a new disklabel to use.
|
|
The driver
|
|
.Em will not
|
|
write the new
|
|
disklabel to the disk.
|
|
.It Dv DIOCWLABEL
|
|
Enable or disable the driver's software
|
|
write protect of the disklabel on the disk.
|
|
.It Dv DIOCWDINFO
|
|
Give the driver a new disklabel to use.
|
|
The driver
|
|
.Em will
|
|
write the new disklabel to the disk.
|
|
.El
|
|
.Sh SYSCTL VARIABLES
|
|
The following variables are available as both
|
|
.Xr sysctl 8
|
|
variables and
|
|
.Xr loader 8
|
|
tunables:
|
|
.Bl -tag -width 12
|
|
.It kern.cam.da.retry_count
|
|
.Pp
|
|
This variable determines how many times the
|
|
.Nm
|
|
driver will retry a READ or WRITE command.
|
|
This does not affect the number of retries used during probe time or for
|
|
the
|
|
.Nm
|
|
driver dump routine.
|
|
This value currently defaults to 4.
|
|
.It kern.cam.da.default_timeout
|
|
.Pp
|
|
This variable determines how long the
|
|
.Nm
|
|
driver will wait before timing out an outstanding command.
|
|
The units for this value are seconds, and the default is currently 60
|
|
seconds.
|
|
.It kern.cam.da.%d.minimum_cmd_size
|
|
.Pp
|
|
This variable determines what the minimum READ/WRITE CDB size is for a
|
|
given
|
|
.Nm
|
|
unit.
|
|
(The %d above denotes the unit number of the
|
|
.Nm
|
|
driver instance, e.g.\& 1, 2, 4, 8, etc.)
|
|
Valid minimum command size values are 6, 10, 12 and 16 bytes.
|
|
The default is 6 bytes.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver issues a CAM Path Inquiry CCB at probe time to determine whether the
|
|
protocol the device in question speaks (e.g.\& ATAPI) typically doesn't allow
|
|
6 byte commands.
|
|
If it doesn't, the
|
|
.Nm
|
|
driver will default to using at least 10 byte CDBs.
|
|
If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the
|
|
.Nm
|
|
driver will then increase the default CDB size for the device to 10 bytes and
|
|
retry the command.
|
|
CDB size is always
|
|
chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum
|
|
command size, and the LBA and length of the READ or WRITE in question.
|
|
(e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.)
|
|
.El
|
|
.Sh NOTES
|
|
If a device becomes invalidated (media is removed, device becomes unresponsive)
|
|
the disklabel and information held within the kernel about the device will
|
|
be invalidated.
|
|
To avoid corruption of a newly inserted piece of media or
|
|
a replacement device, all accesses to the device will be discarded until
|
|
the last file descriptor referencing the old device is closed.
|
|
During this period, all new open attempts will be rejected.
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/rsdXXXXX -compact
|
|
.Sm off
|
|
.It Pa /dev/da Ar u Pa s Ar n
|
|
.Sm on
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
slice
|
|
.Ar n ,
|
|
accessed as an unpartitioned device
|
|
.It Pa /dev/da Ns Ar u Ns Ar p
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
first
|
|
.Fx
|
|
slice, partition
|
|
.Ar p
|
|
.Sm off
|
|
.It Xo
|
|
.Pa /dev/da
|
|
.Ar u
|
|
.Pa s
|
|
.Ar n
|
|
.Ar p
|
|
.Xc
|
|
.Sm on
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
.Ar n Ns th
|
|
slice, partition
|
|
.Ar p
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
None.
|
|
.Sh SEE ALSO
|
|
.Xr ad 4 ,
|
|
.Xr disklabel 5 ,
|
|
.Xr disklabel 8 ,
|
|
.Xr fdisk 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver was written for the
|
|
.Tn CAM
|
|
.Tn SCSI
|
|
subsystem by
|
|
.An Justin T. Gibbs .
|
|
Many ideas were gleaned from the
|
|
.Nm sd
|
|
device driver written and ported from
|
|
.Tn Mach
|
|
2.5
|
|
by
|
|
.An Julian Elischer .
|
|
Support for slices was written by
|
|
.An Bruce Evans .
|