diff options
Diffstat (limited to 'Documentation/driver-api/libata.rst')
| -rw-r--r-- | Documentation/driver-api/libata.rst | 53 |
1 files changed, 8 insertions, 45 deletions
diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst index 207f0d24de69..5da27a749246 100644 --- a/Documentation/driver-api/libata.rst +++ b/Documentation/driver-api/libata.rst @@ -32,22 +32,6 @@ register blocks. :c:type:`struct ata_port_operations <ata_port_operations>` ---------------------------------------------------------- -Disable ATA port -~~~~~~~~~~~~~~~~ - -:: - - void (*port_disable) (struct ata_port *); - - -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, -:c:func:`ata_port_disable` can be used as this hook. - -Called from :c:func:`ata_bus_probe` on a failed probe. Called from -:c:func:`ata_scsi_release`. - Post-IDENTIFY device configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -274,14 +258,6 @@ Exception and probe handling (EH) :: - void (*eng_timeout) (struct ata_port *ap); - void (*phy_reset) (struct ata_port *ap); - - -Deprecated. Use ``->error_handler()`` instead. - -:: - void (*freeze) (struct ata_port *ap); void (*thaw) (struct ata_port *ap); @@ -364,8 +340,7 @@ SATA phy read/write u32 val); -Read and write standard SATA phy registers. Currently only used if -``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function. +Read and write standard SATA phy registers. sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. Init and shutdown @@ -401,7 +376,7 @@ Error handling ============== This chapter describes how errors are handled under libata. Readers are -advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA +advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA exceptions doc first. Origins of commands @@ -424,12 +399,6 @@ How commands are issued ----------------------- Internal commands - 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 @@ -447,11 +416,6 @@ SCSI commands 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, :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->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`` @@ -508,7 +472,7 @@ also complete commands. 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. -3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the +3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the callback is not zero. Completion is short circuited and :c:func:`ata_qc_complete` returns. @@ -547,13 +511,12 @@ to return without deallocating the qc. This leads us to :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 :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`. +timeout and ATAPI error completion. This function will check if a qc is active +and has not failed yet. Such a qc will be marked with AC_ERR_TIMEOUT such that +EH will know to handle it later. Then it calls low level libata driver's +:c:func:`error_handler` callback. -If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and +When the :c:func:`error_handler` callback is invoked it 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 :c:func:`scsi_queue_insert` or finished with |