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