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 16/18] selftests: target_core_uring: Add a minimal server
Date: Sun, 15 Nov 2026 19:18:09 -0500 [thread overview]
Message-ID: <20261115-feat-target-core-uring-v1-16-28cdc137eac6@linux.dev> (raw)
In-Reply-To: <20261115-feat-target-core-uring-v1-0-28cdc137eac6@linux.dev>
target_core_uring needs a userspace server to do anything.
There is none to test the backstore with, and no example of how to use
its interface.
Add tcmur_server, which serves a device from a backing file, from
memory or as a null device. It runs one thread and one io_uring per
queue. With -z it registers the data pages of reads and writes as fixed
buffers and does the I/O on the backing file without copying.
Signed-off-by: Qiliang Yuan <qiliang.yuan@linux.dev>
---
MAINTAINERS | 1 +
.../testing/selftests/target_core_uring/.gitignore | 1 +
tools/testing/selftests/target_core_uring/Makefile | 7 +
.../selftests/target_core_uring/tcmur_server.c | 310 +++++++++++++++++++++
4 files changed, 319 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 07148430d9ea6..b3ac53cd7bf97 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25331,6 +25331,7 @@ F: Documentation/target/
F: drivers/target/
F: include/target/
F: include/uapi/linux/target_core_uring.h
+F: tools/testing/selftests/target_core_uring/
SCTP PROTOCOL
M: Marcelo Ricardo Leitner <marcelo.leitner@gmail.com>
diff --git a/tools/testing/selftests/target_core_uring/.gitignore b/tools/testing/selftests/target_core_uring/.gitignore
new file mode 100644
index 0000000000000..6e2f9115e1392
--- /dev/null
+++ b/tools/testing/selftests/target_core_uring/.gitignore
@@ -0,0 +1 @@
+tcmur_server
diff --git a/tools/testing/selftests/target_core_uring/Makefile b/tools/testing/selftests/target_core_uring/Makefile
new file mode 100644
index 0000000000000..438628fd1606b
--- /dev/null
+++ b/tools/testing/selftests/target_core_uring/Makefile
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: GPL-2.0
+CFLAGS += -O2 -Wall -D_GNU_SOURCE $(KHDR_INCLUDES)
+LDLIBS += -luring -lpthread
+
+TEST_GEN_PROGS_EXTENDED := tcmur_server
+
+include ../lib.mk
diff --git a/tools/testing/selftests/target_core_uring/tcmur_server.c b/tools/testing/selftests/target_core_uring/tcmur_server.c
new file mode 100644
index 0000000000000..128a0021e7796
--- /dev/null
+++ b/tools/testing/selftests/target_core_uring/tcmur_server.c
@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * Minimal server for target_core_uring devices.
+ *
+ * usage: tcmur_server [-z] <tcmur device> null|ram|<backing file>
+ *
+ * Run one thread per queue. With -z, register the data pages of each read
+ * and write as a fixed buffer and do the I/O on the backing file without
+ * copying.
+ */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <liburing.h>
+#include <pthread.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <linux/falloc.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <linux/target_core_uring.h>
+
+enum { BACKEND_NULL, BACKEND_RAM, BACKEND_FILE };
+enum { UD_FETCH, UD_REG, UD_RW, UD_UNREG };
+
+static struct tcmur_dev_info info;
+static int dev_fd, backing_fd = -1, backend;
+static bool zero_copy;
+static char *ram;
+
+struct queue {
+ pthread_t thread;
+ struct io_uring ring;
+ struct tcmur_io_desc *descs;
+ char *buf;
+ int q_id;
+};
+
+static struct io_uring_sqe *get_sqe(struct queue *q)
+{
+ struct io_uring_sqe *sqe = io_uring_get_sqe(&q->ring);
+
+ if (!sqe) {
+ io_uring_submit(&q->ring);
+ sqe = io_uring_get_sqe(&q->ring);
+ }
+ return sqe;
+}
+
+static struct io_uring_sqe *prep_cmd(struct queue *q, unsigned int op, int tag,
+ int result, int kind)
+{
+ struct tcmur_io_cmd cmd = {
+ .q_id = q->q_id,
+ .tag = tag,
+ .result = result,
+ .addr = tag,
+ };
+ struct io_uring_sqe *sqe = get_sqe(q);
+
+ io_uring_prep_rw(IORING_OP_URING_CMD, sqe, dev_fd, NULL, 0, 0);
+ sqe->cmd_op = op;
+ memcpy(sqe->cmd, &cmd, sizeof(cmd));
+ sqe->user_data = (uint64_t)kind << 16 | tag;
+ return sqe;
+}
+
+static int copy_data(struct queue *q, int tag, void *buf, uint32_t len,
+ bool to_cmd)
+{
+ uint64_t pos = tcmur_buf_pos(q->q_id, tag, 0);
+ ssize_t ret;
+
+ if (to_cmd)
+ ret = pwrite(dev_fd, buf, len, pos);
+ else
+ ret = pread(dev_fd, buf, len, pos);
+ return ret == len ? 0 : -EIO;
+}
+
+static int write_same(struct queue *q, int tag, struct tcmur_io_desc *d)
+{
+ uint64_t off;
+ int ret;
+
+ ret = copy_data(q, tag, q->buf, d->data_len, false);
+ if (ret)
+ return ret;
+
+ for (off = d->offset; off < d->offset + d->len; off += d->data_len) {
+ if (backend == BACKEND_RAM)
+ memcpy(ram + off, q->buf, d->data_len);
+ else if (pwrite(backing_fd, q->buf, d->data_len, off) !=
+ d->data_len)
+ return -EIO;
+ }
+ return 0;
+}
+
+/* Start the I/O on the data pages of the command, without copying them */
+static void start_zero_copy(struct queue *q, int tag, struct tcmur_io_desc *d)
+{
+ struct io_uring_sqe *sqe;
+
+ sqe = prep_cmd(q, TCMUR_IO_REGISTER_BUF, tag, 0, UD_REG);
+ sqe->flags |= IOSQE_IO_LINK | IOSQE_CQE_SKIP_SUCCESS;
+
+ sqe = get_sqe(q);
+ if (d->op == TCMUR_OP_READ)
+ io_uring_prep_read_fixed(sqe, backing_fd, NULL, d->data_len,
+ d->offset, tag);
+ else
+ io_uring_prep_write_fixed(sqe, backing_fd, NULL, d->data_len,
+ d->offset, tag);
+ sqe->flags |= IOSQE_IO_HARDLINK;
+ sqe->user_data = (uint64_t)UD_RW << 16 | tag;
+
+ sqe = prep_cmd(q, TCMUR_IO_UNREGISTER_BUF, tag, 0, UD_UNREG);
+ sqe->flags |= IOSQE_CQE_SKIP_SUCCESS;
+}
+
+/* Return true if the command completes later */
+static bool handle(struct queue *q, int tag, int *result)
+{
+ struct tcmur_io_desc *d = &q->descs[tag];
+ bool rd = d->op == TCMUR_OP_READ;
+ int ret = 0;
+
+ switch (d->op) {
+ case TCMUR_OP_READ:
+ case TCMUR_OP_WRITE:
+ if (d->offset + d->len > info.dev_size) {
+ ret = -EINVAL;
+ } else if (backend == BACKEND_RAM) {
+ ret = copy_data(q, tag, ram + d->offset, d->data_len,
+ rd);
+ } else if (backend == BACKEND_FILE && zero_copy) {
+ start_zero_copy(q, tag, d);
+ return true;
+ } else if (backend == BACKEND_FILE && rd) {
+ if (pread(backing_fd, q->buf, d->data_len, d->offset) !=
+ d->data_len)
+ ret = -EIO;
+ else
+ ret = copy_data(q, tag, q->buf, d->data_len,
+ true);
+ } else if (backend == BACKEND_FILE) {
+ ret = copy_data(q, tag, q->buf, d->data_len, false);
+ if (!ret && pwrite(backing_fd, q->buf, d->data_len,
+ d->offset) != d->data_len)
+ ret = -EIO;
+ }
+ if (!ret && backend == BACKEND_FILE &&
+ (d->flags & TCMUR_IO_F_FUA) && fdatasync(backing_fd))
+ ret = -errno;
+ break;
+ case TCMUR_OP_FLUSH:
+ if (backend == BACKEND_FILE && fdatasync(backing_fd))
+ ret = -errno;
+ break;
+ case TCMUR_OP_UNMAP:
+ if (backend == BACKEND_RAM)
+ memset(ram + d->offset, 0, d->len);
+ else if (backend == BACKEND_FILE &&
+ fallocate(backing_fd, FALLOC_FL_PUNCH_HOLE |
+ FALLOC_FL_KEEP_SIZE, d->offset, d->len))
+ ret = -errno;
+ break;
+ case TCMUR_OP_WRITE_SAME:
+ if (backend != BACKEND_NULL)
+ ret = write_same(q, tag, d);
+ break;
+ default:
+ ret = -EOPNOTSUPP;
+ }
+
+ *result = ret;
+ return false;
+}
+
+static void *queue_fn(void *arg)
+{
+ struct io_uring_params p = {
+ .flags = IORING_SETUP_SINGLE_ISSUER | IORING_SETUP_DEFER_TASKRUN,
+ };
+ struct queue *q = arg;
+ struct io_uring_cqe *cqe;
+ unsigned int head, n;
+ int tag, kind, result;
+
+ /* Create the ring here, as only its creator may submit to it */
+ if (io_uring_queue_init_params(info.queue_depth * 4, &q->ring, &p) ||
+ (zero_copy &&
+ io_uring_register_buffers_sparse(&q->ring, info.queue_depth))) {
+ perror("io_uring setup");
+ exit(1);
+ }
+
+ for (tag = 0; tag < info.queue_depth; tag++)
+ prep_cmd(q, TCMUR_IO_FETCH, tag, 0, UD_FETCH);
+
+ for (;;) {
+ if (io_uring_submit_and_wait(&q->ring, 1) < 0) {
+ perror("io_uring_submit_and_wait");
+ exit(1);
+ }
+
+ n = 0;
+ io_uring_for_each_cqe(&q->ring, head, cqe) {
+ n++;
+ tag = cqe->user_data & 0xffff;
+ kind = cqe->user_data >> 16;
+
+ switch (kind) {
+ case UD_FETCH:
+ if (cqe->res < 0)
+ goto out;
+ if (handle(q, tag, &result))
+ continue;
+ break;
+ case UD_RW:
+ result = cqe->res == q->descs[tag].data_len ?
+ 0 : -EIO;
+ break;
+ default:
+ /* Report failures through the I/O that follows */
+ continue;
+ }
+ prep_cmd(q, TCMUR_IO_COMMIT_AND_FETCH, tag, result,
+ UD_FETCH);
+ }
+ io_uring_cq_advance(&q->ring, n);
+ }
+out:
+ return NULL;
+}
+
+int main(int argc, char **argv)
+{
+ struct queue *queues;
+ size_t desc_size;
+ int i, opt;
+
+ while ((opt = getopt(argc, argv, "z")) != -1) {
+ if (opt == 'z')
+ zero_copy = true;
+ else
+ return 1;
+ }
+ if (argc - optind != 2) {
+ fprintf(stderr, "usage: %s [-z] <tcmur device> null|ram|<backing file>\n",
+ argv[0]);
+ return 1;
+ }
+
+ dev_fd = open(argv[optind], O_RDWR);
+ if (dev_fd < 0 || ioctl(dev_fd, TCMUR_GET_DEV_INFO, &info)) {
+ perror(argv[optind]);
+ return 1;
+ }
+
+ if (!strcmp(argv[optind + 1], "null")) {
+ backend = BACKEND_NULL;
+ } else if (!strcmp(argv[optind + 1], "ram")) {
+ backend = BACKEND_RAM;
+ ram = mmap(NULL, info.dev_size, PROT_READ | PROT_WRITE,
+ MAP_PRIVATE | MAP_ANONYMOUS | MAP_POPULATE, -1, 0);
+ if (ram == MAP_FAILED) {
+ perror("mmap");
+ return 1;
+ }
+ } else {
+ backend = BACKEND_FILE;
+ backing_fd = open(argv[optind + 1], O_RDWR);
+ if (backing_fd < 0) {
+ perror(argv[optind + 1]);
+ return 1;
+ }
+ }
+ if (zero_copy && backend != BACKEND_FILE) {
+ fprintf(stderr, "-z needs a backing file\n");
+ return 1;
+ }
+
+ desc_size = info.queue_depth * sizeof(struct tcmur_io_desc);
+ desc_size = (desc_size + getpagesize() - 1) & ~(getpagesize() - 1);
+ queues = calloc(info.nr_queues, sizeof(*queues));
+ for (i = 0; i < info.nr_queues; i++) {
+ struct queue *q = &queues[i];
+
+ q->q_id = i;
+ q->buf = malloc(info.max_io_size);
+ q->descs = mmap(NULL, desc_size, PROT_READ, MAP_SHARED, dev_fd,
+ (off_t)i * TCMUR_DESC_AREA_SIZE);
+ if (!q->buf || q->descs == MAP_FAILED) {
+ perror("queue setup");
+ return 1;
+ }
+ }
+
+ for (i = 0; i < info.nr_queues; i++)
+ pthread_create(&queues[i].thread, NULL, queue_fn, &queues[i]);
+ for (i = 0; i < info.nr_queues; i++)
+ pthread_join(queues[i].thread, NULL);
+ return 0;
+}
--
2.43.0
next prev parent reply other threads:[~2026-11-16 0:20 UTC|newest]
Thread overview: 32+ 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:38 ` sashiko-bot
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:33 ` sashiko-bot
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:46 ` sashiko-bot
2026-11-16 0:17 ` [PATCH RFC 06/18] scsi: target: uring: Hand commands out through TCMUR_IO_FETCH Qiliang Yuan
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:41 ` sashiko-bot
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:37 ` sashiko-bot
2026-11-16 0:18 ` [PATCH RFC 12/18] scsi: target: uring: Support SYNCHRONIZE CACHE Qiliang Yuan
2026-11-16 0:40 ` sashiko-bot
2026-11-16 0:18 ` [PATCH RFC 13/18] scsi: target: uring: Implement UNMAP Qiliang Yuan
2026-11-16 0:45 ` sashiko-bot
2026-11-16 0:18 ` [PATCH RFC 14/18] scsi: target: uring: Handle WRITE SAME Qiliang Yuan
2026-11-16 0:44 ` sashiko-bot
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 ` Qiliang Yuan [this message]
2026-11-16 1:03 ` [PATCH RFC 16/18] selftests: target_core_uring: Add a minimal server sashiko-bot
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:49 ` sashiko-bot
2026-11-16 0:18 ` [PATCH RFC 18/18] Documentation: target: Describe the uring backstore Qiliang Yuan
2026-11-16 2:32 ` [PATCH RFC 00/18] scsi: target: Add target_core_uring, an io_uring based user backstore Ming Lei
2026-11-17 2:46 ` Qiliang Yuan
2026-11-18 1:40 ` Ming Lei
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-16-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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.