| scsi.4 (22986) | scsi.4 (40439) |
|---|---|
| 1.\" $Id$ | 1.\" $Id: scsi.4,v 1.11 1997/02/22 13:24:41 peter Exp $ |
| 2.\" Copyright (c) 1996 3.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. --- 9 unchanged lines hidden (view full) --- 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" | 2.\" Copyright (c) 1996 3.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. --- 9 unchanged lines hidden (view full) --- 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" |
| 27.Dd August 27, 1993 28.Dt SD 4 29.Os FreeBSD | 27.Dd October 15, 1998 28.Dt SCSI 4 29.Os FreeBSD 3.0 |
| 30.Sh NAME | 30.Sh NAME |
| 31.Nm scsi 32.Nd scsi system | 31.Nm SCSI , 32.Nm CAM 33.Nd CAM SCSI subsystem |
| 33.Sh SYNOPSIS 34.Cd "controller scbus0" 35.Cd "controller scbus1 at ahc0" 36.Cd "controller scbus3 at ahc1 bus 0" 37.Cd "controller scbus2 at ahc1 bus 1" 38.Cd "device cd0" 39.Cd "device ch0" | 34.Sh SYNOPSIS 35.Cd "controller scbus0" 36.Cd "controller scbus1 at ahc0" 37.Cd "controller scbus3 at ahc1 bus 0" 38.Cd "controller scbus2 at ahc1 bus 1" 39.Cd "device cd0" 40.Cd "device ch0" |
| 40.Cd "disk sd0" 41.Cd "tape st0" | 41.Cd "device da0" 42.Cd "device pass0" 43.Cd "device pt0" 44.Cd "device sa0" |
| 42.Cd "device ch1 at scbus0 target 4 unit 0" | 45.Cd "device ch1 at scbus0 target 4 unit 0" |
| 46.Cd options CAMDEBUG 47.Cd options "CAM_DEBUG_BUS=-1" 48.Cd options "CAM_DEBUG_TARGET=-1" 49.Cd options "CAM_DEBUG_LUN=-1" 50.Cd options "CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB" 51.Cd options "CAM_MAX_HIGHPOWER=4" 52.Cd options SCSI_NO_SENSE_STRINGS 53.Cd options SCSI_NO_OP_STRINGS 54.Cd options SCSI_DELAY=8000 |
|
| 43.Sh DESCRIPTION | 55.Sh DESCRIPTION |
| 44The 45.Em scsi 46system provides a uniform and modular system for the implementation 47of drivers to control various scsi devices, and to utilize different 48scsi host adapters through host adapter drivers. When the system probes the 49.Em SCSI | 56The CAM 57.Tn SCSI 58subsystem provides a uniform and modular system for the implementation 59of drivers to control various 60.Tn SCSI 61devices, and to utilize different 62.Tn SCSI 63host adapters through host adapter drivers. When the system probes the 64.Tn SCSI |
| 50busses, it attaches any devices it finds to the appropriate | 65busses, it attaches any devices it finds to the appropriate |
| 51drivers. If no driver seems appropriate, then it attaches the device to the 52uk (unknown) driver so that user level scsi ioctls may 53still be performed against the device. | 66drivers. The 67.Xr pass 4 68driver, if it is configured in the kernel, will attach to all 69.Tn SCSI 70devices. |
| 54.Sh KERNEL CONFIGURATION | 71.Sh KERNEL CONFIGURATION |
| 55The option SCSIDEBUG enables the debug ioctl. | 72There are a number of generic kernel configuration options for the 73CAM 74.Tn SCSI 75subsystem: 76.Bl -tag -width SCSI_NO_SENSE_STRINGS 77.It Dv CAMDEBUG 78This option enables the CAM debugging printf code. This won't actually 79cause any debugging information to be printed out when included by itself. 80Enabling printouts requires additional configuration. See below for 81details. 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. An example of this (and the only command currently 86tagged as "high power") is the 87.Tn SCSI 88START UNIT command. Starting a SCSI disk often takes significantly more 89electrical power than normal operation of the disk. This option allows the 90user to specify how many concurrent high power commands may be outstanding 91without overloading the power supply on his computer. 92.It Dv SCSI_NO_SENSE_STRINGS 93This eliminates text descriptions of each 94.Tn SCSI 95Additional Sense Code and Additional Sense Code Qualifier pair. Since this 96is a fairly large text database, eliminating it reduces the size of the 97kernel somewhat. This is primarily necessary for boot floppies and other 98low disk space or low memory space environments. In most cases, though, 99this should be enabled, since it speeds the interpretation of 100.Tn SCSI 101error messages. Don't let the "kernel bloat" zealots get to you -- leave 102the sense descriptions in your kernel! 103.It Dv SCSI_NO_OP_STRINGS 104This disables text descriptions of each 105.Tn SCSI 106opcode. This option, like the sense string option above, is primarily 107useful for environments like a boot floppy where kernel size is critical. 108Enabling this option for normal use isn't recommended, since it slows 109debugging of 110.Tn SCSI 111problems. 112.It Dv SCSI_DELAY=8000 113This is the 114.Tn SCSI 115"bus settle delay." In CAM, it is specified in 116.Em milliseconds , 117not seconds like the old 118.Tn SCSI 119layer used to do. When the kernel boots, it sends a bus reset to each 120.Tn SCSI 121bus to tell each device to reset itself to a default set of transfer 122negotiations and other settings. Most 123.Tn SCSI 124devices need some amount of time to recover from a bus reset. Newer disks 125may need as little as 100ms, while old, slow devices may need much longer. 126If the 127.Dv SCSI_DELAY 128isn't specified, it defaults to 2 seconds. The minimum allowable value for 129.Dv SCSI_DELAY 130is "100", or 100ms. One special case is that if the 131.Dv SCSI_DELAY 132is set to 0, that will be taken to mean the "lowest possible value." In 133that case, the 134.Dv SCSI_DELAY 135will be reset to 100ms. 136.El |
| 56.Pp 57All devices and the SCSI busses support boot time allocation so that 58an upper number of devices and controllers does not need to be configured; | 137.Pp 138All devices and the SCSI busses support boot time allocation so that 139an upper number of devices and controllers does not need to be configured; |
| 59.Em "device sd0" | 140.Cd "device da0" |
| 60will suffice for any number of disk drivers. 61.Pp 62The devices are either 63.Em wired 64so they appear as a particular device unit or 65.Em counted 66so that they appear as the next available unused unit. 67.Pp 68To configure a driver in the kernel without wiring down the device use a 69config line similar to | 141will suffice for any number of disk drivers. 142.Pp 143The devices are either 144.Em wired 145so they appear as a particular device unit or 146.Em counted 147so that they appear as the next available unused unit. 148.Pp 149To configure a driver in the kernel without wiring down the device use a 150config line similar to |
| 70.Em "device ch0" | 151.Cd "device ch0" |
| 71to include the changer driver. 72.Pp 73To wire down a unit use a config line similar to | 152to include the changer driver. 153.Pp 154To wire down a unit use a config line similar to |
| 74.Em "device ch1 at scbus0 target 4 unit 0" | 155.Cd "device ch1 at scbus0 target 4 unit 0" |
| 75to assign changer 1 as the changer with SCSI ID 4, 76SCSI logical unit 0 on SCSI bus 0. 77Individual scbuses can be wired down to specific controllers with 78a config line similar to | 156to assign changer 1 as the changer with SCSI ID 4, 157SCSI logical unit 0 on SCSI bus 0. 158Individual scbuses can be wired down to specific controllers with 159a config line similar to |
| 79.Em "controller scbus0 at ahc0" | 160.Cd "controller scbus0 at ahc0" |
| 80which assigns scsi bus 0 to the first unit using the ahc driver. 81For controllers supporting more than one bus, 82the particular bus can be specified as in | 161which assigns scsi bus 0 to the first unit using the ahc driver. 162For controllers supporting more than one bus, 163the particular bus can be specified as in |
| 83.Em "controller scbus3 at ahc1 bus 1" | 164.Cd "controller scbus3 at ahc1 bus 1" |
| 84which assigns scbus 1 to the second bus probed on the ahc1 device. 85.Pp 86When you have a mixture of wired down and counted devices then the 87counting begins with the first non-wired down unit for a particular 88type. That is, if you have a disk wired down as | 165which assigns scbus 1 to the second bus probed on the ahc1 device. 166.Pp 167When you have a mixture of wired down and counted devices then the 168counting begins with the first non-wired down unit for a particular 169type. That is, if you have a disk wired down as |
| 89.Em "disk sd1" , | 170.Em "device da1" , |
| 90then the first non-wired disk shall come on line as | 171then the first non-wired disk shall come on line as |
| 91.Em sd2 . 92.Sh IOCTLS 93There are a number of ioctls that work on any 94.Em SCSI 95device. They are defined in 96.Em sys/scsiio.h 97and can be applied against any scsi device that permits them. 98For the tape, it must be applied against the control 99device. See the manual page for each device type for more information about 100how generic scsi ioctls may be applied to a specific device. 101.Bl -tag -width DIOCSDINFO____ 102.It Dv SCIOCRESET* 103reset a device. 104.It Dv SCIOCDEBUG 105Turn on debugging.. All scsi operations originating from this device's driver 106will be traced to the console, along with other information. Debugging is 107controlled by four bits, described in the header file. If no debugging is 108configured into the kernel, debugging will have no effect. 109.Em SCSI 110debugging is controlled by the configuration option 111.Em SCSIDEBUG. 112.It Dv SCIOCCOMMAND 113Take a scsi command and data from a user process and apply them to the scsi 114device. Return all status information and return data to the process. The 115ioctl will return a successful status even if the device rejected the 116command. As all status is returned to the user, it is up to the user 117process to examine this information to decide the success of the command. 118.It Dv SCIOCREPROBE 119Ask the system to probe the scsi busses for any new devices. If it finds 120any, they will be attached to the appropriate drivers. The search can be 121narrowed to a specific bus, target or lun. The new device may or may not 122be related to the device on which the ioctl was performed. 123.It Dv SCIOCIDENTIFY 124Ask the driver what it's bus, target and lun are. 125.It Dv SCIOCDECONFIG 126Ask the device to disappear. This may not happen if the device is in use. 127.El 128.Sh NOTES 129the generic scsi part of the system is still being mapped out. 130Watch this space for changes. 131.Pp 132 A device by the name of su (scsi_user) 133(e.g su0-0-0) will map bus, target and lun to minor numbers. I have not 134yet decided yet whether this device will be able to open a device that is 135already controlled by an explicit driver. | 172.Em da2 . |
| 136.Sh ADAPTERS 137The system allows common device drivers to work through many different 138types of adapters. The adapters take requests from the upper layers and do 139all IO between the 140.Em SCSI 141bus and the system. The maximum size of a transfer is governed by the 142adapter. Most adapters can transfer 64KB in a single operation, however 143many can transfer larger amounts. 144.Sh TARGET MODE 145Some adapters support | 173.Sh ADAPTERS 174The system allows common device drivers to work through many different 175types of adapters. The adapters take requests from the upper layers and do 176all IO between the 177.Em SCSI 178bus and the system. The maximum size of a transfer is governed by the 179adapter. Most adapters can transfer 64KB in a single operation, however 180many can transfer larger amounts. 181.Sh TARGET MODE 182Some adapters support |
| 146.Em Target mode | 183.Em target mode |
| 147in which the system is capable of operating as a device, responding to | 184in which the system is capable of operating as a device, responding to |
| 148operations initiated by another system. Target mode will be supported for 149some adapters, but is not yet complete for this version of the scsi system. | 185operations initiated by another system. Target mode is supported for 186some adapters, but is not yet complete for this version of the CAM 187.Tn SCSI 188subsystem. |
| 150.Sh FILES 151see other scsi device entries. 152.Sh DIAGNOSTICS | 189.Sh FILES 190see other scsi device entries. 191.Sh DIAGNOSTICS |
| 153When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 154can be used to enable various amounts of tracing information on any | 192When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be 193used to enable various amounts of tracing information on any |
| 155specific device. Devices not being traced will not produce trace information. | 194specific device. Devices not being traced will not produce trace information. |
| 156The four bits that make up the debug level, each control certain types 157of debugging information. 158.Bl -tag -width THIS_WIDE_PLEASE 159.It Dv Bit 0 160Bit 0 shows all scsi bus operations including scsi commands, 161error information and the first 48 bytes of any data transferred. 162.It Dv Bit 1 163Bit 1 shows routines called. 164.It Dv Bit 2 165Bit 2 shows information about what branches are taken and often some 166of the return values of functions. 167.It Dv Bit 3 168Bit 3 shows more detailed information including DMA scatter-gather logs. | 195There are currently four debugging flags that may be turned on: 196.Bl -tag -width CAM_DEBUG_SUBTRACE 197.It Dv CAM_DEBUG_INFO 198This debugging flag enables general informational printfs for the device 199or devices in question. 200.It Dv CAM_DEBUG_TRACE 201This debugging flag enables function-level command flow tracing. i.e. 202kernel printfs will happen at the entrance and exit of various functions. 203.It Dv CAM_DEBUG_SUBTRACE 204This debugging flag enables debugging output internal to various functions. 205.It Dv CAM_DEBUG_CDB 206This debugging flag will cause the kernel to print out all 207.Tn SCSI 208commands sent to a particular device or devices. |
| 169.El | 209.El |
| 210.Pp 211Some of these flags, most notably 212.Dv CAM_DEBUG_TRACE 213and 214.Dv CAM_DEBUG_SUBTRACE 215will produce kernel printfs in EXTREME numbers. Because of that, they 216aren't especially useful. There aren't many things logged at the 217.Dv CAM_DEBUG_INFO 218level, so it isn't especially useful. The most useful debugging flag is 219the 220.Dv CAM_DEBUG_CDB 221flag. Users can enable debugging from their kernel config file, by using 222the following kernel config options: 223.Bl -tag -width CAM_DEBUG_TARGET 224.It Dv CAMDEBUG 225This enables CAM debugging. Without this option, users will not even be able 226to turn on debugging from userland via 227.Xr camcontrol 8 . 228.It Dv CAM_DEBUG_FLAGS 229This allows the user to set the various debugging flags described above 230in a kernel config file. Flags may be ORed together if the user wishes to 231see printfs for multiple debugging levels. 232.It Dv CAM_DEBUG_BUS 233Specify a bus to debug. To debug all busses, set this to -1. 234.It Dv CAM_DEBUG_TARGET 235Specify a target to debug. To debug all targets, set this to -1. 236.It Dv CAM_DEBUG_LUN 237Specify a lun to debug. To debug all luns, set this to -1. 238.El 239.Pp 240When specifying a bus, target or lun to debug, you 241.Em MUST 242specify all three bus/target/lun options above. Using wildcards, you 243should be able to enable debugging on most anything. 244.Pp 245Users may also enable debugging printfs on the fly, if the 246.Dv CAMDEBUG 247option is their config file, by using the 248.Xr camcontrol 8 249utility. See 250.Xr camcontrol 8 251for details. |
|
| 170.Sh SEE ALSO 171.Xr aha 4 , 172.Xr ahb 4 , | 252.Sh SEE ALSO 253.Xr aha 4 , 254.Xr ahb 4 , |
| 255.Xr ahc 4 , |
|
| 173.Xr bt 4 , 174.Xr cd 4 , 175.Xr ch 4 , | 256.Xr bt 4 , 257.Xr cd 4 , 258.Xr ch 4 , |
| 176.Xr sd 4 , 177.Xr st 4 , 178.Xr su 4 , 179.Xr uha 4 , 180.Xr uk 4 | 259.Xr da 4 , 260.Xr pass 4 , 261.Xr pt 4 , 262.Xr sa 4 , 263.Xr xpt 4 , 264.Xr camcontrol 8 |
| 181.Sh HISTORY | 265.Sh HISTORY |
| 182This 183.Nm 184system appeared in MACH 2.5 at TRW. | 266The CAM 267.Tn SCSI 268subsystem first appeared in 269.Fx 3.0 . 270.Sh AUTHORS 271The CAM 272.Tn SCSI 273subsystem was written by Justin Gibbs and Kenneth Merry. 274 |