Update the da(4) man page for CAM. The da.4 man page was repository-copied

from the sd.4 man page.

This includes a discussion of write caching and its effects.

Reviewed by:	ken
Submitted by:	gibbs

share/man/man4/da.4

@@ -23,71 +23,36 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$Id: sd.4,v 1.10 1997/02/22 13:24:42 peter Exp $
+.\"	$Id: sd.4,v 1.11 1997/04/01 04:04:09 jdp Exp $
 .\"
-.Dd January 18, 1996
-.Dt SD 4
+.Dd October 15, 1998
+.Dt DA 4
 .Os FreeBSD
 .Sh NAME
-.Nm sd
-.Nd SCSI disk driver
+.Nm da
+.Nd SCSI Direct Access Device Driver
 .Sh SYNOPSIS
-.Cd disk sd
-.Cd disk sd1 at scbus0 target 4 lun 0
+.Cd device da0
+.Cd device da1 at scbus0 target 4 lun 0
 .Sh DESCRIPTION
 The
-.Nm sd
-driver provides support for a 
+.Nm da
+driver provides support for all
 .Tn SCSI
-disk. It allows the disk
-to be divided up into a set of pseudo devices called
-.Em partitions .
-In general the interfaces are similar to those described by 
-.Xr wd 4 .
+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
-Where the 
-.Xr wd 4
-device has a fairly low level interface to the system, 
-.Tn SCSI
-devices have a much higher level interface and talk to the system via
-a 
-.Tn SCSI
-host adapter
-(e.g.,
-.Xr ahc 4 ) .
 A
 .Tn SCSI
+Host
 adapter must also be separately configured into the system
 before a
 .Tn SCSI
-disk can be configured.
-.Pp
-When the
-.Tn SCSI
-adapter is probed during boot, the 
-.Tn SCSI
-bus is scanned for devices. Any devices found which answer as 
-.Sq Em Direct
-type devices will be attached to the 
-.Nm
-driver.
-In 
-.Tn FreeBSD
-releases prior to 2.1, the first found was attached as
-.Li sd0 ,
-the second
-.Li sd1 ,
-and so on.
-Beginning in
-.Fx 2.1
-it became possible to lock down the assignment of
-devices on the
-.Tn SCSI
-bus to particular units of the
-.Nm
-device; refer to
-.Xr scsi 4
-for details on kernel configuration.
+direct access device can be configured.
 .Sh PARTITIONING
 The 
 .Nm
@@ -108,10 +73,10 @@ For more information, see
 .Xr fdisk 8
 and
 .Xr disklabel 8 ,
-respectively.)
+respectively.
 .Pp
 If an uninitialized disk is opened, the slice table will be
-initialized with a fictitious
+initialized with a ficticious
 .Tn FreeBSD
 slice spanning the entire disk.  Similarly, if an uninitialized
 (or
@@ -120,9 +85,65 @@ 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 equiped 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 transparant
+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 enabeled 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 transaction
+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 imporatant media
+remapping features are 'Auto Write Reallocation' and 'Auto Read
+Reallocation' which can be enabled via the AWRE and ARRE bits,
+respecitvely, 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
+.Nm da
 device; data structures are dynamically allocated as disks are found
 on the
 .Tn SCSI
@@ -139,11 +160,11 @@ disks as well as to other disks.  They are defined in the header file
 .It Dv DIOCSBAD
 Usually used to set up a bad-block mapping system on the disk. 
 .Tn SCSI
-drive incorporate their own bad-block mapping so this command is not
+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
+drive. This may be a ficticious disklabel if the drive has never
 been initialized, in which case it will contain information read
 from the
 .Tn SCSI
@@ -161,36 +182,23 @@ Give the driver a new disklabel to use. The driver
 .Em will
 write the new disklabel to the disk.
 .El
-.Pp
-In addition, the 
-.Xr scsi 4
-general
-.Fn ioctl
-commands may be used with the 
-.Nm
-driver, but only against the 
-.Sq Li c
-(whole disk) partition.
 .Sh NOTES
-If a removable device is attached to the 
-.Nm
-driver, then the act of changing the media will invalidate the
-disklabel and information held within the kernel.  To avoid
-corruption, all accesses to the device will be discarded until there
-are no more open file descriptors referencing the device.  During this
-period, all new open attempts will be rejected.  When no more open
-file descriptors reference the device, the first next open will load a
-new set of parameters (including disklabel) for the drive.
+If device becomes invalidated (media is removed, device becomes unresponsive)
+the disklabel and information held within the kernel about the device will
+be invalided.  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/rsd Ns Ar u
+.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/sd Ar u Pa s Ar n
+.It Pa /dev/da Ar u Pa s Ar n
 .Sm on
 block mode
 .Tn SCSI
@@ -200,7 +208,7 @@ slice
 .Ar n ,
 accessed as an unpartitioned device
 .Sm off
-.It Pa /dev/rsd Ar u Pa s Ar n
+.It Pa /dev/rda Ar u Pa s Ar n
 .Sm on
 raw mode
 .Tn SCSI
@@ -209,7 +217,7 @@ disk unit
 slice
 .ar n ,
 accessed as an unpartitioned device
-.It Pa /dev/sd Ns Ar u Ns Ar p
+.It Pa /dev/da Ns Ar u Ns Ar p
 block mode
 .Tn SCSI
 disk unit
@@ -218,7 +226,7 @@ first
 .Tn FreeBSD
 slice, partition
 .Ar p
-.It Pa /dev/rsd Ns Ar u Ns Ar p
+.It Pa /dev/dad Ns Ar u Ns Ar p
 raw mode
 .Tn SCSI
 disk unit
@@ -229,7 +237,7 @@ slice, partition
 .Ar p
 .Sm off
 .It Xo
-.Pa /dev/sd
+.Pa /dev/da
 .Ar u
 .Pa s
 .Ar n
@@ -245,7 +253,7 @@ slice, partition
 .Ar p
 .Sm off
 .It Xo
-.Pa /dev/rsd
+.Pa /dev/dad
 .Ar u
 .Pa s
 .Ar n
@@ -266,12 +274,17 @@ None.
 .Xr disklabel 5 ,
 .Xr disklabel 8 ,
 .Xr fdisk 8 ,
-.Xr sd 9
+.Xr da 9
 .Sh HISTORY
 The
 .Nm
-driver was originally written for
+driver was written for the
+.Tn CAM
+.Tn SCSI
+subsystem by Justin T. Gibbs.
+Many ideas were gleaned from the
+.Nm sd
+device driver written and ported from
 .Tn Mach
-2.5, and was ported to
-.Tn FreeBSD
+2.5
 by Julian Elischer.  Support for slices was written by Bruce Evans.