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 March 4, 2010
  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_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB"
  47 .Cd "options CAM_MAX_HIGHPOWER=4"
  48 .Cd "options SCSI_NO_SENSE_STRINGS"
  49 .Cd "options SCSI_NO_OP_STRINGS"
  50 .Cd "options SCSI_DELAY=8000"
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 subsystem provides a uniform and modular system for the implementation
  55 of drivers to control various
  56 .Tn SCSI
  57 and
  58 .Tn ATA
  59 devices, and to utilize different
  60 .Tn SCSI
  61 and
  62 .Tn ATA
  63 host adapters through host adapter drivers.
  64 When the system probes busses, it attaches any devices it finds to the
  65 appropriate drivers.
  66 The
  67 .Xr pass 4
  68 driver, if it is configured in the kernel, will attach to all devices.
  69 .Sh KERNEL CONFIGURATION
  70 There are a number of generic kernel configuration options for the
  71 .Nm
  72 subsystem:
  73 .Bl -tag -width SCSI_NO_SENSE_STRINGS
  74 .It Dv CAMDEBUG
  75 This option enables the
  76 .Nm
  77 debugging printf code.
  78 This will not actually
  79 cause any debugging information to be printed out when included by itself.
  80 Enabling printouts requires additional configuration.
  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 When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be
 252 used to enable various amounts of tracing information on any
 253 specific device.
 254 Devices not being traced will not produce trace information.
 255 There are currently four debugging flags that may be turned on:
 256 .Bl -tag -width CAM_DEBUG_SUBTRACE
 257 .It Dv CAM_DEBUG_INFO
 258 This debugging flag enables general informational printfs for the device
 259 or devices in question.
 260 .It Dv CAM_DEBUG_TRACE
 261 This debugging flag enables function-level command flow tracing.
 262 i.e.\&
 263 kernel printfs will happen at the entrance and exit of various functions.
 264 .It Dv CAM_DEBUG_SUBTRACE
 265 This debugging flag enables debugging output internal to various functions.
 266 .It Dv CAM_DEBUG_CDB
 267 This debugging flag will cause the kernel to print out all
 268 .Tn SCSI
 269 commands sent to a particular device or devices.
 270 .El
 271 .Pp
 272 Some of these flags, most notably
 273 .Dv CAM_DEBUG_TRACE
 274 and
 275 .Dv CAM_DEBUG_SUBTRACE
 276 will produce kernel printfs in EXTREME numbers,
 277 and because of that, they are not especially useful.
 278 There are not many things logged at the
 279 .Dv CAM_DEBUG_INFO
 280 level, so it is not especially useful.
 281 The most useful debugging flag is the
 282 .Dv CAM_DEBUG_CDB
 283 flag.
 284 Users can enable debugging from their kernel config file, by using
 285 the following kernel config options:
 286 .Bl -tag -width CAM_DEBUG_TARGET
 287 .It Dv CAMDEBUG
 288 This enables
 289 .Nm
 290 debugging.
 291 Without this option, users will not even be able
 292 to turn on debugging from userland via
 293 .Xr camcontrol 8 .
 294 .It Dv CAM_DEBUG_FLAGS
 295 This allows the user to set the various debugging flags described above
 296 in a kernel config file.
 297 Flags may be ORed together if the user wishes to
 298 see printfs for multiple debugging levels.
 299 .It Dv CAM_DEBUG_BUS
 300 Specify a bus to debug.
 301 To debug all busses, set this to -1.
 302 .It Dv CAM_DEBUG_TARGET
 303 Specify a target to debug.
 304 To debug all targets, set this to -1.
 305 .It Dv CAM_DEBUG_LUN
 306 Specify a lun to debug.
 307 To debug all luns, set this to -1.
 308 .El
 309 .Pp
 310 When specifying a bus, target or lun to debug, you
 311 .Em MUST
 312 specify all three bus/target/lun options above.
 313 Using wildcards, you
 314 should be able to enable debugging on most anything.
 315 .Pp
 316 Users may also enable debugging printfs on the fly, if the
 317 .Dv CAMDEBUG
 318 option is their config file, by using the
 319 .Xr camcontrol 8
 320 utility.
 321 See
 322 .Xr camcontrol 8
 323 for details.
 324 .Sh SEE ALSO
 325 .Xr ada 4 ,
 326 .Xr aha 4 ,
 327 .Xr ahb 4 ,
 328 .Xr ahc 4 ,
 329 .Xr ahci 4 ,
 330 .Xr ata 4 ,
 331 .Xr bt 4 ,
 332 .Xr cd 4 ,
 333 .Xr ch 4 ,
 334 .Xr da 4 ,
 335 .Xr pass 4 ,
 336 .Xr pt 4 ,
 337 .Xr sa 4 ,
 338 .Xr xpt 4 ,
 339 .Xr camcontrol 8
 340 .Sh HISTORY
 341 The
 342 .Nm
 343 .Tn SCSI
 344 subsystem first appeared in
 345 .Fx 3.0 .
 346 The
 347 .Nm
 348 ATA support was added in
 349 .Fx 8.0 .
 350 .Sh AUTHORS
 351 .An -nosplit
 352 The
 353 .Nm
 354 .Tn SCSI
 355 subsystem was written by
 356 .An Justin Gibbs
 357 and
 358 .An Kenneth Merry .
 359 The
 360 .Nm
 361 .Tn ATA
 362 support was added by
 363 .An Alexander Motin Aq mav@FreeBSD.org .