share/man/man4/da.4

   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 .\" $FreeBSD$
  27 .\"
  28 .Dd September 2, 2003
  29 .Dt DA 4
  30 .Os
  31 .Sh NAME
  32 .Nm da
  33 .Nd SCSI Direct Access device driver
  34 .Sh SYNOPSIS
  35 .Cd device da
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 driver provides support for all
  40 .Tn SCSI
  41 devices of the direct access class that are attached to the system
  42 through a supported
  43 .Tn SCSI
  44 Host Adapter.
  45 The direct access class includes disk, magneto-optical,
  46 and solid-state devices.
  47 .Pp
  48 A
  49 .Tn SCSI
  50 Host
  51 adapter must also be separately configured into the system
  52 before a
  53 .Tn SCSI
  54 direct access device can be configured.
  55 .Sh PARTITIONING
  56 The
  57 .Nm
  58 driver allows the disk to have two levels of partitioning.
  59 One layer, called the
  60 .Dq slice layer ,
  61 is used to separate the
  62 .Fx
  63 areas of the disk from areas used by other operating systems.
  64 The second layer is the native
  65 .Bx 4.4
  66 partitioning scheme,
  67 .Xr disklabel 5 ,
  68 which is used to subdivide the
  69 .Fx
  70 slices into areas for individual file systems and swap spaces.
  71 For more information, see
  72 .Xr fdisk 8
  73 and
  74 .Xr disklabel 8 ,
  75 respectively.
  76 .Pp
  77 If an uninitialized disk is opened, the slice table will be
  78 initialized with a fictitious
  79 .Fx
  80 slice spanning the entire disk.
  81 Similarly, if an uninitialized
  82 (or
  83 .No non- Ns Fx )
  84 slice is opened, its disklabel will be initialized with parameters returned
  85 by the drive and a single
  86 .Sq Li c
  87 partition encompassing the entire slice.
  88 .Sh CACHE EFFECTS
  89 Many direct access devices are equipped with read and/or write caches.
  90 Parameters affecting the device's cache are stored in mode page 8,
  91 the caching control page.
  92 Mode pages can be examined and modified via the
  93 .Xr camcontrol 8
  94 utility.
  95 .Pp
  96 The read cache is used to store data from device-initiated read ahead
  97 operations as well as frequently used data.
  98 The read cache is transparent
  99 to the user and can be enabled without any adverse effect.
 100 Most devices
 101 with a read cache come from the factory with it enabled.
 102 The read cache can be disabled by setting the
 103 .Tn RCD
 104 (Read Cache Disable) bit in the caching control mode page.
 105 .Pp
 106 The write cache can greatly decrease the latency of write operations
 107 and allows the device to reorganize writes to increase efficiency and
 108 performance.
 109 This performance gain comes at a price.
 110 Should the device
 111 lose power while its cache contains uncommitted write operations, these
 112 writes will be lost.
 113 The effect of a loss of write transactions on
 114 a file system is non-deterministic and can cause corruption.
 115 Most
 116 devices age write transactions to limit vulnerability to a few transactions
 117 recently reported as complete, but it is none-the-less recommended that
 118 systems with write cache enabled devices reside on an Uninterruptible
 119 Power Supply (UPS).
 120 The
 121 .Nm
 122 device driver ensures that the cache and media are synchronized upon
 123 final close of the device or an unexpected shutdown (panic) event.
 124 This ensures that it is safe to disconnect power once the operating system
 125 has reported that it has halted.
 126 The write cache can be enabled by setting the
 127 .Tn WCE
 128 (Write Cache Enable) bit in the caching control mode page.
 129 .Sh TAGGED QUEUING
 130 The
 131 .Nm
 132 device driver will take full advantage of the SCSI feature known as tagged
 133 queueing.
 134 Tagged queueing allows the device to process multiple transactions
 135 concurrently, often re-ordering them to reduce the number and length of
 136 seeks.
 137 To ensure that transactions to distant portions of the media,
 138 which may be deferred indefinitely by servicing requests nearer the current
 139 head position, are completed in a timely fashion, an ordered tagged
 140 transaction is sent every 15 seconds during continuous device operation.
 141 .Sh BAD BLOCK RECOVERY
 142 Direct Access devices have the capability of mapping out portions of
 143 defective media.
 144 Media recovery parameters are located in mode page 1,
 145 the Read-Write Error Recovery mode page.
 146 The most important media
 147 remapping features are 'Auto Write Reallocation' and 'Auto Read
 148 Reallocation' which can be enabled via the AWRE and ARRE bits,
 149 respectively, of the Read-Write Error Recovery page.
 150 Many devices do not ship from the factory with these feature enabled.
 151 Mode pages can be examined and modified
 152 via the
 153 .Xr camcontrol 8
 154 utility.
 155 .Sh KERNEL CONFIGURATION
 156 It is only necessary to explicitly configure one
 157 .Nm
 158 device; data structures are dynamically allocated as disks are found
 159 on the
 160 .Tn SCSI
 161 bus.
 162 .Sh IOCTLS
 163 The following
 164 .Xr ioctl 2
 165 calls apply to
 166 .Tn SCSI
 167 disks as well as to other disks.
 168 They are defined in the header file
 169 .In sys/disklabel.h .
 170 .Pp
 171 .Bl -tag -width DIOCSDINFO
 172 .It Dv DIOCSBAD
 173 Usually used to set up a bad-block mapping system on the disk.
 174 .Tn SCSI
 175 drives incorporate their own bad-block mapping so this command is not
 176 implemented.
 177 .It Dv DIOCGDINFO
 178 Read, from the kernel, the in-core copy of the disklabel for the
 179 drive.
 180 This may be a fictitious disklabel if the drive has never
 181 been initialized, in which case it will contain information read
 182 from the
 183 .Tn SCSI
 184 inquiry commands.
 185 .It Dv DIOCSDINFO
 186 Give the driver a new disklabel to use.
 187 The driver
 188 .Em will not
 189 write the new
 190 disklabel to the disk.
 191 .It Dv DIOCWLABEL
 192 Enable or disable the driver's software
 193 write protect of the disklabel on the disk.
 194 .It Dv DIOCWDINFO
 195 Give the driver a new disklabel to use.
 196 The driver
 197 .Em will
 198 write the new disklabel to the disk.
 199 .El
 200 .Sh SYSCTL VARIABLES
 201 The following variables are available as both
 202 .Xr sysctl 8
 203 variables and
 204 .Xr loader 8
 205 tunables:
 206 .Bl -tag -width 12
 207 .It kern.cam.da.retry_count
 208 .Pp
 209 This variable determines how many times the
 210 .Nm
 211 driver will retry a READ or WRITE command.
 212 This does not affect the number of retries used during probe time or for
 213 the
 214 .Nm
 215 driver dump routine.
 216 This value currently defaults to 4.
 217 .It kern.cam.da.default_timeout
 218 .Pp
 219 This variable determines how long the
 220 .Nm
 221 driver will wait before timing out an outstanding command.
 222 The units for this value are seconds, and the default is currently 60
 223 seconds.
 224 .It kern.cam.da.%d.minimum_cmd_size
 225 .Pp
 226 This variable determines what the minimum READ/WRITE CDB size is for a
 227 given
 228 .Nm
 229 unit.
 230 (The %d above denotes the unit number of the
 231 .Nm
 232 driver instance, e.g.\& 1, 2, 4, 8, etc.)
 233 Valid minimum command size values are 6, 10, 12 and 16 bytes.
 234 The default is 6 bytes.
 235 .Pp
 236 The
 237 .Nm
 238 driver issues a CAM Path Inquiry CCB at probe time to determine whether the
 239 protocol the device in question speaks (e.g.\& ATAPI) typically does not allow
 240 6 byte commands.
 241 If it does not, the
 242 .Nm
 243 driver will default to using at least 10 byte CDBs.
 244 If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the
 245 .Nm
 246 driver will then increase the default CDB size for the device to 10 bytes and
 247 retry the command.
 248 CDB size is always
 249 chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum
 250 command size, and the LBA and length of the READ or WRITE in question.
 251 (e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.)
 252 .El
 253 .Sh NOTES
 254 If a device becomes invalidated (media is removed, device becomes unresponsive)
 255 the disklabel and information held within the kernel about the device will
 256 be invalidated.
 257 To avoid corruption of a newly inserted piece of media or
 258 a replacement device, all accesses to the device will be discarded until
 259 the last file descriptor referencing the old device is closed.
 260 During this period, all new open attempts will be rejected.
 261 .Sh FILES
 262 .Bl -tag -width /dev/rsdXXXXX -compact
 263 .Sm off
 264 .It Pa /dev/da Ar u Pa s Ar n
 265 .Sm on
 266 raw mode
 267 .Tn SCSI
 268 disk unit
 269 .Ar u ,
 270 slice
 271 .Ar n ,
 272 accessed as an unpartitioned device
 273 .It Pa /dev/da Ns Ar u Ns Ar p
 274 raw mode
 275 .Tn SCSI
 276 disk unit
 277 .Ar u ,
 278 first
 279 .Fx
 280 slice, partition
 281 .Ar p
 282 .Sm off
 283 .It Xo
 284 .Pa /dev/da
 285 .Ar u
 286 .Pa s
 287 .Ar n
 288 .Ar p
 289 .Xc
 290 .Sm on
 291 raw mode
 292 .Tn SCSI
 293 disk unit
 294 .Ar u ,
 295 .Ar n Ns th
 296 slice, partition
 297 .Ar p
 298 .El
 299 .Sh DIAGNOSTICS
 300 None.
 301 .Sh SEE ALSO
 302 .Xr ad 4 ,
 303 .Xr disklabel 5 ,
 304 .Xr disklabel 8 ,
 305 .Xr fdisk 8
 306 .Sh HISTORY
 307 The
 308 .Nm
 309 driver was written for the
 310 .Tn CAM
 311 .Tn SCSI
 312 subsystem by
 313 .An Justin T. Gibbs .
 314 Many ideas were gleaned from the
 315 .Nm sd
 316 device driver written and ported from
 317 .Tn Mach
 318 2.5
 319 by
 320 .An Julian Elischer .
 321 Support for slices was written by
 322 .An Bruce Evans .