share/man/man4/scsi.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 .Dd June 7, 2012
  28 .Dt CAM 4
  29 .Os
  30 .Sh NAME
  31 .Nm CAM
  32 .Nd Common Access Method SCSI/ATA subsystem
  33 .Sh SYNOPSIS
  34 .Cd "device scbus"
  35 .Cd "device ada"
  36 .Cd "device cd"
  37 .Cd "device ch"
  38 .Cd "device da"
  39 .Cd "device pass"
  40 .Cd "device pt"
  41 .Cd "device sa"
  42 .Cd "options CAMDEBUG"
  43 .Cd "options CAM_DEBUG_BUS=-1"
  44 .Cd "options CAM_DEBUG_TARGET=-1"
  45 .Cd "options CAM_DEBUG_LUN=-1"
  46 .Cd "options CAM_DEBUG_COMPILE=CAM_DEBUG_INFO|CAM_DEBUG_CDB|CAM_DEBUG_PROBE"
  47 .Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB"
  48 .Cd "options CAM_MAX_HIGHPOWER=4"
  49 .Cd "options SCSI_NO_SENSE_STRINGS"
  50 .Cd "options SCSI_NO_OP_STRINGS"
  51 .Cd "options SCSI_DELAY=8000"
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 subsystem provides a uniform and modular system for the implementation
  56 of drivers to control various
  57 .Tn SCSI
  58 and
  59 .Tn ATA
  60 devices, and to utilize different
  61 .Tn SCSI
  62 and
  63 .Tn ATA
  64 host adapters through host adapter drivers.
  65 When the system probes busses, it attaches any devices it finds to the
  66 appropriate drivers.
  67 The
  68 .Xr pass 4
  69 driver, if it is configured in the kernel, will attach to all devices.
  70 .Sh KERNEL CONFIGURATION
  71 There are a number of generic kernel configuration options for the
  72 .Nm
  73 subsystem:
  74 .Bl -tag -width SCSI_NO_SENSE_STRINGS
  75 .It Dv CAMDEBUG
  76 This option compiles in all the
  77 .Nm
  78 debugging printf code.
  79 This will not actually
  80 cause any debugging information to be printed out when included by itself.
  81 See below for details.
  82 .It Dv "CAM_MAX_HIGHPOWER=4"
  83 This sets the maximum allowable number of concurrent "high power" commands.
  84 A "high power" command is a command that takes more electrical power than
  85 most to complete.
  86 An example of this is the
  87 .Tn SCSI
  88 START UNIT command.
  89 Starting a disk often takes significantly more electrical power than normal
  90 operation.
  91 This option allows the
  92 user to specify how many concurrent high power commands may be outstanding
  93 without overloading the power supply on his computer.
  94 .It Dv SCSI_NO_SENSE_STRINGS
  95 This eliminates text descriptions of each
  96 .Tn SCSI
  97 Additional Sense Code and Additional Sense Code Qualifier pair.
  98 Since this
  99 is a fairly large text database, eliminating it reduces the size of the
 100 kernel somewhat.
 101 This is primarily necessary for boot floppies and other
 102 low disk space or low memory space environments.
 103 In most cases, though,
 104 this should be enabled, since it speeds the interpretation of
 105 .Tn SCSI
 106 error messages.
 107 Do not let the "kernel bloat" zealots get to you -- leave
 108 the sense descriptions in your kernel!
 109 .It Dv SCSI_NO_OP_STRINGS
 110 This disables text descriptions of each
 111 .Tn SCSI
 112 opcode.
 113 This option, like the sense string option above, is primarily
 114 useful for environments like a boot floppy where kernel size is critical.
 115 Enabling this option for normal use is not recommended, since it slows
 116 debugging of
 117 .Tn SCSI
 118 problems.
 119 .It Dv SCSI_DELAY=8000
 120 This is the
 121 .Tn SCSI
 122 "bus settle delay."
 123 In
 124 .Nm ,
 125 it is specified in
 126 .Em milliseconds ,
 127 not seconds like the old
 128 .Tn SCSI
 129 layer used to do.
 130 When the kernel boots, it sends a bus reset to each
 131 .Tn SCSI
 132 bus to tell each device to reset itself to a default set of transfer
 133 negotiations and other settings.
 134 Most
 135 .Tn SCSI
 136 devices need some amount of time to recover from a bus reset.
 137 Newer disks
 138 may need as little as 100ms, while old, slow devices may need much longer.
 139 If the
 140 .Dv SCSI_DELAY
 141 is not specified, it defaults to 2 seconds.
 142 The minimum allowable value for
 143 .Dv SCSI_DELAY
 144 is "100", or 100ms.
 145 One special case is that if the
 146 .Dv SCSI_DELAY
 147 is set to 0, that will be taken to mean the "lowest possible value."
 148 In that case, the
 149 .Dv SCSI_DELAY
 150 will be reset to 100ms.
 151 .El
 152 .Pp
 153 All devices and busses support dynamic allocation so that
 154 an upper number of devices and controllers does not need to be configured;
 155 .Cd "device da"
 156 will suffice for any number of disk drivers.
 157 .Pp
 158 The devices are either
 159 .Em wired
 160 so they appear as a particular device unit or
 161 .Em counted
 162 so that they appear as the next available unused unit.
 163 .Pp
 164 Units are wired down by setting kernel environment hints.
 165 This is usually done either interactively from the
 166 .Xr loader 8 ,
 167 or automatically via the
 168 .Pa /boot/device.hints
 169 file.
 170 The basic syntax is:
 171 .Bd -literal -offset indent
 172 hint.device.unit.property="value"
 173 .Ed
 174 .Pp
 175 Individual
 176 .Nm
 177 bus numbers can be wired down to specific controllers with
 178 a config line similar to the following:
 179 .Bd -literal -offset indent
 180 hint.scbus.0.at="ahd1"
 181 .Ed
 182 .Pp
 183 This assigns
 184 .Nm
 185 bus number 0 to the
 186 .Em ahd1
 187 driver instance.
 188 For controllers supporting more than one bus, a particular bus can be assigned
 189 as follows:
 190 .Bd -literal -offset indent
 191 hint.scbus.0.at="ahc1"
 192 hint.scbus.0.bus="1"
 193 .Ed
 194 .Pp
 195 This assigns
 196 .Nm
 197 bus 0 to the bus 1 instance on
 198 .Em ahc0 .
 199 Peripheral drivers can be wired to a specific bus, target, and lun as so:
 200 .Bd -literal -offset indent
 201 hint.da.0.at="scbus0"
 202 hint.da.0.target="0"
 203 hint.da.0.unit="0"
 204 .Ed
 205 .Pp
 206 This assigns
 207 .Em da0
 208 to target 0, unit (lun) 0 of scbus 0.
 209 Omitting the target or unit hints will instruct
 210 .Nm
 211 to treat them as wildcards
 212 and use the first respective counted instances.
 213 These examples can be combined together to allow a peripheral device to be
 214 wired to any particular controller, bus, target, and/or unit instance.
 215 .Pp
 216 When you have a mixture of wired down and counted devices then the
 217 counting begins with the first non-wired down unit for a particular
 218 type.
 219 That is, if you have a disk wired down as
 220 .Em "device da1" ,
 221 then the first non-wired disk shall come on line as
 222 .Em da2 .
 223 .Sh ADAPTERS
 224 The system allows common device drivers to work through many different
 225 types of adapters.
 226 The adapters take requests from the upper layers and do
 227 all IO between the
 228 .Tn SCSI
 229 or
 230 .Tn ATA
 231 bus and the system.
 232 The maximum size of a transfer is governed by the
 233 adapter.
 234 Most adapters can transfer 64KB in a single operation, however
 235 many can transfer larger amounts.
 236 .Sh TARGET MODE
 237 Some adapters support
 238 .Em target mode
 239 in which the system is capable of operating as a device, responding to
 240 operations initiated by another system.
 241 Target mode is supported for
 242 some adapters, but is not yet complete for this version of the
 243 .Nm
 244 .Tn SCSI
 245 subsystem.
 246 .Sh FILES
 247 see other
 248 .Nm
 249 device entries.
 250 .Sh DIAGNOSTICS
 251 An XPT_DEBUG CCB can be used to enable various amounts of tracing information
 252 on any specific bus/device from the list of options compiled into the kernel.
 253 There are currently seven debugging flags that may be compiled in and used:
 254 .Bl -tag -width CAM_DEBUG_SUBTRACE
 255 .It Dv CAM_DEBUG_INFO
 256 This flag enables general informational printfs for the device
 257 or devices in question.
 258 .It Dv CAM_DEBUG_TRACE
 259 This flag enables function-level command flow tracing.
 260 i.e.\&
 261 kernel printfs will happen at the entrance and exit of various functions.
 262 .It Dv CAM_DEBUG_SUBTRACE
 263 This flag enables debugging output internal to various functions.
 264 .It Dv CAM_DEBUG_CDB
 265 This flag will cause the kernel to print out all
 266 .Tn ATA
 267 and
 268 .Tn SCSI
 269 commands sent to a particular device or devices.
 270 .It Dv CAM_DEBUG_XPT
 271 This flag will enable command scheduler tracing.
 272 .It Dv CAM_DEBUG_PERIPH
 273 This flag will enable peripheral drivers messages.
 274 .It Dv CAM_DEBUG_PROBE
 275 This flag will enable devices probe process tracing.
 276 .El
 277 .Pp
 278 Some of these flags, most notably
 279 .Dv CAM_DEBUG_TRACE
 280 and
 281 .Dv CAM_DEBUG_SUBTRACE ,
 282 will produce kernel printfs in EXTREME numbers.
 283 .Pp
 284 Users can enable debugging from their kernel config file, by using
 285 the following kernel config options:
 286 .Bl -tag -width CAM_DEBUG_COMPILE
 287 .It Dv CAMDEBUG
 288 This builds into the kernel all possible
 289 .Nm
 290 debugging.
 291 .It Dv CAM_DEBUG_COMPILE
 292 This allows to specify support for which debugging flags described above
 293 should be built into the kernel.
 294 Flags may be ORed together if the user wishes to
 295 see printfs for multiple debugging levels.
 296 .It Dv CAM_DEBUG_FLAGS
 297 This allows to set the various debugging flags from a kernel config file.
 298 .It Dv CAM_DEBUG_BUS
 299 Specify a bus to debug.
 300 To debug all busses, set this to -1.
 301 .It Dv CAM_DEBUG_TARGET
 302 Specify a target to debug.
 303 To debug all targets, set this to -1.
 304 .It Dv CAM_DEBUG_LUN
 305 Specify a lun to debug.
 306 To debug all luns, set this to -1.
 307 .El
 308 .Pp
 309 Users may also enable debugging on the fly by using the
 310 .Xr camcontrol 8
 311 utility, if wanted options built into the kernel.
 312 See
 313 .Xr camcontrol 8
 314 for details.
 315 .Sh SEE ALSO
 316 .Xr ada 4 ,
 317 .Xr aha 4 ,
 318 .Xr ahb 4 ,
 319 .Xr ahc 4 ,
 320 .Xr ahci 4 ,
 321 .Xr ata 4 ,
 322 .Xr bt 4 ,
 323 .Xr cd 4 ,
 324 .Xr ch 4 ,
 325 .Xr da 4 ,
 326 .Xr pass 4 ,
 327 .Xr pt 4 ,
 328 .Xr sa 4 ,
 329 .Xr xpt 4 ,
 330 .Xr camcontrol 8
 331 .Sh HISTORY
 332 The
 333 .Nm
 334 .Tn SCSI
 335 subsystem first appeared in
 336 .Fx 3.0 .
 337 The
 338 .Nm
 339 ATA support was added in
 340 .Fx 8.0 .
 341 .Sh AUTHORS
 342 .An -nosplit
 343 The
 344 .Nm
 345 .Tn SCSI
 346 subsystem was written by
 347 .An Justin Gibbs
 348 and
 349 .An Kenneth Merry .
 350 The
 351 .Nm
 352 .Tn ATA
 353 support was added by
 354 .An Alexander Motin Aq mav@FreeBSD.org .