1.\" $Id: scsi.4,v 1.5 1996/09/23 22:23:33 wosch 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 SD 4 29.Os FreeBSD 30.Sh NAME 31.Nm scsi 32.Nd scsi system 33.Sh SYNOPSIS 34.Nm controller scbus0 35.Nm controller scbus1 at ahc0 36.Nm controller scbus3 at ahc1 bus 0 37.Nm controller scbus2 at ahc1 bus 1 38.Nm device cd0 39.Nm device ch0 40.Nm disk sd0 41.Nm tape st0 42.Nm device ch1 at scbus0 target 4 unit 0 43.Sh DESCRIPTION 44The 45.Em scsi 46system provides a uniform and modular system for the implementation 47of drivers to control various scsi devices, and to utilize different 48scsi host adapters through host adapter drivers. When the system probes the 49.Em SCSI 50busses, it attaches any devices it finds to the appropriate 51drivers. If no driver seems appropriate, then it attaches the device to the 52uk (unknown) driver so that user level scsi ioctls may 53still be performed against the device. 54.Sh KERNEL CONFIGURATION 55The option SCSIDEBUG enables the debug ioctl. 56.Pp 57All devices and the SCSI busses support boot time allocation so that 58an upper number of devices and controllers does not need to be configured; 59.Em "device sd0" 60will suffice for any number of disk drivers. 61.Pp 62The devices are either 63.Em wired 64so they appear as a particular device unit or 65.Em counted 66so that they appear as the next available unused unit. 67.Pp 68To configure a driver in the kernel without wiring down the device use a 69config line similar to 70.Em "device ch0" 71to include the changer driver. 72.Pp 73To wire down a unit use a config line similar to 74.Em "device ch1 at scbus0 target 4 unit 0" 75to assign changer 1 as the changer with SCSI ID 4, 76SCSI logical unit 0 on SCSI bus 0. 77Individual scbuses can be wired down to specific controllers with 78a config line similar to 79.Em "controller scbus0 at ahc0" 80which assigns scsi bus 0 to the first unit using the ahc driver. 81For controllers supporting more than one bus, 82the particular bus can be specified as in 83.Em "controller scbus3 at ahc1 bus 1" 84which assigns scbus 1 to the second bus probed on the ahc1 device. 85.Pp 86When you have a mixture of wired down and counted devices then the 87counting begins with the first non-wired down unit for a particular 88type. That is, if you have a disk wired down as 89.Em "disk sd1" , 90then the first non-wired disk shall come on line as 91.Em sd2 . 92.Sh IOCTLS 93There are a number of ioctls that work on any 94.Em SCSI 95device. They are defined in 96.Em sys/scsiio.h 97and can be applied against any scsi device that permits them. 98For the tape, it must be applied against the control 99device. See the manual page for each device type for more information about 100how generic scsi ioctls may be applied to a specific device. 101.Bl -tag -width DIOCSDINFO____ 102.It Dv SCIOCRESET* 103reset a device. 104.It Dv SCIOCDEBUG 105Turn on debugging.. All scsi operations originating from this device's driver 106will be traced to the console, along with other information. Debugging is 107controlled by four bits, described in the header file. If no debugging is 108configured into the kernel, debugging will have no effect. 109.Em SCSI 110debugging is controlled by the configuration option 111.Em SCSIDEBUG. 112.It Dv SCIOCCOMMAND 113Take a scsi command and data from a user process and apply them to the scsi 114device. Return all status information and return data to the process. The 115ioctl will return a successful status even if the device rejected the 116command. As all status is returned to the user, it is up to the user 117process to examine this information to decide the success of the command. 118.It Dv SCIOCREPROBE 119Ask the system to probe the scsi busses for any new devices. If it finds 120any, they will be attached to the appropriate drivers. The search can be 121narrowed to a specific bus, target or lun. The new device may or may not 122be related to the device on which the ioctl was performed. 123.It Dv SCIOCIDENTIFY 124Ask the driver what it's bus, target and lun are. 125.It Dv SCIOCDECONFIG 126Ask the device to disappear. This may not happen if the device is in use. 127.El 128.Sh NOTES 129the generic scsi part of the system is still being mapped out. 130Watch this space for changes. 131.Pp 132 A device by the name of su (scsi_user) 133(e.g su0-0-0) will map bus, target and lun to minor numbers. I have not 134yet decided yet whether this device will be able to open a device that is 135already controlled by an explicit driver. 136.Sh ADAPTERS 137The system allows common device drivers to work through many different 138types of adapters. The adapters take requests from the upper layers and do 139all IO between the 140.Em SCSI 141bus and the system. The maximum size of a transfer is governed by the 142adapter. Most adapters can transfer 64KB in a single operation, however 143many can transfer larger amounts. 144.Sh TARGET MODE 145Some adapters support 146.Em Target mode 147in which the system is capable of operating as a device, responding to 148operations initiated by another system. Target mode will be supported for 149some adapters, but is not yet complete for this version of the scsi system. 150.Sh FILES 151see other scsi device entries. 152.Sh DIAGNOSTICS 153When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 154can be used to enable various amounts of tracing information on any 155specific device. Devices not being traced will not produce trace information. 156The four bits that make up the debug level, each control certain types 157of debugging information. 158.Bl -tag -width THIS_WIDE_PLEASE 159.It Dv Bit 0 160Bit 0 shows all scsi bus operations including scsi commands, 161error information and the first 48 bytes of any data transferred. 162.It Dv Bit 1 163Bit 1 shows routines called. 164.It Dv Bit 2 165Bit 2 shows information about what branches are taken and often some 166of the return values of functions. 167.It Dv Bit 3 168Bit 3 shows more detailed information including DMA scatter-gather logs. 169.El 170.Sh SEE ALSO 171.Xr ch 4 , 172.Xr cd 4 , 173.Xr sd 4 , 174.Xr st 4 , 175.Xr uk 4 , 176.Xr su 4 , 177.Xr aha 4 , 178.Xr ahb 4 , 179.Xr bt 4 , 180.Xr uha 4 181.Sh HISTORY 182This 183.Nm 184system appeared in MACH 2.5 at TRW. 185 186