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