Documentation/driver-api/scsi.rst

   1 =====================
   2 SCSI Interfaces Guide
   3 =====================
   4
   5 :Author: James Bottomley
   6 :Author: Rob Landley
   7
   8 Introduction
   9 ============
  10
  11 Protocol vs bus
  12 ---------------
  13
  14 Once upon a time, the Small Computer Systems Interface defined both a
  15 parallel I/O bus and a data protocol to connect a wide variety of
  16 peripherals (disk drives, tape drives, modems, printers, scanners,
  17 optical drives, test equipment, and medical devices) to a host computer.
  18
  19 Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
  20 out of use, the SCSI command set is more widely used than ever to
  21 communicate with devices over a number of different busses.
  22
  23 The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
  24 peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
  25 bytes long, often followed by an associated data payload.
  26
  27 SCSI commands can be transported over just about any kind of bus, and
  28 are the default protocol for storage devices attached to USB, SATA, SAS,
  29 Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also
  30 commonly exchanged over Infiniband,
  31 `I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
  32 (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
  33 ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
  34
  35 Design of the Linux SCSI subsystem
  36 ----------------------------------
  37
  38 The SCSI subsystem uses a three layer design, with upper, mid, and low
  39 layers. Every operation involving the SCSI subsystem (such as reading a
  40 sector from a disk) uses one driver at each of the 3 levels: one upper
  41 layer driver, one lower layer driver, and the SCSI midlayer.
  42
  43 The SCSI upper layer provides the interface between userspace and the
  44 kernel, in the form of block and char device nodes for I/O and ioctl().
  45 The SCSI lower layer contains drivers for specific hardware devices.
  46
  47 In between is the SCSI mid-layer, analogous to a network routing layer
  48 such as the IPv4 stack. The SCSI mid-layer routes a packet based data
  49 protocol between the upper layer's /dev nodes and the corresponding
  50 devices in the lower layer. It manages command queues, provides error
  51 handling and power management functions, and responds to ioctl()
  52 requests.
  53
  54 SCSI upper layer
  55 ================
  56
  57 The upper layer supports the user-kernel interface by providing device
  58 nodes.
  59
  60 sd (SCSI Disk)
  61 --------------
  62
  63 sd (sd_mod.o)
  64
  65 sr (SCSI CD-ROM)
  66 ----------------
  67
  68 sr (sr_mod.o)
  69
  70 st (SCSI Tape)
  71 --------------
  72
  73 st (st.o)
  74
  75 sg (SCSI Generic)
  76 -----------------
  77
  78 sg (sg.o)
  79
  80 ch (SCSI Media Changer)
  81 -----------------------
  82
  83 ch (ch.c)
  84
  85 SCSI mid layer
  86 ==============
  87
  88 SCSI midlayer implementation
  89 ----------------------------
  90
  91 include/scsi/scsi_device.h
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94 .. kernel-doc:: include/scsi/scsi_device.h
  95    :internal:
  96
  97 drivers/scsi/scsi.c
  98 ~~~~~~~~~~~~~~~~~~~
  99
 100 Main file for the SCSI midlayer.
 101
 102 .. kernel-doc:: drivers/scsi/scsi.c
 103    :export:
 104
 105 drivers/scsi/scsicam.c
 106 ~~~~~~~~~~~~~~~~~~~~~~
 107
 108 `SCSI Common Access
 109 Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
 110 functions, for use with HDIO_GETGEO, etc.
 111
 112 .. kernel-doc:: drivers/scsi/scsicam.c
 113    :export:
 114
 115 drivers/scsi/scsi_error.c
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 Common SCSI error/timeout handling routines.
 119
 120 .. kernel-doc:: drivers/scsi/scsi_error.c
 121    :export:
 122
 123 drivers/scsi/scsi_devinfo.c
 124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 125
 126 Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
 127 devices.
 128
 129 .. kernel-doc:: drivers/scsi/scsi_devinfo.c
 130    :internal:
 131
 132 drivers/scsi/scsi_ioctl.c
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 134
 135 Handle ioctl() calls for SCSI devices.
 136
 137 .. kernel-doc:: drivers/scsi/scsi_ioctl.c
 138    :export:
 139
 140 drivers/scsi/scsi_lib.c
 141 ~~~~~~~~~~~~~~~~~~~~~~~~
 142
 143 SCSI queuing library.
 144
 145 .. kernel-doc:: drivers/scsi/scsi_lib.c
 146    :export:
 147
 148 drivers/scsi/scsi_lib_dma.c
 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 150
 151 SCSI library functions depending on DMA (map and unmap scatter-gather
 152 lists).
 153
 154 .. kernel-doc:: drivers/scsi/scsi_lib_dma.c
 155    :export:
 156
 157 drivers/scsi/scsi_proc.c
 158 ~~~~~~~~~~~~~~~~~~~~~~~~~
 159
 160 The functions in this file provide an interface between the PROC file
 161 system and the SCSI device drivers It is mainly used for debugging,
 162 statistics and to pass information directly to the lowlevel driver. I.E.
 163 plumbing to manage /proc/scsi/\*
 164
 165 .. kernel-doc:: drivers/scsi/scsi_proc.c
 166    :internal:
 167
 168 drivers/scsi/scsi_netlink.c
 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 170
 171 Infrastructure to provide async events from transports to userspace via
 172 netlink, using a single NETLINK_SCSITRANSPORT protocol for all
 173 transports. See `the original patch
 174 submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
 175 more details.
 176
 177 .. kernel-doc:: drivers/scsi/scsi_netlink.c
 178    :internal:
 179
 180 drivers/scsi/scsi_scan.c
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 Scan a host to determine which (if any) devices are attached. The
 184 general scanning/probing algorithm is as follows, exceptions are made to
 185 it depending on device specific flags, compilation options, and global
 186 variable (boot or module load time) settings. A specific LUN is scanned
 187 via an INQUIRY command; if the LUN has a device attached, a scsi_device
 188 is allocated and setup for it. For every id of every channel on the
 189 given host, start by scanning LUN 0. Skip hosts that don't respond at
 190 all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached,
 191 allocate and setup a scsi_device for it. If target is SCSI-3 or up,
 192 issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN;
 193 else, sequentially scan LUNs up until some maximum is reached, or a LUN
 194 is seen that cannot have a device attached to it.
 195
 196 .. kernel-doc:: drivers/scsi/scsi_scan.c
 197    :internal:
 198
 199 drivers/scsi/scsi_sysctl.c
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 Set up the sysctl entry: "/dev/scsi/logging_level"
 203 (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
 204
 205 drivers/scsi/scsi_sysfs.c
 206 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 207
 208 SCSI sysfs interface routines.
 209
 210 .. kernel-doc:: drivers/scsi/scsi_sysfs.c
 211    :export:
 212
 213 drivers/scsi/hosts.c
 214 ~~~~~~~~~~~~~~~~~~~~
 215
 216 mid to lowlevel SCSI driver interface
 217
 218 .. kernel-doc:: drivers/scsi/hosts.c
 219    :export:
 220
 221 drivers/scsi/scsi_common.c
 222 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 223
 224 general support functions
 225
 226 .. kernel-doc:: drivers/scsi/scsi_common.c
 227    :export:
 228
 229 Transport classes
 230 -----------------
 231
 232 Transport classes are service libraries for drivers in the SCSI lower
 233 layer, which expose transport attributes in sysfs.
 234
 235 Fibre Channel transport
 236 ~~~~~~~~~~~~~~~~~~~~~~~
 237
 238 The file drivers/scsi/scsi_transport_fc.c defines transport attributes
 239 for Fibre Channel.
 240
 241 .. kernel-doc:: drivers/scsi/scsi_transport_fc.c
 242    :export:
 243
 244 iSCSI transport class
 245 ~~~~~~~~~~~~~~~~~~~~~
 246
 247 The file drivers/scsi/scsi_transport_iscsi.c defines transport
 248 attributes for the iSCSI class, which sends SCSI packets over TCP/IP
 249 connections.
 250
 251 .. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
 252    :export:
 253
 254 Serial Attached SCSI (SAS) transport class
 255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 256
 257 The file drivers/scsi/scsi_transport_sas.c defines transport
 258 attributes for Serial Attached SCSI, a variant of SATA aimed at large
 259 high-end systems.
 260
 261 The SAS transport class contains common code to deal with SAS HBAs, an
 262 aproximated representation of SAS topologies in the driver model, and
 263 various sysfs attributes to expose these topologies and management
 264 interfaces to userspace.
 265
 266 In addition to the basic SCSI core objects this transport class
 267 introduces two additional intermediate objects: The SAS PHY as
 268 represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
 269 Expander, and the SAS remote PHY represented by struct sas_rphy defines
 270 an "incoming" PHY on a SAS Expander or end device. Note that this is
 271 purely a software concept, the underlying hardware for a PHY and a
 272 remote PHY is the exactly the same.
 273
 274 There is no concept of a SAS port in this code, users can see what PHYs
 275 form a wide port based on the port_identifier attribute, which is the
 276 same for all PHYs in a port.
 277
 278 .. kernel-doc:: drivers/scsi/scsi_transport_sas.c
 279    :export:
 280
 281 SATA transport class
 282 ~~~~~~~~~~~~~~~~~~~~
 283
 284 The SATA transport is handled by libata, which has its own book of
 285 documentation in this directory.
 286
 287 Parallel SCSI (SPI) transport class
 288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 289
 290 The file drivers/scsi/scsi_transport_spi.c defines transport
 291 attributes for traditional (fast/wide/ultra) SCSI busses.
 292
 293 .. kernel-doc:: drivers/scsi/scsi_transport_spi.c
 294    :export:
 295
 296 SCSI RDMA (SRP) transport class
 297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 298
 299 The file drivers/scsi/scsi_transport_srp.c defines transport
 300 attributes for SCSI over Remote Direct Memory Access.
 301
 302 .. kernel-doc:: drivers/scsi/scsi_transport_srp.c
 303    :export:
 304
 305 SCSI lower layer
 306 ================
 307
 308 Host Bus Adapter transport types
 309 --------------------------------
 310
 311 Many modern device controllers use the SCSI command set as a protocol to
 312 communicate with their devices through many different types of physical
 313 connections.
 314
 315 In SCSI language a bus capable of carrying SCSI commands is called a
 316 "transport", and a controller connecting to such a bus is called a "host
 317 bus adapter" (HBA).
 318
 319 Debug transport
 320 ~~~~~~~~~~~~~~~
 321
 322 The file drivers/scsi/scsi_debug.c simulates a host adapter with a
 323 variable number of disks (or disk like devices) attached, sharing a
 324 common amount of RAM. Does a lot of checking to make sure that we are
 325 not getting blocks mixed up, and panics the kernel if anything out of
 326 the ordinary is seen.
 327
 328 To be more realistic, the simulated devices have the transport
 329 attributes of SAS disks.
 330
 331 For documentation see http://sg.danny.cz/sg/sdebug26.html
 332
 333 todo
 334 ~~~~
 335
 336 Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
 337 FireWire, ATAPI devices, Infiniband, I2O, iSCSI, Parallel ports,
 338 netlink...