[PATCH] scsi: core: Introduce an enumeration type for the SCSI_MLQUEUE constants

[PATCH] scsi: core: Introduce an enumeration type for the SCSI_MLQUEUE constants

[Bart Van Assche]

Multiple functions in the SCSI core accept an 'int reason' argument.
The 'int' type of these arguments doesn't make it clear what values are
acceptable for these arguments. Document which values are supported for
these arguments by introducing the enumeration type scsi_qc_status. 'qc'
in the type name stands for 'queuecommand' since the values passed as the
'reason' argument are the .queuecommand() return values.

Cc: John Garry <john.g.garry@oracle.com>
Cc: Hannes Reinecke <hare@suse.de>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 drivers/scsi/scsi_lib.c  | 11 ++++++-----
 drivers/scsi/scsi_priv.h |  3 ++-
 include/scsi/scsi.h      | 13 ++++++++-----
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index 51ad2ad07e43..75c94f353114 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -76,7 +76,7 @@ int scsi_init_sense_cache(struct Scsi_Host *shost)
 }
 
 static void
-scsi_set_blocked(struct scsi_cmnd *cmd, int reason)
+scsi_set_blocked(struct scsi_cmnd *cmd, enum scsi_qc_status reason)
 {
 	struct Scsi_Host *host = cmd->device->host;
 	struct scsi_device *device = cmd->device;
@@ -139,7 +139,8 @@ static void scsi_mq_requeue_cmd(struct scsi_cmnd *cmd, unsigned long msecs)
  * for a requeue after completion, which should only occur in this
  * file.
  */
-static void __scsi_queue_insert(struct scsi_cmnd *cmd, int reason, bool unbusy)
+static void __scsi_queue_insert(struct scsi_cmnd *cmd,
+				enum scsi_qc_status reason, bool unbusy)
 {
 	struct scsi_device *device = cmd->device;
 
@@ -179,7 +180,7 @@ static void __scsi_queue_insert(struct scsi_cmnd *cmd, int reason, bool unbusy)
  * Context: This could be called either from an interrupt context or a normal
  * process context.
  */
-void scsi_queue_insert(struct scsi_cmnd *cmd, int reason)
+void scsi_queue_insert(struct scsi_cmnd *cmd, enum scsi_qc_status reason)
 {
 	__scsi_queue_insert(cmd, reason, true);
 }
@@ -1577,7 +1578,7 @@ static void scsi_complete(struct request *rq)
  * Return: nonzero return request was rejected and device's queue needs to be
  * plugged.
  */
-static int scsi_dispatch_cmd(struct scsi_cmnd *cmd)
+static enum scsi_qc_status scsi_dispatch_cmd(struct scsi_cmnd *cmd)
 {
 	struct Scsi_Host *host = cmd->device->host;
 	int rtn = 0;
@@ -1826,7 +1827,7 @@ static blk_status_t scsi_queue_rq(struct blk_mq_hw_ctx *hctx,
 	struct Scsi_Host *shost = sdev->host;
 	struct scsi_cmnd *cmd = blk_mq_rq_to_pdu(req);
 	blk_status_t ret;
-	int reason;
+	enum scsi_qc_status reason;
 
 	WARN_ON_ONCE(cmd->budget_token < 0);
 
diff --git a/drivers/scsi/scsi_priv.h b/drivers/scsi/scsi_priv.h
index d07ec15d6c00..7a193cc04e5b 100644
--- a/drivers/scsi/scsi_priv.h
+++ b/drivers/scsi/scsi_priv.h
@@ -102,7 +102,8 @@ void scsi_eh_done(struct scsi_cmnd *scmd);
 
 /* scsi_lib.c */
 extern void scsi_device_unbusy(struct scsi_device *sdev, struct scsi_cmnd *cmd);
-extern void scsi_queue_insert(struct scsi_cmnd *cmd, int reason);
+extern void scsi_queue_insert(struct scsi_cmnd *cmd,
+			      enum scsi_qc_status reason);
 extern void scsi_io_completion(struct scsi_cmnd *, unsigned int);
 extern void scsi_run_host_queues(struct Scsi_Host *shost);
 extern void scsi_requeue_run_queue(struct work_struct *work);
diff --git a/include/scsi/scsi.h b/include/scsi/scsi.h
index 96b350366670..08ac3200b4a4 100644
--- a/include/scsi/scsi.h
+++ b/include/scsi/scsi.h
@@ -106,12 +106,15 @@ enum scsi_disposition {
 };
 
 /*
- * Midlevel queue return values.
+ * Status values returned by the .queuecommand() callback if a command has not
+ * been queued.
  */
-#define SCSI_MLQUEUE_HOST_BUSY   0x1055
-#define SCSI_MLQUEUE_DEVICE_BUSY 0x1056
-#define SCSI_MLQUEUE_EH_RETRY    0x1057
-#define SCSI_MLQUEUE_TARGET_BUSY 0x1058
+enum scsi_qc_status {
+	SCSI_MLQUEUE_HOST_BUSY   = 0x1055,
+	SCSI_MLQUEUE_DEVICE_BUSY = 0x1056,
+	SCSI_MLQUEUE_EH_RETRY    = 0x1057,
+	SCSI_MLQUEUE_TARGET_BUSY = 0x1058,
+};
 
 /*
  *  Use these to separate status msg and our bytes

Re: [PATCH] scsi: core: Introduce an enumeration type for the SCSI_MLQUEUE constants

[Martin K. Petersen]

Bart,

> Multiple functions in the SCSI core accept an 'int reason' argument.
> The 'int' type of these arguments doesn't make it clear what values
> are acceptable for these arguments. Document which values are
> supported for these arguments by introducing the enumeration type
> scsi_qc_status. 'qc' in the type name stands for 'queuecommand' since
> the values passed as the 'reason' argument are the .queuecommand()
> return values.

Applied to 6.20/scsi-staging, thanks!

-- 
Martin K. Petersen

Re: [PATCH] scsi: core: Introduce an enumeration type for the SCSI_MLQUEUE constants

[Martin K. Petersen]

On Thu, 13 Nov 2025 10:17:30 -0800, Bart Van Assche wrote:

> Multiple functions in the SCSI core accept an 'int reason' argument.
> The 'int' type of these arguments doesn't make it clear what values are
> acceptable for these arguments. Document which values are supported for
> these arguments by introducing the enumeration type scsi_qc_status. 'qc'
> in the type name stands for 'queuecommand' since the values passed as the
> 'reason' argument are the .queuecommand() return values.
> 
> [...]

Applied to 6.20/scsi-queue, thanks!

[1/1] scsi: core: Introduce an enumeration type for the SCSI_MLQUEUE constants
      https://git.kernel.org/mkp/scsi/c/0f9c4be787f7

-- 
Martin K. Petersen