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