mirror of https://lore.kernel.org/lkml/
 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: 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 ` [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: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 ` Qiliang Yuan [this message]

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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®