[RFC PATCH 0/3] bsg: add io_uring command support for SCSI passthrough

[RFC PATCH 0/3] bsg: add io_uring command support for SCSI passthrough

[Yang Xiuwei]

This RFC series adds io_uring command support to the BSG (Block layer
SCSI Generic) driver, enabling asynchronous SCSI passthrough operations
via io_uring.

Motivation:
-----------
The current BSG interface uses ioctl() for SCSI passthrough, which is
synchronous and has limitations for high-performance applications. By
integrating with io_uring, we can provide:

1. Asynchronous I/O support for better scalability
2. Zero-copy I/O via io_uring fixed buffers
3. Better integration with modern async I/O frameworks
4. Reduced system call overhead

Design:
-------
The implementation follows the io_uring uring_cmd pattern used by other
drivers (e.g., nvme, ublk). Key design decisions:

1. UAPI Structure: A new bsg_uring_cmd structure is defined that fits
   within the 80-byte cmd field of a 128-byte SQE, with 16 bytes reserved
   for future extensions.

2. Status Information: SCSI status (device_status, host_status,
   driver_status, sense_len, resid_len) is returned in the CQE res2 field
   using a compact 64-bit encoding.

3. Zero-copy Support: The implementation supports both traditional
   user buffers and io_uring fixed buffers for zero-copy I/O.

4. Async Completion: Command completion is handled via task work to
   safely access user space and copy sense data.

5. Non-blocking I/O: Support for IO_URING_F_NONBLOCK flag to enable
   non-blocking command submission.

Limitations:
-----------
- Scatter/gather I/O (iovec arrays) is not currently supported, but
  the data structure includes fields for future implementation.
- Bidirectional transfers are not supported (consistent with existing
  BSG behavior).

Testing:
--------
A user-space test program has been developed to validate the
implementation, including:
- Basic SCSI commands (INQUIRY, READ CAPACITY (10), READ (10),
  WRITE (10))
- Zero-copy mode using fixed buffers
- Error handling (invalid flags, unsupported features)

The test program is available separately and can be provided upon request.

Patch Series:
-------------
Patch 1/3: Adds the bsg_uring_cmd UAPI structure
Patch 2/3: Adds uring_cmd handler to the generic BSG layer
Patch 3/3: Implements the SCSI-specific uring_cmd handler

Yang Xiuwei (3):
  bsg: add bsg_uring_cmd uapi structure
  bsg: add uring_cmd support to BSG generic layer
  bsg: implement SCSI BSG uring_cmd handler

 include/uapi/linux/bsg.h | 23 +++++++++++++++++++++++
 block/bsg.c              | 21 +++++++++++++++++++++
 drivers/scsi/scsi_bsg.c  | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/bsg.h      |  4 ++++
 4 files changed, 241 insertions(+)

-- 
2.25.1

[RFC PATCH 1/3] bsg: add bsg_uring_cmd uapi structure

[Yang Xiuwei]

Add the bsg_uring_cmd structure to the BSG UAPI header to support
io_uring-based SCSI passthrough operations via IORING_OP_URING_CMD.

This structure is designed to work with 128-byte SQE (IO_URING_F_SQE128)
and provides a compact interface similar to sg_io_v4, but optimized
for io_uring's async I/O model. The structure is packed to fit within
the 80-byte cmd field of a 128-byte SQE, with 16 bytes reserved for
future extensions.

Key features:
- CDB address and length for SCSI command passthrough
- Protocol and subprotocol identifiers (BSG_PROTOCOL_SCSI)
- Data transfer parameters supporting both flat buffers and iovec arrays
- Sense data buffer information for error reporting
- Timeout and flags for command control

Signed-off-by: Yang Xiuwei <yangxiuwei@kylinos.cn>

diff --git a/include/uapi/linux/bsg.h b/include/uapi/linux/bsg.h
index cd6302def5ed..24b08fece509 100644
--- a/include/uapi/linux/bsg.h
+++ b/include/uapi/linux/bsg.h
@@ -63,5 +63,23 @@ struct sg_io_v4 {
 	__u32 padding;
 };
 
+struct bsg_uring_cmd {
+	__u64 cdb_addr;
+	__u8  cdb_len;
+	__u8  protocol;		/* [i] protocol type (BSG_PROTOCOL_*) */
+	__u8  subprotocol;	/* [i] subprotocol type (BSG_SUB_PROTOCOL_*) */
+	__u8  reserved1;
+	__u32 din_iovec_count;	/* [i] 0 -> flat din transfer else
+				 * din_xferp points to array of iovec
+				 */
+	__u32 din_xfer_len;	/* [i] bytes to be transferred from device */
+	__u64 din_xferp;	/* [i] data in buffer address or iovec array
+				 * address
+				 */
+	__u32 dout_iovec_count;	/* [i] 0 -> flat dout transfer else
+				 * dout_xferp points to array of iovec
+				 */
+	__u32 dout_xfer_len;	/* [i] bytes to be transferred to device */
+	__u64 dout_xferp;	/* [i] data out buffer address or iovec array address */
+	__u32 sense_len;
+	__u64 sense_addr;
+	__u32 timeout_ms;
+	__u32 flags;		/* [i] bit mask (BSG_FLAG_*) - reserved for future use */
+	__u8  reserved[16];	/* reserved for future extension */
+} __packed;
 
 #endif /* _UAPIBSG_H */
-- 
2.25.1

[RFC PATCH 2/3] bsg: add uring_cmd support to BSG generic layer

[Yang Xiuwei]

Add io_uring command handler to the generic BSG layer. This handler
validates that SQE128 and CQE32 flags are set (required for the command
structure and status information), then delegates to the SCSI-specific
handler.

The handler is registered via the file_operations.uring_cmd field.
Add function declaration in include/linux/bsg.h and a stub
implementation
in drivers/scsi/scsi_bsg.c to allow compilation.

Signed-off-by: Yang Xiuwei <yangxiuwei@kylinos.cn>

diff --git a/block/bsg.c b/block/bsg.c
index 72157a59b788..cdccf86b8673 100644
--- a/block/bsg.c
+++ b/block/bsg.c
@@ -12,6 +12,7 @@
 #include <linux/idr.h>
 #include <linux/bsg.h>
 #include <linux/slab.h>
+#include <linux/io_uring/cmd.h>
 
 #include <scsi/scsi.h>
 #include <scsi/scsi_ioctl.h>
@@ -158,11 +159,38 @@ static long bsg_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
 	}
 }
 
+static int bsg_uring_cmd_checks(unsigned int issue_flags)
+{
+	/* BSG passthrough requires big SQE/CQE support */
+	if ((issue_flags & (IO_URING_F_SQE128|IO_URING_F_CQE32)) !=
+	    (IO_URING_F_SQE128|IO_URING_F_CQE32))
+		return -EOPNOTSUPP;
+	return 0;
+}
+
+static int bsg_uring_cmd(struct io_uring_cmd *ioucmd, unsigned int issue_flags)
+{
+	struct bsg_device *bd = to_bsg_device(file_inode(ioucmd->file));
+	struct request_queue *q = bd->queue;
+	bool open_for_write = ioucmd->file->f_mode & FMODE_WRITE;
+	int ret;
+
+	if (!q)
+		return -EINVAL;
+
+	ret = bsg_uring_cmd_checks(issue_flags);
+	if (ret)
+		return ret;
+
+	return scsi_bsg_uring_cmd(q, ioucmd, issue_flags, open_for_write);
+}
+
 static const struct file_operations bsg_fops = {
 	.open		=	bsg_open,
 	.release	=	bsg_release,
 	.unlocked_ioctl	=	bsg_ioctl,
 	.compat_ioctl	=	compat_ptr_ioctl,
+	.uring_cmd	=	bsg_uring_cmd,
 	.owner		=	THIS_MODULE,
 	.llseek		=	default_llseek,
 };
diff --git a/drivers/scsi/scsi_bsg.c b/drivers/scsi/scsi_bsg.c
index a9a9ec086a7e..4399a25990fc 100644
--- a/drivers/scsi/scsi_bsg.c
+++ b/drivers/scsi/scsi_bsg.c
@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0
 #include <linux/bsg.h>
+#include <linux/io_uring/cmd.h>
 #include <scsi/scsi.h>
 #include <scsi/scsi_ioctl.h>
 #include <scsi/scsi_cmnd.h>
@@ -9,6 +10,12 @@
 
 #define uptr64(val) ((void __user *)(uintptr_t)(val))
 
+int scsi_bsg_uring_cmd(struct request_queue *q, struct io_uring_cmd *ioucmd,
+		       unsigned int issue_flags, bool open_for_write)
+{
+	return -EOPNOTSUPP;
+}
+
 static int scsi_bsg_sg_io_fn(struct request_queue *q, struct sg_io_v4 *hdr,
 		bool open_for_write, unsigned int timeout)
 {
diff --git a/include/linux/bsg.h b/include/linux/bsg.h
index ee2df73edf83..68ec50b5e97c 100644
--- a/include/linux/bsg.h
+++ b/include/linux/bsg.h
@@ -7,6 +7,7 @@
 struct bsg_device;
 struct device;
 struct request_queue;
+struct io_uring_cmd;
 
 typedef int (bsg_sg_io_fn)(struct request_queue *, struct sg_io_v4 *hdr,
 		bool open_for_write, unsigned int timeout);
@@ -16,4 +17,7 @@ struct bsg_device *bsg_register_queue(struct request_queue *q,
 		bsg_sg_io_fn *sg_io_fn);
 void bsg_unregister_queue(struct bsg_device *bcd);
 
+int scsi_bsg_uring_cmd(struct request_queue *q, struct io_uring_cmd *ioucmd,
+		       unsigned int issue_flags, bool open_for_write);
+
 #endif /* _LINUX_BSG_H */
-- 
2.25.1

[RFC PATCH 3/3] bsg: implement SCSI BSG uring_cmd handler

[Yang Xiuwei]

Implement the SCSI-specific io_uring command handler for BSG. This
handler processes SCSI passthrough commands asynchronously via io_uring,
supporting both traditional user buffers and zero-copy fixed buffers.

Key features:
- Async command execution with proper completion handling
- Zero-copy support via io_uring fixed buffers
- Status information returned in CQE res2 field
- Non-blocking I/O support via IO_URING_F_NONBLOCK
- Proper error handling and validation

The implementation uses a PDU structure overlaying io_uring_cmd.pdu[32]
to store temporary state during command execution. Completion is handled
via task work to safely access user space.

This patch replaces the stub implementation from patch 2/3 with the full
implementation.

Signed-off-by: Yang Xiuwei <yangxiuwei@kylinos.cn>

diff --git a/drivers/scsi/scsi_bsg.c b/drivers/scsi/scsi_bsg.c
index 4399a25990fc..1c4c29ef7e35 100644
--- a/drivers/scsi/scsi_bsg.c
+++ b/drivers/scsi/scsi_bsg.c
@@ -10,10 +10,205 @@
 
 #define uptr64(val) ((void __user *)(uintptr_t)(val))
 
+/*
+ * BSG io_uring PDU structure overlaying io_uring_cmd.pdu[32].
+ * Stores temporary data needed during command execution.
+ */
+struct scsi_bsg_uring_cmd_pdu {
+	struct bio *bio;		/* mapped user buffer, unmap in task work */
+	struct request *req;		/* block request, freed in task work */
+	u64 sense_addr;			/* user space sense buffer address */
+	u32 resid_len;			/* residual transfer length */
+	u8 sense_len_wr;		/* actual sense data length written */
+	u8 device_status;		/* SCSI device status (low 8 bits of result) */
+	u8 host_status;			/* SCSI host status (host_byte of result) */
+	u8 driver_status;		/* SCSI driver status (DRIVER_SENSE if check condition) */
+};
+
+static inline struct scsi_bsg_uring_cmd_pdu *scsi_bsg_uring_cmd_pdu(
+	struct io_uring_cmd *ioucmd)
+{
+	return io_uring_cmd_to_pdu(ioucmd, struct scsi_bsg_uring_cmd_pdu);
+}
+
+/*
+ * Task work callback executed in process context.
+ * Builds res2 with status information and copies sense data to user space.
+ * res2 layout (64-bit):
+ *   0-7:   device_status
+ *   8-15:  driver_status
+ *   16-23: sense_len_wr
+ *   24-31: host_status
+ *   32-63: resid_len
+ */
+static void scsi_bsg_uring_task_cb(struct io_tw_req tw_req, io_tw_token_t tw)
+{
+	struct io_uring_cmd *ioucmd = io_uring_cmd_from_tw(tw_req);
+	struct scsi_bsg_uring_cmd_pdu *pdu = scsi_bsg_uring_cmd_pdu(ioucmd);
+	struct scsi_cmnd *scmd;
+	struct request *rq = pdu->req;
+	int ret = 0;
+	u64 res2;
+
+	scmd = blk_mq_rq_to_pdu(rq);
+
+	if (pdu->bio)
+		blk_rq_unmap_user(pdu->bio);
+
+	res2 = ((u64)pdu->resid_len << 32) |
+	       ((u64)(pdu->host_status & 0xff) << 24) |
+	       ((u64)(pdu->sense_len_wr & 0xff) << 16) |
+	       ((u64)(pdu->driver_status & 0xff) << 8) |
+	       (pdu->device_status & 0xff);
+
+	if (pdu->sense_len_wr && pdu->sense_addr) {
+		if (copy_to_user(uptr64(pdu->sense_addr), scmd->sense_buffer,
+				 pdu->sense_len_wr))
+			ret = -EFAULT;
+	}
+
+	blk_mq_free_request(rq);
+	io_uring_cmd_done32(ioucmd, ret, res2,
+			    IO_URING_CMD_TASK_WORK_ISSUE_FLAGS);
+}
+
+/*
+ * Async completion callback executed in interrupt/atomic context.
+ * Saves SCSI status information and schedules task work for final completion.
+ */
+static enum rq_end_io_ret scsi_bsg_uring_cmd_done(struct request *req,
+						  blk_status_t status)
+{
+	struct io_uring_cmd *ioucmd = req->end_io_data;
+	struct scsi_bsg_uring_cmd_pdu *pdu = scsi_bsg_uring_cmd_pdu(ioucmd);
+	struct scsi_cmnd *scmd = blk_mq_rq_to_pdu(req);
+
+	pdu->device_status = scmd->result & 0xff;
+	pdu->host_status = host_byte(scmd->result);
+	pdu->driver_status = 0;
+	pdu->sense_len_wr = 0;
+
+	if (scsi_status_is_check_condition(scmd->result)) {
+		pdu->driver_status = DRIVER_SENSE;
+		if (pdu->sense_addr)
+			pdu->sense_len_wr = min_t(u8, scmd->sense_len, SCSI_SENSE_BUFFERSIZE);
+	}
+
+	pdu->resid_len = scmd->resid_len;
+
+	io_uring_cmd_do_in_task_lazy(ioucmd, scsi_bsg_uring_task_cb);
+	return RQ_END_IO_NONE;
+}
+
+/*
+ * Map user buffer to request, supporting both zero-copy (fixed buffers)
+ * and traditional mode.
+ */
+static int scsi_bsg_map_user_buffer(struct request *req,
+				    struct io_uring_cmd *ioucmd,
+				    unsigned int issue_flags, gfp_t gfp_mask)
+{
+	const struct bsg_uring_cmd *cmd = io_uring_sqe_cmd(ioucmd->sqe);
+	struct request_queue *q = req->q;
+	struct iov_iter iter;
+	bool is_write = cmd->dout_xfer_len > 0;
+	u64 buf_addr = is_write ? cmd->dout_xferp : cmd->din_xferp;
+	unsigned long buf_len = is_write ? cmd->dout_xfer_len : cmd->din_xfer_len;
+	bool use_fixed = (ioucmd->flags & IORING_URING_CMD_FIXED) != 0;
+	int ddir = is_write ? WRITE : READ;
+	int ret;
+
+	if (use_fixed) {
+		ret = io_uring_cmd_import_fixed(buf_addr, buf_len, ddir,
+						&iter, ioucmd, issue_flags);
+		if (ret < 0)
+			return ret;
+		ret = blk_rq_map_user_iov(q, req, NULL, &iter, gfp_mask);
+	} else {
+		ret = blk_rq_map_user(q, req, NULL, uptr64(buf_addr),
+				      buf_len, gfp_mask);
+	}
+
+	return ret;
+}
+
 int scsi_bsg_uring_cmd(struct request_queue *q, struct io_uring_cmd *ioucmd,
 		       unsigned int issue_flags, bool open_for_write)
 {
-	return -EOPNOTSUPP;
+	struct scsi_bsg_uring_cmd_pdu *pdu = scsi_bsg_uring_cmd_pdu(ioucmd);
+	const struct bsg_uring_cmd *cmd = io_uring_sqe_cmd(ioucmd->sqe);
+	struct scsi_cmnd *scmd;
+	struct request *req;
+	blk_mq_req_flags_t blk_flags = 0;
+	gfp_t gfp_mask = GFP_KERNEL;
+	int ret = 0;
+
+	if (cmd->protocol != BSG_PROTOCOL_SCSI ||
+	    cmd->subprotocol != BSG_SUB_PROTOCOL_SCSI_CMD)
+		return -EINVAL;
+
+	if (cmd->cdb_len == 0 || cmd->cdb_len > 32)
+		return -EINVAL;
+
+	if (!cmd->cdb_addr)
+		return -EINVAL;
+
+	if (cmd->dout_xfer_len && cmd->din_xfer_len)
+		return -EOPNOTSUPP;
+
+	if (cmd->dout_iovec_count > 0 || cmd->din_iovec_count > 0)
+		return -EOPNOTSUPP;
+
+	if (issue_flags & IO_URING_F_NONBLOCK) {
+		blk_flags = BLK_MQ_REQ_NOWAIT;
+		gfp_mask = GFP_NOWAIT;
+	}
+
+	req = scsi_alloc_request(q, cmd->dout_xfer_len ?
+				 REQ_OP_DRV_OUT : REQ_OP_DRV_IN, blk_flags);
+	if (IS_ERR(req))
+		return PTR_ERR(req);
+
+	scmd = blk_mq_rq_to_pdu(req);
+	scmd->cmd_len = cmd->cdb_len;
+	scmd->allowed = SG_DEFAULT_RETRIES;
+
+	if (copy_from_user(scmd->cmnd, uptr64(cmd->cdb_addr), cmd->cdb_len)) {
+		ret = -EFAULT;
+		goto out_free_req;
+	}
+
+	if (!scsi_cmd_allowed(scmd->cmnd, open_for_write)) {
+		ret = -EPERM;
+		goto out_free_req;
+	}
+
+	pdu->sense_addr = cmd->sense_addr;
+	scmd->sense_len = cmd->sense_len ?
+		min(cmd->sense_len, SCSI_SENSE_BUFFERSIZE) : SCSI_SENSE_BUFFERSIZE;
+
+	if (cmd->dout_xfer_len || cmd->din_xfer_len) {
+		ret = scsi_bsg_map_user_buffer(req, ioucmd, issue_flags, gfp_mask);
+		if (ret)
+			goto out_free_req;
+		pdu->bio = req->bio;
+	} else {
+		pdu->bio = NULL;
+	}
+
+	req->timeout = cmd->timeout_ms ?
+		msecs_to_jiffies(cmd->timeout_ms) : BLK_DEFAULT_SG_TIMEOUT;
+
+	req->end_io = scsi_bsg_uring_cmd_done;
+	req->end_io_data = ioucmd;
+	pdu->req = req;
+
+	blk_execute_rq_nowait(req, false);
+	return -EIOCBQUEUED;
+
+out_free_req:
+	blk_mq_free_request(req);
+	return ret;
 }
 
 static int scsi_bsg_sg_io_fn(struct request_queue *q, struct sg_io_v4 *hdr,
-- 
2.25.1

Re: [RFC PATCH 1/3] bsg: add bsg_uring_cmd uapi structure

[Bart Van Assche]

On 1/12/26 1:46 AM, Yang Xiuwei wrote:
> +struct bsg_uring_cmd {
> +	__u64 cdb_addr;
> +	__u8  cdb_len;
> +	__u8  protocol;		/* [i] protocol type (BSG_PROTOCOL_*) */
> +	__u8  subprotocol;	/* [i] subprotocol type (BSG_SUB_PROTOCOL_*) */
> +	__u8  reserved1;
> +	__u32 din_iovec_count;	/* [i] 0 -> flat din transfer else
> +				 * din_xferp points to array of iovec
> +				 */
> +	__u32 din_xfer_len;	/* [i] bytes to be transferred from device */
> +	__u64 din_xferp;	/* [i] data in buffer address or iovec array
> +				 * address
> +				 */
> +	__u32 dout_iovec_count;	/* [i] 0 -> flat dout transfer else
> +				 * dout_xferp points to array of iovec
> +				 */
> +	__u32 dout_xfer_len;	/* [i] bytes to be transferred to device */
> +	__u64 dout_xferp;	/* [i] data out buffer address or iovec array address */
> +	__u32 sense_len;
> +	__u64 sense_addr;
> +	__u32 timeout_ms;
> +	__u32 flags;		/* [i] bit mask (BSG_FLAG_*) - reserved for future use */
> +	__u8  reserved[16];	/* reserved for future extension */

BSG supports much more than only SCSI. The above seems to support SCSI
commands only.

> +} __packed;

Applying __packed to a data structure in its entirety is wrong because
it causes compilers to generate suboptimal code on architectures that do
not support unaligned 16-/32-/64-bit accesses.

Bart.

Re: [RFC PATCH 1/3] bsg: add bsg_uring_cmd uapi structure

[Yang Xiuwei]

On 1/12/26 17:44, Bart Van Assche wrote:
> On 1/12/26 1:46 AM, Yang Xiuwei wrote:
> > +struct bsg_uring_cmd {
> > +	__u64 cdb_addr;
> > +	__u8  cdb_len;
> > +	__u8  protocol;		/* [i] protocol type (BSG_PROTOCOL_*) */
> > +	__u8  subprotocol;	/* [i] subprotocol type (BSG_SUB_PROTOCOL_*) */
> > +	__u8  reserved1;
> > +	__u32 din_iovec_count;	/* [i] 0 -> flat din transfer else
> > +				 * din_xferp points to array of iovec
> > +				 */
> > +	__u32 din_xfer_len;	/* [i] bytes to be transferred from device */
> > +	__u64 din_xferp;	/* [i] data in buffer address or iovec array
> > +				 * address
> > +				 */
> > +	__u32 dout_iovec_count;	/* [i] 0 -> flat dout transfer else
> > +				 * dout_xferp points to array of iovec
> > +				 */
> > +	__u32 dout_xfer_len;	/* [i] bytes to be transferred to device */
> > +	__u64 dout_xferp;	/* [i] data out buffer address or iovec array address */
> > +	__u32 sense_len;
> > +	__u64 sense_addr;
> > +	__u32 timeout_ms;
> > +	__u32 flags;		/* [i] bit mask (BSG_FLAG_*) - reserved for future use */
> > +	__u8  reserved[16];	/* reserved for future extension */
> 
> BSG supports much more than only SCSI. The above seems to support SCSI
> commands only.

While the current BSG implementation only supports SCSI (BSG_PROTOCOL_SCSI
is the only defined protocol), I understand that the design should allow
for future protocol extensions. I notice that sg_io_v4 uses generic field
names (request, request_len) rather than SCSI-specific names (cdb), which
aligns with this design philosophy.

I'll change cdb_addr/cdb_len to more generic names (request_addr,
request_len) to match the naming convention used in sg_io_v4, even though
the current implementation is SCSI-specific.

> > +} __packed;
> 
> Applying __packed to a data structure in its entirety is wrong because
> it causes compilers to generate suboptimal code on architectures that do
> not support unaligned 16-/32-/64-bit accesses.

You're correct that using __packed on the entire structure can cause
suboptimal code generation on architectures that don't support unaligned
access. I'll remove __packed and reorganize the fields to ensure proper
alignment while maintaining the 80-byte size requirement to fit within the
128-byte SQE cmd field.

I'll prepare a revised patch addressing these issues in the next version
of the series.

As I'm relatively new to kernel development, I appreciate your detailed
feedback. I'll incorporate these improvements and continue learning from
the community.

Thanks again for your review!

Best regards,
Yang Xiuwei