Commit | Line | Data |
---|---|---|
0ec88413 MCC |
1 | ======================== |
2 | libATA Developer's Guide | |
3 | ======================== | |
4 | ||
5 | :Author: Jeff Garzik | |
6 | ||
7 | Introduction | |
8 | ============ | |
9 | ||
10 | libATA is a library used inside the Linux kernel to support ATA host | |
11 | controllers and devices. libATA provides an ATA driver API, class | |
12 | transports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA | |
13 | devices according to the T10 SAT specification. | |
14 | ||
15 | This Guide documents the libATA driver API, library functions, library | |
16 | internals, and a couple sample ATA low-level drivers. | |
17 | ||
18 | libata Driver API | |
19 | ================= | |
20 | ||
21 | struct ata_port_operations is defined for every low-level libata | |
22 | hardware driver, and it controls how the low-level driver interfaces | |
23 | with the ATA and SCSI layers. | |
24 | ||
25 | FIS-based drivers will hook into the system with ->qc_prep() and | |
26 | ->qc_issue() high-level hooks. Hardware which behaves in a manner | |
27 | similar to PCI IDE hardware may utilize several generic helpers, | |
28 | defining at a bare minimum the bus I/O addresses of the ATA shadow | |
29 | register blocks. | |
30 | ||
31 | struct ata_port_operations | |
32 | ---------------------------- | |
33 | ||
34 | Disable ATA port | |
35 | ~~~~~~~~~~~~~~~~ | |
36 | ||
37 | :: | |
38 | ||
39 | void (*port_disable) (struct ata_port *); | |
40 | ||
41 | ||
42 | Called from ata_bus_probe() error path, as well as when unregistering | |
43 | from the SCSI module (rmmod, hot unplug). This function should do | |
44 | whatever needs to be done to take the port out of use. In most cases, | |
45 | ata_port_disable() can be used as this hook. | |
46 | ||
47 | Called from ata_bus_probe() on a failed probe. Called from | |
48 | ata_scsi_release(). | |
49 | ||
50 | Post-IDENTIFY device configuration | |
51 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
52 | ||
53 | :: | |
54 | ||
55 | void (*dev_config) (struct ata_port *, struct ata_device *); | |
56 | ||
57 | ||
58 | Called after IDENTIFY [PACKET] DEVICE is issued to each device found. | |
59 | Typically used to apply device-specific fixups prior to issue of SET | |
60 | FEATURES - XFER MODE, and prior to operation. | |
61 | ||
62 | This entry may be specified as NULL in ata_port_operations. | |
63 | ||
64 | Set PIO/DMA mode | |
65 | ~~~~~~~~~~~~~~~~ | |
66 | ||
67 | :: | |
68 | ||
69 | void (*set_piomode) (struct ata_port *, struct ata_device *); | |
70 | void (*set_dmamode) (struct ata_port *, struct ata_device *); | |
71 | void (*post_set_mode) (struct ata_port *); | |
72 | unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); | |
73 | ||
74 | ||
75 | Hooks called prior to the issue of SET FEATURES - XFER MODE command. The | |
76 | optional ->mode_filter() hook is called when libata has built a mask of | |
77 | the possible modes. This is passed to the ->mode_filter() function | |
78 | which should return a mask of valid modes after filtering those | |
79 | unsuitable due to hardware limits. It is not valid to use this interface | |
80 | to add modes. | |
81 | ||
82 | dev->pio_mode and dev->dma_mode are guaranteed to be valid when | |
83 | ->set_piomode() and when ->set_dmamode() is called. The timings for | |
84 | any other drive sharing the cable will also be valid at this point. That | |
85 | is the library records the decisions for the modes of each drive on a | |
86 | channel before it attempts to set any of them. | |
87 | ||
88 | ->post_set_mode() is called unconditionally, after the SET FEATURES - | |
89 | XFER MODE command completes successfully. | |
90 | ||
91 | ->set_piomode() is always called (if present), but ->set_dma_mode() | |
92 | is only called if DMA is possible. | |
93 | ||
94 | Taskfile read/write | |
95 | ~~~~~~~~~~~~~~~~~~~ | |
96 | ||
97 | :: | |
98 | ||
99 | void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); | |
100 | void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); | |
101 | ||
102 | ||
103 | ->tf_load() is called to load the given taskfile into hardware | |
104 | registers / DMA buffers. ->tf_read() is called to read the hardware | |
105 | registers / DMA buffers, to obtain the current set of taskfile register | |
106 | values. Most drivers for taskfile-based hardware (PIO or MMIO) use | |
107 | ata_sff_tf_load() and ata_sff_tf_read() for these hooks. | |
108 | ||
109 | PIO data read/write | |
110 | ~~~~~~~~~~~~~~~~~~~ | |
111 | ||
112 | :: | |
113 | ||
114 | void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); | |
115 | ||
116 | ||
117 | All bmdma-style drivers must implement this hook. This is the low-level | |
118 | operation that actually copies the data bytes during a PIO data | |
119 | transfer. Typically the driver will choose one of | |
120 | ata_sff_data_xfer_noirq(), ata_sff_data_xfer(), or | |
121 | ata_sff_data_xfer32(). | |
122 | ||
123 | ATA command execute | |
124 | ~~~~~~~~~~~~~~~~~~~ | |
125 | ||
126 | :: | |
127 | ||
128 | void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); | |
129 | ||
130 | ||
131 | causes an ATA command, previously loaded with ->tf_load(), to be | |
132 | initiated in hardware. Most drivers for taskfile-based hardware use | |
133 | ata_sff_exec_command() for this hook. | |
134 | ||
135 | Per-cmd ATAPI DMA capabilities filter | |
136 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
137 | ||
138 | :: | |
139 | ||
140 | int (*check_atapi_dma) (struct ata_queued_cmd *qc); | |
141 | ||
142 | ||
143 | Allow low-level driver to filter ATA PACKET commands, returning a status | |
144 | indicating whether or not it is OK to use DMA for the supplied PACKET | |
145 | command. | |
146 | ||
147 | This hook may be specified as NULL, in which case libata will assume | |
148 | that atapi dma can be supported. | |
149 | ||
150 | Read specific ATA shadow registers | |
151 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
152 | ||
153 | :: | |
154 | ||
155 | u8 (*sff_check_status)(struct ata_port *ap); | |
156 | u8 (*sff_check_altstatus)(struct ata_port *ap); | |
157 | ||
158 | ||
159 | Reads the Status/AltStatus ATA shadow register from hardware. On some | |
160 | hardware, reading the Status register has the side effect of clearing | |
161 | the interrupt condition. Most drivers for taskfile-based hardware use | |
162 | ata_sff_check_status() for this hook. | |
163 | ||
164 | Write specific ATA shadow register | |
165 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
166 | ||
167 | :: | |
168 | ||
169 | void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); | |
170 | ||
171 | ||
172 | Write the device control ATA shadow register to the hardware. Most | |
173 | drivers don't need to define this. | |
174 | ||
175 | Select ATA device on bus | |
176 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
177 | ||
178 | :: | |
179 | ||
180 | void (*sff_dev_select)(struct ata_port *ap, unsigned int device); | |
181 | ||
182 | ||
183 | Issues the low-level hardware command(s) that causes one of N hardware | |
184 | devices to be considered 'selected' (active and available for use) on | |
185 | the ATA bus. This generally has no meaning on FIS-based devices. | |
186 | ||
187 | Most drivers for taskfile-based hardware use ata_sff_dev_select() for | |
188 | this hook. | |
189 | ||
190 | Private tuning method | |
191 | ~~~~~~~~~~~~~~~~~~~~~ | |
192 | ||
193 | :: | |
194 | ||
195 | void (*set_mode) (struct ata_port *ap); | |
196 | ||
197 | ||
198 | By default libata performs drive and controller tuning in accordance | |
199 | with the ATA timing rules and also applies blacklists and cable limits. | |
200 | Some controllers need special handling and have custom tuning rules, | |
201 | typically raid controllers that use ATA commands but do not actually do | |
202 | drive timing. | |
203 | ||
204 | **Warning** | |
205 | ||
206 | This hook should not be used to replace the standard controller | |
207 | tuning logic when a controller has quirks. Replacing the default | |
208 | tuning logic in that case would bypass handling for drive and bridge | |
209 | quirks that may be important to data reliability. If a controller | |
210 | needs to filter the mode selection it should use the mode_filter | |
211 | hook instead. | |
212 | ||
213 | Control PCI IDE BMDMA engine | |
214 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
215 | ||
216 | :: | |
217 | ||
218 | void (*bmdma_setup) (struct ata_queued_cmd *qc); | |
219 | void (*bmdma_start) (struct ata_queued_cmd *qc); | |
220 | void (*bmdma_stop) (struct ata_port *ap); | |
221 | u8 (*bmdma_status) (struct ata_port *ap); | |
222 | ||
223 | ||
224 | When setting up an IDE BMDMA transaction, these hooks arm | |
225 | (->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the | |
226 | hardware's DMA engine. ->bmdma_status is used to read the standard PCI | |
227 | IDE DMA Status register. | |
228 | ||
229 | These hooks are typically either no-ops, or simply not implemented, in | |
230 | FIS-based drivers. | |
231 | ||
232 | Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() | |
233 | hook. ata_bmdma_setup() will write the pointer to the PRD table to the | |
234 | IDE PRD Table Address register, enable DMA in the DMA Command register, | |
235 | and call exec_command() to begin the transfer. | |
236 | ||
237 | Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() | |
238 | hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA | |
239 | Command register. | |
240 | ||
241 | Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() | |
242 | hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA | |
243 | command register. | |
244 | ||
245 | Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() | |
246 | hook. | |
247 | ||
248 | High-level taskfile hooks | |
249 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
250 | ||
251 | :: | |
252 | ||
253 | void (*qc_prep) (struct ata_queued_cmd *qc); | |
254 | int (*qc_issue) (struct ata_queued_cmd *qc); | |
255 | ||
256 | ||
257 | Higher-level hooks, these two hooks can potentially supercede several of | |
258 | the above taskfile/DMA engine hooks. ->qc_prep is called after the | |
259 | buffers have been DMA-mapped, and is typically used to populate the | |
260 | hardware's DMA scatter-gather table. Most drivers use the standard | |
261 | ata_qc_prep() helper function, but more advanced drivers roll their | |
262 | own. | |
263 | ||
264 | ->qc_issue is used to make a command active, once the hardware and S/G | |
265 | tables have been prepared. IDE BMDMA drivers use the helper function | |
266 | ata_qc_issue_prot() for taskfile protocol-based dispatch. More | |
267 | advanced drivers implement their own ->qc_issue. | |
268 | ||
269 | ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and | |
270 | ->bmdma_start() as necessary to initiate a transfer. | |
271 | ||
272 | Exception and probe handling (EH) | |
273 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
274 | ||
275 | :: | |
276 | ||
277 | void (*eng_timeout) (struct ata_port *ap); | |
278 | void (*phy_reset) (struct ata_port *ap); | |
279 | ||
280 | ||
281 | Deprecated. Use ->error_handler() instead. | |
282 | ||
283 | :: | |
284 | ||
285 | void (*freeze) (struct ata_port *ap); | |
286 | void (*thaw) (struct ata_port *ap); | |
287 | ||
288 | ||
289 | ata_port_freeze() is called when HSM violations or some other | |
290 | condition disrupts normal operation of the port. A frozen port is not | |
291 | allowed to perform any operation until the port is thawed, which usually | |
292 | follows a successful reset. | |
293 | ||
294 | The optional ->freeze() callback can be used for freezing the port | |
295 | hardware-wise (e.g. mask interrupt and stop DMA engine). If a port | |
296 | cannot be frozen hardware-wise, the interrupt handler must ack and clear | |
297 | interrupts unconditionally while the port is frozen. | |
298 | ||
299 | The optional ->thaw() callback is called to perform the opposite of | |
300 | ->freeze(): prepare the port for normal operation once again. Unmask | |
301 | interrupts, start DMA engine, etc. | |
302 | ||
303 | :: | |
304 | ||
305 | void (*error_handler) (struct ata_port *ap); | |
306 | ||
307 | ||
308 | ->error_handler() is a driver's hook into probe, hotplug, and recovery | |
309 | and other exceptional conditions. The primary responsibility of an | |
310 | implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with | |
311 | a set of EH hooks as arguments: | |
312 | ||
313 | 'prereset' hook (may be NULL) is called during an EH reset, before any | |
314 | other actions are taken. | |
315 | ||
316 | 'postreset' hook (may be NULL) is called after the EH reset is | |
317 | performed. Based on existing conditions, severity of the problem, and | |
318 | hardware capabilities, | |
319 | ||
320 | Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be | |
321 | called to perform the low-level EH reset. | |
322 | ||
323 | :: | |
324 | ||
325 | void (*post_internal_cmd) (struct ata_queued_cmd *qc); | |
326 | ||
327 | ||
328 | Perform any hardware-specific actions necessary to finish processing | |
329 | after executing a probe-time or EH-time command via | |
330 | ata_exec_internal(). | |
331 | ||
332 | Hardware interrupt handling | |
333 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
334 | ||
335 | :: | |
336 | ||
337 | irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); | |
338 | void (*irq_clear) (struct ata_port *); | |
339 | ||
340 | ||
341 | ->irq_handler is the interrupt handling routine registered with the | |
342 | system, by libata. ->irq_clear is called during probe just before the | |
343 | interrupt handler is registered, to be sure hardware is quiet. | |
344 | ||
345 | The second argument, dev_instance, should be cast to a pointer to | |
346 | struct ata_host_set. | |
347 | ||
348 | Most legacy IDE drivers use ata_sff_interrupt() for the irq_handler | |
349 | hook, which scans all ports in the host_set, determines which queued | |
350 | command was active (if any), and calls ata_sff_host_intr(ap,qc). | |
351 | ||
352 | Most legacy IDE drivers use ata_sff_irq_clear() for the irq_clear() | |
353 | hook, which simply clears the interrupt and error flags in the DMA | |
354 | status register. | |
355 | ||
356 | SATA phy read/write | |
357 | ~~~~~~~~~~~~~~~~~~~ | |
358 | ||
359 | :: | |
360 | ||
361 | int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, | |
362 | u32 *val); | |
363 | int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, | |
364 | u32 val); | |
365 | ||
366 | ||
367 | Read and write standard SATA phy registers. Currently only used if | |
368 | ->phy_reset hook called the sata_phy_reset() helper function. sc_reg | |
369 | is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. | |
370 | ||
371 | Init and shutdown | |
372 | ~~~~~~~~~~~~~~~~~ | |
373 | ||
374 | :: | |
375 | ||
376 | int (*port_start) (struct ata_port *ap); | |
377 | void (*port_stop) (struct ata_port *ap); | |
378 | void (*host_stop) (struct ata_host_set *host_set); | |
379 | ||
380 | ||
381 | ->port_start() is called just after the data structures for each port | |
382 | are initialized. Typically this is used to alloc per-port DMA buffers / | |
383 | tables / rings, enable DMA engines, and similar tasks. Some drivers also | |
384 | use this entry point as a chance to allocate driver-private memory for | |
385 | ap->private_data. | |
386 | ||
387 | Many drivers use ata_port_start() as this hook or call it from their | |
388 | own port_start() hooks. ata_port_start() allocates space for a legacy | |
389 | IDE PRD table and returns. | |
390 | ||
391 | ->port_stop() is called after ->host_stop(). Its sole function is to | |
392 | release DMA/memory resources, now that they are no longer actively being | |
393 | used. Many drivers also free driver-private data from port at this time. | |
394 | ||
395 | ->host_stop() is called after all ->port_stop() calls have completed. | |
396 | The hook must finalize hardware shutdown, release DMA and other | |
397 | resources, etc. This hook may be specified as NULL, in which case it is | |
398 | not called. | |
399 | ||
400 | Error handling | |
401 | ============== | |
402 | ||
403 | This chapter describes how errors are handled under libata. Readers are | |
404 | advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA | |
405 | exceptions doc first. | |
406 | ||
407 | Origins of commands | |
408 | ------------------- | |
409 | ||
410 | In libata, a command is represented with struct ata_queued_cmd or qc. | |
411 | qc's are preallocated during port initialization and repetitively used | |
412 | for command executions. Currently only one qc is allocated per port but | |
413 | yet-to-be-merged NCQ branch allocates one for each tag and maps each qc | |
414 | to NCQ tag 1-to-1. | |
415 | ||
416 | libata commands can originate from two sources - libata itself and SCSI | |
417 | midlayer. libata internal commands are used for initialization and error | |
418 | handling. All normal blk requests and commands for SCSI emulation are | |
419 | passed as SCSI commands through queuecommand callback of SCSI host | |
420 | template. | |
421 | ||
422 | How commands are issued | |
423 | ----------------------- | |
424 | ||
425 | Internal commands | |
426 | First, qc is allocated and initialized using ata_qc_new_init(). | |
427 | Although ata_qc_new_init() doesn't implement any wait or retry | |
428 | mechanism when qc is not available, internal commands are currently | |
429 | issued only during initialization and error recovery, so no other | |
430 | command is active and allocation is guaranteed to succeed. | |
431 | ||
432 | Once allocated qc's taskfile is initialized for the command to be | |
433 | executed. qc currently has two mechanisms to notify completion. One | |
434 | is via qc->complete_fn() callback and the other is completion | |
435 | qc->waiting. qc->complete_fn() callback is the asynchronous path | |
436 | used by normal SCSI translated commands and qc->waiting is the | |
437 | synchronous (issuer sleeps in process context) path used by internal | |
438 | commands. | |
439 | ||
440 | Once initialization is complete, host_set lock is acquired and the | |
441 | qc is issued. | |
442 | ||
443 | SCSI commands | |
444 | All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand | |
445 | callback. scmds can either be simulated or translated. No qc is | |
446 | involved in processing a simulated scmd. The result is computed | |
447 | right away and the scmd is completed. | |
448 | ||
449 | For a translated scmd, ata_qc_new_init() is invoked to allocate a | |
450 | qc and the scmd is translated into the qc. SCSI midlayer's | |
451 | completion notification function pointer is stored into | |
452 | qc->scsidone. | |
453 | ||
454 | qc->complete_fn() callback is used for completion notification. ATA | |
455 | commands use ata_scsi_qc_complete() while ATAPI commands use | |
456 | atapi_qc_complete(). Both functions end up calling qc->scsidone to | |
457 | notify upper layer when the qc is finished. After translation is | |
458 | completed, the qc is issued with ata_qc_issue(). | |
459 | ||
460 | Note that SCSI midlayer invokes hostt->queuecommand while holding | |
461 | host_set lock, so all above occur while holding host_set lock. | |
462 | ||
463 | How commands are processed | |
464 | -------------------------- | |
465 | ||
466 | Depending on which protocol and which controller are used, commands are | |
467 | processed differently. For the purpose of discussion, a controller which | |
468 | uses taskfile interface and all standard callbacks is assumed. | |
469 | ||
470 | Currently 6 ATA command protocols are used. They can be sorted into the | |
471 | following four categories according to how they are processed. | |
472 | ||
473 | ATA NO DATA or DMA | |
474 | ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. These | |
475 | types of commands don't require any software intervention once | |
476 | issued. Device will raise interrupt on completion. | |
477 | ||
478 | ATA PIO | |
479 | ATA_PROT_PIO is in this category. libata currently implements PIO | |
480 | with polling. ATA_NIEN bit is set to turn off interrupt and | |
481 | pio_task on ata_wq performs polling and IO. | |
482 | ||
483 | ATAPI NODATA or DMA | |
484 | ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this | |
485 | category. packet_task is used to poll BSY bit after issuing PACKET | |
486 | command. Once BSY is turned off by the device, packet_task | |
487 | transfers CDB and hands off processing to interrupt handler. | |
488 | ||
489 | ATAPI PIO | |
490 | ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as | |
491 | in ATAPI NODATA or DMA, packet_task submits cdb. However, after | |
492 | submitting cdb, further processing (data transfer) is handed off to | |
493 | pio_task. | |
494 | ||
495 | How commands are completed | |
496 | -------------------------- | |
497 | ||
498 | Once issued, all qc's are either completed with ata_qc_complete() or | |
499 | time out. For commands which are handled by interrupts, | |
500 | ata_host_intr() invokes ata_qc_complete(), and, for PIO tasks, | |
501 | pio_task invokes ata_qc_complete(). In error cases, packet_task may | |
502 | also complete commands. | |
503 | ||
504 | ata_qc_complete() does the following. | |
505 | ||
506 | 1. DMA memory is unmapped. | |
507 | ||
508 | 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. | |
509 | ||
510 | 3. qc->complete_fn() callback is invoked. If the return value of the | |
511 | callback is not zero. Completion is short circuited and | |
512 | ata_qc_complete() returns. | |
513 | ||
514 | 4. __ata_qc_complete() is called, which does | |
515 | ||
516 | 1. qc->flags is cleared to zero. | |
517 | ||
518 | 2. ap->active_tag and qc->tag are poisoned. | |
519 | ||
520 | 3. qc->waiting is cleared & completed (in that order). | |
521 | ||
522 | 4. qc is deallocated by clearing appropriate bit in ap->qactive. | |
523 | ||
524 | So, it basically notifies upper layer and deallocates qc. One exception | |
525 | is short-circuit path in #3 which is used by atapi_qc_complete(). | |
526 | ||
527 | For all non-ATAPI commands, whether it fails or not, almost the same | |
528 | code path is taken and very little error handling takes place. A qc is | |
529 | completed with success status if it succeeded, with failed status | |
530 | otherwise. | |
531 | ||
532 | However, failed ATAPI commands require more handling as REQUEST SENSE is | |
533 | needed to acquire sense data. If an ATAPI command fails, | |
534 | ata_qc_complete() is invoked with error status, which in turn invokes | |
535 | atapi_qc_complete() via qc->complete_fn() callback. | |
536 | ||
537 | This makes atapi_qc_complete() set scmd->result to | |
538 | SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the | |
539 | sense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer | |
540 | will invoke EH for the scmd, and returning 1 makes ata_qc_complete() | |
541 | to return without deallocating the qc. This leads us to | |
542 | ata_scsi_error() with partially completed qc. | |
543 | ||
544 | ata_scsi_error() | |
545 | ------------------ | |
546 | ||
547 | ata_scsi_error() is the current transportt->eh_strategy_handler() | |
548 | for libata. As discussed above, this will be entered in two cases - | |
549 | timeout and ATAPI error completion. This function calls low level libata | |
550 | driver's eng_timeout() callback, the standard callback for which is | |
551 | ata_eng_timeout(). It checks if a qc is active and calls | |
552 | ata_qc_timeout() on the qc if so. Actual error handling occurs in | |
553 | ata_qc_timeout(). | |
554 | ||
555 | If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and | |
556 | completes the qc. Note that as we're currently in EH, we cannot call | |
557 | scsi_done. As described in SCSI EH doc, a recovered scmd should be | |
558 | either retried with scsi_queue_insert() or finished with | |
559 | scsi_finish_command(). Here, we override qc->scsidone with | |
560 | scsi_finish_command() and calls ata_qc_complete(). | |
561 | ||
562 | If EH is invoked due to a failed ATAPI qc, the qc here is completed but | |
563 | not deallocated. The purpose of this half-completion is to use the qc as | |
564 | place holder to make EH code reach this place. This is a bit hackish, | |
565 | but it works. | |
566 | ||
567 | Once control reaches here, the qc is deallocated by invoking | |
568 | __ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE | |
569 | is issued. Once sense data is acquired, scmd is finished by directly | |
570 | invoking scsi_finish_command() on the scmd. Note that as we already | |
571 | have completed and deallocated the qc which was associated with the | |
572 | scmd, we don't need to/cannot call ata_qc_complete() again. | |
573 | ||
574 | Problems with the current EH | |
575 | ---------------------------- | |
576 | ||
577 | - Error representation is too crude. Currently any and all error | |
578 | conditions are represented with ATA STATUS and ERROR registers. | |
579 | Errors which aren't ATA device errors are treated as ATA device | |
580 | errors by setting ATA_ERR bit. Better error descriptor which can | |
581 | properly represent ATA and other errors/exceptions is needed. | |
582 | ||
583 | - When handling timeouts, no action is taken to make device forget | |
584 | about the timed out command and ready for new commands. | |
585 | ||
586 | - EH handling via ata_scsi_error() is not properly protected from | |
587 | usual command processing. On EH entrance, the device is not in | |
588 | quiescent state. Timed out commands may succeed or fail any time. | |
589 | pio_task and atapi_task may still be running. | |
590 | ||
591 | - Too weak error recovery. Devices / controllers causing HSM mismatch | |
592 | errors and other errors quite often require reset to return to known | |
593 | state. Also, advanced error handling is necessary to support features | |
594 | like NCQ and hotplug. | |
595 | ||
596 | - ATA errors are directly handled in the interrupt handler and PIO | |
597 | errors in pio_task. This is problematic for advanced error handling | |
598 | for the following reasons. | |
599 | ||
600 | First, advanced error handling often requires context and internal qc | |
601 | execution. | |
602 | ||
603 | Second, even a simple failure (say, CRC error) needs information | |
604 | gathering and could trigger complex error handling (say, resetting & | |
605 | reconfiguring). Having multiple code paths to gather information, | |
606 | enter EH and trigger actions makes life painful. | |
607 | ||
608 | Third, scattered EH code makes implementing low level drivers | |
609 | difficult. Low level drivers override libata callbacks. If EH is | |
610 | scattered over several places, each affected callbacks should perform | |
611 | its part of error handling. This can be error prone and painful. | |
612 | ||
613 | libata Library | |
614 | ============== | |
615 | ||
616 | .. kernel-doc:: drivers/ata/libata-core.c | |
617 | :export: | |
618 | ||
619 | libata Core Internals | |
620 | ===================== | |
621 | ||
622 | .. kernel-doc:: drivers/ata/libata-core.c | |
623 | :internal: | |
624 | ||
625 | libata SCSI translation/emulation | |
626 | ================================= | |
627 | ||
628 | .. kernel-doc:: drivers/ata/libata-scsi.c | |
629 | :export: | |
630 | ||
631 | .. kernel-doc:: drivers/ata/libata-scsi.c | |
632 | :internal: | |
633 | ||
634 | ATA errors and exceptions | |
635 | ========================= | |
636 | ||
637 | This chapter tries to identify what error/exception conditions exist for | |
638 | ATA/ATAPI devices and describe how they should be handled in | |
639 | implementation-neutral way. | |
640 | ||
641 | The term 'error' is used to describe conditions where either an explicit | |
642 | error condition is reported from device or a command has timed out. | |
643 | ||
644 | The term 'exception' is either used to describe exceptional conditions | |
645 | which are not errors (say, power or hotplug events), or to describe both | |
646 | errors and non-error exceptional conditions. Where explicit distinction | |
647 | between error and exception is necessary, the term 'non-error exception' | |
648 | is used. | |
649 | ||
650 | Exception categories | |
651 | -------------------- | |
652 | ||
653 | Exceptions are described primarily with respect to legacy taskfile + bus | |
654 | master IDE interface. If a controller provides other better mechanism | |
655 | for error reporting, mapping those into categories described below | |
656 | shouldn't be difficult. | |
657 | ||
658 | In the following sections, two recovery actions - reset and | |
659 | reconfiguring transport - are mentioned. These are described further in | |
660 | `EH recovery actions <#exrec>`__. | |
661 | ||
662 | HSM violation | |
663 | ~~~~~~~~~~~~~ | |
664 | ||
665 | This error is indicated when STATUS value doesn't match HSM requirement | |
666 | during issuing or execution any ATA/ATAPI command. | |
667 | ||
668 | - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to | |
669 | issue a command. | |
670 | ||
671 | - !BSY && !DRQ during PIO data transfer. | |
672 | ||
673 | - DRQ on command completion. | |
674 | ||
675 | - !BSY && ERR after CDB transfer starts but before the last byte of CDB | |
676 | is transferred. ATA/ATAPI standard states that "The device shall not | |
677 | terminate the PACKET command with an error before the last byte of | |
678 | the command packet has been written" in the error outputs description | |
679 | of PACKET command and the state diagram doesn't include such | |
680 | transitions. | |
681 | ||
682 | In these cases, HSM is violated and not much information regarding the | |
683 | error can be acquired from STATUS or ERROR register. IOW, this error can | |
684 | be anything - driver bug, faulty device, controller and/or cable. | |
685 | ||
686 | As HSM is violated, reset is necessary to restore known state. | |
687 | Reconfiguring transport for lower speed might be helpful too as | |
688 | transmission errors sometimes cause this kind of errors. | |
689 | ||
690 | ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) | |
691 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
692 | ||
693 | These are errors detected and reported by ATA/ATAPI devices indicating | |
694 | device problems. For this type of errors, STATUS and ERROR register | |
695 | values are valid and describe error condition. Note that some of ATA bus | |
696 | errors are detected by ATA/ATAPI devices and reported using the same | |
697 | mechanism as device errors. Those cases are described later in this | |
698 | section. | |
699 | ||
700 | For ATA commands, this type of errors are indicated by !BSY && ERR | |
701 | during command execution and on completion. | |
702 | ||
703 | For ATAPI commands, | |
704 | ||
705 | - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET | |
706 | command is not supported and falls in this category. | |
707 | ||
708 | - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred | |
709 | indicates CHECK CONDITION and doesn't fall in this category. | |
710 | ||
711 | - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred | |
712 | \*probably\* indicates CHECK CONDITION and doesn't fall in this | |
713 | category. | |
714 | ||
715 | Of errors detected as above, the following are not ATA/ATAPI device | |
716 | errors but ATA bus errors and should be handled according to | |
717 | `ATA bus error <#excatATAbusErr>`__. | |
718 | ||
719 | CRC error during data transfer | |
720 | This is indicated by ICRC bit in the ERROR register and means that | |
721 | corruption occurred during data transfer. Up to ATA/ATAPI-7, the | |
722 | standard specifies that this bit is only applicable to UDMA | |
723 | transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be | |
724 | applicable to multiword DMA and PIO. | |
725 | ||
726 | ABRT error during data transfer or on completion | |
727 | Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on | |
728 | ICRC errors and on cases where a device is not able to complete a | |
729 | command. Combined with the fact that MWDMA and PIO transfer errors | |
730 | aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply | |
731 | that ABRT bit alone could indicate transfer errors. | |
732 | ||
733 | However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC | |
734 | errors can turn on ABRT. So, this is kind of gray area. Some | |
735 | heuristics are needed here. | |
736 | ||
737 | ATA/ATAPI device errors can be further categorized as follows. | |
738 | ||
739 | Media errors | |
740 | This is indicated by UNC bit in the ERROR register. ATA devices | |
741 | reports UNC error only after certain number of retries cannot | |
742 | recover the data, so there's nothing much else to do other than | |
743 | notifying upper layer. | |
744 | ||
745 | READ and WRITE commands report CHS or LBA of the first failed sector | |
746 | but ATA/ATAPI standard specifies that the amount of transferred data | |
747 | on error completion is indeterminate, so we cannot assume that | |
748 | sectors preceding the failed sector have been transferred and thus | |
749 | cannot complete those sectors successfully as SCSI does. | |
750 | ||
751 | Media changed / media change requested error | |
752 | <<TODO: fill here>> | |
753 | ||
754 | Address error | |
755 | This is indicated by IDNF bit in the ERROR register. Report to upper | |
756 | layer. | |
757 | ||
758 | Other errors | |
759 | This can be invalid command or parameter indicated by ABRT ERROR bit | |
760 | or some other error condition. Note that ABRT bit can indicate a lot | |
761 | of things including ICRC and Address errors. Heuristics needed. | |
762 | ||
763 | Depending on commands, not all STATUS/ERROR bits are applicable. These | |
764 | non-applicable bits are marked with "na" in the output descriptions but | |
765 | up to ATA/ATAPI-7 no definition of "na" can be found. However, | |
766 | ATA/ATAPI-8 draft revision 1f describes "N/A" as follows. | |
767 | ||
768 | 3.2.3.3a N/A | |
769 | A keyword the indicates a field has no defined value in this | |
770 | standard and should not be checked by the host or device. N/A | |
771 | fields should be cleared to zero. | |
772 | ||
773 | So, it seems reasonable to assume that "na" bits are cleared to zero by | |
774 | devices and thus need no explicit masking. | |
775 | ||
776 | ATAPI device CHECK CONDITION | |
777 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
778 | ||
779 | ATAPI device CHECK CONDITION error is indicated by set CHK bit (ERR bit) | |
780 | in the STATUS register after the last byte of CDB is transferred for a | |
781 | PACKET command. For this kind of errors, sense data should be acquired | |
782 | to gather information regarding the errors. REQUEST SENSE packet command | |
783 | should be used to acquire sense data. | |
784 | ||
785 | Once sense data is acquired, this type of errors can be handled | |
786 | similarly to other SCSI errors. Note that sense data may indicate ATA | |
787 | bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI | |
788 | PARITY ERROR). In such cases, the error should be considered as an ATA | |
789 | bus error and handled according to `ATA bus error <#excatATAbusErr>`__. | |
790 | ||
791 | ATA device error (NCQ) | |
792 | ~~~~~~~~~~~~~~~~~~~~~~ | |
793 | ||
794 | NCQ command error is indicated by cleared BSY and set ERR bit during NCQ | |
795 | command phase (one or more NCQ commands outstanding). Although STATUS | |
796 | and ERROR registers will contain valid values describing the error, READ | |
797 | LOG EXT is required to clear the error condition, determine which | |
798 | command has failed and acquire more information. | |
799 | ||
800 | READ LOG EXT Log Page 10h reports which tag has failed and taskfile | |
801 | register values describing the error. With this information the failed | |
802 | command can be handled as a normal ATA command error as in | |
803 | `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__ | |
804 | and all other in-flight commands must be retried. Note that this retry | |
805 | should not be counted - it's likely that commands retried this way would | |
806 | have completed normally if it were not for the failed command. | |
807 | ||
808 | Note that ATA bus errors can be reported as ATA device NCQ errors. This | |
809 | should be handled as described in `ATA bus error <#excatATAbusErr>`__. | |
810 | ||
811 | If READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly | |
812 | screwed. This condition should be treated according to | |
813 | `HSM violation <#excatHSMviolation>`__. | |
814 | ||
815 | ATA bus error | |
816 | ~~~~~~~~~~~~~ | |
817 | ||
818 | ATA bus error means that data corruption occurred during transmission | |
819 | over ATA bus (SATA or PATA). This type of errors can be indicated by | |
820 | ||
821 | - ICRC or ABRT error as described in | |
822 | `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__. | |
823 | ||
824 | - Controller-specific error completion with error information | |
825 | indicating transmission error. | |
826 | ||
827 | - On some controllers, command timeout. In this case, there may be a | |
828 | mechanism to determine that the timeout is due to transmission error. | |
829 | ||
830 | - Unknown/random errors, timeouts and all sorts of weirdities. | |
831 | ||
832 | As described above, transmission errors can cause wide variety of | |
833 | symptoms ranging from device ICRC error to random device lockup, and, | |
834 | for many cases, there is no way to tell if an error condition is due to | |
835 | transmission error or not; therefore, it's necessary to employ some kind | |
836 | of heuristic when dealing with errors and timeouts. For example, | |
837 | encountering repetitive ABRT errors for known supported command is | |
838 | likely to indicate ATA bus error. | |
839 | ||
840 | Once it's determined that ATA bus errors have possibly occurred, | |
841 | lowering ATA bus transmission speed is one of actions which may | |
842 | alleviate the problem. See `Reconfigure transport <#exrecReconf>`__ for | |
843 | more information. | |
844 | ||
845 | PCI bus error | |
846 | ~~~~~~~~~~~~~ | |
847 | ||
848 | Data corruption or other failures during transmission over PCI (or other | |
849 | system bus). For standard BMDMA, this is indicated by Error bit in the | |
850 | BMDMA Status register. This type of errors must be logged as it | |
851 | indicates something is very wrong with the system. Resetting host | |
852 | controller is recommended. | |
853 | ||
854 | Late completion | |
855 | ~~~~~~~~~~~~~~~ | |
856 | ||
857 | This occurs when timeout occurs and the timeout handler finds out that | |
858 | the timed out command has completed successfully or with error. This is | |
859 | usually caused by lost interrupts. This type of errors must be logged. | |
860 | Resetting host controller is recommended. | |
861 | ||
862 | Unknown error (timeout) | |
863 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
864 | ||
865 | This is when timeout occurs and the command is still processing or the | |
866 | host and device are in unknown state. When this occurs, HSM could be in | |
867 | any valid or invalid state. To bring the device to known state and make | |
868 | it forget about the timed out command, resetting is necessary. The timed | |
869 | out command may be retried. | |
870 | ||
871 | Timeouts can also be caused by transmission errors. Refer to | |
872 | `ATA bus error <#excatATAbusErr>`__ for more details. | |
873 | ||
874 | Hotplug and power management exceptions | |
875 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
876 | ||
877 | <<TODO: fill here>> | |
878 | ||
879 | EH recovery actions | |
880 | ------------------- | |
881 | ||
882 | This section discusses several important recovery actions. | |
883 | ||
884 | Clearing error condition | |
885 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
886 | ||
887 | Many controllers require its error registers to be cleared by error | |
888 | handler. Different controllers may have different requirements. | |
889 | ||
890 | For SATA, it's strongly recommended to clear at least SError register | |
891 | during error handling. | |
892 | ||
893 | Reset | |
894 | ~~~~~ | |
895 | ||
896 | During EH, resetting is necessary in the following cases. | |
897 | ||
898 | - HSM is in unknown or invalid state | |
899 | ||
900 | - HBA is in unknown or invalid state | |
901 | ||
902 | - EH needs to make HBA/device forget about in-flight commands | |
903 | ||
904 | - HBA/device behaves weirdly | |
905 | ||
906 | Resetting during EH might be a good idea regardless of error condition | |
907 | to improve EH robustness. Whether to reset both or either one of HBA and | |
908 | device depends on situation but the following scheme is recommended. | |
909 | ||
910 | - When it's known that HBA is in ready state but ATA/ATAPI device is in | |
911 | unknown state, reset only device. | |
912 | ||
913 | - If HBA is in unknown state, reset both HBA and device. | |
914 | ||
915 | HBA resetting is implementation specific. For a controller complying to | |
916 | taskfile/BMDMA PCI IDE, stopping active DMA transaction may be | |
917 | sufficient iff BMDMA state is the only HBA context. But even mostly | |
918 | taskfile/BMDMA PCI IDE complying controllers may have implementation | |
919 | specific requirements and mechanism to reset themselves. This must be | |
920 | addressed by specific drivers. | |
921 | ||
922 | OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI | |
923 | devices. | |
924 | ||
925 | PATA hardware reset | |
926 | This is hardware initiated device reset signalled with asserted PATA | |
927 | RESET- signal. There is no standard way to initiate hardware reset | |
928 | from software although some hardware provides registers that allow | |
929 | driver to directly tweak the RESET- signal. | |
930 | ||
931 | Software reset | |
932 | This is achieved by turning CONTROL SRST bit on for at least 5us. | |
933 | Both PATA and SATA support it but, in case of SATA, this may require | |
934 | controller-specific support as the second Register FIS to clear SRST | |
935 | should be transmitted while BSY bit is still set. Note that on PATA, | |
936 | this resets both master and slave devices on a channel. | |
937 | ||
938 | EXECUTE DEVICE DIAGNOSTIC command | |
939 | Although ATA/ATAPI standard doesn't describe exactly, EDD implies | |
940 | some level of resetting, possibly similar level with software reset. | |
941 | Host-side EDD protocol can be handled with normal command processing | |
942 | and most SATA controllers should be able to handle EDD's just like | |
943 | other commands. As in software reset, EDD affects both devices on a | |
944 | PATA bus. | |
945 | ||
946 | Although EDD does reset devices, this doesn't suit error handling as | |
947 | EDD cannot be issued while BSY is set and it's unclear how it will | |
948 | act when device is in unknown/weird state. | |
949 | ||
950 | ATAPI DEVICE RESET command | |
951 | This is very similar to software reset except that reset can be | |
952 | restricted to the selected device without affecting the other device | |
953 | sharing the cable. | |
954 | ||
955 | SATA phy reset | |
956 | This is the preferred way of resetting a SATA device. In effect, | |
957 | it's identical to PATA hardware reset. Note that this can be done | |
958 | with the standard SCR Control register. As such, it's usually easier | |
959 | to implement than software reset. | |
960 | ||
961 | One more thing to consider when resetting devices is that resetting | |
962 | clears certain configuration parameters and they need to be set to their | |
963 | previous or newly adjusted values after reset. | |
964 | ||
965 | Parameters affected are. | |
966 | ||
967 | - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) | |
968 | ||
969 | - Parameters set with SET FEATURES including transfer mode setting | |
970 | ||
971 | - Block count set with SET MULTIPLE MODE | |
972 | ||
973 | - Other parameters (SET MAX, MEDIA LOCK...) | |
974 | ||
975 | ATA/ATAPI standard specifies that some parameters must be maintained | |
976 | across hardware or software reset, but doesn't strictly specify all of | |
977 | them. Always reconfiguring needed parameters after reset is required for | |
978 | robustness. Note that this also applies when resuming from deep sleep | |
979 | (power-off). | |
980 | ||
981 | Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET | |
982 | DEVICE is issued after any configuration parameter is updated or a | |
983 | hardware reset and the result used for further operation. OS driver is | |
984 | required to implement revalidation mechanism to support this. | |
985 | ||
986 | Reconfigure transport | |
987 | ~~~~~~~~~~~~~~~~~~~~~ | |
988 | ||
989 | For both PATA and SATA, a lot of corners are cut for cheap connectors, | |
990 | cables or controllers and it's quite common to see high transmission | |
991 | error rate. This can be mitigated by lowering transmission speed. | |
992 | ||
993 | The following is a possible scheme Jeff Garzik suggested. | |
994 | ||
995 | If more than $N (3?) transmission errors happen in 15 minutes, | |
996 | ||
997 | - if SATA, decrease SATA PHY speed. if speed cannot be decreased, | |
998 | ||
999 | - decrease UDMA xfer speed. if at UDMA0, switch to PIO4, | |
1000 | ||
1001 | - decrease PIO xfer speed. if at PIO3, complain, but continue | |
1002 | ||
1003 | ata_piix Internals | |
1004 | =================== | |
1005 | ||
1006 | .. kernel-doc:: drivers/ata/ata_piix.c | |
1007 | :internal: | |
1008 | ||
1009 | sata_sil Internals | |
1010 | =================== | |
1011 | ||
1012 | .. kernel-doc:: drivers/ata/sata_sil.c | |
1013 | :internal: | |
1014 | ||
1015 | Thanks | |
1016 | ====== | |
1017 | ||
1018 | The bulk of the ATA knowledge comes thanks to long conversations with | |
1019 | Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and | |
1020 | SCSI specifications. | |
1021 | ||
1022 | Thanks to Alan Cox for pointing out similarities between SATA and SCSI, | |
1023 | and in general for motivation to hack on libata. | |
1024 | ||
1025 | libata's device detection method, ata_pio_devchk, and in general all | |
1026 | the early probing was based on extensive study of Hale Landis's | |
1027 | probe/reset code in his ATADRVR driver (www.ata-atapi.com). |