STRUCT VB2_QUEUE(9)

📦 version 7.3.1, in nixpkgs unstable

🎀 struct vb2_queue(9) 🎀

Hiii bestie, welcome to the Kernel API Manual!! 💖 Today’s main character is struct vb2_queue, aka a videobuf2 queue, and she is literally the blueprint for how buffers get queued, owned, allocated, and streamed. Buckle up, because this struct has lore. 🦋

💖 NAME 💖

struct vb2_queue — a videobuf2 queue. That’s the whole name, bestie, no cap.

🦋 SYNOPSIS 🦋

okay so the vibe is this exact struct, and yes every field matters:

       struct vb2_queue {
           unsigned int                    type;
           unsigned int                    io_modes;
           struct device                   *dev;
           unsigned long                   dma_attrs;
           unsigned int                    bidirectional:1;
           unsigned int                    fileio_read_once:1;
           unsigned int                    fileio_write_immediately:1;
           unsigned int                    allow_zero_bytesused:1;
           unsigned int
       quirk_poll_must_check_waiting_for_buffers:1;
           unsigned int                    supports_requests:1;
           unsigned int                    requires_requests:1;
           unsigned int                    uses_qbuf:1;
           unsigned int                    uses_requests:1;
           unsigned int                    allow_cache_hints:1;
           unsigned int                    non_coherent_mem:1;
           struct mutex                    *lock;
           void *owner;
           const struct vb2_ops            *ops;
           const struct vb2_mem_ops        *mem_ops;
           const struct vb2_buf_ops        *buf_ops;
           void *drv_priv;
           u32 subsystem_flags;
           unsigned int                    buf_struct_size;
           u32 timestamp_flags;
           gfp_t gfp_flags;
           u32 min_queued_buffers;
           u32 min_reqbufs_allocation;
           struct device                   *alloc_devs[VB2_MAX_PLANES];
        };

💅 Members 💅

  • type — this is the private buffer type, and the vb2-core caller defines what it means. For V4L2 girlies, it should match the types defined on enum v4l2_buf_type. 🎀
  • io_modes — the supported io methods for this queue; peep enum vb2_io_modes for the menu. ✨
  • dev — the device used for the default allocation context when the driver doesn’t fill in the alloc_devs array. 🫶
  • dma_attrs — the DMA attributes to use for the DMA. Simple as that. 💅
  • bidirectional — when this flag is set, the DMA direction for the buffers of this queue gets overridden with the DMA_BIDIRECTIONAL direction. This is useful when the hardware/firmware writes to a buffer that’s mapped as read (DMA_TO_DEVICE), or reads from a buffer mapped for write (DMA_FROM_DEVICE), because of some internal hardware restrictions or because it adds padding needed by the processing algorithm. But listen: if the DMA mapping is not bidirectional and the hardware/firmware tries to access the buffer in the opposite direction, this could lead to IOMMU protection faults. 💀
  • fileio_read_once — report EOF after reading the first buffer. 🍓
  • fileio_write_immediately — queue the buffer after each write call. 🌸
  • allow_zero_bytesused — allow bytesused == 0 to be passed to the driver. ✨
  • quirk_poll_must_check_waiting_for_buffers — return EPOLLERR at poll when QBUF has not been called. This is a vb1 idiom that has been adopted also by vb2. Quirky, but valid. 🌀
  • supports_requests — this queue supports the Request API. 👑
  • requires_requests — this queue requires the Request API. If this is set to 1, then supports_requests must be set to 1 as well. No exceptions, bestie. 🚨
  • uses_qbuf — qbuf was used directly for this queue. It gets set to 1 the first time this is called, and set to 0 when the queue is canceled. If this is 1, then you cannot queue buffers from a request. 🔥
  • uses_requests — requests are used for this queue. It gets set to 1 the first time a request is queued, and set to 0 when the queue is canceled. If this is 1, then you cannot queue buffers directly. 🌈
  • allow_cache_hints — when set, user-space can pass cache management hints in order to skip cache flush/invalidation on ->prepare or/and ->finish. 🧚
  • non_coherent_mem — when set, the queue will attempt to allocate buffers using non-coherent memory. 💜
  • lock — pointer to a mutex that protects the struct vb2_queue. The driver must set this to a mutex to let the v4l2 core serialize the queuing ioctls. This lock is used when waiting for a new buffer to arrive: the lock is released, we wait for the new buffer, and then it’s retaken. 🔐
  • owner — the filehandle that “owns” the buffers, i.e. the filehandle that called reqbufs, create_buffers or started fileio. This field is not used by the videobuf2 core API, but it allows drivers to easily associate an owner filehandle with the queue. 🫶
  • ops — driver-specific callbacks. 🛠️
  • mem_ops — memory allocator specific callbacks. 🧠
  • buf_ops — callbacks to deliver buffer information between user-space and kernel-space. 📬
  • drv_priv — driver private data. 🙈
  • subsystem_flags — flags specific to the subsystem (V4L2/DVB/etc.). Not used by the vb2 core. 🎟️
  • buf_struct_size — size of the driver-specific buffer structure; "0" indicates the driver doesn’t want to use a custom buffer structure type. In that case a subsystem-specific struct will be used (in the case of V4L2 that is sizeof(struct vb2_v4l2_buffer)). The first field of the driver-specific buffer structure must be the subsystem-specific struct (vb2_v4l2_buffer in the case of V4L2). 📏
  • timestamp_flags — timestamp flags; V4L2_BUF_FLAG_TIMESTAMP_* and V4L2_BUF_FLAG_TSTAMP_SRC_*. ⏰
  • gfp_flags — additional gfp flags used when allocating the buffers. Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32 to force the buffer allocation to a specific memory zone. 🌱
  • min_queued_buffers — the minimum number of queued buffers needed before start_streaming can be called. Used when a DMA engine cannot be started unless at least this number of buffers have been queued into the driver. VIDIOC_REQBUFS will ensure at least min_queued_buffers + 1 buffers will be allocated. Note that VIDIOC_CREATE_BUFS will not modify the requested buffer count. 📦
  • min_reqbufs_allocation — the minimum number of buffers to be allocated when calling VIDIOC_REQBUFS. Note that VIDIOC_CREATE_BUFS will not modify the requested buffer count and does not use this field. Drivers can set this if there has to be a certain number of buffers available for the hardware to work effectively. This allows calling VIDIOC_REQBUFS with a buffer count of 1 and it will be automatically adjusted to a workable buffer count. If set, then min_reqbufs_allocation must be larger than min_queued_buffers + 1. If this field is > 3, then it is highly recommended that the driver implements the V4L2_CID_MIN_BUFFERS_FOR_CAPTURE/OUTPUT control. 🧮
  • alloc_devs — struct device memory type/allocator-specific per-plane device. 🧩

👀 SEE ALSO 👀

Kernel file ./include/media/videobuf2-core.h — and the whole friend group is:

okay bye bestie!! 💖 this page came from ./include/media, dated October 2026, and it’s all the lore for struct vb2_queue(9) ✨👑

📦 where this page comes from