Commit | Line | Data |
---|---|---|
60202365 MCC |
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, | |
9cb07248 | 31 | `I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP |
60202365 MCC |
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 | ||
60202365 MCC |
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 | ||
e8fd31c5 RD |
221 | drivers/scsi/scsi_common.c |
222 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
223 | ||
224 | general support functions | |
225 | ||
226 | .. kernel-doc:: drivers/scsi/scsi_common.c | |
227 | :export: | |
228 | ||
60202365 MCC |
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, | |
6a59fd77 | 337 | FireWire, ATAPI devices, Infiniband, I2O, Parallel ports, |
60202365 | 338 | netlink... |