svn commit: r199532 - head/share/man/man4

[Alexander Motin]

Author: mav
Date: Thu Nov 19 16:19:05 2009
New Revision: 199532
URL: http://svn.freebsd.org/changeset/base/199532

Log:
  Add ada(4) man page.

Added:
  head/share/man/man4/ada.4   (contents, props changed)
Modified:
  head/share/man/man4/Makefile

Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile	Thu Nov 19 15:45:24 2009	(r199531)
+++ head/share/man/man4/Makefile	Thu Nov 19 16:19:05 2009	(r199532)
@@ -15,6 +15,7 @@ MAN=	aac.4 \
 	${_acpi_toshiba.4} \
 	acpi_video.4 \
 	${_acpi_wmi.4} \
+	ada.4 \
 	adv.4 \
 	adw.4 \
 	ae.4 \

Added: head/share/man/man4/ada.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/ada.4	Thu Nov 19 16:19:05 2009	(r199532)
@@ -0,0 +1,138 @@
+.\" Copyright (c) 2009 Alexander Motin <mav at 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 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 at FreeBSD.org .