All of lore.kernel.org
 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 18/18] Documentation: target: Describe the uring backstore
Date: Sun, 15 Nov 2026 19:18:11 -0500	[thread overview]
Message-ID: <20261115-feat-target-core-uring-v1-18-28cdc137eac6@linux.dev> (raw)
In-Reply-To: <20261115-feat-target-core-uring-v1-0-28cdc137eac6@linux.dev>

target_core_uring is a new LIO backstore served by a userspace process.

Its configfs parameters and the protocol between the kernel and the
server are only described by the uAPI header and the code.

Add tcm-uring.rst, which explains how the backstore differs from
TCM/USER, how to create a device and what a server has to do.

Signed-off-by: Qiliang Yuan <qiliang.yuan@linux.dev>
---
 Documentation/target/index.rst     |  1 +
 Documentation/target/tcm-uring.rst | 84 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
index 51fa8ebc652ef..253b5fe422732 100644
--- a/Documentation/target/index.rst
+++ b/Documentation/target/index.rst
@@ -8,5 +8,6 @@ TCM Virtual Device
     :maxdepth: 1
 
     tcmu-design
+    tcm-uring
     tcm_mod_builder
     scripts
diff --git a/Documentation/target/tcm-uring.rst b/Documentation/target/tcm-uring.rst
new file mode 100644
index 0000000000000..2911d80721f75
--- /dev/null
+++ b/Documentation/target/tcm-uring.rst
@@ -0,0 +1,84 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+TCM io_uring backstore
+======================
+
+target_core_uring is a LIO backstore whose block commands are served by a
+userspace process, like TCM/USER (see tcmu-design.rst). It differs from
+TCM/USER in three ways:
+
+- The kernel emulates the SCSI commands. The server only reads, writes,
+  flushes and unmaps blocks and never parses a CDB.
+- A device has several queues. Each queue is served through its own
+  io_uring, so that queues do not contend with each other.
+- Data is copied once, with pread() and pwrite(), or not at all when the
+  server registers the data pages of a command as a fixed buffer.
+
+Creating a device
+=================
+
+A device is created through configfs like any other backstore::
+
+    mkdir -p /sys/kernel/config/target/core/uring_0/disk0
+    cd /sys/kernel/config/target/core/uring_0/disk0
+    echo "dev_size=1073741824,nr_queues=4,queue_depth=128" > control
+    echo 1 > enable
+
+The ``control`` file takes these parameters:
+
+``dev_size``
+    Size of the device in bytes. It must be a multiple of the block size.
+
+``block_size``
+    Logical block size in bytes, 512 by default.
+
+``nr_queues``
+    Number of queues, 1 by default. A command goes to the queue selected by
+    the CPU it was submitted on.
+
+``queue_depth``
+    Number of commands the server can work on per queue, 128 by default.
+
+``cmd_time_out``
+    Seconds after which a command the server has not completed fails. 30 by
+    default; 0 waits forever.
+
+Once the device is enabled, the ``info`` file shows the character device
+the server has to open, for instance ``/dev/tcmur0``.
+
+Serving a device
+================
+
+The interface is defined in ``include/uapi/linux/target_core_uring.h``.
+Only one process can open the character device at a time. The server:
+
+1. Reads the geometry with the ``TCMUR_GET_DEV_INFO`` ioctl.
+2. Maps the descriptors of each queue read-only, at offset
+   ``q_id * TCMUR_DESC_AREA_SIZE``. The area holds one
+   ``struct tcmur_io_desc`` per tag.
+3. Issues one ``TCMUR_IO_FETCH`` io_uring command (``IORING_OP_URING_CMD``)
+   per tag. A fetch command completes with 0 once the descriptor of its tag
+   holds a command.
+4. Handles the command and issues ``TCMUR_IO_COMMIT_AND_FETCH`` with the
+   result, which also waits for the next command of the tag.
+
+The server owns a tag from the completion of the fetch command until it
+commits the result. Meanwhile it accesses the data of the command in one of
+two ways:
+
+- pread() and pwrite() on the character device at the position returned by
+  ``tcmur_buf_pos()``. Reading returns the data of a write command; writing
+  fills the data of a read command.
+- ``TCMUR_IO_REGISTER_BUF`` registers the data pages as a fixed buffer of
+  the io_uring, which the server then passes to ``IORING_OP_READ_FIXED`` or
+  ``IORING_OP_WRITE_FIXED`` on its backing store. The buffer has to be
+  removed with ``TCMUR_IO_UNREGISTER_BUF``; the command only completes once
+  it is gone.
+
+Commands that arrive while no tag is waiting stay queued in the kernel.
+When the server exits, the commands it was working on fail and the queued
+ones wait for the next server, until they time out.
+
+``tools/testing/selftests/target_core_uring/tcmur_server.c`` is a small
+server that implements all of the above.

-- 
2.43.0


  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 ` [PATCH RFC 16/18] selftests: target_core_uring: Add a minimal server Qiliang Yuan
2026-11-16  1:03   ` 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 ` Qiliang Yuan [this message]
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-18-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.