Skip to content

engines/io_uring: Introduce BSG io uring cmd - #2102

Merged
axboe merged 3 commits into
axboe:masterfrom
ljw8161:upstream-io_uring-bsg
Jun 24, 2026
Merged

axboe merged 3 commits into
axboe:masterfrom
ljw8161:upstream-io_uring-bsg

Conversation

@ljw8161

@ljw8161 ljw8161 commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

Background

This feature requires a kernel patch to work correctly on the latest Linux
kernel (eb3f4b7).
The io_uring_cmd engine was introduced to issue device-specific passthrough
commands directly through io_uring, bypassing the block layer. Until now
it was exclusively coupled to NVMe — the cmd_type option accepted only
"nvme", and the internal data structures, initialization paths, and error
reporting all assumed NVMe command semantics throughout.

SCSI devices exposed via the kernel's BSG (Block SCSI Generic) interface
can also be driven through io_uring using the bsg_uring_cmd path (upstream
pretty recent), but fio had no way to exercise that path.

What This Series Does

Patch 1 ("Separate NVMe-specific logic") is a pure preparatory refactor
with no functional changes. It moves all NVMe-specific code — DSM
allocation, cdw12 flag setup, write-opcode selection, PI flags parsing,
and the NVMe-only ZBD callbacks (get_zoned_model, report_zones, reset_wp,
get_max_open_zones, fetch_ruhs) — behind explicit FIO_URING_CMD_NVME
guards. The intent is to make the engine's cmd_type dispatch structure
uniform and correct before new device types are introduced.

Patch 2 ("Add bsg support for io_uring_cmd engine") builds on top of that
refactor to add a new cmd_type=bsg option. It introduces:

- engines/bsg.c / engines/bsg.h: a self-contained BSG helper layer
  with big-endian helpers for CDB and data field manipulation.
- SCSI command construction for the four fundamental I/O directions:
    read  → READ(10)
    write → WRITE(10)
    trim  → UNMAP
    fsync → SYNCHRONIZE CACHE(10)
- FUA (Force Unit Access) support for read and write via the CDB FUA bit.
- Device size detection via a READ CAPACITY(10) SG_IO ioctl issued at
  open/get_file_size time, populating the bsg_data per-file structure.
- CQE result interpretation: the BSG 32-byte CQE packs SCSI device
  status in bits 0–7 and host status in bits 16–23 of big_cqe[0].
- Error detail reporting that separates SCSI status from host status.
- The same IORING_SETUP_SQE128 / IORING_SETUP_CQE32 ring flags already
  used by NVMe, since BSG passthrough also requires the extended SQE/CQE
  layout.

How It Works

When cmd_type=bsg is selected the engine allocates a per-slot bsg_cmd
array (indexed by io_u->index) at init time. At prep time,
fio_bsg_uring_cmd_prep() fills the 128-byte SQE cmd payload (a
struct bsg_uring_cmd / sg_io_v4) with the appropriate CDB, transfer
direction pointers, and lengths. At completion time the driver reads the
packed status word from big_cqe[0] and maps it to io_u->error.

Usage example:
fio --filename=/dev/bsg/0\:0\:0\:0
--ioengine=io_uring_cmd --cmd_type=bsg
--rw=read --bs=4k --iodepth=32

Testing

The BSG io_uring passthrough path returns -ENOMEM
during data transfers due to a conflict between commit b520c4e ("block: split
bio_alloc_bioset more clearly into a fast and slowpath") and the BSG
io_uring handler commit 7b6d325.

After b520c4e, bio_alloc_bioset() returns NULL immediately when GFP_NOWAIT
is used and slab allocation fails, bypassing the mempool entirely.
scsi_bsg_uring_cmd() uses GFP_NOWAIT when IO_URING_F_NONBLOCK is set,
causing allocation failures. The NVMe path is unaffected as it hardcodes
GFP_KERNEL.

The fix is to hardcode GFP_KERNEL in scsi_bsg_map_user_buffer() in the
kernel, mirroring the NVMe passthrough path behavior.

diff --git a/drivers/scsi/scsi_bsg.c b/drivers/scsi/scsi_bsg.c
index e80dec53174e..3cb1f607815b 100644
--- a/drivers/scsi/scsi_bsg.c
+++ b/drivers/scsi/scsi_bsg.c
@@ -91,10 +91,10 @@ static int scsi_bsg_map_user_buffer(struct request *req,
                                              &iter, ioucmd, issue_flags);
              if (ret < 0)
                      return ret;
-               ret = blk_rq_map_user_iov(req->q, req, NULL, &iter, gfp_mask);
+               ret = blk_rq_map_user_iov(req->q, req, NULL, &iter, GFP_KERNEL);
      } else {
              ret = blk_rq_map_user(req->q, req, NULL, uptr64(buf_addr),
-                                     buf_len, gfp_mask);
+                                     buf_len, GFP_KERNEL);
      }

      return ret;

I'm planning to post this issue to the kernel community.

@ljw8161

ljw8161 commented Jun 4, 2026 •

Copy link
Copy Markdown
Contributor Author

This CI failure is due to the BSG-related UAPI (see link below) not being updated in the CI system.
https://lore.kernel.org/all/20260317072226.2598233-2-yangxiuwei@kylinos.cn/

@vincentkfu

This comment was marked as resolved.

@ljw8161
ljw8161 force-pushed the upstream-io_uring-bsg branch 2 times, most recently from 21eaa2f to 5db2944 Compare June 4, 2026 08:24

@ankit-sam ankit-sam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ljw8161 a couple of minor comments.
And can you update the fio documentation HOWTO.rst and fio.1
And it would be nice to add an example file. Please check examples/uring-cmd-*

Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
@ljw8161
ljw8161 force-pushed the upstream-io_uring-bsg branch from 5db2944 to 5512d83 Compare June 5, 2026 05:08
@ljw8161

This comment was marked as resolved.

@ljw8161

ljw8161 commented Jun 5, 2026

Copy link
Copy Markdown
Contributor Author

Hello, @ankit-sam !
Thanks for the suggestions. I've updated HOWTO.rst and fio.1 to document the new bsg option for cmd_type, and added an example job file at examples/uring-cmd-bsg.fio and examples/uring-cmd-bsg.png

@k831-kim
k831-kim force-pushed the upstream-io_uring-bsg branch 2 times, most recently from d155df6 to 314903f Compare June 15, 2026 21:59
@k831-kim

Copy link
Copy Markdown

Resolved the conflict and updated.

Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/bsg.c Resolved
Comment thread engines/bsg.c Resolved
Comment thread engines/io_uring.c Resolved
@k831-kim
k831-kim force-pushed the upstream-io_uring-bsg branch 4 times, most recently from 1fe4057 to 4e53ee8 Compare June 17, 2026 01:18
Comment thread engines/bsg.c Resolved
Comment thread engines/bsg.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
@k831-kim
k831-kim force-pushed the upstream-io_uring-bsg branch from 4e53ee8 to 0e8dd7a Compare June 22, 2026 23:09
Comment thread engines/nvme.c Outdated
return 0;
}

int fio_nvme_uring_cmd_prep_split(struct thread_data *td,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies for not being more specific. Please create the helper inside engines/io_uring.c and reduce the number of parameters passed to this function. There is no need to pass read_opcode and write_opcode since this is a write operation and this function will select the opcode.

Inside this helper just define:

	struct ioring_data *ld = td->io_ops_data;
	struct ioring_options *o = td->eo;

Then there will be no need to pass as parameters

o->wmode_split
o->wmode_split_nr
o->deac
ld->wmode_state

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As you mentioned, I have organized it in io_uring.c.
However, since io_uring.c is a general I/O path, I don't think NVMe‑specific variables should be passed as parameters, so I redeclared the NVMe‑related variables inside the function.
That said, this could result in duplicate work during the hot‑path preparation stage; I would appreciate any feedback.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's ok to pass NVMe-specific parameters. If any other cmd_types gain support for multiple write modes we can change things.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems there will be no problem if we proceed in the direction you mentioned.
I have changed code according to your suggestions.

Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
@k831-kim
k831-kim force-pushed the upstream-io_uring-bsg branch from 0e8dd7a to 791ab0f Compare June 23, 2026 22:59
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Resolved
Comment thread engines/io_uring.c Outdated
unsigned int perc = 0;
int i;

sqe = &ld->sqes[(io_u->index) << 1];

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider passing sqe and cmd as parameters to this function in order to simplify things a bit.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I have made the changes according to your suggestion and deleted the line.

Comment thread engines/bsg.c Resolved
@vincentkfu

This comment was marked as resolved.

ljw8161 and others added 3 commits June 24, 2026 11:01
Previously, io_uring_cmd engine was tightly coupled with NVMe command
structures, making it difficult to use with other device types.

This patch supports separated NVMe-specific logic from io_uring_cmd
engine to enable support for other device types such as bsg next to this
patch.

Note that this patch is a prep patch for the followings with no
functional changes.

Signed-off-by: Jungwon Lee <jjung1.lee@samsung.com>
Signed-off-by: Kyoungrul Kim <k831.kim@samsung.com>
The six static inline byte-order helpers (sgio_get/set_be16/32/64)
were defined privately inside sg.c, making them inaccessible to other
engines that also need to construct or parse SCSI CDBs.

Move them into a new engines/sg.h so that any engine speaking SCSI can
include the header directly rather than reimplementing the same
byte-swap wrappers independently.  sg.c gains an include of sg.h in
place of the now-removed definitions; no behaviour is changed.

Signed-off-by: Kyoungrul Kim <k831.kim@samsung.com>
Extend io_uring_cmd engine to support SCSI commands via bsg (Block SCSI
Generic) interface. Previously, io_uring_cmd engine only supported NVMe
deivces through cmd_type=nvme.

This patch introduces:
- NEW cmd_type option "bsg" to select bsg_uring_cmd interface
- BSG-specific command preparation and completion handling
- SCSI CDB (Command Descriptor Block) construction
- Read Capacity support for device size detection
- Proper error reporting with SCSI status and host status separation

Currently, the following basic fio --rw= are supported:
- read: READ(10)
- write: WRITE(10)
- trim: UNMAP
- fsync: SYNC CACHE(10)

Example:
--filename=/dev/bsg/0\:0\:0\:0 --ioengine=io_uring_cmd --cmd_type=bsg

Signed-off-by: Jungwon Lee <jjung1.lee@samsung.com>
Signed-off-by: Kyoungrul Kim <k831.kim@samsung.com>
@k831-kim
k831-kim force-pushed the upstream-io_uring-bsg branch from 791ab0f to d77ed2b Compare June 24, 2026 02:03
@axboe
axboe merged commit bdb1265 into axboe:master Jun 24, 2026
39 of 40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants

⌂ 换网址