Re: [PATCH V5 2/2] io_uring: uring_cmd: add multishot support

[Jens Axboe <axboe@kernel.dk>]

On 8/21/25 10:29 AM, Caleb Sander Mateos wrote:
> On Wed, Aug 20, 2025 at 9:02?PM Ming Lei <ming.lei@redhat.com> wrote:
>>
>> Add UAPI flag IORING_URING_CMD_MULTISHOT for supporting multishot
>> uring_cmd operations with provided buffer.
>>
>> This enables drivers to post multiple completion events from a single
>> uring_cmd submission, which is useful for:
>>
>> - Notifying userspace of device events (e.g., interrupt handling)
>> - Supporting devices with multiple event sources (e.g., multi-queue devices)
>> - Avoiding the need for device poll() support when events originate
>>   from multiple sources device-wide
>>
>> The implementation adds two new APIs:
>> - io_uring_cmd_select_buffer(): selects a buffer from the provided
>>   buffer group for multishot uring_cmd
>> - io_uring_mshot_cmd_post_cqe(): posts a CQE after event data is
>>   pushed to the provided buffer
>>
>> Multishot uring_cmd must be used with buffer select (IOSQE_BUFFER_SELECT)
>> and is mutually exclusive with IORING_URING_CMD_FIXED for now.
>>
>> The ublk driver will be the first user of this functionality:
>>
>>         https://github.com/ming1/linux/commits/ublk-devel/
>>
>> Signed-off-by: Ming Lei <ming.lei@redhat.com>
>> ---
>>  include/linux/io_uring/cmd.h  | 27 +++++++++++++
>>  include/uapi/linux/io_uring.h |  6 ++-
>>  io_uring/opdef.c              |  1 +
>>  io_uring/uring_cmd.c          | 71 ++++++++++++++++++++++++++++++++++-
>>  4 files changed, 103 insertions(+), 2 deletions(-)
>>
>> diff --git a/include/linux/io_uring/cmd.h b/include/linux/io_uring/cmd.h
>> index cfa6d0c0c322..856d343b8e2a 100644
>> --- a/include/linux/io_uring/cmd.h
>> +++ b/include/linux/io_uring/cmd.h
>> @@ -70,6 +70,21 @@ void io_uring_cmd_mark_cancelable(struct io_uring_cmd *cmd,
>>  /* Execute the request from a blocking context */
>>  void io_uring_cmd_issue_blocking(struct io_uring_cmd *ioucmd);
>>
>> +/*
>> + * Select a buffer from the provided buffer group for multishot uring_cmd.
>> + * Returns the selected buffer address and size.
>> + */
>> +struct io_br_sel io_uring_cmd_buffer_select(struct io_uring_cmd *ioucmd,
>> +                                           unsigned buf_group, size_t *len,
>> +                                           unsigned int issue_flags);
>> +
>> +/*
>> + * Complete a multishot uring_cmd event. This will post a CQE to the completion
>> + * queue and update the provided buffer.
>> + */
>> +bool io_uring_mshot_cmd_post_cqe(struct io_uring_cmd *ioucmd,
>> +                                struct io_br_sel *sel, unsigned int issue_flags);
>> +
>>  #else
>>  static inline int
>>  io_uring_cmd_import_fixed(u64 ubuf, unsigned long len, int rw,
>> @@ -102,6 +117,18 @@ static inline void io_uring_cmd_mark_cancelable(struct io_uring_cmd *cmd,
>>  static inline void io_uring_cmd_issue_blocking(struct io_uring_cmd *ioucmd)
>>  {
>>  }
>> +static inline int io_uring_cmd_select_buffer(struct io_uring_cmd *ioucmd,
>> +                               unsigned buf_group,
>> +                               void **buf, size_t *len,
>> +                               unsigned int issue_flags)
>> +{
>> +       return -EOPNOTSUPP;
>> +}
>> +static inline bool io_uring_mshot_cmd_post_cqe(struct io_uring_cmd *ioucmd,
>> +                               ssize_t ret, unsigned int issue_flags)
>> +{
>> +       return true;
>> +}
>>  #endif
>>
>>  /*
>> diff --git a/include/uapi/linux/io_uring.h b/include/uapi/linux/io_uring.h
>> index 6957dc539d83..1e935f8901c5 100644
>> --- a/include/uapi/linux/io_uring.h
>> +++ b/include/uapi/linux/io_uring.h
>> @@ -298,9 +298,13 @@ enum io_uring_op {
>>   * sqe->uring_cmd_flags                top 8bits aren't available for userspace
>>   * IORING_URING_CMD_FIXED      use registered buffer; pass this flag
>>   *                             along with setting sqe->buf_index.
>> + * IORING_URING_CMD_MULTISHOT  must be used with buffer select, like other
>> + *                             multishot commands. Not compatible with
>> + *                             IORING_URING_CMD_FIXED, for now.
>>   */
>>  #define IORING_URING_CMD_FIXED (1U << 0)
>> -#define IORING_URING_CMD_MASK  IORING_URING_CMD_FIXED
>> +#define IORING_URING_CMD_MULTISHOT     (1U << 1)
>> +#define IORING_URING_CMD_MASK  (IORING_URING_CMD_FIXED | IORING_URING_CMD_MULTISHOT)
> 
> One other question: what is the purpose of this additional flag?
> io_uring_cmd_prep() checks that it matches IOSQE_BUFFER_SELECT, so
> could we just check that flag instead and drop the check that
> IORING_URING_CMD_MULTISHOT matches REQ_F_BUFFER_SELECT?

This is a good question - if we don't strictly needs to exist, eg it
overlaps 100% with IOSQE_BUFFER_SELECT, we should just drop it.

-- 
Jens Axboe