Lines Matching +full:ata +full:- +full:generic
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
301 to perform the low-level EH reset. If both operations are defined,
302 'hardreset' is preferred and used. If both are not defined, no low-level reset
303 is performed and EH assumes that an ATA class device is connected through the
311 Perform any hardware-specific actions necessary to finish processing
312 after executing a probe-time or EH-time command via
324 ``->irq_handler`` is the interrupt handling routine registered with the
325 system, by libata. ``->irq_clear`` is called during probe just before the
363 ``->port_start()`` is called just after the data structures for each port
364 are initialized. Typically this is used to alloc per-port DMA buffers /
366 use this entry point as a chance to allocate driver-private memory for
367 ``ap->private_data``.
373 ``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
375 used. Many drivers also free driver-private data from port at this time.
377 ``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
386 advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA
390 -------------------
396 yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
397 to NCQ tag 1-to-1.
399 libata commands can originate from two sources - libata itself and SCSI
406 -----------------------
411 is via ``qc->complete_fn()`` callback and the other is completion
412 ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
413 used by normal SCSI translated commands and ``qc->waiting`` is the
422 ``hostt->queuecommand`` callback. scmds can either be simulated or
426 ``qc->complete_fn()`` callback is used for completion notification. ATA
428 :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
432 Note that SCSI midlayer invokes hostt->queuecommand while holding
436 --------------------------
442 Currently 6 ATA command protocols are used. They can be sorted into the
445 ATA NO DATA or DMA
450 ATA PIO
468 --------------------------
480 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
482 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
488 1. ``qc->flags`` is cleared to zero.
490 2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
492 3. ``qc->waiting`` is cleared & completed (in that order).
494 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
497 is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
499 For all non-ATAPI commands, whether it fails or not, almost the same
507 :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
509 This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
511 sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
517 ------------------------
519 :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
520 for libata. As discussed above, this will be entered in two cases -
530 :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
534 not deallocated. The purpose of this half-completion is to use the qc as
546 ----------------------------
548 - Error representation is too crude. Currently any and all error
549 conditions are represented with ATA STATUS and ERROR registers.
550 Errors which aren't ATA device errors are treated as ATA device
552 properly represent ATA and other errors/exceptions is needed.
554 - When handling timeouts, no action is taken to make device forget
557 - EH handling via :c:func:`ata_scsi_error` is not properly protected from
562 - Too weak error recovery. Devices / controllers causing HSM mismatch
567 - ATA errors are directly handled in the interrupt handler and PIO
587 .. kernel-doc:: drivers/ata/libata-core.c
593 .. kernel-doc:: drivers/ata/libata-core.c
596 .. kernel-doc:: drivers/ata/libata-eh.c
601 .. kernel-doc:: drivers/ata/libata-scsi.c
604 .. kernel-doc:: drivers/ata/libata-scsi.c
607 ATA errors and exceptions
611 ATA/ATAPI devices and describe how they should be handled in
612 implementation-neutral way.
619 errors and non-error exceptional conditions. Where explicit distinction
620 between error and exception is necessary, the term 'non-error exception'
624 --------------------
631 In the following sections, two recovery actions - reset and
632 reconfiguring transport - are mentioned. These are described further in
639 during issuing or execution any ATA/ATAPI command.
641 - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
644 - !BSY && !DRQ during PIO data transfer.
646 - DRQ on command completion.
648 - !BSY && ERR after CDB transfer starts but before the last byte of CDB
649 is transferred. ATA/ATAPI standard states that "The device shall not
657 be anything - driver bug, faulty device, controller and/or cable.
663 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
666 These are errors detected and reported by ATA/ATAPI devices indicating
668 values are valid and describe error condition. Note that some of ATA bus
669 errors are detected by ATA/ATAPI devices and reported using the same
673 For ATA commands, this type of errors are indicated by !BSY && ERR
678 - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
681 - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
684 - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred
688 Of errors detected as above, the following are not ATA/ATAPI device
689 errors but ATA bus errors and should be handled according to
690 `ATA bus error <#excatATAbusErr>`__.
694 corruption occurred during data transfer. Up to ATA/ATAPI-7, the
696 transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
700 Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on
703 aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
706 However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
710 ATA/ATAPI device errors can be further categorized as follows.
713 This is indicated by UNC bit in the ERROR register. ATA devices
719 but ATA/ATAPI standard specifies that the amount of transferred data
737 non-applicable bits are marked with "na" in the output descriptions but
738 up to ATA/ATAPI-7 no definition of "na" can be found. However,
739 ATA/ATAPI-8 draft revision 1f describes "N/A" as follows.
759 similarly to other SCSI errors. Note that sense data may indicate ATA
761 PARITY ERROR). In such cases, the error should be considered as an ATA
762 bus error and handled according to `ATA bus error <#excatATAbusErr>`__.
764 ATA device error (NCQ)
775 command can be handled as a normal ATA command error as in
776 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
777 and all other in-flight commands must be retried. Note that this retry
778 should not be counted - it's likely that commands retried this way would
781 Note that ATA bus errors can be reported as ATA device NCQ errors. This
782 should be handled as described in `ATA bus error <#excatATAbusErr>`__.
788 ATA bus error
791 ATA bus error means that data corruption occurred during transmission
792 over ATA bus (SATA or PATA). This type of errors can be indicated by
794 - ICRC or ABRT error as described in
795 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.
797 - Controller-specific error completion with error information
800 - On some controllers, command timeout. In this case, there may be a
803 - Unknown/random errors, timeouts and all sorts of weirdities.
811 likely to indicate ATA bus error.
813 Once it's determined that ATA bus errors have possibly occurred,
814 lowering ATA bus transmission speed is one of actions which may
845 `ATA bus error <#excatATAbusErr>`__ for more details.
853 -------------------
871 - HSM is in unknown or invalid state
873 - HBA is in unknown or invalid state
875 - EH needs to make HBA/device forget about in-flight commands
877 - HBA/device behaves weirdly
883 - When it's known that HBA is in ready state but ATA/ATAPI device is in
886 - If HBA is in unknown state, reset both HBA and device.
895 OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI
900 RESET- signal. There is no standard way to initiate hardware reset
902 driver to directly tweak the RESET- signal.
907 controller-specific support as the second Register FIS to clear SRST
912 Although ATA/ATAPI standard doesn't describe exactly, EDD implies
914 Host-side EDD protocol can be handled with normal command processing
940 - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
942 - Parameters set with SET FEATURES including transfer mode setting
944 - Block count set with SET MULTIPLE MODE
946 - Other parameters (SET MAX, MEDIA LOCK...)
948 ATA/ATAPI standard specifies that some parameters must be maintained
952 (power-off).
954 Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET
970 - if SATA, decrease SATA PHY speed. if speed cannot be decreased,
972 - decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
974 - decrease PIO xfer speed. if at PIO3, complain, but continue
979 .. kernel-doc:: drivers/ata/ata_piix.c
985 .. kernel-doc:: drivers/ata/sata_sil.c
991 The bulk of the ATA knowledge comes thanks to long conversations with
992 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
1000 probe/reset code in his ATADRVR driver (www.ata-atapi.com).