projects/linux·blob master · refs

336 lines · 9.4 KiB

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