Documentation/driver-api/libata.rst

10 libATA is a library used inside the Linux kernel to support ATA host
11 controllers and devices. libATA provides an ATA driver API, class
12 transports for ATA and ATAPI devices, and SCSI<->ATA translation for ATA
16 internals, and a couple sample ATA low-level drivers.
22 is defined for every low-level libata
23 hardware driver, and it controls how the low-level driver interfaces
24 with the ATA and SCSI layers.
26 FIS-based drivers will hook into the system with ``->qc_prep()`` and
27 ``->qc_issue()`` high-level hooks. Hardware which behaves in a manner
28 similar to PCI IDE hardware may utilize several generic helpers,
29 defining at a bare minimum the bus I/O addresses of the ATA shadow
33 ----------------------------------------------------------
35 Post-IDENTIFY device configuration
44 Typically used to apply device-specific fixups prior to issue of SET
45 FEATURES - XFER MODE, and prior to operation.
60 Hooks called prior to the issue of SET FEATURES - XFER MODE command. The
61 optional ``->mode_filter()`` hook is called when libata has built a mask of
62 the possible modes. This is passed to the ``->mode_filter()`` function
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
73 ``->post_set_mode()`` is called unconditionally, after the SET FEATURES -
76 ``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``
88 ``->tf_load()`` is called to load the given taskfile into hardware
89 registers / DMA buffers. ``->tf_read()`` is called to read the hardware
91 values. Most drivers for taskfile-based hardware (PIO or MMIO) use
102 All bmdma-style drivers must implement this hook. This is the low-level
107 ATA command execute
115 causes an ATA command, previously loaded with ``->tf_load()``, to be
116 initiated in hardware. Most drivers for taskfile-based hardware use
119 Per-cmd ATAPI DMA capabilities filter
127 Allow low-level driver to filter ATA PACKET commands, returning a status
134 Read specific ATA shadow registers
143 Reads the Status/AltStatus ATA shadow register from hardware. On some
145 the interrupt condition. Most drivers for taskfile-based hardware use
148 Write specific ATA shadow register
156 Write the device control ATA shadow register to the hardware. Most
159 Select ATA device on bus
167 Issues the low-level hardware command(s) that causes one of N hardware
169 the ATA bus. This generally has no meaning on FIS-based devices.
171 Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
183 with the ATA timing rules and also applies blacklists and cable limits.
185 typically raid controllers that use ATA commands but do not actually do
209 (``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the
210 hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
213 These hooks are typically either no-ops, or simply not implemented, in
214 FIS-based drivers.
232 High-level taskfile hooks
241 Higher-level hooks, these two hooks can potentially supersede several of
242 the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
243 buffers have been DMA-mapped, and is typically used to populate the
244 hardware's DMA scatter-gather table. Some drivers use the standard
248 ``->qc_issue`` is used to make a command active, once the hardware and S/G
250 :c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. More
251 advanced drivers implement their own ``->qc_issue``.
253 :c:func:`ata_sff_qc_issue` calls ``->sff_tf_load()``, ``->bmdma_setup()``, and
254 ``->bmdma_start()`` as necessary to initiate a transfer.
270 The optional ``->freeze()`` callback can be used for freezing the port
271 hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
272 cannot be frozen hardware-wise, the interrupt handler must ack and clear
275 The optional ``->thaw()`` callback is called to perform the opposite of
276 ``->freeze()``: prepare the port for normal operation once again. Unmask
284 ``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
297 called to perform the low-level EH reset.
304 Perform any hardware-specific actions necessary to finish processing
305 after executing a probe-time or EH-time command via
317 ``->irq_handler`` is the interrupt handling routine registered with the
318 system, by libata. ``->irq_clear`` is called during probe just before the
356 ``->port_start()`` is called just after the data structures for each port
357 are initialized. Typically this is used to alloc per-port DMA buffers /
359 use this entry point as a chance to allocate driver-private memory for
360 ``ap->private_data``.
366 ``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
368 used. Many drivers also free driver-private data from port at this time.
370 ``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
379 advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA
383 -------------------
389 yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
390 to NCQ tag 1-to-1.
392 libata commands can originate from two sources - libata itself and SCSI
399 -----------------------
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
415     ``hostt->queuecommand`` callback. scmds can either be simulated or
419     ``qc->complete_fn()`` callback is used for completion notification. ATA
421     :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
425     Note that SCSI midlayer invokes hostt->queuecommand while holding
429 --------------------------
435 Currently 6 ATA command protocols are used. They can be sorted into the
438 ATA NO DATA or DMA
443 ATA PIO
461 --------------------------
473 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
475 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
481    1. ``qc->flags`` is cleared to zero.
483    2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
485    3. ``qc->waiting`` is cleared & completed (in that order).
487    4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
490 is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
492 For all non-ATAPI commands, whether it fails or not, almost the same
500 :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
502 This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
504 sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
510 ------------------------
512 :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
513 for libata. As discussed above, this will be entered in two cases -
523 :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
527 not deallocated. The purpose of this half-completion is to use the qc as
539 ----------------------------
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
545    properly represent ATA and other errors/exceptions is needed.
547 -  When handling timeouts, no action is taken to make device forget
550 -  EH handling via :c:func:`ata_scsi_error` is not properly protected from
555 -  Too weak error recovery. Devices / controllers causing HSM mismatch
560 -  ATA errors are directly handled in the interrupt handler and PIO
580 .. kernel-doc:: drivers/ata/libata-core.c
586 .. kernel-doc:: drivers/ata/libata-core.c
589 .. kernel-doc:: drivers/ata/libata-eh.c
594 .. kernel-doc:: drivers/ata/libata-scsi.c
597 .. kernel-doc:: drivers/ata/libata-scsi.c
600 ATA errors and exceptions
604 ATA/ATAPI devices and describe how they should be handled in
605 implementation-neutral way.
612 errors and non-error exceptional conditions. Where explicit distinction
613 between error and exception is necessary, the term 'non-error exception'
617 --------------------
624 In the following sections, two recovery actions - reset and
625 reconfiguring transport - are mentioned. These are described further in
632 during issuing or execution any ATA/ATAPI command.
634 -  ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
637 -  !BSY && !DRQ during PIO data transfer.
639 -  DRQ on command completion.
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
650 be anything - driver bug, faulty device, controller and/or cable.
656 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
659 These are errors detected and reported by ATA/ATAPI devices indicating
661 values are valid and describe error condition. Note that some of ATA bus
662 errors are detected by ATA/ATAPI devices and reported using the same
666 For ATA commands, this type of errors are indicated by !BSY && ERR
671 -  !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
674 -  !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
677 -  !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred
681 Of errors detected as above, the following are not ATA/ATAPI device
682 errors but ATA bus errors and should be handled according to
683 `ATA bus error <#excatATAbusErr>`__.
687     corruption occurred during data transfer. Up to ATA/ATAPI-7, the
689     transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
693     Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on
696     aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
699     However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
703 ATA/ATAPI device errors can be further categorized as follows.
706     This is indicated by UNC bit in the ERROR register. ATA devices
712     but ATA/ATAPI standard specifies that the amount of transferred data
730 non-applicable bits are marked with "na" in the output descriptions but
731 up to ATA/ATAPI-7 no definition of "na" can be found. However,
732 ATA/ATAPI-8 draft revision 1f describes "N/A" as follows.
752 similarly to other SCSI errors. Note that sense data may indicate ATA
754 PARITY ERROR). In such cases, the error should be considered as an ATA
755 bus error and handled according to `ATA bus error <#excatATAbusErr>`__.
757 ATA device error (NCQ)
768 command can be handled as a normal ATA command error as in
769 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
770 and all other in-flight commands must be retried. Note that this retry
771 should not be counted - it's likely that commands retried this way would
774 Note that ATA bus errors can be reported as ATA device NCQ errors. This
775 should be handled as described in `ATA bus error <#excatATAbusErr>`__.
781 ATA bus error
784 ATA bus error means that data corruption occurred during transmission
785 over ATA bus (SATA or PATA). This type of errors can be indicated by
787 -  ICRC or ABRT error as described in
788    `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.
790 -  Controller-specific error completion with error information
793 -  On some controllers, command timeout. In this case, there may be a
796 -  Unknown/random errors, timeouts and all sorts of weirdities.
804 likely to indicate ATA bus error.
806 Once it's determined that ATA bus errors have possibly occurred,
807 lowering ATA bus transmission speed is one of actions which may
838 `ATA bus error <#excatATAbusErr>`__ for more details.
846 -------------------
864 -  HSM is in unknown or invalid state
866 -  HBA is in unknown or invalid state
868 -  EH needs to make HBA/device forget about in-flight commands
870 -  HBA/device behaves weirdly
876 -  When it's known that HBA is in ready state but ATA/ATAPI device is in
879 -  If HBA is in unknown state, reset both HBA and device.
888 OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI
893     RESET- signal. There is no standard way to initiate hardware reset
895     driver to directly tweak the RESET- signal.
900     controller-specific support as the second Register FIS to clear SRST
905     Although ATA/ATAPI standard doesn't describe exactly, EDD implies
907     Host-side EDD protocol can be handled with normal command processing
933 -  CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
935 -  Parameters set with SET FEATURES including transfer mode setting
937 -  Block count set with SET MULTIPLE MODE
939 -  Other parameters (SET MAX, MEDIA LOCK...)
941 ATA/ATAPI standard specifies that some parameters must be maintained
945 (power-off).
947 Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET
963     -  if SATA, decrease SATA PHY speed. if speed cannot be decreased,
965     -  decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
967     -  decrease PIO xfer speed. if at PIO3, complain, but continue
972 .. kernel-doc:: drivers/ata/ata_piix.c
978 .. kernel-doc:: drivers/ata/sata_sil.c
984 The bulk of the ATA knowledge comes thanks to long conversations with
985 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
993 probe/reset code in his ATADRVR driver (www.ata-atapi.com).