From d41fb84baba059951c9f40f13c8b2d006fe14adf Mon Sep 17 00:00:00 2001 From: mav Date: Thu, 19 Nov 2009 16:19:05 +0000 Subject: Add ada(4) man page. --- share/man/man4/ada.4 | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 share/man/man4/ada.4 (limited to 'share/man/man4/ada.4') diff --git a/share/man/man4/ada.4 b/share/man/man4/ada.4 new file mode 100644 index 0000000..8d2cf0e --- /dev/null +++ b/share/man/man4/ada.4 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2009 Alexander Motin +.\" 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 November 19, 2009 +.Dt ADA 4 +.Os +.Sh NAME +.Nm ada +.Nd ATA Direct Access device driver +.Sh SYNOPSIS +.Cd device ada +.Sh DESCRIPTION +The +.Nm +driver provides support for direct access devices, implementing +.Tn ATA +command protocol, that are attached to the system through a host adapter +supported by CAM subsystem. +.Pp +Host adapter must also be separately configured into the system before a +.Tn ATA +direct access device can be configured. +.Sh COMMAND QUEUING +Command queueing allows the device to process multiple transactions +concurrently, often re-ordering them to reduce the number and length of +seeks. +.Tn ATA +defines two types of queueing: +.Tn TCQ (Tagged Command Queueing, PATA legacy) +and +.Tn NCQ (Native Command Queueing, SATA). +The +.Nm +device driver takes full advantage of the NCQ, when supported. +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 +transaction is sent every 7 seconds during continuous device operation. +.Sh CACHE EFFECTS +Many direct access devices are equipped with read and/or write caches. +Parameters affecting the device's cache are reported in device IDENTIFY data +and 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. +.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. +.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.ada.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.ada.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 30 +seconds. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/ada*" -compact +.It Pa /dev/ada* +ATA device nodes +.El +.Sh SEE ALSO +.Xr ahci 4 , +.Xr siis 4 , +.Xr ad 4 +.Xr da 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An Alexander Motin Aq mav@FreeBSD.org . -- cgit v1.1