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: src/share/man/man4/scsi.4,v 1.18.2.7 2001/08/17 13:08:39 ru Exp $ 27.\" $DragonFly: src/share/man/man4/scsi.4,v 1.2 2003/06/17 04:36:59 dillon Exp $ 28.Dd October 15, 1998 29.Dt SCSI 4 30.Os 31.Sh NAME 32.Nm SCSI , 33.Nm CAM 34.Nd CAM SCSI subsystem 35.Sh SYNOPSIS 36.Cd "device scbus" 37.Cd "device scbus1 at ahc0" 38.Cd "device scbus3 at ahc1 bus 0" 39.Cd "device scbus2 at ahc1 bus 1" 40.Cd "device cd" 41.Cd "device ch" 42.Cd "device da" 43.Cd "device pass" 44.Cd "device pt" 45.Cd "device sa" 46.Cd "device ch1 at scbus0 target 4 unit 0" 47.Cd "options CAMDEBUG" 48.Cd "options CAM_DEBUG_BUS=-1" 49.Cd "options CAM_DEBUG_TARGET=-1" 50.Cd "options CAM_DEBUG_LUN=-1" 51.Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB" 52.Cd "options CAM_MAX_HIGHPOWER=4" 53.Cd "options SCSI_NO_SENSE_STRINGS" 54.Cd "options SCSI_NO_OP_STRINGS" 55.Cd "options SCSI_DELAY=8000" 56.Sh DESCRIPTION 57The CAM 58.Tn SCSI 59subsystem provides a uniform and modular system for the implementation 60of drivers to control various 61.Tn SCSI 62devices, and to utilize different 63.Tn SCSI 64host adapters through host adapter drivers. 65When the system probes the 66.Tn SCSI 67busses, it attaches any devices it finds to the appropriate 68drivers. The 69.Xr pass 4 70driver, if it is configured in the kernel, will attach to all 71.Tn SCSI 72devices. 73.Sh KERNEL CONFIGURATION 74There are a number of generic kernel configuration options for the 75CAM 76.Tn SCSI 77subsystem: 78.Bl -tag -width SCSI_NO_SENSE_STRINGS 79.It Dv CAMDEBUG 80This option enables the CAM debugging printf code. This won't actually 81cause any debugging information to be printed out when included by itself. 82Enabling printouts requires additional configuration. See below for 83details. 84.It Dv "CAM_MAX_HIGHPOWER=4" 85This sets the maximum allowable number of concurrent "high power" commands. 86A "high power" command is a command that takes more electrical power than 87most to complete. An example of this (and the only command currently 88tagged as "high power") is the 89.Tn SCSI 90START UNIT command. Starting a SCSI disk often takes significantly more 91electrical power than normal operation of the disk. This 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. Since this 98is a fairly large text database, eliminating it reduces the size of the 99kernel somewhat. This is primarily necessary for boot floppies and other 100low disk space or low memory space environments. In most cases, though, 101this should be enabled, since it speeds the interpretation of 102.Tn SCSI 103error messages. Don't let the "kernel bloat" zealots get to you -- leave 104the sense descriptions in your kernel! 105.It Dv SCSI_NO_OP_STRINGS 106This disables text descriptions of each 107.Tn SCSI 108opcode. This option, like the sense string option above, is primarily 109useful for environments like a boot floppy where kernel size is critical. 110Enabling this option for normal use isn't recommended, since it slows 111debugging of 112.Tn SCSI 113problems. 114.It Dv SCSI_DELAY=8000 115This is the 116.Tn SCSI 117"bus settle delay." In CAM, it is specified in 118.Em milliseconds , 119not seconds like the old 120.Tn SCSI 121layer used to do. When the kernel boots, it sends a bus reset to each 122.Tn SCSI 123bus to tell each device to reset itself to a default set of transfer 124negotiations and other settings. Most 125.Tn SCSI 126devices need some amount of time to recover from a bus reset. Newer disks 127may need as little as 100ms, while old, slow devices may need much longer. 128If the 129.Dv SCSI_DELAY 130isn't specified, it defaults to 2 seconds. The minimum allowable value for 131.Dv SCSI_DELAY 132is "100", or 100ms. One special case is that if the 133.Dv SCSI_DELAY 134is set to 0, that will be taken to mean the "lowest possible value." In 135that case, the 136.Dv SCSI_DELAY 137will be reset to 100ms. 138.El 139.Pp 140All devices and the SCSI busses support boot time allocation so that 141an upper number of devices and controllers does not need to be configured; 142.Cd "device da0" 143will suffice for any number of disk drivers. 144.Pp 145The devices are either 146.Em wired 147so they appear as a particular device unit or 148.Em counted 149so that they appear as the next available unused unit. 150.Pp 151To configure a driver in the kernel without wiring down the device use a 152config line similar to 153.Cd "device ch0" 154to include the changer driver. 155.Pp 156To wire down a unit use a config line similar to 157.Cd "device ch1 at scbus0 target 4 unit 0" 158to assign changer 1 as the changer with SCSI ID 4, 159SCSI logical unit 0 on SCSI bus 0. 160Individual scbuses can be wired down to specific controllers with 161a config line similar to 162.Cd "device scbus0 at ahc0" 163which assigns scsi bus 0 to the first unit using the ahc driver. 164For controllers supporting more than one bus, 165the particular bus can be specified as in 166.Cd "device scbus3 at ahc1 bus 1" 167which assigns scbus 1 to the second bus probed on the ahc1 device. 168.Pp 169When you have a mixture of wired down and counted devices then the 170counting begins with the first non-wired down unit for a particular 171type. That is, if you have a disk wired down as 172.Em "device da1" , 173then the first non-wired disk shall come on line as 174.Em da2 . 175.Sh ADAPTERS 176The system allows common device drivers to work through many different 177types of adapters. 178The adapters take requests from the upper layers and do 179all IO between the 180.Em SCSI 181bus and the system. 182The maximum size of a transfer is governed by the 183adapter. 184Most adapters can transfer 64KB in a single operation, however 185many can transfer larger amounts. 186.Sh TARGET MODE 187Some adapters support 188.Em target mode 189in which the system is capable of operating as a device, responding to 190operations initiated by another system. 191Target mode is supported for 192some adapters, but is not yet complete for this version of the CAM 193.Tn SCSI 194subsystem. 195.Sh FILES 196see other scsi device entries. 197.Sh DIAGNOSTICS 198When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be 199used to enable various amounts of tracing information on any 200specific device. 201Devices not being traced will not produce trace information. 202There are currently four debugging flags that may be turned on: 203.Bl -tag -width CAM_DEBUG_SUBTRACE 204.It Dv CAM_DEBUG_INFO 205This debugging flag enables general informational printfs for the device 206or devices in question. 207.It Dv CAM_DEBUG_TRACE 208This debugging flag enables function-level command flow tracing. i.e.\& 209kernel printfs will happen at the entrance and exit of various functions. 210.It Dv CAM_DEBUG_SUBTRACE 211This debugging flag enables debugging output internal to various functions. 212.It Dv CAM_DEBUG_CDB 213This debugging flag will cause the kernel to print out all 214.Tn SCSI 215commands sent to a particular device or devices. 216.El 217.Pp 218Some of these flags, most notably 219.Dv CAM_DEBUG_TRACE 220and 221.Dv CAM_DEBUG_SUBTRACE 222will produce kernel printfs in EXTREME numbers. Because of that, they 223aren't especially useful. There aren't many things logged at the 224.Dv CAM_DEBUG_INFO 225level, so it isn't especially useful. The most useful debugging flag is 226the 227.Dv CAM_DEBUG_CDB 228flag. Users can enable debugging from their kernel config file, by using 229the following kernel config options: 230.Bl -tag -width CAM_DEBUG_TARGET 231.It Dv CAMDEBUG 232This enables CAM debugging. Without this option, users will not even be able 233to turn on debugging from userland via 234.Xr camcontrol 8 . 235.It Dv CAM_DEBUG_FLAGS 236This allows the user to set the various debugging flags described above 237in a kernel config file. Flags may be ORed together if the user wishes to 238see printfs for multiple debugging levels. 239.It Dv CAM_DEBUG_BUS 240Specify a bus to debug. To debug all busses, set this to -1. 241.It Dv CAM_DEBUG_TARGET 242Specify a target to debug. To debug all targets, set this to -1. 243.It Dv CAM_DEBUG_LUN 244Specify a lun to debug. To debug all luns, set this to -1. 245.El 246.Pp 247When specifying a bus, target or lun to debug, you 248.Em MUST 249specify all three bus/target/lun options above. Using wildcards, you 250should be able to enable debugging on most anything. 251.Pp 252Users may also enable debugging printfs on the fly, if the 253.Dv CAMDEBUG 254option is their config file, by using the 255.Xr camcontrol 8 256utility. See 257.Xr camcontrol 8 258for details. 259.Sh SEE ALSO 260.Xr aha 4 , 261.Xr ahb 4 , 262.Xr ahc 4 , 263.Xr bt 4 , 264.Xr cd 4 , 265.Xr ch 4 , 266.Xr da 4 , 267.Xr pass 4 , 268.Xr pt 4 , 269.Xr sa 4 , 270.Xr xpt 4 , 271.Xr camcontrol 8 272.Sh HISTORY 273The CAM 274.Tn SCSI 275subsystem first appeared in 276.Fx 3.0 . 277.Sh AUTHORS 278.An -nosplit 279The CAM 280.Tn SCSI 281subsystem was written by 282.An Justin Gibbs 283and 284.An Kenneth Merry . 285