Linux Documentation
 help / color / mirror / Atom feed
From: Qiliang Yuan <qiliang.yuan@linux.dev>
To: "Martin K. Petersen" <mkp@kernel.org>,
	Shuah Khan <shuah@kernel.org>,  Jonathan Corbet <corbet@lwn.net>,
	Shuah Khan <skhan@linuxfoundation.org>,
	 Randy Dunlap <rdunlap@infradead.org>
Cc: linux-kernel@vger.kernel.org, linux-scsi@vger.kernel.org,
	 target-devel@vger.kernel.org, linux-kselftest@vger.kernel.org,
	 linux-doc@vger.kernel.org, Jens Axboe <axboe@kernel.dk>,
	 io-uring@vger.kernel.org,
	Mike Christie <michael.christie@oracle.com>,
	 Bodo Stroesser <bostroesser@gmail.com>,
	Ming Lei <tom.leiming@gmail.com>,
	 Qiliang Yuan <qiliang.yuan@linux.dev>
Subject: [PATCH RFC 06/18] scsi: target: uring: Hand commands out through TCMUR_IO_FETCH
Date: Sun, 15 Nov 2026 19:17:59 -0500	[thread overview]
Message-ID: <20261115-feat-target-core-uring-v1-6-28cdc137eac6@linux.dev> (raw)
In-Reply-To: <20261115-feat-target-core-uring-v1-0-28cdc137eac6@linux.dev>

Reads and writes of a target_core_uring device wait on the pending list
of their queue.

Nothing takes commands off that list.

Add the TCMUR_IO_FETCH io_uring command. The server issues one per tag;
it completes once the descriptor of the tag holds a command. If a
command is pending, hand it out right away. Otherwise park the fetch
command on the idle list of the queue and complete it from task work
when a command arrives. Complete parked fetch commands with -ECANCELED
when io_uring cancels them, and with -ENODEV when the device goes away.

Signed-off-by: Qiliang Yuan <qiliang.yuan@linux.dev>
---
 drivers/target/target_core_uring.c     | 216 ++++++++++++++++++++++++++++++++-
 include/uapi/linux/target_core_uring.h |  24 +++-
 2 files changed, 235 insertions(+), 5 deletions(-)

diff --git a/drivers/target/target_core_uring.c b/drivers/target/target_core_uring.c
index 90e443ecb944c..85c9a1ae84433 100644
--- a/drivers/target/target_core_uring.c
+++ b/drivers/target/target_core_uring.c
@@ -2,6 +2,10 @@
 /*
  * LIO backstore that hands block commands to a userspace server through
  * io_uring commands.
+ *
+ * Each device has a character device and a set of queues. A queue holds
+ * queue_depth tags; the server owns a tag from the moment the kernel
+ * completes its fetch command until it commits the result.
  */
 
 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
@@ -10,6 +14,7 @@
 #include <linux/cdev.h>
 #include <linux/device.h>
 #include <linux/idr.h>
+#include <linux/io_uring/cmd.h>
 #include <linux/mm.h>
 #include <linux/parser.h>
 #include <linux/scatterlist.h>
@@ -46,16 +51,34 @@ struct tcmur_cmd {
 	struct tcmur_io_desc	desc;
 };
 
+/**
+ * struct tcmur_io - State of one tag
+ * @node:	Entry in tcmur_queue.idle while @ucmd waits for a command
+ * @ucmd:	Fetch command of the server
+ * @cmd:	Command the server is working on
+ * @owned:	The server owns the tag and has to commit it
+ */
+struct tcmur_io {
+	struct list_head	node;
+	struct io_uring_cmd	*ucmd;
+	struct tcmur_cmd	*cmd;
+	bool			owned;
+};
+
 /**
  * struct tcmur_queue - One command queue
- * @lock:	Protect the list
+ * @lock:	Protect the lists and the tags
+ * @idle:	Tags with a fetch command waiting for a command
  * @pending:	Commands waiting for a tag
+ * @ios:	Tags of the queue
  * @descs:	Command descriptors, indexed by tag and mapped by the server
  * @udev:	Device the queue belongs to
  */
 struct tcmur_queue {
 	spinlock_t		lock;
+	struct list_head	idle;
 	struct list_head	pending;
+	struct tcmur_io		*ios;
 	struct tcmur_io_desc	*descs;
 	struct tcmur_dev	*udev;
 } ____cacheline_aligned_in_smp;
@@ -66,6 +89,7 @@ struct tcmur_dev {
 	struct cdev		cdev;
 	int			dev_id;
 	unsigned long		flags;
+	bool			dead;
 
 	u64			dev_size;
 	u32			block_size;
@@ -75,6 +99,18 @@ struct tcmur_dev {
 	struct tcmur_queue	*queues;
 };
 
+/**
+ * struct tcmur_uring_pdu - State of a parked fetch command
+ * @q:		Queue of the tag
+ * @io:		Tag the command fetches for
+ * @res:	Result to complete the command with
+ */
+struct tcmur_uring_pdu {
+	struct tcmur_queue	*q;
+	struct tcmur_io		*io;
+	int			res;
+};
+
 static struct kmem_cache *tcmur_cmd_cache;
 static DEFINE_IDA(tcmur_ida);
 static dev_t tcmur_devt;
@@ -94,13 +130,46 @@ static struct tcmur_queue *tcmur_cmd_queue(struct tcmur_dev *udev,
 	return &udev->queues[(unsigned int)se_cmd->cpuid % udev->nr_queues];
 }
 
+/* Hand @tcmd to the server through the tag @io */
+static void tcmur_io_start(struct tcmur_queue *q, struct tcmur_io *io,
+			   struct tcmur_cmd *tcmd)
+{
+	lockdep_assert_held(&q->lock);
+
+	io->cmd = tcmd;
+	io->owned = true;
+	q->descs[io - q->ios] = tcmd->desc;
+}
+
+static void tcmur_fetch_tw_cb(struct io_tw_req tw_req, io_tw_token_t tw)
+{
+	struct io_uring_cmd *ucmd = io_uring_cmd_from_tw(tw_req);
+	struct tcmur_uring_pdu *pdu = io_uring_cmd_to_pdu(ucmd,
+						struct tcmur_uring_pdu);
+
+	io_uring_cmd_done(ucmd, pdu->res, IO_URING_CMD_TASK_WORK_ISSUE_FLAGS);
+}
+
 static void tcmur_queue_cmd(struct tcmur_dev *udev, struct tcmur_cmd *tcmd)
 {
 	struct tcmur_queue *q = tcmur_cmd_queue(udev, tcmd->se_cmd);
+	struct io_uring_cmd *ucmd = NULL;
+	struct tcmur_io *io;
 
 	spin_lock(&q->lock);
-	list_add_tail(&tcmd->node, &q->pending);
+	io = list_first_entry_or_null(&q->idle, struct tcmur_io, node);
+	if (io) {
+		list_del(&io->node);
+		ucmd = io->ucmd;
+		io->ucmd = NULL;
+		tcmur_io_start(q, io, tcmd);
+	} else {
+		list_add_tail(&tcmd->node, &q->pending);
+	}
 	spin_unlock(&q->lock);
+
+	if (ucmd)
+		io_uring_cmd_complete_in_task(ucmd, tcmur_fetch_tw_cb);
 }
 
 static sense_reason_t tcmur_submit(struct se_cmd *se_cmd, u32 op, u64 offset,
@@ -140,6 +209,113 @@ static sense_reason_t tcmur_execute_rw(struct se_cmd *se_cmd,
 			    se_cmd->data_length, sgl, sgl_nents);
 }
 
+static void tcmur_cancel_fetch(struct io_uring_cmd *ucmd,
+			       unsigned int issue_flags)
+{
+	struct tcmur_uring_pdu *pdu = io_uring_cmd_to_pdu(ucmd,
+						struct tcmur_uring_pdu);
+	struct tcmur_queue *q = pdu->q;
+	struct tcmur_io *io = pdu->io;
+	bool found = false;
+
+	spin_lock(&q->lock);
+	if (io->ucmd == ucmd) {
+		list_del(&io->node);
+		io->ucmd = NULL;
+		found = true;
+	}
+	spin_unlock(&q->lock);
+
+	if (found)
+		io_uring_cmd_done(ucmd, -ECANCELED, issue_flags);
+}
+
+static int tcmur_fetch(struct tcmur_queue *q, struct tcmur_io *io,
+		       struct io_uring_cmd *ucmd, unsigned int issue_flags)
+{
+	struct tcmur_uring_pdu *pdu = io_uring_cmd_to_pdu(ucmd,
+						struct tcmur_uring_pdu);
+	struct tcmur_cmd *tcmd;
+	int ret = 0;
+
+	spin_lock(&q->lock);
+	if (q->udev->dead) {
+		ret = -ENODEV;
+	} else if (io->ucmd || io->owned) {
+		ret = -EBUSY;
+	} else if (!list_empty(&q->pending)) {
+		tcmd = list_first_entry(&q->pending, struct tcmur_cmd, node);
+		list_del(&tcmd->node);
+		tcmur_io_start(q, io, tcmd);
+	} else {
+		pdu->q = q;
+		pdu->io = io;
+		pdu->res = 0;
+		io->ucmd = ucmd;
+		list_add(&io->node, &q->idle);
+		ret = -EIOCBQUEUED;
+	}
+	spin_unlock(&q->lock);
+
+	if (ret == -EIOCBQUEUED)
+		io_uring_cmd_mark_cancelable(ucmd, issue_flags);
+	return ret;
+}
+
+static int tcmur_ch_uring_cmd_local(struct io_uring_cmd *ucmd,
+				    unsigned int issue_flags)
+{
+	const struct tcmur_io_cmd *ioc = io_uring_sqe_cmd(ucmd->sqe,
+							  struct tcmur_io_cmd);
+	struct tcmur_dev *udev = ucmd->file->private_data;
+	u16 q_id = READ_ONCE(ioc->q_id);
+	u16 tag = READ_ONCE(ioc->tag);
+	struct tcmur_queue *q;
+	struct tcmur_io *io;
+
+	if (q_id >= udev->nr_queues || tag >= udev->queue_depth)
+		return -EINVAL;
+
+	q = &udev->queues[q_id];
+	io = &q->ios[tag];
+
+	switch (ucmd->cmd_op) {
+	case TCMUR_IO_FETCH:
+		return tcmur_fetch(q, io, ucmd, issue_flags);
+	default:
+		return -EOPNOTSUPP;
+	}
+}
+
+static void tcmur_ch_uring_cmd_tw_cb(struct io_tw_req tw_req, io_tw_token_t tw)
+{
+	unsigned int issue_flags = IO_URING_CMD_TASK_WORK_ISSUE_FLAGS;
+	struct io_uring_cmd *ucmd = io_uring_cmd_from_tw(tw_req);
+	int ret = -ECANCELED;
+
+	if (!tw.cancel)
+		ret = tcmur_ch_uring_cmd_local(ucmd, issue_flags);
+	if (ret != -EIOCBQUEUED)
+		io_uring_cmd_done(ucmd, ret, issue_flags);
+}
+
+static int tcmur_ch_uring_cmd(struct io_uring_cmd *ucmd,
+			      unsigned int issue_flags)
+{
+	if (unlikely(issue_flags & IO_URING_F_CANCEL)) {
+		tcmur_cancel_fetch(ucmd, issue_flags);
+		return 0;
+	}
+
+	/* Run in the submitting task, where fetch commands are completed */
+	if (unlikely(issue_flags & IO_URING_F_UNLOCKED)) {
+		io_uring_cmd_complete_in_task(ucmd, tcmur_ch_uring_cmd_tw_cb);
+		return -EIOCBQUEUED;
+	}
+
+	return tcmur_ch_uring_cmd_local(ucmd, issue_flags);
+}
+
 static size_t tcmur_desc_area_size(struct tcmur_dev *udev)
 {
 	return PAGE_ALIGN(udev->queue_depth * sizeof(struct tcmur_io_desc));
@@ -210,6 +386,7 @@ static const struct file_operations tcmur_ch_fops = {
 	.owner		= THIS_MODULE,
 	.open		= tcmur_ch_open,
 	.release	= tcmur_ch_release,
+	.uring_cmd	= tcmur_ch_uring_cmd,
 	.mmap		= tcmur_ch_mmap,
 	.unlocked_ioctl	= tcmur_ch_ioctl,
 	.compat_ioctl	= compat_ptr_ioctl,
@@ -222,8 +399,10 @@ static void tcmur_free_queues(struct tcmur_dev *udev)
 	if (!udev->queues)
 		return;
 
-	for (i = 0; i < udev->nr_queues; i++)
+	for (i = 0; i < udev->nr_queues; i++) {
 		vfree(udev->queues[i].descs);
+		kvfree(udev->queues[i].ios);
+	}
 	kvfree(udev->queues);
 	udev->queues = NULL;
 }
@@ -242,10 +421,13 @@ static int tcmur_alloc_queues(struct tcmur_dev *udev)
 		q = &udev->queues[i];
 
 		spin_lock_init(&q->lock);
+		INIT_LIST_HEAD(&q->idle);
 		INIT_LIST_HEAD(&q->pending);
 		q->udev = udev;
+		q->ios = kvcalloc(udev->queue_depth, sizeof(*q->ios),
+				  GFP_KERNEL);
 		q->descs = vmalloc_user(tcmur_desc_area_size(udev));
-		if (!q->descs) {
+		if (!q->ios || !q->descs) {
 			tcmur_free_queues(udev);
 			return -ENOMEM;
 		}
@@ -348,8 +530,34 @@ static int tcmur_configure_device(struct se_device *dev)
 static void tcmur_destroy_device(struct se_device *dev)
 {
 	struct tcmur_dev *udev = TCMUR_DEV(dev);
+	struct tcmur_uring_pdu *pdu;
+	struct io_uring_cmd *ucmd;
+	struct tcmur_queue *q;
+	struct tcmur_io *io;
+	unsigned int i;
 
 	cdev_device_del(&udev->cdev, &udev->cdev_dev);
+
+	/*
+	 * Tell the server that the device is gone. Complete the fetch
+	 * commands from task work, like tcmur_queue_cmd() does.
+	 */
+	for (i = 0; i < udev->nr_queues; i++) {
+		q = &udev->queues[i];
+
+		spin_lock(&q->lock);
+		udev->dead = true;
+		while (!list_empty(&q->idle)) {
+			io = list_first_entry(&q->idle, struct tcmur_io, node);
+			list_del(&io->node);
+			ucmd = io->ucmd;
+			io->ucmd = NULL;
+			pdu = io_uring_cmd_to_pdu(ucmd, struct tcmur_uring_pdu);
+			pdu->res = -ENODEV;
+			io_uring_cmd_complete_in_task(ucmd, tcmur_fetch_tw_cb);
+		}
+		spin_unlock(&q->lock);
+	}
 }
 
 static void tcmur_free_device(struct se_device *dev)
diff --git a/include/uapi/linux/target_core_uring.h b/include/uapi/linux/target_core_uring.h
index d2b8ffe40bf7a..9ce871d2e2087 100644
--- a/include/uapi/linux/target_core_uring.h
+++ b/include/uapi/linux/target_core_uring.h
@@ -7,7 +7,9 @@
 
 /*
  * target_core_uring hands the block commands of a LIO device to a userspace
- * server. The server opens /dev/tcmurN to drive the device.
+ * server. The server opens /dev/tcmurN, maps the command descriptors of
+ * each queue and exchanges commands with the kernel through io_uring
+ * commands (IORING_OP_URING_CMD) issued on that file.
  */
 
 #define TCMUR_MAX_NR_QUEUES	512
@@ -37,6 +39,26 @@ struct tcmur_dev_info {
 
 #define TCMUR_GET_DEV_INFO	_IOR(0xBB, 0x00, struct tcmur_dev_info)
 
+/**
+ * struct tcmur_io_cmd - Payload of the io_uring commands, placed in sqe->cmd
+ * @q_id:	Queue of the tag
+ * @tag:	Tag the command is for
+ * @reserved:	Zero
+ * @reserved1:	Zero
+ */
+struct tcmur_io_cmd {
+	__u16	q_id;
+	__u16	tag;
+	__s32	reserved;
+	__u64	reserved1;
+};
+
+/*
+ * TCMUR_IO_FETCH: wait for a command on (q_id, tag). The CQE result is 0
+ * once the descriptor of the tag holds a command.
+ */
+#define TCMUR_IO_FETCH			_IOWR(0xBB, 0x08, struct tcmur_io_cmd)
+
 enum tcmur_io_op {
 	TCMUR_OP_READ,
 	TCMUR_OP_WRITE,

-- 
2.43.0


  parent reply	other threads:[~2026-11-16  0:18 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-16  0:17 [PATCH RFC 00/18] scsi: target: Add target_core_uring, an io_uring based user backstore Qiliang Yuan
2026-11-16  0:17 ` [PATCH RFC 01/18] scsi: target: uring: Introduce " Qiliang Yuan
2026-11-16  0:17 ` [PATCH RFC 02/18] scsi: target: uring: Allocate per-queue command descriptors Qiliang Yuan
2026-11-16  0:17 ` [PATCH RFC 03/18] scsi: target: uring: Create a character device per backstore device Qiliang Yuan
2026-11-16  0:17 ` [PATCH RFC 04/18] scsi: target: uring: Map the command descriptors into the server Qiliang Yuan
2026-11-16  0:17 ` [PATCH RFC 05/18] scsi: target: uring: Queue commands until a server fetches them Qiliang Yuan
2026-11-16  0:17 ` Qiliang Yuan [this message]
2026-11-16  0:18 ` [PATCH RFC 07/18] scsi: target: uring: Complete commands with TCMUR_IO_COMMIT_AND_FETCH Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 08/18] scsi: target: uring: Copy command data with pread() and pwrite() Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 09/18] scsi: target: uring: Fail in-flight commands when the server exits Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 10/18] scsi: target: uring: Time out commands the server does not complete Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 11/18] scsi: target: uring: Drop aborted commands that are still queued Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 12/18] scsi: target: uring: Support SYNCHRONIZE CACHE Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 13/18] scsi: target: uring: Implement UNMAP Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 14/18] scsi: target: uring: Handle WRITE SAME Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 15/18] scsi: target: uring: Register command data as io_uring fixed buffers Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 16/18] selftests: target_core_uring: Add a minimal server Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 17/18] selftests: target_core_uring: Test a device exported through tcm_loop Qiliang Yuan
2026-11-16  0:18 ` [PATCH RFC 18/18] Documentation: target: Describe the uring backstore Qiliang Yuan

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261115-feat-target-core-uring-v1-6-28cdc137eac6@linux.dev \
    --to=qiliang.yuan@linux.dev \
    --cc=axboe@kernel.dk \
    --cc=bostroesser@gmail.com \
    --cc=corbet@lwn.net \
    --cc=io-uring@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-kselftest@vger.kernel.org \
    --cc=linux-scsi@vger.kernel.org \
    --cc=michael.christie@oracle.com \
    --cc=mkp@kernel.org \
    --cc=rdunlap@infradead.org \
    --cc=shuah@kernel.org \
    --cc=skhan@linuxfoundation.org \
    --cc=target-devel@vger.kernel.org \
    --cc=tom.leiming@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox