Re: [PATCH v1 06/30] io_uring/kbuf: add buffer ring pinning/unpinning

[Caleb Sander Mateos <csander@purestorage.com>]

On Tue, Dec 2, 2025 at 4:36 PM Joanne Koong <joannelkoong@gmail.com> wrote:
>
> Add kernel APIs to pin and unpin buffer rings, preventing userspace from
> unregistering a buffer ring while it is pinned by the kernel.
>
> This provides a mechanism for kernel subsystems to safely access buffer
> ring contents while ensuring the buffer ring remains valid. A pinned
> buffer ring cannot be unregistered until explicitly unpinned. On the
> userspace side, trying to unregister a pinned buffer will return -EBUSY.
> Pinning an already-pinned bufring is acceptable and returns 0.
>
> The API accepts a "struct io_ring_ctx *ctx" rather than a cmd pointer,
> as the buffer ring may need to be unpinned in contexts where a cmd is
> not readily available.
>
> This is a preparatory change for upcoming fuse usage of kernel-managed
> buffer rings. It is necessary for fuse to pin the buffer ring because
> fuse may need to select a buffer in atomic contexts, which it can only
> do so by using the underlying buffer list pointer.
>
> Signed-off-by: Joanne Koong <joannelkoong@gmail.com>
> ---
>  include/linux/io_uring/buf.h | 28 +++++++++++++++++++++++
>  io_uring/kbuf.c              | 43 ++++++++++++++++++++++++++++++++++++
>  io_uring/kbuf.h              |  5 +++++
>  3 files changed, 76 insertions(+)
>  create mode 100644 include/linux/io_uring/buf.h
>
> diff --git a/include/linux/io_uring/buf.h b/include/linux/io_uring/buf.h
> new file mode 100644
> index 000000000000..7a1cf197434d
> --- /dev/null
> +++ b/include/linux/io_uring/buf.h
> @@ -0,0 +1,28 @@
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
> +#ifndef _LINUX_IO_URING_BUF_H
> +#define _LINUX_IO_URING_BUF_H
> +
> +#include <linux/io_uring_types.h>
> +
> +#if defined(CONFIG_IO_URING)
> +int io_uring_buf_ring_pin(struct io_ring_ctx *ctx, unsigned buf_group,
> +                         unsigned issue_flags, struct io_buffer_list **bl);
> +int io_uring_buf_ring_unpin(struct io_ring_ctx *ctx, unsigned buf_group,
> +                           unsigned issue_flags);
> +#else
> +static inline int io_uring_buf_ring_pin(struct io_ring_ctx *ctx,
> +                                       unsigned buf_group,
> +                                       unsigned issue_flags,
> +                                       struct io_buffer_list **bl);
> +{
> +       return -EOPNOTSUPP;
> +}
> +static inline int io_uring_buf_ring_unpin(struct io_ring_ctx *ctx,
> +                                         unsigned buf_group,
> +                                         unsigned issue_flags)
> +{
> +       return -EOPNOTSUPP;
> +}
> +#endif /* CONFIG_IO_URING */
> +
> +#endif /* _LINUX_IO_URING_BUF_H */
> diff --git a/io_uring/kbuf.c b/io_uring/kbuf.c
> index 00ab17a034b5..ddda1338e652 100644
> --- a/io_uring/kbuf.c
> +++ b/io_uring/kbuf.c
> @@ -9,6 +9,7 @@
>  #include <linux/poll.h>
>  #include <linux/vmalloc.h>
>  #include <linux/io_uring.h>
> +#include <linux/io_uring/buf.h>
>
>  #include <uapi/linux/io_uring.h>
>
> @@ -237,6 +238,46 @@ struct io_br_sel io_buffer_select(struct io_kiocb *req, size_t *len,
>         return sel;
>  }
>
> +int io_uring_buf_ring_pin(struct io_ring_ctx *ctx, unsigned buf_group,
> +                         unsigned issue_flags, struct io_buffer_list **bl)
> +{
> +       struct io_buffer_list *buffer_list;
> +       int ret = -EINVAL;
> +
> +       io_ring_submit_lock(ctx, issue_flags);
> +
> +       buffer_list = io_buffer_get_list(ctx, buf_group);
> +       if (likely(buffer_list) && (buffer_list->flags & IOBL_BUF_RING)) {

Since there's no reference-counting of pins, I think it might make
more sense to fail io_uring_buf_ring_pin() if the buffer ring is
already pinned. Otherwise, the buffer ring will be unpinned in the
first call to io_uring_buf_ring_unpin(), when it might still be in use
by another caller of io_uring_buf_ring_pin().

Best,
Caleb

> +               buffer_list->flags |= IOBL_PINNED;
> +               ret = 0;
> +               *bl = buffer_list;
> +       }
> +
> +       io_ring_submit_unlock(ctx, issue_flags);
> +       return ret;
> +}
> +EXPORT_SYMBOL_GPL(io_uring_buf_ring_pin);
> +
> +int io_uring_buf_ring_unpin(struct io_ring_ctx *ctx, unsigned buf_group,
> +                           unsigned issue_flags)
> +{
> +       struct io_buffer_list *bl;
> +       int ret = -EINVAL;
> +
> +       io_ring_submit_lock(ctx, issue_flags);
> +
> +       bl = io_buffer_get_list(ctx, buf_group);
> +       if (likely(bl) && (bl->flags & IOBL_BUF_RING) &&
> +           (bl->flags & IOBL_PINNED)) {
> +               bl->flags &= ~IOBL_PINNED;
> +               ret = 0;
> +       }
> +
> +       io_ring_submit_unlock(ctx, issue_flags);
> +       return ret;
> +}
> +EXPORT_SYMBOL_GPL(io_uring_buf_ring_unpin);
> +
>  /* cap it at a reasonable 256, will be one page even for 4K */
>  #define PEEK_MAX_IMPORT                256
>
> @@ -743,6 +784,8 @@ int io_unregister_buf_ring(struct io_ring_ctx *ctx, void __user *arg)
>                 return -ENOENT;
>         if (!(bl->flags & IOBL_BUF_RING))
>                 return -EINVAL;
> +       if (bl->flags & IOBL_PINNED)
> +               return -EBUSY;
>
>         scoped_guard(mutex, &ctx->mmap_lock)
>                 xa_erase(&ctx->io_bl_xa, bl->bgid);
> diff --git a/io_uring/kbuf.h b/io_uring/kbuf.h
> index 11d165888b8e..781630c2cc10 100644
> --- a/io_uring/kbuf.h
> +++ b/io_uring/kbuf.h
> @@ -12,6 +12,11 @@ enum {
>         IOBL_INC                = 2,
>         /* buffers are kernel managed */
>         IOBL_KERNEL_MANAGED     = 4,
> +       /*
> +        * buffer ring is pinned and cannot be unregistered by userspace until
> +        * it has been unpinned
> +        */
> +       IOBL_PINNED             = 8,
>  };
>
>  struct io_buffer_list {
> --
> 2.47.3
>