github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-09-23 13:14:02 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

Documentation: media: vidioc-g-ext-ctrls: clarify try/set behavior

Browse Source 
It was not clearly stated in the documentation that calling
VIDIOC_S_EXT_CTRLS implies an internal VIDIOC_TRY_EXT_CTRLS
call.

Clarify this.

Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
Acked-by: Linus Walleij <linusw@kernel.org>
Link: https://lore.kernel.org/linux-media/20260701-v4l2-doc-v1-1-9cce64b7a1c2@kernel.org/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Hans Verkuil 2026-07-01 13:10:33 +02:00 committed by Mauro Carvalho Chehab
parent 42f83a3225
commit d590d26710
1 changed files with 9 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
View File

@ -72,12 +72,6 @@ partial array, all elements have to be set or retrieved. The total size
is calculated as ``elems`` * ``elem_size``. These values can be obtained
by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
To change the value of a set of controls applications initialize the
``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
of each struct :c:type:`v4l2_ext_control` and call
the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
control values are valid.
To check if a set of controls have correct values applications
initialize the ``id``, ``size``, ``reserved2`` and
``value/value64/string/ptr`` fields of each struct
@ -86,6 +80,15 @@ initialize the ``id``, ``size``, ``reserved2`` and
values are automatically adjusted to a valid value or if an error is
returned.
To change the value of a set of controls applications initialize the
``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
of each struct :c:type:`v4l2_ext_control` and call
the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl.
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` will implicitly call
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` first and return an
error if that fails. So the controls will only be set if *all*
control values are valid.
When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
code. When the value is out of bounds drivers can choose to take the
closest valid value or return an ``ERANGE`` error code, whatever seems more