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