Lines Matching +full:poll +full:- +full:retry +full:- +full:count
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
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
33 ----------------------------------------------------------
51 Post-IDENTIFY device configuration
60 Typically used to apply device-specific fixups prior to issue of SET
61 FEATURES - XFER MODE, and prior to operation.
76 Hooks called prior to the issue of SET FEATURES - XFER MODE command. The
77 optional ``->mode_filter()`` hook is called when libata has built a mask of
78 the possible modes. This is passed to the ``->mode_filter()`` function
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
89 ``->post_set_mode()`` is called unconditionally, after the SET FEATURES -
92 ``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``
104 ``->tf_load()`` is called to load the given taskfile into hardware
105 registers / DMA buffers. ``->tf_read()`` is called to read the hardware
107 values. Most drivers for taskfile-based hardware (PIO or MMIO) use
118 All bmdma-style drivers must implement this hook. This is the low-level
131 causes an ATA command, previously loaded with ``->tf_load()``, to be
132 initiated in hardware. Most drivers for taskfile-based hardware use
135 Per-cmd ATAPI DMA capabilities filter
143 Allow low-level driver to filter ATA PACKET commands, returning a status
161 the interrupt condition. Most drivers for taskfile-based hardware use
183 Issues the low-level hardware command(s) that causes one of N hardware
185 the ATA bus. This generally has no meaning on FIS-based devices.
187 Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
225 (``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the
226 hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
229 These hooks are typically either no-ops, or simply not implemented, in
230 FIS-based drivers.
248 High-level taskfile hooks
257 Higher-level hooks, these two hooks can potentially supersede several of
258 the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
259 buffers have been DMA-mapped, and is typically used to populate the
260 hardware's DMA scatter-gather table. Some drivers use the standard
264 ``->qc_issue`` is used to make a command active, once the hardware and S/G
266 :c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. More
267 advanced drivers implement their own ``->qc_issue``.
269 :c:func:`ata_sff_qc_issue` calls ``->sff_tf_load()``, ``->bmdma_setup()``, and
270 ``->bmdma_start()`` as necessary to initiate a transfer.
281 Deprecated. Use ``->error_handler()`` instead.
294 The optional ``->freeze()`` callback can be used for freezing the port
295 hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
296 cannot be frozen hardware-wise, the interrupt handler must ack and clear
299 The optional ``->thaw()`` callback is called to perform the opposite of
300 ``->freeze()``: prepare the port for normal operation once again. Unmask
308 ``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
321 called to perform the low-level EH reset.
328 Perform any hardware-specific actions necessary to finish processing
329 after executing a probe-time or EH-time command via
341 ``->irq_handler`` is the interrupt handling routine registered with the
342 system, by libata. ``->irq_clear`` is called during probe just before the
368 ``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function.
381 ``->port_start()`` is called just after the data structures for each port
382 are initialized. Typically this is used to alloc per-port DMA buffers /
384 use this entry point as a chance to allocate driver-private memory for
385 ``ap->private_data``.
391 ``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
393 used. Many drivers also free driver-private data from port at this time.
395 ``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
408 -------------------
414 yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
415 to NCQ tag 1-to-1.
417 libata commands can originate from two sources - libata itself and SCSI
424 -----------------------
428 Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry
435 is via ``qc->complete_fn()`` callback and the other is completion
436 ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
437 used by normal SCSI translated commands and ``qc->waiting`` is the
446 ``hostt->queuecommand`` callback. scmds can either be simulated or
453 ``qc->scsidone``.
455 ``qc->complete_fn()`` callback is used for completion notification. ATA
457 :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
461 Note that SCSI midlayer invokes hostt->queuecommand while holding
465 --------------------------
486 category. packet_task is used to poll BSY bit after issuing PACKET
497 --------------------------
509 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
511 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the
517 1. ``qc->flags`` is cleared to zero.
519 2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
521 3. ``qc->waiting`` is cleared & completed (in that order).
523 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
526 is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
528 For all non-ATAPI commands, whether it fails or not, almost the same
536 :c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
538 This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
540 sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
546 ------------------------
548 :c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
549 for libata. As discussed above, this will be entered in two cases -
560 :c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
564 not deallocated. The purpose of this half-completion is to use the qc as
576 ----------------------------
578 - Error representation is too crude. Currently any and all error
584 - When handling timeouts, no action is taken to make device forget
587 - EH handling via :c:func:`ata_scsi_error` is not properly protected from
592 - Too weak error recovery. Devices / controllers causing HSM mismatch
597 - ATA errors are directly handled in the interrupt handler and PIO
617 .. kernel-doc:: drivers/ata/libata-core.c
623 .. kernel-doc:: drivers/ata/libata-core.c
626 .. kernel-doc:: drivers/ata/libata-eh.c
631 .. kernel-doc:: drivers/ata/libata-scsi.c
634 .. kernel-doc:: drivers/ata/libata-scsi.c
642 implementation-neutral way.
649 errors and non-error exceptional conditions. Where explicit distinction
650 between error and exception is necessary, the term 'non-error exception'
654 --------------------
661 In the following sections, two recovery actions - reset and
662 reconfiguring transport - are mentioned. These are described further in
671 - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
674 - !BSY && !DRQ during PIO data transfer.
676 - DRQ on command completion.
678 - !BSY && ERR after CDB transfer starts but before the last byte of CDB
687 be anything - driver bug, faulty device, controller and/or cable.
693 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
708 - !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
711 - !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
714 - !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred
724 corruption occurred during data transfer. Up to ATA/ATAPI-7, the
726 transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
730 Up to ATA/ATAPI-7, the standard specifies that ABRT could be set on
733 aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
736 However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
767 non-applicable bits are marked with "na" in the output descriptions but
768 up to ATA/ATAPI-7 no definition of "na" can be found. However,
769 ATA/ATAPI-8 draft revision 1f describes "N/A" as follows.
806 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
807 and all other in-flight commands must be retried. Note that this retry
808 should not be counted - it's likely that commands retried this way would
824 - ICRC or ABRT error as described in
825 `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.
827 - Controller-specific error completion with error information
830 - On some controllers, command timeout. In this case, there may be a
833 - Unknown/random errors, timeouts and all sorts of weirdities.
883 -------------------
901 - HSM is in unknown or invalid state
903 - HBA is in unknown or invalid state
905 - EH needs to make HBA/device forget about in-flight commands
907 - HBA/device behaves weirdly
913 - When it's known that HBA is in ready state but ATA/ATAPI device is in
916 - If HBA is in unknown state, reset both HBA and device.
930 RESET- signal. There is no standard way to initiate hardware reset
932 driver to directly tweak the RESET- signal.
937 controller-specific support as the second Register FIS to clear SRST
944 Host-side EDD protocol can be handled with normal command processing
970 - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
972 - Parameters set with SET FEATURES including transfer mode setting
974 - Block count set with SET MULTIPLE MODE
976 - Other parameters (SET MAX, MEDIA LOCK...)
982 (power-off).
1000 - if SATA, decrease SATA PHY speed. if speed cannot be decreased,
1002 - decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
1004 - decrease PIO xfer speed. if at PIO3, complain, but continue
1009 .. kernel-doc:: drivers/ata/ata_piix.c
1015 .. kernel-doc:: drivers/ata/sata_sil.c
1022 Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
1030 probe/reset code in his ATADRVR driver (www.ata-atapi.com).