Lines Matching +full:ide +full:- +full:port
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
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
145 the interrupt condition. Most drivers for taskfile-based hardware use
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
197 Control PCI IDE BMDMA engine
208 When setting up an IDE BMDMA transaction, these hooks arm
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
211 IDE DMA Status register.
213 These hooks are typically either no-ops, or simply not implemented, in
214 FIS-based drivers.
216 Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the
218 to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA
221 Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the
225 Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the
229 Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the
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
249 tables have been prepared. IDE BMDMA drivers use the helper function
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.
266 condition disrupts normal operation of the port. A frozen port is not
267 allowed to perform any operation until the port is thawed, which usually
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
273 interrupts unconditionally while the port is frozen.
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
290 This function will call the various reset operations for a port, as needed.
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
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
331 Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler
335 Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for 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``.
371 a legacy IDE PRD table and returns.
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.
390 -------------------
394 qc's are preallocated during port initialization and repetitively used
395 for command executions. Currently only one qc is allocated per port but
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 --------------------------
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
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
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 --------------------
627 master IDE interface. If a controller provides other better mechanism
631 In the following sections, two recovery actions - reset and
632 reconfiguring transport - are mentioned. These are described further in
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
657 be anything - driver bug, faulty device, controller and/or cable.
663 ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
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
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
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.
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
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.
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.
889 taskfile/BMDMA PCI IDE, stopping active DMA transaction may be
891 taskfile/BMDMA PCI IDE complying controllers may have implementation
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
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...)
952 (power-off).
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
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).