aboutsummaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/v4l/vidioc-qbuf.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-qbuf.rst')
-rw-r--r--Documentation/media/uapi/v4l/vidioc-qbuf.rst37
1 files changed, 35 insertions, 2 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
index 9e448a4aa3aa..753b3b5946b1 100644
--- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
+++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
@@ -65,7 +65,7 @@ To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
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.
+``EINVAL`` error code.
To enqueue a :ref:`user pointer <userp>` buffer applications set the
``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
@@ -98,6 +98,28 @@ dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
device is closed.
+The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
+the file descriptor of a :ref:`request <media-request-api>`, 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 ``EACCES`` 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
+ :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
+ the check for this will be reset.
+
+ For :ref:`memory-to-memory devices <codec>` 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 ``EACCES`` error.
+
Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
(capturing) or displayed (output) buffer from the driver's outgoing
queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
@@ -133,7 +155,9 @@ EAGAIN
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.
+ ``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_DQBUF`` failed due to an internal error. Can also indicate
@@ -153,3 +177,12 @@ EPIPE
``VIDIOC_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.
+
+EACCES
+ The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not
+ support requests for the given buffer type.
+
+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).