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