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