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