/share/man/man4/da.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 217 lines · 217 code · 0 blank · 0 comment · 6 complexity · 0b1274198189209754665dd1e64a6886 MD5 · raw file
- .\" 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 February 8, 2012
- .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 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 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 does not allow
- 6 byte commands.
- If it does not, 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 ".Pa /dev/da*" -compact
- .It Pa /dev/da*
- SCSI disk device nodes
- .El
- .Sh DIAGNOSTICS
- None.
- .Sh SEE ALSO
- .Xr ada 4 ,
- .Xr cam 4 ,
- .Xr geom 4 ,
- .Xr bsdlabel 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 .