From 97ffa0bb19eb5bd7acf4ce5ddd44bb0b89cbd463 Mon Sep 17 00:00:00 2001 From: ken Date: Fri, 16 Oct 1998 03:28:12 +0000 Subject: 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 | 187 ++++++++++++++++++++++++++++------------------------ 1 file changed, 100 insertions(+), 87 deletions(-) (limited to 'share') diff --git a/share/man/man4/da.4 b/share/man/man4/da.4 index d13ba61..eac5aa8 100644 --- a/share/man/man4/da.4 +++ b/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 -.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 . -.Pp -Where the -.Xr wd 4 -device has a fairly low level interface to the system, +.Nm da +driver provides support for all .Tn SCSI -devices have a much higher level interface and talk to the system via -a +devices of the direct access class that are attached to the system +through a supported .Tn SCSI -host adapter -(e.g., -.Xr ahc 4 ) . +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 -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. -- cgit v1.1