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