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