1.\" Copyright (c) 1996 2.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd September 10, 2022 27.Dt DA 4 28.Os 29.Sh NAME 30.Nm da 31.Nd SCSI Direct Access device driver 32.Sh SYNOPSIS 33.Cd device da 34.Sh DESCRIPTION 35The 36.Nm 37driver provides support for all 38.Tn SCSI 39devices of the direct access class that are attached to the system 40through a supported 41.Tn SCSI 42Host Adapter. 43The direct access class includes disk, magneto-optical, 44and solid-state devices. 45.Pp 46A 47.Tn SCSI 48Host 49adapter must also be separately configured into the system 50before a 51.Tn SCSI 52direct access device can be configured. 53.Sh CACHE EFFECTS 54Many direct access devices are equipped with read and/or write caches. 55Parameters affecting the device's cache are stored in mode page 8, 56the caching control page. 57Mode pages can be examined and modified via the 58.Xr camcontrol 8 59utility. 60.Pp 61The read cache is used to store data from device-initiated read ahead 62operations as well as frequently used data. 63The read cache is transparent 64to the user and can be enabled without any adverse effect. 65Most devices 66with a read cache come from the factory with it enabled. 67The read cache can be disabled by setting the 68.Tn RCD 69(Read Cache Disable) bit in the caching control mode page. 70.Pp 71The write cache can greatly decrease the latency of write operations 72and allows the device to reorganize writes to increase efficiency and 73performance. 74This performance gain comes at a price. 75Should the device 76lose power while its cache contains uncommitted write operations, these 77writes will be lost. 78The effect of a loss of write transactions on 79a file system is non-deterministic and can cause corruption. 80Most 81devices age write transactions to limit vulnerability to a few transactions 82recently reported as complete, but it is none-the-less recommended that 83systems with write cache enabled devices reside on an Uninterruptible 84Power Supply (UPS). 85The 86.Nm 87device driver ensures that the cache and media are synchronized upon 88final close of the device or an unexpected shutdown (panic) event. 89This ensures that it is safe to disconnect power once the operating system 90has reported that it has halted. 91The write cache can be enabled by setting the 92.Tn WCE 93(Write Cache Enable) bit in the caching control mode page. 94.Sh TAGGED QUEUING 95The 96.Nm 97device driver will take full advantage of the SCSI feature known as tagged 98queueing. 99Tagged queueing allows the device to process multiple transactions 100concurrently, often re-ordering them to reduce the number and length of 101seeks. 102To ensure that transactions to distant portions of the media, 103which may be deferred indefinitely by servicing requests nearer the current 104head position, are completed in a timely fashion, an ordered tagged 105transaction is sent every 15 seconds during continuous device operation. 106.Sh BAD BLOCK RECOVERY 107Direct Access devices have the capability of mapping out portions of 108defective media. 109Media recovery parameters are located in mode page 1, 110the Read-Write Error Recovery mode page. 111The most important media 112remapping features are 'Auto Write Reallocation' and 'Auto Read 113Reallocation' which can be enabled via the AWRE and ARRE bits, 114respectively, of the Read-Write Error Recovery page. 115Many devices do not ship from the factory with these feature enabled. 116Mode pages can be examined and modified 117via the 118.Xr camcontrol 8 119utility. 120.Sh KERNEL CONFIGURATION 121It is only necessary to explicitly configure one 122.Nm 123device; data structures are dynamically allocated as disks are found 124on the 125.Tn SCSI 126bus. 127.Sh SYSCTL VARIABLES 128The following variables are available as both 129.Xr sysctl 8 130variables and 131.Xr loader 8 132tunables: 133.Bl -tag -width 12 134.It Va kern.cam.da.default_timeout 135This variable determines how long the 136.Nm 137driver will wait before timing out an outstanding command. 138The units for this value are seconds, and the default is currently 60 139seconds. 140.It Va kern.cam.da.disable_wp_protection 141Disable detection of write-protected disks. 142Default is disabled. 143.Po 144detection of write-protected disks is enabled 145.Pc . 146.It Va kern.cam.da.enable_biospeedup 147Enable 148.Dv BIO_SPEEDUP 149processing. 150Default is enabled. 151.It Va kern.cam.da.enable_uma_ccbs 152Use UMA for CCBs. 153Default is enabled. 154.It Va kern.cam.da.poll_period 155Media polling period in seconds. 156Default is 3 seconds. 157.It Va kern.cam.da.retry_count 158This variable determines how many times the 159.Nm 160driver will retry a READ or WRITE command. 161This does not affect the number of retries used during probe time or for 162the 163.Nm 164driver dump routine. 165This value currently defaults to 4. 166.It Va kern.cam.da.send_ordered 167Send Ordered Tags. 168On shutdown, step through all the 169.Nm 170peripheral drivers, and if the device is still open, 171sync the disk to physical media. 172Default is enabled. 173.It Va kern.cam.sort_io_queue 174.It Va kern.cam.da . Ns Ar X Ns Va .sort_io_queue 175These variables determine whether request queue should be sorted trying 176to optimize head seeks. 177Set to 1 to enable sorting, 0 to disable, -1 to leave it as-is. 178The default is sorting enabled for HDDs and disabled for SSDs. 179.It Va kern.cam.da . Ns Ar X Ns Va .delete_method 180This variable specifies method to handle BIO_DELETE requests: 181.Bl -tag -width "ATA_TRIM" 182.It ATA_TRIM 183ATA TRIM via ATA COMMAND PASS THROUGH command, 184.It UNMAP 185UNMAP command, 186.It WS16 187WRITE SAME(16) command with UNMAP flag, 188.It WS10 189WRITE SAME(10) command with UNMAP flag, 190.It ZERO 191WRITE SAME(10) command without UNMAP flag, 192.It DISABLE 193disable BIO_DELETE support. 194.El 195.It Va kern.cam.da . Ns Ar X Ns Va .minimum_cmd_size 196This variable determines what the minimum READ/WRITE CDB size is for a 197given 198.Nm 199unit. 200Valid minimum command size values are 6, 10, 12 and 16 bytes. 201The default is 6 bytes. 202.Pp 203The 204.Nm 205driver issues a CAM Path Inquiry CCB at probe time to determine whether the 206protocol the device in question speaks (e.g.\& ATAPI) typically does not allow 2076 byte commands. 208If it does not, the 209.Nm 210driver will default to using at least 10 byte CDBs. 211If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the 212.Nm 213driver will then increase the default CDB size for the device to 10 bytes and 214retry the command. 215CDB size is always 216chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum 217command size, and the LBA and length of the READ or WRITE in question. 218(e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.) 219.El 220.Sh NOTES 221If a device becomes invalidated (media is removed, device becomes unresponsive) 222the disklabel and information held within the kernel about the device will 223be invalidated. 224To avoid corruption of a newly inserted piece of media or 225a replacement device, all accesses to the device will be discarded until 226the last file descriptor referencing the old device is closed. 227During this period, all new open attempts will be rejected. 228.Sh FILES 229.Bl -tag -width ".Pa /dev/da*" -compact 230.It Pa /dev/da* 231SCSI disk device nodes 232.El 233.Sh DIAGNOSTICS 234None. 235.Sh SEE ALSO 236.Xr ada 4 , 237.Xr cam 4 , 238.Xr geom 4 , 239.Xr nda 4 , 240.Xr gpart 8 241.Sh HISTORY 242The 243.Nm 244driver was written for the 245.Tn CAM 246.Tn SCSI 247subsystem by 248.An Justin T. Gibbs . 249Many ideas were gleaned from the 250.Nm sd 251device driver written and ported from 252.Tn Mach 2532.5 254by 255.An Julian Elischer . 256