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. Don't 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 isn't 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 139isn't 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 162To configure a driver in the kernel without wiring down the device use a 163config line similar to 164.Cd "device ch0" 165to include the changer driver. 166.Pp 167To wire down a unit use a config line similar to 168.Cd "device ch1 at scbus0 target 4 unit 0" 169to assign changer 1 as the changer with SCSI ID 4, 170SCSI logical unit 0 on SCSI bus 0. 171Individual scbuses can be wired down to specific controllers with 172a config line similar to 173.Cd "device scbus0 at ahc0" 174which assigns scsi bus 0 to the first unit using the ahc driver. 175For controllers supporting more than one bus, 176the particular bus can be specified as in 177.Cd "device scbus3 at ahc1 bus 1" 178which assigns scbus 1 to the second bus probed on the ahc1 device. 179.Pp 180When you have a mixture of wired down and counted devices then the 181counting begins with the first non-wired down unit for a particular 182type. 183That is, if you have a disk wired down as 184.Em "device da1" , 185then the first non-wired disk shall come on line as 186.Em da2 . 187.Sh ADAPTERS 188The system allows common device drivers to work through many different 189types of adapters. 190The adapters take requests from the upper layers and do 191all IO between the 192.Em SCSI 193bus and the system. 194The maximum size of a transfer is governed by the 195adapter. 196Most adapters can transfer 64KB in a single operation, however 197many can transfer larger amounts. 198.Sh TARGET MODE 199Some adapters support 200.Em target mode 201in which the system is capable of operating as a device, responding to 202operations initiated by another system. 203Target mode is supported for 204some adapters, but is not yet complete for this version of the CAM 205.Tn SCSI 206subsystem. 207.Sh FILES 208see other scsi device entries. 209.Sh DIAGNOSTICS 210When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be 211used to enable various amounts of tracing information on any 212specific device. 213Devices not being traced will not produce trace information. 214There are currently four debugging flags that may be turned on: 215.Bl -tag -width CAM_DEBUG_SUBTRACE 216.It Dv CAM_DEBUG_INFO 217This debugging flag enables general informational printfs for the device 218or devices in question. 219.It Dv CAM_DEBUG_TRACE 220This debugging flag enables function-level command flow tracing. i.e.\& 221kernel printfs will happen at the entrance and exit of various functions. 222.It Dv CAM_DEBUG_SUBTRACE 223This debugging flag enables debugging output internal to various functions. 224.It Dv CAM_DEBUG_CDB 225This debugging flag will cause the kernel to print out all 226.Tn SCSI 227commands sent to a particular device or devices. 228.El 229.Pp 230Some of these flags, most notably 231.Dv CAM_DEBUG_TRACE 232and 233.Dv CAM_DEBUG_SUBTRACE 234will produce kernel printfs in EXTREME numbers, 235and because of that, they aren't especially useful. 236There aren't many things logged at the 237.Dv CAM_DEBUG_INFO 238level, so it isn't especially useful. 239The most useful debugging flag is the 240.Dv CAM_DEBUG_CDB 241flag. Users can enable debugging from their kernel config file, by using 242the following kernel config options: 243.Bl -tag -width CAM_DEBUG_TARGET 244.It Dv CAMDEBUG 245This enables CAM debugging. 246Without this option, users will not even be able 247to turn on debugging from userland via 248.Xr camcontrol 8 . 249.It Dv CAM_DEBUG_FLAGS 250This allows the user to set the various debugging flags described above 251in a kernel config file. 252Flags may be ORed together if the user wishes to 253see printfs for multiple debugging levels. 254.It Dv CAM_DEBUG_BUS 255Specify a bus to debug. 256To debug all busses, set this to -1. 257.It Dv CAM_DEBUG_TARGET 258Specify a target to debug. 259To debug all targets, set this to -1. 260.It Dv CAM_DEBUG_LUN 261Specify a lun to debug. 262To debug all luns, set this to -1. 263.El 264.Pp 265When specifying a bus, target or lun to debug, you 266.Em MUST 267specify all three bus/target/lun options above. 268Using wildcards, you 269should be able to enable debugging on most anything. 270.Pp 271Users may also enable debugging printfs on the fly, if the 272.Dv CAMDEBUG 273option is their config file, by using the 274.Xr camcontrol 8 275utility. See 276.Xr camcontrol 8 277for details. 278.Sh SEE ALSO 279.Xr aha 4 , 280.Xr ahb 4 , 281.Xr ahc 4 , 282.Xr bt 4 , 283.Xr cd 4 , 284.Xr ch 4 , 285.Xr da 4 , 286.Xr pass 4 , 287.Xr pt 4 , 288.Xr sa 4 , 289.Xr xpt 4 , 290.Xr camcontrol 8 291.Sh HISTORY 292The CAM 293.Tn SCSI 294subsystem first appeared in 295.Fx 3.0 . 296.Sh AUTHORS 297.An -nosplit 298The CAM 299.Tn SCSI 300subsystem was written by 301.An Justin Gibbs 302and 303.An Kenneth Merry . 304