7.50. ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF¶

7.50.1. Name¶

VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver

7.50.2. Synopsis¶

int ioctl(int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp)¶

int ioctl(int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp)¶

7.50.3. Arguments¶

fd: File descriptor returned by open().
argp: Pointer to struct v4l2_ext_buffer.

7.50.4. Description¶

Applications call the VIDIOC_EXT_QBUF ioctl to enqueue an empty (capturing) or filled (output) buffer in the driver’s incoming queue. The semantics depend on the selected I/O method.

To enqueue a buffer applications set the type field of a struct v4l2_ext_buffer to the same buffer type as was previously used with struct v4l2_ext_pix_format type. Applications must also set the index field. Valid index numbers range from zero to the number of buffers allocated with ioctl VIDIOC_EXT_CREATE_BUFS (struct v4l2_ext_create_buffers count) minus one. The contents of the struct v4l2_ext_buffer returned by a ioctl VIDIOC_EXT_QUERYBUF ioctl will do as well. When the buffer is intended for output (type is V4L2_BUF_TYPE_VIDEO_OUTPUT) applications must also initialize the timestamp fields and the planes[i].plane_length for each valid plane, and invalid ones must be set as zero. see Buffers for details. Applications must also set flags to 0. The reserved field must be set to 0.

To enqueue a memory mapped buffer applications set the planes[i].memory field to V4L2_MEMORY_MMAP in all the valid planes, and invalid ones must be set as zero. When VIDIOC_EXT_QBUF is called with a pointer to this structure the driver sets the V4L2_BUF_FLAG_MAPPED and V4L2_BUF_FLAG_QUEUED flags and clears the V4L2_BUF_FLAG_DONE flag in the flags field, or it returns an EINVAL error code.

To enqueue a user pointer buffer applications set the planes[i].memory field to V4L2_MEMORY_USERPTR in all the valid planes, and invalid ones must be set as zero, the planes[i].m.userptr field to the address of the buffer,``planes[i].buffer_length`` to the size of the memory buffer, planes[i].plane_length to the size that should be used by the plane, and planes[i].offset of the plane in the memory buffer.

When VIDIOC_EXT_QBUF is called with a pointer to this structure the driver sets the V4L2_BUF_FLAG_QUEUED flag and clears the V4L2_BUF_FLAG_MAPPED and V4L2_BUF_FLAG_DONE flags in the flags field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, they cannot be swapped out to disk. Buffers remain locked until dequeued, until the VIDIOC_STREAMOFF or ioctl VIDIOC_EXT_CREATE_BUFS ioctl is called, or until the device is closed.

To enqueue a DMABUF buffer applications set the planes[i].memory field to V4L2_MEMORY_DMABUF in all the valid planes, and invalid ones must be set as zero, the planes[i].m.fd field to a file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to the size of the memory buffer, planes[i].plane_length to the size that should be used by the plane, and planes[i].offset of the plane in the memory buffer. When VIDIOC_EXT_QBUF is called with a pointer to this structure the driver sets the V4L2_BUF_FLAG_QUEUED flag and clears the V4L2_BUF_FLAG_MAPPED and V4L2_BUF_FLAG_DONE flags in the flags field, or it returns an error code. This ioctl locks the buffer. Locking a buffer means passing it to a driver for a hardware access (usually DMA). If an application accesses (reads/writes) a locked buffer then the result is undefined. Buffers remain locked until dequeued, until the VIDIOC_STREAMOFF or ioctl VIDIOC_EXT_CREATE_BUFS ioctl is called, or until the device is closed.

The request_fd field can be used with the VIDIOC_EXT_QBUF ioctl to specify the file descriptor of a request, if requests are in use. Setting it means that the buffer will not be passed to the driver until the request itself is queued. Also, the driver will apply any settings associated with the request for this buffer. This field will be ignored unless the V4L2_BUF_FLAG_REQUEST_FD flag is set. If the device does not support requests, then EBADR will be returned. If requests are supported but an invalid request file descriptor is given, then EINVAL will be returned.

Caution

It is not allowed to mix queuing requests with queuing buffers directly. EBUSY will be returned if the first buffer was queued directly and then the application tries to queue a request, or vice versa. After closing the file descriptor, calling VIDIOC_STREAMOFF or calling ioctl VIDIOC_EXT_CREATE_BUFS the check for this will be reset.

For memory-to-memory devices you can specify the request_fd only for output buffers, not for capture buffers. Attempting to specify this for a capture buffer will result in an EBADR error.

Applications call the VIDIOC_EXT_DQBUF ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver’s outgoing queue. They just set the type, planes[i].memory and reserved fields of a struct v4l2_ext_buffer as above, when VIDIOC_EXT_DQBUF is called with a pointer to this structure the driver fills the remaining fields or returns an error code. The driver may also set V4L2_BUF_FLAG_ERROR in the flags field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the dequeued buffer might be corrupted. When using the multi-planar API, the planes array must be passed in as well.

If the application sets the memory field to V4L2_MEMORY_DMABUF to dequeue a DMABUF buffer, the driver fills the m.fd field with a file descriptor numerically the same as the one given to VIDIOC_EXT_QBUF when the buffer was enqueued. No new file descriptor is created at dequeue time and the value is only for the application convenience.

By default VIDIOC_EXT_DQBUF blocks when no buffer is in the outgoing queue. When the O_NONBLOCK flag was given to the open() function, VIDIOC_EXT_DQBUF returns immediately with an EAGAIN error code when no buffer is available.

7.50.5. Return Value¶

On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.

EAGAIN: Non-blocking I/O has been selected using O_NONBLOCK and no buffer was in the outgoing queue.
EINVAL: The buffer type is not supported, or the index is out of bounds, or no buffers have been allocated yet, or the userptr or length are invalid, or the V4L2_BUF_FLAG_REQUEST_FD flag was set but the the given request_fd was invalid, or m.fd was an invalid DMABUF file descriptor.
EIO: VIDIOC_EXT_DQBUF failed due to an internal error. Can also indicate temporary problems like signal loss.

Note

The driver might dequeue an (empty) buffer despite returning an error, or even stop capturing. Reusing such buffer may be unsafe though and its details (e.g. index) may not be returned either. It is recommended that drivers indicate recoverable errors by setting the V4L2_BUF_FLAG_ERROR and returning 0 instead. In that case the application should be able to safely reuse the buffer and continue streaming.
EPIPE: VIDIOC_EXT_DQBUF returns this on an empty capture queue for mem2mem codecs if a buffer with the V4L2_BUF_FLAG_LAST was already dequeued and no new buffers are expected to become available.
EBADR: The V4L2_BUF_FLAG_REQUEST_FD flag was set but the device does not support requests for the given buffer type, or the V4L2_BUF_FLAG_REQUEST_FD flag was not set but the device requires that the buffer is part of a request.
EBUSY: The first buffer was queued via a request, but the application now tries to queue it directly, or vice versa (it is not permitted to mix the two APIs).