298 lines
8.2 KiB
Groff
298 lines
8.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 October 15, 1998
|
|
.Dt DA 4
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm da
|
|
.Nd SCSI Direct Access Device Driver
|
|
.Sh SYNOPSIS
|
|
.Cd device da
|
|
.Cd device da1 at scbus0 target 4 unit 0
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm da
|
|
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
|
|
.Tn FreeBSD
|
|
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
|
|
.Tn FreeBSD
|
|
slices into areas for individual filesystems 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
|
|
.Tn FreeBSD
|
|
slice spanning the entire disk. Similarly, if an uninitialized
|
|
(or
|
|
.No non- Ns Tn FreeBSD )
|
|
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.
|
|
|
|
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.
|
|
|
|
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 da
|
|
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 da
|
|
device driver will take full advantage of the SCSI feature known as tagged
|
|
queuing. Tagged queuing 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 modifie
|
|
via the
|
|
.Xr camcontrol 8
|
|
utility.
|
|
.Sh KERNEL CONFIGURATION
|
|
It is only necessary to explicitly configure one
|
|
.Nm da
|
|
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
|
|
.Aq Pa 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 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
|
|
.It Pa /dev/rda Ns Ar u
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
accessed as an unpartitioned device
|
|
.Sm off
|
|
.It Pa /dev/da Ar u Pa s Ar n
|
|
.Sm on
|
|
block mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
slice
|
|
.Ar n ,
|
|
accessed as an unpartitioned device
|
|
.Sm off
|
|
.It Pa /dev/rda 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
|
|
block mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
first
|
|
.Tn FreeBSD
|
|
slice, partition
|
|
.Ar p
|
|
.It Pa /dev/rda Ns Ar u Ns Ar p
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
first
|
|
.Tn FreeBSD
|
|
slice, partition
|
|
.Ar p
|
|
.Sm off
|
|
.It Xo
|
|
.Pa /dev/da
|
|
.Ar u
|
|
.Pa s
|
|
.Ar n
|
|
.Ar p
|
|
.Xc
|
|
.Sm on
|
|
block mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
.No Ar n Ns th
|
|
slice, partition
|
|
.Ar p
|
|
.Sm off
|
|
.It Xo
|
|
.Pa /dev/rda
|
|
.Ar u
|
|
.Pa s
|
|
.Ar n
|
|
.Ar p
|
|
.Xc
|
|
.Sm on
|
|
raw mode
|
|
.Tn SCSI
|
|
disk unit
|
|
.Ar u ,
|
|
.No 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 .
|