Document the new min_num_buffers and rec_num_buffers fields and the
corresponding V4L2_BUF_CAP_SUPPORTS_MIN_REC_NUM_BUFFERS capability flag.
Signed-off-by: Hans Verkuil <hverkuil@xxxxxxxxx>
---
.../media/v4l/vidioc-create-bufs.rst | 34 +++++++++++++++----
.../media/v4l/vidioc-reqbufs.rst | 6 ++++
2 files changed, 33 insertions(+), 7 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
index 49232c9006c2..a400d464cc9f 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
@@ -68,7 +68,12 @@ When the ioctl is called with a pointer to this structure the driver
will attempt to allocate up to the requested number of buffers and store
the actual number allocated and the starting index in the ``count`` and
the ``index`` fields respectively. On return ``count`` can be smaller
-than the number requested.
+than the number requested, but never larger. If no buffers could be
+allocated, then -1 is returned and errno is set to the ``ENOMEM`` error code.
+
+If ``count`` was set to 0, then no buffers are allocated, and instead
+it just sets the various informative fields, e.g. ``capabilities``,
+``max_num_buffers``, etc.
.. c:type:: v4l2_create_buffers
@@ -88,9 +93,9 @@ than the number requested.
:ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
created buffers, and it will check the validity of ``memory`` and
``format.type``. If those are invalid -1 is returned and errno is
- set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
- 0. It will never set errno to ``EBUSY`` error code in this particular
- case.
+ set to the ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS`
+ returns 0. It will never set errno to the ``EBUSY`` error code in this
+ particular case.
* - __u32
- ``memory``
- Applications set this field to ``V4L2_MEMORY_MMAP``,
@@ -118,11 +123,26 @@ than the number requested.
See :ref:`memory-flags`.
* - __u32
- ``max_num_buffers``
- - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set
- this field indicates the maximum possible number of buffers
+ - If the ``V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS`` capability flag is
+ set this field indicates the maximum possible number of buffers
for this queue.
+ * - __u16
+ - ``min_num_buffers``
+ - If the ``V4L2_BUF_CAP_SUPPORTS_MIN_REC_NUM_BUFFERS`` capability flag is
+ set this field indicates the minimum number of buffers for this queue.
+ Allocating this number of buffers will allow video streaming, but frame
+ drops might happen.
+ * - __u16
+ - ``rec_num_buffers``
+ - If the ``V4L2_BUF_CAP_SUPPORTS_MIN_REC_NUM_BUFFERS`` capability flag is
+ set this field indicates the recommended number of buffers for this
+ queue.
+ The :ref:`VIDIOC_REQBUFS` will use this value if the requested number of
+ buffers is less than this value. This value ensures reliable video
+ streaming without frame drops, provided the application can process
+ a dequeued buffer within a single frame period.
* - __u32
- - ``reserved``\ [5]
+ - ``reserved``\ [4]
- A place holder for future extensions. Drivers and applications
must set the array to zero.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
index daf9a6621b50..4c5bb303b5a2 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
@@ -124,6 +124,7 @@ aborting or finishing any DMA in progress, an implicit
.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:
.. _V4L2-BUF-CAP-SUPPORTS-MAX-NUM-BUFFERS:
.. _V4L2-BUF-CAP-SUPPORTS-REMOVE-BUFS:
+.. _V4L2-BUF-CAP-SUPPORTS-MIN-REC-NUM-BUFFERS:
.. flat-table:: V4L2 Buffer Capabilities Flags
:header-rows: 0
@@ -167,6 +168,11 @@ aborting or finishing any DMA in progress, an implicit
* - ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS``
- 0x00000100
- If set, then ``VIDIOC_REMOVE_BUFS`` is supported.
+ * - ``V4L2_BUF_CAP_SUPPORTS_MIN_REC_NUM_BUFFERS``
+ - 0x00000200
+ - If set, then the ``min_num_buffers`` and ``rec_num_buffers`` fields in
+ ``struct v4l2_create_buffers`` are valid. If not set, then these fields
+ are 0.
.. _memory-flags:
.. _V4L2-MEMORY-FLAG-NON-COHERENT:
--
2.45.2
