1.\" $OpenBSD: scsi.4,v 1.36 2012/08/14 01:08:19 dlg Exp $ 2.\" 3.\" Copyright (c) 1996 4.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: August 14 2012 $ 29.Dt SCSI 4 30.Os 31.Sh NAME 32.Nm scsi 33.Nd SCSI system 34.Sh SYNOPSIS 35.Cd "cd* at scsibus?" 36.Cd "ch* at scsibus?" 37.Cd "safte* at scsibus?" 38.Cd "sd* at scsibus?" 39.Cd "ses* at scsibus?" 40.Cd "st* at scsibus?" 41.Cd "uk* at scsibus?" 42.Pp 43.Cd "# multipath support" 44.Cd "emc* at scsibus?" 45.Cd "hds* at scsibus?" 46.Cd "rdac* at scsibus?" 47.Cd "sym* at scsibus?" 48.Sh DESCRIPTION 49The 50.Em SCSI 51system provides a uniform and modular system for the implementation 52of drivers to control various SCSI devices, and to utilize different 53SCSI host adapters through host adapter drivers. 54When the system probes the 55.Em SCSI 56buses, it attaches any devices it finds to the appropriate 57drivers. 58If no driver seems appropriate, then it attaches the device to the 59uk (unknown) driver so that user level SCSI ioctls may 60still be performed against the device. 61.Sh KERNEL CONFIGURATION 62The option SCSIDEBUG enables the debug ioctl. 63.Pp 64All devices and the SCSI buses support boot time allocation so that 65an upper number of devices and controllers does not need to be configured; 66.Cd "sd* at scsibus?" 67will suffice for any number of disk drivers. 68.Pp 69The devices are either 70.Em wired 71so they appear as a particular device unit or 72.Em counted 73so that they appear as the next available unused unit. 74.Pp 75To configure a driver in the kernel without wiring down the device use a 76config line similar to 77.Cd "ch* at scsibus?" 78to include the changer driver. 79.Pp 80To wire down a unit use a config line similar to 81.Cd "ch1 at scsibus0 target 4 lun 0" 82to assign changer 1 as the changer with SCSI ID 4, 83SCSI logical unit 0 on SCSI bus 0. 84Individual scsibuses can be wired down to specific controllers with 85a config line similar to 86.Cd "scsibus0 at ahc0" 87which assigns SCSI bus 0 to the first unit using the ahc driver. 88For controllers supporting more than one bus, 89the particular bus can be specified as in 90.Cd "scsibus3 at ahc1 bus 1" 91which assigns scsibus 1 to the second bus probed on the ahc1 device. 92.Pp 93When there is a mixture of wired down and counted devices then the 94counting begins with the first non-wired down unit for a particular 95type. 96That is, if a disk is wired down as 97.Cd "sd1 at scsibus?" , 98then the first non-wired disk shall come on line as 99.Em sd2 . 100.Sh IOCTLS 101There are a number of ioctls that work on any 102.Em SCSI 103device. 104They are defined in 105.Aq Pa sys/scsiio.h 106and can be applied against any SCSI device that permits them. 107For the tape, it must be applied against the control 108device. 109See the manual page for each device type for more information about 110how generic SCSI ioctls may be applied to a specific device. 111.Bl -tag -width DIOCSDINFO____ 112.It Dv SCIOCRESET* 113Reset a device. 114.It Dv SCIOCDEBUG 115Turn on debugging. 116All SCSI operations originating from this device's driver 117will be traced to the console, along with other information. 118Debugging is controlled by four bits, described in the header file. 119If no debugging is configured into the kernel, debugging will have 120no effect. 121.Em SCSI 122debugging is controlled by the configuration option 123.Em SCSIDEBUG . 124.It Dv SCIOCCOMMAND 125Take a SCSI command and data from a user process and apply them to the SCSI 126device. 127Return all status information and return data to the process. 128The ioctl will return a successful status even if the device rejected the 129command. 130As all status is returned to the user, it is up to the user 131process to examine this information to decide the success of the command. 132.It Dv SCIOCIDENTIFY 133Ask the driver what its bus, target and lun are. 134In addition, the device type, ATAPI or SCSI, is returned. 135.El 136.Sh ADAPTERS 137The system allows common device drivers to work through many different 138types of adapters. 139The adapters take requests from the upper layers and do all I/O between the 140.Em SCSI 141bus and the system. 142The maximum size of a transfer is governed by the adapter. 143Most adapters can transfer 64KB in a single operation, and many can transfer 144larger amounts. 145.Sh DIAGNOSTICS 146When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 147can be used to enable various amounts of tracing information on any 148specific device. 149Devices not being traced will not produce trace information. 150The four bits that make up the debug level each control certain types 151of debugging information. 152.Bl -tag -width "Bit 0" 153.It Dv Bit 0 154shows all SCSI bus operations including SCSI commands, 155error information and the first 48 bytes of any data transferred. 156.It Dv Bit 1 157shows routines called. 158.It Dv Bit 2 159shows information about what branches are taken and often some 160of the return values of functions. 161.It Dv Bit 3 162shows more detailed information including DMA scatter-gather logs. 163.El 164.Sh SEE ALSO 165.Xr cd 4 , 166.Xr ch 4 , 167.Xr emc 4 , 168.Xr hds 4 , 169.Xr intro 4 , 170.Xr mpath 4 , 171.Xr rdac 4 , 172.Xr safte 4 , 173.Xr sd 4 , 174.Xr ses 4 , 175.Xr st 4 , 176.Xr sym 4 , 177.Xr uk 4 , 178.Xr scsi 8 179.Sh HISTORY 180This 181.Nm 182system appeared in MACH 2.5 at TRW. 183