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