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