share/man/man4/scsi.4

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