1.\" $OpenBSD: scsi.4,v 1.30 2008/01/26 23:07:55 jmc 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: January 26 2008 $ 29.Dt SCSI 4 30.Os 31.Sh NAME 32.Nm scsi 33.Nd scsi system 34.Sh SYNOPSIS 35.Cd "scsibus at ..." 36.Pp 37.Cd "cd* at scsibus?" 38.Cd "ch* at scsibus?" 39.Cd "safte* at scsibus?" 40.Cd "sd* at scsibus?" 41.Cd "ses* at scsibus?" 42.Cd "st* at scsibus?" 43.Cd "ss* at scsibus?" 44.Cd "uk* at scsibus?" 45.Sh DESCRIPTION 46The 47.Em SCSI 48system provides a uniform and modular system for the implementation 49of drivers to control various scsi devices, and to utilize different 50scsi host adapters through host adapter drivers. 51When the system probes the 52.Em SCSI 53buses, it attaches any devices it finds to the appropriate 54drivers. 55If no driver seems appropriate, then it attaches the device to the 56uk (unknown) driver so that user level scsi ioctls may 57still be performed against the device. 58.Sh KERNEL CONFIGURATION 59The option SCSIDEBUG enables the debug ioctl. 60.Pp 61All devices and the SCSI buses support boot time allocation so that 62an upper number of devices and controllers does not need to be configured; 63.Cd "sd* at scsibus?" 64will suffice for any number of disk drivers. 65.Pp 66The devices are either 67.Em wired 68so they appear as a particular device unit or 69.Em counted 70so that they appear as the next available unused unit. 71.Pp 72To configure a driver in the kernel without wiring down the device use a 73config line similar to 74.Cd "ch* at scsibus?" 75to include the changer driver. 76.Pp 77To wire down a unit use a config line similar to 78.Cd "ch1 at scsibus0 target 4 lun 0" 79to assign changer 1 as the changer with SCSI ID 4, 80SCSI logical unit 0 on SCSI bus 0. 81Individual scsibuses can be wired down to specific controllers with 82a config line similar to 83.Cd "scsibus0 at ahc0" 84which assigns scsi bus 0 to the first unit using the ahc driver. 85For controllers supporting more than one bus, 86the particular bus can be specified as in 87.Cd "scsibus3 at ahc1 bus 1" 88which assigns scsibus 1 to the second bus probed on the ahc1 device. 89.Pp 90When there is a mixture of wired down and counted devices then the 91counting begins with the first non-wired down unit for a particular 92type. 93That is, if a disk is wired down as 94.Cd "sd1 at scsibus?" , 95then the first non-wired disk shall come on line as 96.Em sd2 . 97.Sh IOCTLS 98There are a number of ioctls that work on any 99.Em SCSI 100device. 101They are defined in 102.Aq Pa sys/scsiio.h 103and can be applied against any scsi device that permits them. 104For the tape, it must be applied against the control 105device. 106See the manual page for each device type for more information about 107how generic scsi ioctls may be applied to a specific device. 108.Bl -tag -width DIOCSDINFO____ 109.It Dv SCIOCRESET* 110Reset a device. 111.It Dv SCIOCDEBUG 112Turn on debugging. 113All scsi operations originating from this device's driver 114will be traced to the console, along with other information. 115Debugging is controlled by four bits, described in the header file. 116If no debugging is configured into the kernel, debugging will have 117no effect. 118.Em SCSI 119debugging is controlled by the configuration option 120.Em SCSIDEBUG . 121.It Dv SCIOCCOMMAND 122Take a scsi command and data from a user process and apply them to the scsi 123device. 124Return all status information and return data to the process. 125The ioctl will return a successful status even if the device rejected the 126command. 127As all status is returned to the user, it is up to the user 128process to examine this information to decide the success of the command. 129.It Dv SCIOCIDENTIFY 130Ask the driver what its bus, target and lun are. 131In addition, the device type, ATAPI or SCSI, is returned. 132.El 133.Sh ADAPTERS 134The system allows common device drivers to work through many different 135types of adapters. 136The adapters take requests from the upper layers and do all I/O between the 137.Em SCSI 138bus and the system. 139The maximum size of a transfer is governed by the adapter. 140Most adapters can transfer 64KB in a single operation, and many can transfer 141larger amounts. 142.Sh DIAGNOSTICS 143When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 144can be used to enable various amounts of tracing information on any 145specific device. 146Devices not being traced will not produce trace information. 147The four bits that make up the debug level each control certain types 148of debugging information. 149.Bl -tag -width "Bit 0" 150.It Dv Bit 0 151shows all scsi bus operations including scsi commands, 152error information and the first 48 bytes of any data transferred. 153.It Dv Bit 1 154shows routines called. 155.It Dv Bit 2 156shows information about what branches are taken and often some 157of the return values of functions. 158.It Dv Bit 3 159shows more detailed information including DMA scatter-gather logs. 160.El 161.Sh SEE ALSO 162.Xr cd 4 , 163.Xr ch 4 , 164.Xr intro 4 , 165.Xr safte 4 , 166.Xr sd 4 , 167.Xr ses 4 , 168.Xr ss 4 , 169.Xr st 4 , 170.Xr uk 4 , 171.Xr scsi 8 172.Sh HISTORY 173This 174.Nm 175system appeared in MACH 2.5 at TRW. 176