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 kern
11 controllers and devices. libATA provides an AT
12 transports for ATA and ATAPI devices, and SCSI
13 devices according to the T10 SAT specification
14
15 This Guide documents the libATA driver API, li
16 internals, and a couple sample ATA low-level d
17
18 libata Driver API
19 =================
20
21 :c:type:`struct ata_port_operations <ata_port_
22 is defined for every low-level libata
23 hardware driver, and it controls how the low-l
24 with the ATA and SCSI layers.
25
26 FIS-based drivers will hook into the system wi
27 ``->qc_issue()`` high-level hooks. Hardware wh
28 similar to PCI IDE hardware may utilize severa
29 defining at a bare minimum the bus I/O address
30 register blocks.
31
32 :c:type:`struct ata_port_operations <ata_port_
33 ----------------------------------------------
34
35 Post-IDENTIFY device configuration
36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38 ::
39
40 void (*dev_config) (struct ata_port *, str
41
42
43 Called after IDENTIFY [PACKET] DEVICE is issue
44 Typically used to apply device-specific fixups
45 FEATURES - XFER MODE, and prior to operation.
46
47 This entry may be specified as NULL in ata_por
48
49 Set PIO/DMA mode
50 ~~~~~~~~~~~~~~~~
51
52 ::
53
54 void (*set_piomode) (struct ata_port *, st
55 void (*set_dmamode) (struct ata_port *, st
56 void (*post_set_mode) (struct ata_port *);
57 unsigned int (*mode_filter) (struct ata_po
58
59
60 Hooks called prior to the issue of SET FEATURE
61 optional ``->mode_filter()`` hook is called wh
62 the possible modes. This is passed to the ``->
63 which should return a mask of valid modes afte
64 unsuitable due to hardware limits. It is not v
65 to add modes.
66
67 ``dev->pio_mode`` and ``dev->dma_mode`` are gu
68 ``->set_piomode()`` and when ``->set_dmamode()
69 any other drive sharing the cable will also be
70 is the library records the decisions for the m
71 channel before it attempts to set any of them.
72
73 ``->post_set_mode()`` is called unconditionall
74 XFER MODE command completes successfully.
75
76 ``->set_piomode()`` is always called (if prese
77 is only called if DMA is possible.
78
79 Taskfile read/write
80 ~~~~~~~~~~~~~~~~~~~
81
82 ::
83
84 void (*sff_tf_load) (struct ata_port *ap,
85 void (*sff_tf_read) (struct ata_port *ap,
86
87
88 ``->tf_load()`` is called to load the given ta
89 registers / DMA buffers. ``->tf_read()`` is ca
90 registers / DMA buffers, to obtain the current
91 values. Most drivers for taskfile-based hardwa
92 :c:func:`ata_sff_tf_load` and :c:func:`ata_sff
93
94 PIO data read/write
95 ~~~~~~~~~~~~~~~~~~~
96
97 ::
98
99 void (*sff_data_xfer) (struct ata_device *
100
101
102 All bmdma-style drivers must implement this ho
103 operation that actually copies the data bytes
104 transfer. Typically the driver will choose one
105 :c:func:`ata_sff_data_xfer`, or :c:func:`ata_s
106
107 ATA command execute
108 ~~~~~~~~~~~~~~~~~~~
109
110 ::
111
112 void (*sff_exec_command)(struct ata_port *
113
114
115 causes an ATA command, previously loaded with
116 initiated in hardware. Most drivers for taskfi
117 :c:func:`ata_sff_exec_command` for this hook.
118
119 Per-cmd ATAPI DMA capabilities filter
120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121
122 ::
123
124 int (*check_atapi_dma) (struct ata_queued_
125
126
127 Allow low-level driver to filter ATA PACKET co
128 indicating whether or not it is OK to use DMA
129 command.
130
131 This hook may be specified as NULL, in which c
132 that atapi dma can be supported.
133
134 Read specific ATA shadow registers
135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136
137 ::
138
139 u8 (*sff_check_status)(struct ata_port *
140 u8 (*sff_check_altstatus)(struct ata_por
141
142
143 Reads the Status/AltStatus ATA shadow register
144 hardware, reading the Status register has the
145 the interrupt condition. Most drivers for task
146 :c:func:`ata_sff_check_status` for this hook.
147
148 Write specific ATA shadow register
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
150
151 ::
152
153 void (*sff_set_devctl)(struct ata_port *ap
154
155
156 Write the device control ATA shadow register t
157 drivers don't need to define this.
158
159 Select ATA device on bus
160 ~~~~~~~~~~~~~~~~~~~~~~~~
161
162 ::
163
164 void (*sff_dev_select)(struct ata_port *ap
165
166
167 Issues the low-level hardware command(s) that
168 devices to be considered 'selected' (active an
169 the ATA bus. This generally has no meaning on
170
171 Most drivers for taskfile-based hardware use :
172 this hook.
173
174 Private tuning method
175 ~~~~~~~~~~~~~~~~~~~~~
176
177 ::
178
179 void (*set_mode) (struct ata_port *ap);
180
181
182 By default libata performs drive and controlle
183 with the ATA timing rules and also applies bla
184 Some controllers need special handling and hav
185 typically raid controllers that use ATA comman
186 drive timing.
187
188 **Warning**
189
190 This hook should not be used to replace th
191 tuning logic when a controller has quirks.
192 tuning logic in that case would bypass han
193 quirks that may be important to data relia
194 needs to filter the mode selection it shou
195 hook instead.
196
197 Control PCI IDE BMDMA engine
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199
200 ::
201
202 void (*bmdma_setup) (struct ata_queued_cmd
203 void (*bmdma_start) (struct ata_queued_cmd
204 void (*bmdma_stop) (struct ata_port *ap);
205 u8 (*bmdma_status) (struct ata_port *ap)
206
207
208 When setting up an IDE BMDMA transaction, thes
209 (``->bmdma_setup``), fire (``->bmdma_start``),
210 hardware's DMA engine. ``->bmdma_status`` is u
211 IDE DMA Status register.
212
213 These hooks are typically either no-ops, or si
214 FIS-based drivers.
215
216 Most legacy IDE drivers use :c:func:`ata_bmdma
217 :c:func:`bmdma_setup` hook. :c:func:`ata_bmdma
218 to the PRD table to the IDE PRD Table Address
219 Command register, and call :c:func:`exec_comma
220
221 Most legacy IDE drivers use :c:func:`ata_bmdma
222 :c:func:`bmdma_start` hook. :c:func:`ata_bmdma
223 ATA_DMA_START flag to the DMA Command register
224
225 Many legacy IDE drivers use :c:func:`ata_bmdma
226 :c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_
227 flag in the DMA command register.
228
229 Many legacy IDE drivers use :c:func:`ata_bmdma
230 :c:func:`bmdma_status` hook.
231
232 High-level taskfile hooks
233 ~~~~~~~~~~~~~~~~~~~~~~~~~
234
235 ::
236
237 enum ata_completion_errors (*qc_prep) (str
238 int (*qc_issue) (struct ata_queued_cmd *qc
239
240
241 Higher-level hooks, these two hooks can potent
242 the above taskfile/DMA engine hooks. ``->qc_pr
243 buffers have been DMA-mapped, and is typically
244 hardware's DMA scatter-gather table. Some driv
245 :c:func:`ata_bmdma_qc_prep` and :c:func:`ata_b
246 functions, but more advanced drivers roll thei
247
248 ``->qc_issue`` is used to make a command activ
249 tables have been prepared. IDE BMDMA drivers u
250 :c:func:`ata_sff_qc_issue` for taskfile protoc
251 advanced drivers implement their own ``->qc_is
252
253 :c:func:`ata_sff_qc_issue` calls ``->sff_tf_lo
254 ``->bmdma_start()`` as necessary to initiate a
255
256 Exception and probe handling (EH)
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258
259 ::
260
261 void (*freeze) (struct ata_port *ap);
262 void (*thaw) (struct ata_port *ap);
263
264
265 :c:func:`ata_port_freeze` is called when HSM v
266 condition disrupts normal operation of the por
267 allowed to perform any operation until the por
268 follows a successful reset.
269
270 The optional ``->freeze()`` callback can be us
271 hardware-wise (e.g. mask interrupt and stop DM
272 cannot be frozen hardware-wise, the interrupt
273 interrupts unconditionally while the port is f
274
275 The optional ``->thaw()`` callback is called t
276 ``->freeze()``: prepare the port for normal op
277 interrupts, start DMA engine, etc.
278
279 ::
280
281 void (*error_handler) (struct ata_port *ap
282
283
284 ``->error_handler()`` is a driver's hook into
285 and other exceptional conditions. The primary
286 implementation is to call :c:func:`ata_do_eh`
287 with a set of EH hooks as arguments:
288
289 'prereset' hook (may be NULL) is called during
290 other actions are taken.
291
292 'postreset' hook (may be NULL) is called after
293 performed. Based on existing conditions, sever
294 hardware capabilities,
295
296 Either 'softreset' (may be NULL) or 'hardreset
297 called to perform the low-level EH reset.
298
299 ::
300
301 void (*post_internal_cmd) (struct ata_queu
302
303
304 Perform any hardware-specific actions necessar
305 after executing a probe-time or EH-time comman
306 :c:func:`ata_exec_internal`.
307
308 Hardware interrupt handling
309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
310
311 ::
312
313 irqreturn_t (*irq_handler)(int, void *, st
314 void (*irq_clear) (struct ata_port *);
315
316
317 ``->irq_handler`` is the interrupt handling ro
318 system, by libata. ``->irq_clear`` is called d
319 interrupt handler is registered, to be sure ha
320
321 The second argument, dev_instance, should be c
322 :c:type:`struct ata_host_set <ata_host_set>`.
323
324 Most legacy IDE drivers use :c:func:`ata_sff_i
325 hook, which scans all ports in the host_set, d
326 command was active (if any), and calls ata_sff
327
328 Most legacy IDE drivers use :c:func:`ata_sff_i
329 :c:func:`irq_clear` hook, which simply clears
330 in the DMA status register.
331
332 SATA phy read/write
333 ~~~~~~~~~~~~~~~~~~~
334
335 ::
336
337 int (*scr_read) (struct ata_port *ap, unsi
338 u32 *val);
339 int (*scr_write) (struct ata_port *ap, uns
340 u32 val);
341
342
343 Read and write standard SATA phy registers.
344 sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_
345
346 Init and shutdown
347 ~~~~~~~~~~~~~~~~~
348
349 ::
350
351 int (*port_start) (struct ata_port *ap);
352 void (*port_stop) (struct ata_port *ap);
353 void (*host_stop) (struct ata_host_set *ho
354
355
356 ``->port_start()`` is called just after the da
357 are initialized. Typically this is used to all
358 tables / rings, enable DMA engines, and simila
359 use this entry point as a chance to allocate d
360 ``ap->private_data``.
361
362 Many drivers use :c:func:`ata_port_start` as t
363 own :c:func:`port_start` hooks. :c:func:`ata_p
364 a legacy IDE PRD table and returns.
365
366 ``->port_stop()`` is called after ``->host_sto
367 release DMA/memory resources, now that they ar
368 used. Many drivers also free driver-private da
369
370 ``->host_stop()`` is called after all ``->port
371 The hook must finalize hardware shutdown, rele
372 resources, etc. This hook may be specified as
373 not called.
374
375 Error handling
376 ==============
377
378 This chapter describes how errors are handled
379 advised to read SCSI EH (Documentation/scsi/sc
380 exceptions doc first.
381
382 Origins of commands
383 -------------------
384
385 In libata, a command is represented with
386 :c:type:`struct ata_queued_cmd <ata_queued_cmd
387 qc's are preallocated during port initializati
388 for command executions. Currently only one qc
389 yet-to-be-merged NCQ branch allocates one for
390 to NCQ tag 1-to-1.
391
392 libata commands can originate from two sources
393 midlayer. libata internal commands are used fo
394 handling. All normal blk requests and commands
395 passed as SCSI commands through queuecommand c
396 template.
397
398 How commands are issued
399 -----------------------
400
401 Internal commands
402 Once allocated qc's taskfile is initialize
403 executed. qc currently has two mechanisms
404 is via ``qc->complete_fn()`` callback and
405 ``qc->waiting``. ``qc->complete_fn()`` cal
406 used by normal SCSI translated commands an
407 synchronous (issuer sleeps in process cont
408 commands.
409
410 Once initialization is complete, host_set
411 qc is issued.
412
413 SCSI commands
414 All libata drivers use :c:func:`ata_scsi_q
415 ``hostt->queuecommand`` callback. scmds ca
416 translated. No qc is involved in processin
417 result is computed right away and the scmd
418
419 ``qc->complete_fn()`` callback is used for
420 commands use :c:func:`ata_scsi_qc_complete
421 :c:func:`atapi_qc_complete`. Both function
422 to notify upper layer when the qc is finis
423 completed, the qc is issued with :c:func:`
424
425 Note that SCSI midlayer invokes hostt->que
426 host_set lock, so all above occur while ho
427
428 How commands are processed
429 --------------------------
430
431 Depending on which protocol and which controll
432 processed differently. For the purpose of disc
433 uses taskfile interface and all standard callb
434
435 Currently 6 ATA command protocols are used. Th
436 following four categories according to how the
437
438 ATA NO DATA or DMA
439 ATA_PROT_NODATA and ATA_PROT_DMA fall into
440 types of commands don't require any softwa
441 issued. Device will raise interrupt on com
442
443 ATA PIO
444 ATA_PROT_PIO is in this category. libata c
445 with polling. ATA_NIEN bit is set to turn
446 pio_task on ata_wq performs polling and IO
447
448 ATAPI NODATA or DMA
449 ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_D
450 category. packet_task is used to poll BSY
451 command. Once BSY is turned off by the dev
452 transfers CDB and hands off processing to
453
454 ATAPI PIO
455 ATA_PROT_ATAPI is in this category. ATA_NI
456 in ATAPI NODATA or DMA, packet_task submit
457 submitting cdb, further processing (data t
458 pio_task.
459
460 How commands are completed
461 --------------------------
462
463 Once issued, all qc's are either completed wit
464 time out. For commands which are handled by in
465 :c:func:`ata_host_intr` invokes :c:func:`ata_q
466 pio_task invokes :c:func:`ata_qc_complete`. In
467 also complete commands.
468
469 :c:func:`ata_qc_complete` does the following.
470
471 1. DMA memory is unmapped.
472
473 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags
474
475 3. :c:expr:`qc->complete_fn` callback is invok
476 callback is not zero. Completion is short c
477 :c:func:`ata_qc_complete` returns.
478
479 4. :c:func:`__ata_qc_complete` is called, whic
480
481 1. ``qc->flags`` is cleared to zero.
482
483 2. ``ap->active_tag`` and ``qc->tag`` are p
484
485 3. ``qc->waiting`` is cleared & completed (
486
487 4. qc is deallocated by clearing appropriat
488
489 So, it basically notifies upper layer and deal
490 is short-circuit path in #3 which is used by :
491
492 For all non-ATAPI commands, whether it fails o
493 code path is taken and very little error handl
494 completed with success status if it succeeded,
495 otherwise.
496
497 However, failed ATAPI commands require more ha
498 needed to acquire sense data. If an ATAPI comm
499 :c:func:`ata_qc_complete` is invoked with erro
500 :c:func:`atapi_qc_complete` via ``qc->complete
501
502 This makes :c:func:`atapi_qc_complete` set ``s
503 SAM_STAT_CHECK_CONDITION, complete the scmd an
504 sense data is empty but ``scmd->result`` is CH
505 will invoke EH for the scmd, and returning 1 m
506 to return without deallocating the qc. This le
507 :c:func:`ata_scsi_error` with partially comple
508
509 :c:func:`ata_scsi_error`
510 ------------------------
511
512 :c:func:`ata_scsi_error` is the current ``tran
513 for libata. As discussed above, this will be e
514 timeout and ATAPI error completion. This funct
515 and has not failed yet. Such a qc will be mark
516 EH will know to handle it later. Then it calls
517 :c:func:`error_handler` callback.
518
519 When the :c:func:`error_handler` callback is i
520 completes the qc. Note that as we're currently
521 scsi_done. As described in SCSI EH doc, a reco
522 either retried with :c:func:`scsi_queue_insert
523 :c:func:`scsi_finish_command`. Here, we overri
524 :c:func:`scsi_finish_command` and calls :c:fun
525
526 If EH is invoked due to a failed ATAPI qc, the
527 not deallocated. The purpose of this half-comp
528 place holder to make EH code reach this place.
529 but it works.
530
531 Once control reaches here, the qc is deallocat
532 :c:func:`__ata_qc_complete` explicitly. Then,
533 is issued. Once sense data is acquired, scmd i
534 invoking :c:func:`scsi_finish_command` on the
535 have completed and deallocated the qc which wa
536 scmd, we don't need to/cannot call :c:func:`at
537
538 Problems with the current EH
539 ----------------------------
540
541 - Error representation is too crude. Currentl
542 conditions are represented with ATA STATUS
543 Errors which aren't ATA device errors are t
544 errors by setting ATA_ERR bit. Better error
545 properly represent ATA and other errors/exc
546
547 - When handling timeouts, no action is taken
548 about the timed out command and ready for n
549
550 - EH handling via :c:func:`ata_scsi_error` is
551 usual command processing. On EH entrance, t
552 quiescent state. Timed out commands may suc
553 pio_task and atapi_task may still be runnin
554
555 - Too weak error recovery. Devices / controll
556 errors and other errors quite often require
557 state. Also, advanced error handling is nec
558 like NCQ and hotplug.
559
560 - ATA errors are directly handled in the inte
561 errors in pio_task. This is problematic for
562 for the following reasons.
563
564 First, advanced error handling often requir
565 execution.
566
567 Second, even a simple failure (say, CRC err
568 gathering and could trigger complex error h
569 reconfiguring). Having multiple code paths
570 enter EH and trigger actions makes life pai
571
572 Third, scattered EH code makes implementing
573 difficult. Low level drivers override libat
574 scattered over several places, each affecte
575 its part of error handling. This can be err
576
577 libata Library
578 ==============
579
580 .. kernel-doc:: drivers/ata/libata-core.c
581 :export:
582
583 libata Core Internals
584 =====================
585
586 .. kernel-doc:: drivers/ata/libata-core.c
587 :internal:
588
589 .. kernel-doc:: drivers/ata/libata-eh.c
590
591 libata SCSI translation/emulation
592 =================================
593
594 .. kernel-doc:: drivers/ata/libata-scsi.c
595 :export:
596
597 .. kernel-doc:: drivers/ata/libata-scsi.c
598 :internal:
599
600 ATA errors and exceptions
601 =========================
602
603 This chapter tries to identify what error/exce
604 ATA/ATAPI devices and describe how they should
605 implementation-neutral way.
606
607 The term 'error' is used to describe condition
608 error condition is reported from device or a c
609
610 The term 'exception' is either used to describ
611 which are not errors (say, power or hotplug ev
612 errors and non-error exceptional conditions. W
613 between error and exception is necessary, the
614 is used.
615
616 Exception categories
617 --------------------
618
619 Exceptions are described primarily with respec
620 master IDE interface. If a controller provides
621 for error reporting, mapping those into catego
622 shouldn't be difficult.
623
624 In the following sections, two recovery action
625 reconfiguring transport - are mentioned. These
626 `EH recovery actions <#exrec>`__.
627
628 HSM violation
629 ~~~~~~~~~~~~~
630
631 This error is indicated when STATUS value does
632 during issuing or execution any ATA/ATAPI comm
633
634 - ATA_STATUS doesn't contain !BSY && DRDY &&
635 issue a command.
636
637 - !BSY && !DRQ during PIO data transfer.
638
639 - DRQ on command completion.
640
641 - !BSY && ERR after CDB transfer starts but b
642 is transferred. ATA/ATAPI standard states t
643 terminate the PACKET command with an error
644 the command packet has been written" in the
645 of PACKET command and the state diagram doe
646 transitions.
647
648 In these cases, HSM is violated and not much i
649 error can be acquired from STATUS or ERROR reg
650 be anything - driver bug, faulty device, contr
651
652 As HSM is violated, reset is necessary to rest
653 Reconfiguring transport for lower speed might
654 transmission errors sometimes cause this kind
655
656 ATA/ATAPI device error (non-NCQ / non-CHECK CO
657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
658
659 These are errors detected and reported by ATA/
660 device problems. For this type of errors, STAT
661 values are valid and describe error condition.
662 errors are detected by ATA/ATAPI devices and r
663 mechanism as device errors. Those cases are de
664 section.
665
666 For ATA commands, this type of errors are indi
667 during command execution and on completion.
668
669 For ATAPI commands,
670
671 - !BSY && ERR && ABRT right after issuing PAC
672 command is not supported and falls in this
673
674 - !BSY && ERR(==CHK) && !ABRT after the last
675 indicates CHECK CONDITION and doesn't fall
676
677 - !BSY && ERR(==CHK) && ABRT after the last b
678 \*probably\* indicates CHECK CONDITION and
679 category.
680
681 Of errors detected as above, the following are
682 errors but ATA bus errors and should be handle
683 `ATA bus error <#excatATAbusErr>`__.
684
685 CRC error during data transfer
686 This is indicated by ICRC bit in the ERROR
687 corruption occurred during data transfer.
688 standard specifies that this bit is only a
689 transfers but ATA/ATAPI-8 draft revision 1
690 applicable to multiword DMA and PIO.
691
692 ABRT error during data transfer or on completi
693 Up to ATA/ATAPI-7, the standard specifies
694 ICRC errors and on cases where a device is
695 command. Combined with the fact that MWDMA
696 aren't allowed to use ICRC bit up to ATA/A
697 that ABRT bit alone could indicate transfe
698
699 However, ATA/ATAPI-8 draft revision 1f rem
700 errors can turn on ABRT. So, this is kind
701 heuristics are needed here.
702
703 ATA/ATAPI device errors can be further categor
704
705 Media errors
706 This is indicated by UNC bit in the ERROR
707 reports UNC error only after certain numbe
708 recover the data, so there's nothing much
709 notifying upper layer.
710
711 READ and WRITE commands report CHS or LBA
712 but ATA/ATAPI standard specifies that the
713 on error completion is indeterminate, so w
714 sectors preceding the failed sector have b
715 cannot complete those sectors successfully
716
717 Media changed / media change requested error
718 <<TODO: fill here>>
719
720 Address error
721 This is indicated by IDNF bit in the ERROR
722 layer.
723
724 Other errors
725 This can be invalid command or parameter i
726 or some other error condition. Note that A
727 of things including ICRC and Address error
728
729 Depending on commands, not all STATUS/ERROR bi
730 non-applicable bits are marked with "na" in th
731 up to ATA/ATAPI-7 no definition of "na" can be
732 ATA/ATAPI-8 draft revision 1f describes "N/A"
733
734 3.2.3.3a N/A
735 A keyword the indicates a field has no
736 standard and should not be checked by
737 fields should be cleared to zero.
738
739 So, it seems reasonable to assume that "na" bi
740 devices and thus need no explicit masking.
741
742 ATAPI device CHECK CONDITION
743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
744
745 ATAPI device CHECK CONDITION error is indicate
746 in the STATUS register after the last byte of
747 PACKET command. For this kind of errors, sense
748 to gather information regarding the errors. RE
749 should be used to acquire sense data.
750
751 Once sense data is acquired, this type of erro
752 similarly to other SCSI errors. Note that sens
753 bus error (e.g. Sense Key 04h HARDWARE ERROR &
754 PARITY ERROR). In such cases, the error should
755 bus error and handled according to `ATA bus er
756
757 ATA device error (NCQ)
758 ~~~~~~~~~~~~~~~~~~~~~~
759
760 NCQ command error is indicated by cleared BSY
761 command phase (one or more NCQ commands outsta
762 and ERROR registers will contain valid values
763 LOG EXT is required to clear the error conditi
764 command has failed and acquire more informatio
765
766 READ LOG EXT Log Page 10h reports which tag ha
767 register values describing the error. With thi
768 command can be handled as a normal ATA command
769 `ATA/ATAPI device error (non-NCQ / non-CHECK C
770 and all other in-flight commands must be retri
771 should not be counted - it's likely that comma
772 have completed normally if it were not for the
773
774 Note that ATA bus errors can be reported as AT
775 should be handled as described in `ATA bus err
776
777 If READ LOG EXT Log Page 10h fails or reports
778 screwed. This condition should be treated acco
779 `HSM violation <#excatHSMviolation>`__.
780
781 ATA bus error
782 ~~~~~~~~~~~~~
783
784 ATA bus error means that data corruption occur
785 over ATA bus (SATA or PATA). This type of erro
786
787 - ICRC or ABRT error as described in
788 `ATA/ATAPI device error (non-NCQ / non-CHEC
789
790 - Controller-specific error completion with e
791 indicating transmission error.
792
793 - On some controllers, command timeout. In th
794 mechanism to determine that the timeout is
795
796 - Unknown/random errors, timeouts and all sor
797
798 As described above, transmission errors can ca
799 symptoms ranging from device ICRC error to ran
800 for many cases, there is no way to tell if an
801 transmission error or not; therefore, it's nec
802 of heuristic when dealing with errors and time
803 encountering repetitive ABRT errors for known
804 likely to indicate ATA bus error.
805
806 Once it's determined that ATA bus errors have
807 lowering ATA bus transmission speed is one of
808 alleviate the problem. See `Reconfigure transp
809 more information.
810
811 PCI bus error
812 ~~~~~~~~~~~~~
813
814 Data corruption or other failures during trans
815 system bus). For standard BMDMA, this is indic
816 BMDMA Status register. This type of errors mus
817 indicates something is very wrong with the sys
818 controller is recommended.
819
820 Late completion
821 ~~~~~~~~~~~~~~~
822
823 This occurs when timeout occurs and the timeou
824 the timed out command has completed successful
825 usually caused by lost interrupts. This type o
826 Resetting host controller is recommended.
827
828 Unknown error (timeout)
829 ~~~~~~~~~~~~~~~~~~~~~~~
830
831 This is when timeout occurs and the command is
832 host and device are in unknown state. When thi
833 any valid or invalid state. To bring the devic
834 it forget about the timed out command, resetti
835 out command may be retried.
836
837 Timeouts can also be caused by transmission er
838 `ATA bus error <#excatATAbusErr>`__ for more d
839
840 Hotplug and power management exceptions
841 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
842
843 <<TODO: fill here>>
844
845 EH recovery actions
846 -------------------
847
848 This section discusses several important recov
849
850 Clearing error condition
851 ~~~~~~~~~~~~~~~~~~~~~~~~
852
853 Many controllers require its error registers t
854 handler. Different controllers may have differ
855
856 For SATA, it's strongly recommended to clear a
857 during error handling.
858
859 Reset
860 ~~~~~
861
862 During EH, resetting is necessary in the follo
863
864 - HSM is in unknown or invalid state
865
866 - HBA is in unknown or invalid state
867
868 - EH needs to make HBA/device forget about in
869
870 - HBA/device behaves weirdly
871
872 Resetting during EH might be a good idea regar
873 to improve EH robustness. Whether to reset bot
874 device depends on situation but the following
875
876 - When it's known that HBA is in ready state
877 unknown state, reset only device.
878
879 - If HBA is in unknown state, reset both HBA
880
881 HBA resetting is implementation specific. For
882 taskfile/BMDMA PCI IDE, stopping active DMA tr
883 sufficient iff BMDMA state is the only HBA con
884 taskfile/BMDMA PCI IDE complying controllers m
885 specific requirements and mechanism to reset t
886 addressed by specific drivers.
887
888 OTOH, ATA/ATAPI standard describes in detail w
889 devices.
890
891 PATA hardware reset
892 This is hardware initiated device reset si
893 RESET- signal. There is no standard way to
894 from software although some hardware provi
895 driver to directly tweak the RESET- signal
896
897 Software reset
898 This is achieved by turning CONTROL SRST b
899 Both PATA and SATA support it but, in case
900 controller-specific support as the second
901 should be transmitted while BSY bit is sti
902 this resets both master and slave devices
903
904 EXECUTE DEVICE DIAGNOSTIC command
905 Although ATA/ATAPI standard doesn't descri
906 some level of resetting, possibly similar
907 Host-side EDD protocol can be handled with
908 and most SATA controllers should be able t
909 other commands. As in software reset, EDD
910 PATA bus.
911
912 Although EDD does reset devices, this does
913 EDD cannot be issued while BSY is set and
914 act when device is in unknown/weird state.
915
916 ATAPI DEVICE RESET command
917 This is very similar to software reset exc
918 restricted to the selected device without
919 sharing the cable.
920
921 SATA phy reset
922 This is the preferred way of resetting a S
923 it's identical to PATA hardware reset. Not
924 with the standard SCR Control register. As
925 to implement than software reset.
926
927 One more thing to consider when resetting devi
928 clears certain configuration parameters and th
929 previous or newly adjusted values after reset.
930
931 Parameters affected are.
932
933 - CHS set up with INITIALIZE DEVICE PARAMETER
934
935 - Parameters set with SET FEATURES including
936
937 - Block count set with SET MULTIPLE MODE
938
939 - Other parameters (SET MAX, MEDIA LOCK...)
940
941 ATA/ATAPI standard specifies that some paramet
942 across hardware or software reset, but doesn't
943 them. Always reconfiguring needed parameters a
944 robustness. Note that this also applies when r
945 (power-off).
946
947 Also, ATA/ATAPI standard requires that IDENTIF
948 DEVICE is issued after any configuration param
949 hardware reset and the result used for further
950 required to implement revalidation mechanism t
951
952 Reconfigure transport
953 ~~~~~~~~~~~~~~~~~~~~~
954
955 For both PATA and SATA, a lot of corners are c
956 cables or controllers and it's quite common to
957 error rate. This can be mitigated by lowering
958
959 The following is a possible scheme Jeff Garzik
960
961 If more than $N (3?) transmission errors h
962
963 - if SATA, decrease SATA PHY speed. if sp
964
965 - decrease UDMA xfer speed. if at UDMA0,
966
967 - decrease PIO xfer speed. if at PIO3, co
968
969 ata_piix Internals
970 ===================
971
972 .. kernel-doc:: drivers/ata/ata_piix.c
973 :internal:
974
975 sata_sil Internals
976 ===================
977
978 .. kernel-doc:: drivers/ata/sata_sil.c
979 :internal:
980
981 Thanks
982 ======
983
984 The bulk of the ATA knowledge comes thanks to
985 Andre Hedrick (www.linux-ide.org), and long ho
986 SCSI specifications.
987
988 Thanks to Alan Cox for pointing out similariti
989 and in general for motivation to hack on libat
990
991 libata's device detection method, ata_pio_devc
992 the early probing was based on extensive study
993 probe/reset code in his ATADRVR driver (www.at
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.