1.\" $NetBSD: scsi.4,v 1.20 2002/04/22 21:05:20 ad 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. 10.\" 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 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 SCSI 4 29.Os 30.Sh NAME 31.Nm scsi , 32.Nm scsibus 33.Nd Small Computer Systems Interface (SCSI) bus driver 34.Sh SYNOPSIS 35.Cd "scsibus* at adv?" 36.Cd "scsibus* at adw?" 37.Cd "scsibus* at aha?" 38.Cd "scsibus* at ahb?" 39.Cd "scsibus* at ahc?" 40.Cd "scsibus* at aic?" 41.Cd "scsibus* at asc?" 42.Cd "scsibus* at bha?" 43.Cd "scsibus* at cosc?" 44.Cd "scsibus* at dpt?" 45.Cd "scsibus* at esp?" 46.Cd "scsibus* at icpsp?" 47.Cd "scsibus* at iha?" 48.Cd "scsibus* at iopsp?" 49.Cd "scsibus* at isp?" 50.Cd "scsibus* at mesh?" 51.Cd "scsibus* at mha?" 52.Cd "scsibus* at mly?" 53.Cd "scsibus* at nca?" 54.Cd "scsibus* at oak?" 55.Cd "scsibus* at osiop?" 56.Cd "scsibus* at pcscp?" 57.Cd "scsibus* at ptsc?" 58.Cd "scsibus* at sea?" 59.Cd "scsibus* at si?" 60.Cd "scsibus* at siop?" 61.Cd "scsibus* at spc?" 62.Cd "scsibus* at sw?" 63.Cd "scsibus* at trm?" 64.Cd "scsibus* at uha?" 65.Cd "scsibus* at umass?" 66.Cd "scsibus* at wds?" 67.Cd "atapibus* at wdc? channel ?" 68.Cd "atapibus* at pciide? channel ?" 69.Cd "atapibus* at umass? channel ?" 70.Cd options SCSIDEBUG 71.Cd options SCSIVERBOSE 72.Sh DESCRIPTION 73The 74.Nm 75driver is the top, machine-independent layer of the two-layer 76software system that provides an interface for the 77implementation of drivers to control various 78.Tn SCSI 79or 80.Tn ATAPI 81bus devices, and to utilize different 82.Tn SCSI 83bus host adapters or 84.Tn EIDE 85controllers. 86.Tn SCSI 87bus is capable of supporting a wide variety of peripherals, including 88hard disks, removable disks, 89.Tn CD-ROMs , 90scanners, tape drives, and other miscellaneous high-speed devices. 91.Pp 92The bottom layer is composed of the drivers for individual 93.Tn EIDE 94or 95.Tn SCSI 96bus controller chips (e.g. NCR 5380), accessed through various host bus 97interfaces, including, but not limited to 98.Tn PCI , 99.Tn ISA , 100.Tn Sbus , 101.Tn TURBOchannel , 102and 103.Tn NuBus . 104These individual devices are referred to as 105.Qq host adaptors 106in 107.Tn SCSI 108terminology, 109because they connect the 110.Tn SCSI 111bus to the host computer. 112.Pp 113When 114.Nx 115probes the 116.Tn SCSI 117busses, it 118.Qq attaches 119any devices it finds to the appropriate drivers. 120.Pp 121.Bl -tag -compact -width "sd(4)" 122.It Xr sd 4 123hard disks 124.It Xr cd 4 125.Tn CD-ROM 126drives 127.It Xr st 4 128tape drives 129.It Xr ch 4 130media changers 131.It Xr ss 4 132scanners 133.El 134.Pp 135If no specific driver matches the device, 136then 137.Nm 138attaches the device to the 139.Xr uk 4 140driver so that user level 141.Tn SCSI 142.Xr ioctl 2 143calls may still be performed against the device. Currently, only 144.Xr sd 4 , 145.Xr cd 4 146or 147.Xr uk 4 148can attach to an atapi bus. 149.Pp 150Please see the 151.Xr intro 4 152manual page to see which 153.Tn SCSI 154bus host adaptors are supported by 155.Nx 156on your computer system. 157.Sh KERNEL CONFIGURATION 158The 159.Nm 160software supports some 161.Nx 162kernel 163.Xr config 8 164options. 165They are: 166.Bl -tag -width SCSIVERBOSE 167.It Dv SCSIDEBUG 168Compile in a wide variety of 169.Fn printf 170statements that can be turned on by 171.Xr ioctl 2 . 172.It Dv SCSIVERBOSE 173Enable additional and more descriptive error and status messages 174from the 175.Nm 176software. 177.El 178.Pp 179All devices and the 180.Tn SCSI 181busses support boot time allocation so that an upper number of 182devices and controllers does not need to be configured. 183.Pp 184The devices are either 185.Em wired 186so they appear at a particular device unit number or 187.Em counted 188so that they appear as the next available unused unit number. 189.Pp 190To configure a driver in the kernel without wiring down the device use a 191config line similar to 192.Pp 193.Cd "ch* at scsibus? target ? lun ?" 194.Pp 195to include the 196.Xr ch 4 197changer driver. 198.Pp 199To wire down a unit use a config line similar to 200.Pp 201.Cd "ch1 at scsibus0 target 4 lun 0" 202.Pp 203to assign changer 1 as the changer with 204.Tn SCSI 205ID 4, logical unit 0, on bus 0. 206Individual 207.Tn SCSI 208busses can be wired down to specific controllers with a config line 209similar to 210.Pp 211.Cd "scsibus0 at ahc0" 212.Pp 213which assigns 214.Tn SCSI 215bus 0 to the first unit using the 216.Xr ahc 4 217driver. 218.Pp 219When you have a mixture of wired down and counted devices then the counting 220begins with the first non-wired down unit for a particular type. 221That is, if you have a disk wired down as 222.Pp 223.Cd "sd1 at scsibus0 target 1 lun 0" 224.Pp 225then the first non-wired disk shall come on line as 226.Em sd2 . 227.Sh IOCTLS 228There are a number of 229.Xr ioctl 2 230calls that work on any 231.Tn SCSI 232device. 233They are defined in 234.Pa sys/scsiio.h 235and can be applied against any 236.Tn SCSI 237device that permits them. 238For the tape, it must be applied against the control device. 239See the manual page for each device type for more information about 240how generic 241.Tn SCSI 242.Xr ioctl 2 243calls may be applied to a specific device. 244.Bl -tag -width DIOCSDINFO____ 245.It Dv SCIOCRESET 246reset a 247.Tn SCSI 248device. 249.It Dv SCIOCDEBUG 250Turn on debugging. 251All 252.Tn SCSI 253operations originating from this device's driver 254will be traced to the console, along with other information. 255Debugging is controlled by four bits, described in the header file. 256If no debugging is configured into the kernel, debugging will have 257no effect. 258.Tn SCSI 259debugging is controlled by the configuration option 260.Dv SCSIDEBUG . 261.It Dv SCIOCCOMMAND 262Take a 263.Tn SCSI 264command and data from a user process and apply them to the 265.Tn SCSI 266device. 267Return all status information and return data to the process. 268The 269.Xr ioctl 2 270call will return a successful status even if the device rejected the command. 271As all status is returned to the user, it is up to the user 272process to examine this information to decide the success of the command. 273.It Dv SCIOCREPROBE 274Ask the system to probe the 275.Tn SCSI 276busses for any new devices. 277If it finds any, they will be attached to the appropriate drivers. 278The search can be narrowed to a specific bus, target or Logical 279Unit Number (LUN). 280The new device may or may not be related to the device on which 281the ioctl was performed. 282.It Dv SCIOCIDENTIFY 283Ask the driver what its bus, target and LUN are. 284.It Dv SCIOCDECONFIG 285Ask the device to disappear. 286This may not happen if the device is in use. 287.El 288.Sh ADAPTERS 289The system allows common device drivers to work through many different 290types of adapters. 291The adapters take requests from the upper layers and do all IO between the 292.Tn SCSI 293bus and the system. 294The maximum size of a transfer is governed by the adapter. 295Most adapters can transfer 64KB in a single operation, however 296many can transfer larger amounts. 297.Sh TARGET MODE 298Some adapters support 299.Em Target Mode 300in which the system is capable of operating as a device, responding to 301operations initiated by another system. 302Target Mode will be supported for 303some host adapters, but is not yet complete for this version of the 304.Tn SCSI 305system. 306.Sh DIAGNOSTICS 307When the kernel is compiled with option 308.Dv SCSIDEBUG , 309the 310.Dv SCIOCDEBUG 311.Xr ioctl 2 312can be used to enable various amounts of tracing information on any 313specific device. 314Devices not being traced will not produce trace information. 315The four bits that make up the debug level, each control certain types 316of debugging information. 317.Bl -tag -width "Bit 0" 318.It Dv Bit 0 319shows all 320.Tn SCSI 321bus operations including 322.Tn SCSI 323commands, 324error information and the first 48 bytes of any data transferred. 325.It Dv Bit 1 326shows routines called. 327.It Dv Bit 2 328shows information about what branches are taken and often some 329of the return values of functions. 330.It Dv Bit 3 331shows more detailed information including 332.Tn DMA 333scatter-gather logs. 334.El 335.Sh SEE ALSO 336.Xr ioctl 2 , 337.Xr cd 4 , 338.Xr ch 4 , 339.Xr intro 4 , 340.Xr sd 4 , 341.Xr se 4 , 342.Xr ss 4 , 343.Xr st 4 , 344.Xr uk 4 , 345.Xr config 8 346.Sh HISTORY 347This 348.Nm 349system appeared in MACH 2.5 at TRW. 350.Pp 351This man page was originally written by Julian Elischer 352.Aq julian@freebsd.org 353for 354.Fx 355and extensively modified by Erik Fair 356.Aq fair@netbsd.org 357for 358.Nx . 359.Sh BUGS 360Not every device obeys the 361.Tn SCSI 362specification as faithfully as it should. 363As such devices are discovered by the 364.Nx 365Project, their names are added to a 366.Em quirk list 367compiled into the 368.Nm 369driver along a list of flags indicating which particular bad behaviors the 370device exhibits (and that the driver should be prepared to work around). 371