Lines Matching +full:no +full:- +full:reset +full:- +full:on +full:- +full:init
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 ----------------------------------------------------------
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
70 is the library records the decisions for the modes of each drive on a
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
145 the interrupt condition. Most drivers for taskfile-based hardware use
159 Select ATA device on bus
167 Issues the low-level hardware command(s) that causes one of N hardware
168 devices to be considered 'selected' (active and available for use) on
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.
268 follows a successful reset.
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
289 'prereset' hook (may be NULL) is called during an EH reset, before any
292 'postreset' hook (may be NULL) is called after the EH reset is
293 performed. Based on existing conditions, severity of the problem, and
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
346 Init and shutdown
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
367 release DMA/memory resources, now that they are no longer actively being
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.
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
416 translated. No qc is involved in processing a simulated scmd. The
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 --------------------------
431 Depending on which protocol and which controller are used, commands are
438 ATA NO DATA or DMA
441 issued. Device will raise interrupt on completion.
446 pio_task on ata_wq performs polling and IO.
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
534 invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
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
551 usual command processing. On EH entrance, the device is not in
555 - Too weak error recovery. Devices / controllers causing HSM mismatch
556 errors and other errors quite often require reset to return to known
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.
652 As HSM is violated, reset is necessary to restore known state.
656 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
667 during command execution and on completion.
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
692 ABRT 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
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
700 errors can turn on ABRT. So, this is kind of gray area. Some
713 on error completion is indeterminate, so we cannot assume that
729 Depending on commands, not all STATUS/ERROR bits are applicable. These
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.
735 A keyword the indicates a field has no defined value in this
740 devices and thus need no explicit masking.
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.
800 for many cases, there is no way to tell if an error condition is due to
846 -------------------
859 Reset subsection
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
873 to improve EH robustness. Whether to reset both or either one of HBA and
874 device depends on situation but the following scheme is recommended.
876 - When it's known that HBA is in ready state but ATA/ATAPI device is in
877 unknown state, reset only device.
879 - If HBA is in unknown state, reset both HBA and device.
885 specific requirements and mechanism to reset themselves. This must be
888 OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPI
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
895 driver to directly tweak the RESET- signal.
897 Software reset
898 This is achieved by turning CONTROL SRST bit on for at least 5us.
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.
906 some level of resetting, possibly similar level with software reset.
907 Host-side EDD protocol can be handled with normal command processing
909 other commands. As in software reset, EDD affects both devices on a
912 Although EDD does reset devices, this doesn't suit error handling as
916 ATAPI DEVICE RESET command
917 This is very similar to software reset except that reset can be
921 SATA phy reset
923 it's identical to PATA hardware reset. Note that this can be done
925 to implement than software reset.
929 previous or newly adjusted values after reset.
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
943 them. Always reconfiguring needed parameters after reset is required for
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
989 and in general for motivation to hack on libata.
992 the early probing was based on extensive study of Hale Landis's
993 probe/reset code in his ATADRVR driver (www.ata-atapi.com).