1 .\" Copyright (c) 2009 Alexander Motin <mav@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd ATA Direct Access device driver
39 driver provides support for direct access devices, implementing the
41 command protocol, that are attached to the system through a host adapter
42 supported by the CAM subsystem.
44 The host adapter must also be separately configured into the system before an
46 direct access device can be configured.
48 Command queueing allows the device to process multiple transactions
49 concurrently, often re-ordering them to reduce the number and length of
52 defines two types of queueing:
53 .Tn TCQ (Tagged Command Queueing, PATA legacy)
55 .Tn NCQ (Native Command Queueing, SATA) .
58 device driver takes full advantage of NCQ, when supported.
59 To ensure that transactions to distant parts of the media,
60 which may be deferred indefinitely by servicing requests closer to the current
61 head position, are completed in a timely fashion, an ordered
62 transaction is sent every 7 seconds during continuous device operation.
64 Many direct access devices are equipped with read and/or write caches.
65 Parameters affecting the device's cache are reported in device IDENTIFY data
66 and can be examined and modified via the
70 The read cache is used to store data from device-initiated read ahead
71 operations as well as frequently used data.
72 The read cache is transparent
73 to the user and can be enabled without any adverse effect.
75 with a read cache come from the factory with it enabled.
77 The write cache can greatly decrease the latency of write operations
78 and allows the device to reorganize writes to increase efficiency and
80 This performance gain comes at a price.
82 lose power while its cache contains uncommitted write operations, these
84 The effect of a loss of write transactions on
85 a file system is non-deterministic and can cause corruption.
87 devices age write transactions to limit the vulnerability to a few transactions
88 recently reported as complete, but it is nonetheless recommended that
89 systems with write cache enabled devices reside on an Uninterruptible
93 device driver ensures that the cache and media are synchronized upon
94 final close of the device or an unexpected shutdown (panic) event.
95 This ensures that it is safe to disconnect power once the operating system
96 has reported that it has halted.
98 The following variables are available as both
104 .It Va kern.cam.ada.retry_count
106 This variable determines how many times the
108 driver will retry a READ or WRITE command.
109 This does not affect the number of retries used during probe time or for
113 This value currently defaults to 4.
114 .It Va kern.cam.ada.default_timeout
116 This variable determines how long the
118 driver will wait before timing out an outstanding command.
119 The units for this value are seconds, and the default is currently 30
121 .It Va kern.cam.ada.spindown_shutdown
123 This variable determines whether to spin-down disks when shutting down.
124 Set to 1 to enable spin-down, 0 to disable.
125 The default is currently enabled.
126 .It Va kern.cam.sort_io_queue
127 .It Va kern.cam.ada. Ns Ar X Ns Va .sort_io_queue
129 These variables determine whether request queue should be sorted trying
130 to optimize head seeks.
131 Set to 1 to enable sorting, 0 to disable, -1 to leave it as-is.
132 The default is sorting enabled for HDDs and disabled SSDs.
133 .It Va kern.cam.ada.read_ahead
134 .It Va kern.cam.ada. Ns Ar X Ns Va .read_ahead
135 .It Va kern.cam.ada.write_cache
136 .It Va kern.cam.ada. Ns Ar X Ns Va .write_cache
138 These variables determine whether device read-ahead and write caches
139 should be enabled globally or per-device or disabled.
140 Set to 1 to enable write cache, 0 to disable, -1 to leave it as-is.
141 Values modified at runtime take effect only after device reset
142 .Pq using the reset subcommand of Xr camcontrol 8 .
143 Because of that, this setting should be changed in
144 .Pa /boot/loader.conf
146 .Pa /etc/sysctl.conf .
147 The global default is currently 1.
148 The per-device default is to leave it as-is (follow global setting).
151 .Bl -tag -width ".Pa /dev/ada*" -compact
164 driver first appeared in
167 .An Alexander Motin Aq mav@FreeBSD.org