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