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

[Jens Axboe <axboe@kernel.dk>]

On 8/21/25 6:52 PM, Ming Lei wrote:
> On Thu, Aug 21, 2025 at 10:38:57AM -0600, Jens Axboe wrote:
>> 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.
> 
> Without this flag, who knows it is one mshot command?
> 
> Other mshot OPs use new OP for showing the purpose, here I just want to
> avoid to add another uring_cmd variant.

Basically all other multishot command types use a flag, not a new
opcode. Read mshot is the odd one out, because it doesn't have private
flags. Hence I do agree with you, the current approach is fine. For some
reason I remembered it as a IO_URING_CMD_* buffer select flag, but it's
not. The other mshot commands also generally require
IOSQE_BUFFER_SELECT, rather than have it be implied by the command type.

-- 
Jens Axboe