[PATCH] scsi: core: Document the role of scsi_done()

[PATCH] scsi: core: Document the role of scsi_done()

[Bart Van Assche]

Document the role of scsi_done() and also how it deals with commands owned
by the SCSI error handler.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 drivers/scsi/scsi_lib.c | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index f695a6605815..ab39514cc0c6 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -1789,6 +1789,20 @@ static void scsi_done_internal(struct scsi_cmnd *cmd, bool complete_directly)
 		blk_mq_complete_request(req);
 }
 
+/**
+ * scsi_done - Notify the SCSI mid-layer that a command has completed
+ * @cmd: Completed SCSI command
+ *
+ * Called by a SCSI low-level driver to notify the SCSI mid-layer that the
+ * command has completed. There are two cases:
+ *
+ * - The SCSI error handler does not own @cmd. In this case scsi_complete()
+ *   decides how to complete the command based on the value of @cmd->result.
+ * - The SCSI error handler owns @cmd because scsi_timeout() has set
+ *   SCMD_STATE_COMPLETE. In this case this function has no effect, @cmd->result
+ *   is ignored and the SCSI error handler decides whether to retry or fail
+ *   @cmd. See also scmd_eh_abort_handler() and scsi_eh_flush_done_q().
+ */
 void scsi_done(struct scsi_cmnd *cmd)
 {
 	scsi_done_internal(cmd, false);

Re: [PATCH] scsi: core: Document the role of scsi_done()

[Martin K. Petersen]

Bart,

> Document the role of scsi_done() and also how it deals with commands
> owned by the SCSI error handler.

Applied to 7.4/scsi-staging, thanks!

-- 
Martin K. Petersen

Re: [PATCH] scsi: core: Document the role of scsi_done()

[Martin K. Petersen (Oracle)]

On Wed, 14 Oct 2026 17:05:10 -0700, Bart Van Assche wrote:

> Document the role of scsi_done() and also how it deals with commands owned
> by the SCSI error handler.

Applied to 7.4/scsi-queue, thanks!

[1/1] scsi: core: Document the role of scsi_done()
      https://git.kernel.org/mkp/scsi/c/cfb7224381c9

-- 
Martin K. Petersen