[PATCH] ata: libata: Fix scsi_done() documentation

[PATCH] ata: libata: Fix scsi_done() documentation

[Bart Van Assche]

In 2008 the SCSI core was converted to use the block layer timeout
infrastructure instead of its own infrastructure (see also patch
"block: unify request timeout handling"). Since then, calling
scsi_done() while SCSI host recovery is in progress has no effect.
Originally the REQ_ATOM_COMPLETE flag was used to prevent double
completions. Today the SCMD_STATE_COMPLETE flag is used to prevent
double completions.

Instead of mentioning that calling scsi_done() is not allowed while
host recovery is in progress, mention that it has no effect.

Cc: Damien Le Moal <dlemoal@kernel.org>
Cc: Niklas Cassel <cassel@kernel.org>
Cc: linux-ide@vger.kernel.org
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/driver-api/libata.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
index 28b8437f6e4f..c130b480180f 100644
--- a/Documentation/driver-api/libata.rst
+++ b/Documentation/driver-api/libata.rst
@@ -524,8 +524,8 @@ EH will know to handle it later. Then it calls low level libata driver's
 :c:func:`error_handler` callback.
 
 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
+completes the qc. Note that as we're currently in EH, scsi_done() has
+no effect. As described in SCSI EH doc, a recovered scmd should be
 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`.

Re: [PATCH] ata: libata: Fix scsi_done() documentation

[Damien Le Moal]

On 2026/09/25 20:05, Bart Van Assche wrote:
> In 2008 the SCSI core was converted to use the block layer timeout
> infrastructure instead of its own infrastructure (see also patch
> "block: unify request timeout handling"). Since then, calling
> scsi_done() while SCSI host recovery is in progress has no effect.
> Originally the REQ_ATOM_COMPLETE flag was used to prevent double
> completions. Today the SCMD_STATE_COMPLETE flag is used to prevent
> double completions.
> 
> Instead of mentioning that calling scsi_done() is not allowed while
> host recovery is in progress, mention that it has no effect.
> 
> Cc: Damien Le Moal <dlemoal@kernel.org>
> Cc: Niklas Cassel <cassel@kernel.org>
> Cc: linux-ide@vger.kernel.org
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>

Looks good.

Reviewed-by: Damien Le Moal <dlemoal@kernel.org>


-- 
Damien Le Moal
Western Digital Research