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