libata.rst: add c function and struct cross-references

libata Driver API

=================

struct ata_port_operations is defined for every low-level libata

:c:type:`struct ata_port_operations <ata_port_operations>`

is defined for every low-level libata

hardware driver, and it controls how the low-level driver interfaces

with the ATA and SCSI layers.

FIS-based drivers will hook into the system with ->qc_prep() and

->qc_issue() high-level hooks. Hardware which behaves in a manner

FIS-based drivers will hook into the system with ``->qc_prep()`` and

``->qc_issue()`` high-level hooks. Hardware which behaves in a manner

similar to PCI IDE hardware may utilize several generic helpers,

defining at a bare minimum the bus I/O addresses of the ATA shadow

register blocks.

struct ata_port_operations

----------------------------

:c:type:`struct ata_port_operations <ata_port_operations>`

----------------------------------------------------------

Disable ATA port

~~~~~~~~~~~~~~~~

    void (*port_disable) (struct ata_port *);

Called from ata_bus_probe() error path, as well as when unregistering

Called from :c:func:`ata_bus_probe` error path, as well as when unregistering

from the SCSI module (rmmod, hot unplug). This function should do

whatever needs to be done to take the port out of use. In most cases,

ata_port_disable() can be used as this hook.

:c:func:`ata_port_disable` can be used as this hook.

Called from ata_bus_probe() on a failed probe. Called from

ata_scsi_release().

Called from :c:func:`ata_bus_probe` on a failed probe. Called from

:c:func:`ata_scsi_release`.

Post-IDENTIFY device configuration

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hooks called prior to the issue of SET FEATURES - XFER MODE command. The

optional ->mode_filter() hook is called when libata has built a mask of

the possible modes. This is passed to the ->mode_filter() function

optional ``->mode_filter()`` hook is called when libata has built a mask of

the possible modes. This is passed to the ``->mode_filter()`` function

which should return a mask of valid modes after filtering those

unsuitable due to hardware limits. It is not valid to use this interface

to add modes.

dev->pio_mode and dev->dma_mode are guaranteed to be valid when

->set_piomode() and when ->set_dmamode() is called. The timings for

``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when

``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for

any other drive sharing the cable will also be valid at this point. That

is the library records the decisions for the modes of each drive on a

channel before it attempts to set any of them.

->post_set_mode() is called unconditionally, after the SET FEATURES -

``->post_set_mode()`` is called unconditionally, after the SET FEATURES -

XFER MODE command completes successfully.

->set_piomode() is always called (if present), but ->set_dma_mode()

``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``

is only called if DMA is possible.

Taskfile read/write

    void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);

->tf_load() is called to load the given taskfile into hardware

registers / DMA buffers. ->tf_read() is called to read the hardware

``->tf_load()`` is called to load the given taskfile into hardware

registers / DMA buffers. ``->tf_read()`` is called to read the hardware

registers / DMA buffers, to obtain the current set of taskfile register

values. Most drivers for taskfile-based hardware (PIO or MMIO) use

ata_sff_tf_load() and ata_sff_tf_read() for these hooks.

:c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks.

PIO data read/write

~~~~~~~~~~~~~~~~~~~

All bmdma-style drivers must implement this hook. This is the low-level

operation that actually copies the data bytes during a PIO data

transfer. Typically the driver will choose one of

ata_sff_data_xfer_noirq(), ata_sff_data_xfer(), or

ata_sff_data_xfer32().

:c:func:`ata_sff_data_xfer_noirq`, :c:func:`ata_sff_data_xfer`, or

:c:func:`ata_sff_data_xfer32`.

ATA command execute

~~~~~~~~~~~~~~~~~~~

    void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);

causes an ATA command, previously loaded with ->tf_load(), to be

causes an ATA command, previously loaded with ``->tf_load()``, to be

initiated in hardware. Most drivers for taskfile-based hardware use

ata_sff_exec_command() for this hook.

:c:func:`ata_sff_exec_command` for this hook.

Per-cmd ATAPI DMA capabilities filter

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reads the Status/AltStatus ATA shadow register from hardware. On some

hardware, reading the Status register has the side effect of clearing

the interrupt condition. Most drivers for taskfile-based hardware use

ata_sff_check_status() for this hook.

:c:func:`ata_sff_check_status` for this hook.

Write specific ATA shadow register

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

devices to be considered 'selected' (active and available for use) on

the ATA bus. This generally has no meaning on FIS-based devices.

Most drivers for taskfile-based hardware use ata_sff_dev_select() for

Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for

this hook.

Private tuning method

When setting up an IDE BMDMA transaction, these hooks arm

(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the

hardware's DMA engine. ->bmdma_status is used to read the standard PCI

(``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the

hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI

IDE DMA Status register.

These hooks are typically either no-ops, or simply not implemented, in

FIS-based drivers.

Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()

hook. ata_bmdma_setup() will write the pointer to the PRD table to the

IDE PRD Table Address register, enable DMA in the DMA Command register,

and call exec_command() to begin the transfer.

Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the

:c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer

to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA

Command register, and call :c:func:`exec_command` to begin the transfer.

Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()

hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA

Command register.

Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the

:c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the

ATA_DMA_START flag to the DMA Command register.

Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()

hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA

command register.

Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the

:c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START

flag in the DMA command register.

Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status()

hook.

Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the

:c:func:`bmdma_status` hook.

High-level taskfile hooks

~~~~~~~~~~~~~~~~~~~~~~~~~

Higher-level hooks, these two hooks can potentially supercede several of

the above taskfile/DMA engine hooks. ->qc_prep is called after the

the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the

buffers have been DMA-mapped, and is typically used to populate the

hardware's DMA scatter-gather table. Most drivers use the standard

ata_qc_prep() helper function, but more advanced drivers roll their

:c:func:`ata_qc_prep` helper function, but more advanced drivers roll their

own.

->qc_issue is used to make a command active, once the hardware and S/G

``->qc_issue`` is used to make a command active, once the hardware and S/G

tables have been prepared. IDE BMDMA drivers use the helper function

ata_qc_issue_prot() for taskfile protocol-based dispatch. More

advanced drivers implement their own ->qc_issue.

:c:func:`ata_qc_issue_prot` for taskfile protocol-based dispatch. More

advanced drivers implement their own ``->qc_issue``.

ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and

->bmdma_start() as necessary to initiate a transfer.

:c:func:`ata_qc_issue_prot` calls ``->tf_load()``, ``->bmdma_setup()``, and

``->bmdma_start()`` as necessary to initiate a transfer.

Exception and probe handling (EH)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    void (*phy_reset) (struct ata_port *ap);

Deprecated. Use ->error_handler() instead.

Deprecated. Use ``->error_handler()`` instead.

::

    void (*thaw) (struct ata_port *ap);

ata_port_freeze() is called when HSM violations or some other

:c:func:`ata_port_freeze` is called when HSM violations or some other

condition disrupts normal operation of the port. A frozen port is not

allowed to perform any operation until the port is thawed, which usually

follows a successful reset.

The optional ->freeze() callback can be used for freezing the port

The optional ``->freeze()`` callback can be used for freezing the port

hardware-wise (e.g. mask interrupt and stop DMA engine). If a port

cannot be frozen hardware-wise, the interrupt handler must ack and clear

interrupts unconditionally while the port is frozen.

The optional ->thaw() callback is called to perform the opposite of

->freeze(): prepare the port for normal operation once again. Unmask

The optional ``->thaw()`` callback is called to perform the opposite of

``->freeze()``: prepare the port for normal operation once again. Unmask

interrupts, start DMA engine, etc.

::

    void (*error_handler) (struct ata_port *ap);

->error_handler() is a driver's hook into probe, hotplug, and recovery

``->error_handler()`` is a driver's hook into probe, hotplug, and recovery

and other exceptional conditions. The primary responsibility of an

implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with

a set of EH hooks as arguments:

implementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh`

with a set of EH hooks as arguments:

'prereset' hook (may be NULL) is called during an EH reset, before any

other actions are taken.

Perform any hardware-specific actions necessary to finish processing

after executing a probe-time or EH-time command via

ata_exec_internal().

:c:func:`ata_exec_internal`.

Hardware interrupt handling

~~~~~~~~~~~~~~~~~~~~~~~~~~~

    void (*irq_clear) (struct ata_port *);

->irq_handler is the interrupt handling routine registered with the

system, by libata. ->irq_clear is called during probe just before the

``->irq_handler`` is the interrupt handling routine registered with the

system, by libata. ``->irq_clear`` is called during probe just before the

interrupt handler is registered, to be sure hardware is quiet.

The second argument, dev_instance, should be cast to a pointer to

struct ata_host_set.

:c:type:`struct ata_host_set <ata_host_set>`.

Most legacy IDE drivers use ata_sff_interrupt() for the irq_handler

Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler

hook, which scans all ports in the host_set, determines which queued

command was active (if any), and calls ata_sff_host_intr(ap,qc).

Most legacy IDE drivers use ata_sff_irq_clear() for the irq_clear()

hook, which simply clears the interrupt and error flags in the DMA

status register.

Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the

:c:func:`irq_clear` hook, which simply clears the interrupt and error flags

in the DMA status register.

SATA phy read/write

~~~~~~~~~~~~~~~~~~~

Read and write standard SATA phy registers. Currently only used if

->phy_reset hook called the sata_phy_reset() helper function. sc_reg

is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.

``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function.

sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.

Init and shutdown

~~~~~~~~~~~~~~~~~

    void (*host_stop) (struct ata_host_set *host_set);

->port_start() is called just after the data structures for each port

``->port_start()`` is called just after the data structures for each port

are initialized. Typically this is used to alloc per-port DMA buffers /

tables / rings, enable DMA engines, and similar tasks. Some drivers also

use this entry point as a chance to allocate driver-private memory for

ap->private_data.

``ap->private_data``.

Many drivers use ata_port_start() as this hook or call it from their

own port_start() hooks. ata_port_start() allocates space for a legacy

IDE PRD table and returns.

Many drivers use :c:func:`ata_port_start` as this hook or call it from their

own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for

a legacy IDE PRD table and returns.

->port_stop() is called after ->host_stop(). Its sole function is to

``->port_stop()`` is called after ``->host_stop()``. Its sole function is to

release DMA/memory resources, now that they are no longer actively being

used. Many drivers also free driver-private data from port at this time.

->host_stop() is called after all ->port_stop() calls have completed.

``->host_stop()`` is called after all ``->port_stop()`` calls have completed.

The hook must finalize hardware shutdown, release DMA and other

resources, etc. This hook may be specified as NULL, in which case it is

not called.

Origins of commands

-------------------

In libata, a command is represented with struct ata_queued_cmd or qc.

In libata, a command is represented with

:c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc.

qc's are preallocated during port initialization and repetitively used

for command executions. Currently only one qc is allocated per port but

yet-to-be-merged NCQ branch allocates one for each tag and maps each qc

-----------------------

Internal commands

    First, qc is allocated and initialized using ata_qc_new_init().

    Although ata_qc_new_init() doesn't implement any wait or retry

    First, qc is allocated and initialized using :c:func:`ata_qc_new_init`.

    Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry

    mechanism when qc is not available, internal commands are currently

    issued only during initialization and error recovery, so no other

    command is active and allocation is guaranteed to succeed.

    Once allocated qc's taskfile is initialized for the command to be

    executed. qc currently has two mechanisms to notify completion. One

    is via qc->complete_fn() callback and the other is completion

    qc->waiting. qc->complete_fn() callback is the asynchronous path

    used by normal SCSI translated commands and qc->waiting is the

    is via ``qc->complete_fn()`` callback and the other is completion

    ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path

    used by normal SCSI translated commands and ``qc->waiting`` is the

    synchronous (issuer sleeps in process context) path used by internal

    commands.

    qc is issued.

SCSI commands

    All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand

    callback. scmds can either be simulated or translated. No qc is

    involved in processing a simulated scmd. The result is computed

    right away and the scmd is completed.

    All libata drivers use :c:func:`ata_scsi_queuecmd` as

    ``hostt->queuecommand`` callback. scmds can either be simulated or

    translated. No qc is involved in processing a simulated scmd. The

    result is computed right away and the scmd is completed.

    For a translated scmd, ata_qc_new_init() is invoked to allocate a

    For a translated scmd, :c:func:`ata_qc_new_init` is invoked to allocate a

    qc and the scmd is translated into the qc. SCSI midlayer's

    completion notification function pointer is stored into

    qc->scsidone.

    ``qc->scsidone``.

    qc->complete_fn() callback is used for completion notification. ATA

    commands use ata_scsi_qc_complete() while ATAPI commands use

    atapi_qc_complete(). Both functions end up calling qc->scsidone to

    notify upper layer when the qc is finished. After translation is

    completed, the qc is issued with ata_qc_issue().

    ``qc->complete_fn()`` callback is used for completion notification. ATA

    commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use

    :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``

    to notify upper layer when the qc is finished. After translation is

    completed, the qc is issued with :c:func:`ata_qc_issue`.

    Note that SCSI midlayer invokes hostt->queuecommand while holding

    host_set lock, so all above occur while holding host_set lock.

How commands are completed

--------------------------

Once issued, all qc's are either completed with ata_qc_complete() or

Once issued, all qc's are either completed with :c:func:`ata_qc_complete` or

time out. For commands which are handled by interrupts,

ata_host_intr() invokes ata_qc_complete(), and, for PIO tasks,

pio_task invokes ata_qc_complete(). In error cases, packet_task may

:c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks,

pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may

also complete commands.

ata_qc_complete() does the following.

:c:func:`ata_qc_complete` does the following.

1. DMA memory is unmapped.

2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.

3. qc->complete_fn() callback is invoked. If the return value of the

3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the

   callback is not zero. Completion is short circuited and

   ata_qc_complete() returns.

   :c:func:`ata_qc_complete` returns.

4. __ata_qc_complete() is called, which does

4. :c:func:`__ata_qc_complete` is called, which does

   1. qc->flags is cleared to zero.

   1. ``qc->flags`` is cleared to zero.

   2. ap->active_tag and qc->tag are poisoned.

   2. ``ap->active_tag`` and ``qc->tag`` are poisoned.

   3. qc->waiting is cleared & completed (in that order).

   3. ``qc->waiting`` is cleared & completed (in that order).

   4. qc is deallocated by clearing appropriate bit in ap->qactive.

   4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.

So, it basically notifies upper layer and deallocates qc. One exception

is short-circuit path in #3 which is used by atapi_qc_complete().

is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.

For all non-ATAPI commands, whether it fails or not, almost the same

code path is taken and very little error handling takes place. A qc is

However, failed ATAPI commands require more handling as REQUEST SENSE is

needed to acquire sense data. If an ATAPI command fails,

ata_qc_complete() is invoked with error status, which in turn invokes

atapi_qc_complete() via qc->complete_fn() callback.

:c:func:`ata_qc_complete` is invoked with error status, which in turn invokes

:c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.

This makes atapi_qc_complete() set scmd->result to

This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to

SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the

sense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer

will invoke EH for the scmd, and returning 1 makes ata_qc_complete()

sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer

will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`

to return without deallocating the qc. This leads us to

ata_scsi_error() with partially completed qc.

:c:func:`ata_scsi_error` with partially completed qc.

ata_scsi_error()

------------------

:c:func:`ata_scsi_error`

------------------------

ata_scsi_error() is the current transportt->eh_strategy_handler()

:c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``

for libata. As discussed above, this will be entered in two cases -

timeout and ATAPI error completion. This function calls low level libata

driver's eng_timeout() callback, the standard callback for which is

ata_eng_timeout(). It checks if a qc is active and calls

ata_qc_timeout() on the qc if so. Actual error handling occurs in

ata_qc_timeout().

driver's :c:func:`eng_timeout` callback, the standard callback for which is

:c:func:`ata_eng_timeout`. It checks if a qc is active and calls

:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in

:c:func:`ata_qc_timeout`.

If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and

If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and

completes the qc. Note that as we're currently in EH, we cannot call

scsi_done. As described in SCSI EH doc, a recovered scmd should be

either retried with scsi_queue_insert() or finished with

scsi_finish_command(). Here, we override qc->scsidone with

scsi_finish_command() and calls ata_qc_complete().

either retried with :c:func:`scsi_queue_insert` or finished with

:c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with

:c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.

If EH is invoked due to a failed ATAPI qc, the qc here is completed but

not deallocated. The purpose of this half-completion is to use the qc as

but it works.

Once control reaches here, the qc is deallocated by invoking

__ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE

:c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE

is issued. Once sense data is acquired, scmd is finished by directly

invoking scsi_finish_command() on the scmd. Note that as we already

invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already

have completed and deallocated the qc which was associated with the

scmd, we don't need to/cannot call ata_qc_complete() again.

scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.

Problems with the current EH

----------------------------

-  When handling timeouts, no action is taken to make device forget

   about the timed out command and ready for new commands.

-  EH handling via ata_scsi_error() is not properly protected from

-  EH handling via :c:func:`ata_scsi_error` is not properly protected from

   usual command processing. On EH entrance, the device is not in

   quiescent state. Timed out commands may succeed or fail any time.

   pio_task and atapi_task may still be running.

.. kernel-doc:: drivers/ata/libata-core.c

   :internal:

.. kernel-doc:: drivers/ata/libata-eh.c

libata SCSI translation/emulation

=================================