Lines Matching +full:hardware +full:- +full:wise
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
28 similar to PCI IDE hardware may utilize several generic helpers,
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
64 unsuitable due to hardware limits. It is not valid to use this interface
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
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
143 Reads the Status/AltStatus ATA shadow register from hardware. On some
144 hardware, reading the Status register has the side effect of clearing
145 the interrupt condition. Most drivers for taskfile-based hardware use
156 Write the device control ATA shadow register to the hardware. Most
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
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
294 hardware capabilities,
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
308 Hardware interrupt handling
317 ``->irq_handler`` is the interrupt handling routine registered with the
318 system, by libata. ``->irq_clear`` is called during probe just before the
319 interrupt handler is registered, to be sure hardware is quiet.
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.
371 The hook must finalize hardware shutdown, release DMA and other
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 --------------------------
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
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
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
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
650 be anything - driver bug, faulty device, controller and/or cable.
656 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
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
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
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.
753 bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI
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
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.
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.
891 PATA 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.
900 controller-specific support as the second Register FIS to clear SRST
907 Host-side EDD protocol can be handled with normal command processing
923 it's identical to PATA hardware reset. Note that this can be done
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...)
942 across hardware or software reset, but doesn't strictly specify all of
945 (power-off).
949 hardware reset and the result used for further operation. OS driver is
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
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).