]> git.ipfire.org Git - thirdparty/kernel/stable.git/commit
io_uring: introduce io_uring querying
authorPavel Begunkov <asml.silence@gmail.com>
Sun, 7 Sep 2025 23:03:00 +0000 (00:03 +0100)
committerJens Axboe <axboe@kernel.dk>
Mon, 8 Sep 2025 14:06:37 +0000 (08:06 -0600)
commitc265ae75f900cea4e415230a77b5d152377627dd
tree96fc4197736946cf3c241bc57e8d700bb155263a
parent63805d0a9b9670ade00c4f49e4fe093668b31ba5
io_uring: introduce io_uring querying

There are many parameters users might want to query about io_uring like
available request types or the ring sizes. This patch introduces an
interface for such slow path queries.

It was written with several requirements in mind:
- Can be used with or without an io_uring instance. Asking for supported
  setup flags before creating an instance as well as qeurying info about
  an already created ring are valid use cases.
- Should be moderately fast. For example, users might use it to
  periodically retrieve ring attributes at runtime. As a consequence,
  it should be able to query multiple attributes in a single syscall.
- Backward and forward compatible.
- Should be reasobably easy to use.
- Reduce the kernel code size for introducing new query types.

It's implemented as a new registration opcode IORING_REGISTER_QUERY.
The user passes one or more query strutctures linked together, each
represented by struct io_uring_query_hdr. The header stores common
control fields needed for processing and points to query type specific
information.

The header contains
- The query type
- The result field, which on return contains the error code for the query
- Pointer to the query type specific information
- The size of the query structure. The kernel will only populate up to
  the size, which helps with backward compatibility. The kernel can also
  reduce the size, so if the current kernel is older than the inteface
  the user tries to use, it'll get only the supported bits.
- next_entry field is used to chain multiple queries.

Apart from common registeration syscall failures, it can only immediately
return an error code in case when the headers are incorrect or any
other addresses and invalid. That usually mean that the userspace
doesn't use the API right and should be corrected. All query type
specific errors are returned in the header's result field.

As an example, the patch adds a single query type for now, i.e.
IO_URING_QUERY_OPCODES, which tells what register / request / etc.
opcodes are supported, but there are particular plans to extend it.

Note: there is a request probing interface via IORING_REGISTER_PROBE,
but it's a mess. It requires the user to create a ring first, it only
works for requests, and requires dynamic allocations.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>
include/uapi/linux/io_uring.h
include/uapi/linux/io_uring/query.h [new file with mode: 0644]
io_uring/Makefile
io_uring/query.c [new file with mode: 0644]
io_uring/query.h [new file with mode: 0644]
io_uring/register.c