diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst | 538 |
1 files changed, 200 insertions, 338 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst index 01561ddfe73b..5ab8d2ac27b9 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst @@ -111,127 +111,73 @@ still cause this situation. :stub-columns: 0 :widths: 1 1 1 2 - - - .. row 1 - - - __u32 - - - ``id`` - - - - - Identifies the control, set by the application. - - - .. row 2 - - - __u32 - - - ``size`` - - - - - The total size in bytes of the payload of this control. This is - normally 0, but for pointer controls this should be set to the - size of the memory containing the payload, or that will receive - the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is - less than is required to store the payload result, then it is set - to a value large enough to store the payload result and ``ENOSPC`` is - returned. - - .. note:: - - For string controls, this ``size`` field should - not be confused with the length of the string. This field refers - to the size of the memory that contains the string. The actual - *length* of the string may well be much smaller. - - - .. row 3 - - - __u32 - - - ``reserved2``\ [1] - - - - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - - .. row 4 - - - union - - - (anonymous) - - - .. row 5 - - - - - __s32 - - - ``value`` - - - New value or current value. Valid if this control is not of type - ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is - not set. - - - .. row 6 - - - - - __s64 - - - ``value64`` - - - New value or current value. Valid if this control is of type - ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is - not set. - - - .. row 7 - - - - - char * - - - ``string`` - - - A pointer to a string. Valid if this control is of type - ``V4L2_CTRL_TYPE_STRING``. - - - .. row 8 - - - - - __u8 * - - - ``p_u8`` - - - A pointer to a matrix control of unsigned 8-bit values. Valid if - this control is of type ``V4L2_CTRL_TYPE_U8``. - - - .. row 9 - - - - - __u16 * - - - ``p_u16`` - - - A pointer to a matrix control of unsigned 16-bit values. Valid if - this control is of type ``V4L2_CTRL_TYPE_U16``. - - - .. row 10 - - - - - __u32 * - - - ``p_u32`` - - - A pointer to a matrix control of unsigned 32-bit values. Valid if - this control is of type ``V4L2_CTRL_TYPE_U32``. - - - .. row 11 - - - - - void * - - - ``ptr`` - - - A pointer to a compound type which can be an N-dimensional array - and/or a compound type (the control's type is >= - ``V4L2_CTRL_COMPOUND_TYPES``). Valid if - ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control. + * - __u32 + - ``id`` + - + - Identifies the control, set by the application. + * - __u32 + - ``size`` + - + - The total size in bytes of the payload of this control. This is + normally 0, but for pointer controls this should be set to the + size of the memory containing the payload, or that will receive + the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is + less than is required to store the payload result, then it is set + to a value large enough to store the payload result and ``ENOSPC`` is + returned. + + .. note:: + + For string controls, this ``size`` field should + not be confused with the length of the string. This field refers + to the size of the memory that contains the string. The actual + *length* of the string may well be much smaller. + * - __u32 + - ``reserved2``\ [1] + - + - Reserved for future extensions. Drivers and applications must set + the array to zero. + * - union + - (anonymous) + * - + - __s32 + - ``value`` + - New value or current value. Valid if this control is not of type + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is + not set. + * - + - __s64 + - ``value64`` + - New value or current value. Valid if this control is of type + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is + not set. + * - + - char * + - ``string`` + - A pointer to a string. Valid if this control is of type + ``V4L2_CTRL_TYPE_STRING``. + * - + - __u8 * + - ``p_u8`` + - A pointer to a matrix control of unsigned 8-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U8``. + * - + - __u16 * + - ``p_u16`` + - A pointer to a matrix control of unsigned 16-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U16``. + * - + - __u32 * + - ``p_u32`` + - A pointer to a matrix control of unsigned 32-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_U32``. + * - + - void * + - ``ptr`` + - A pointer to a compound type which can be an N-dimensional array + and/or a compound type (the control's type is >= + ``V4L2_CTRL_COMPOUND_TYPES``). Valid if + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control. .. tabularcolumns:: |p{4.0cm}|p{2.0cm}|p{2.0cm}|p{8.5cm}| @@ -245,130 +191,96 @@ still cause this situation. :stub-columns: 0 :widths: 1 1 2 1 - - - .. row 1 - - - union - - - (anonymous) - - - .. row 2 - - - - - __u32 - - - ``ctrl_class`` - - - The control class to which all controls belong, see - :ref:`ctrl-class`. Drivers that use a kernel framework for - handling controls will also accept a value of 0 here, meaning that - the controls can belong to any control class. Whether drivers - support this can be tested by setting ``ctrl_class`` to 0 and - calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that - succeeds, then the driver supports this feature. - - - .. row 3 - - - - - __u32 - - - ``which`` - - - Which value of the control to get/set/try. - ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default - value of the control. - - .. note:: - - You can only get the default value of the control, - you cannot set or try it. - - For backwards compatibility you can also use a control class here - (see :ref:`ctrl-class`). In that case all controls have to - belong to that control class. This usage is deprecated, instead - just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old - drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and - that require a control class here. You can test for such drivers - by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling - VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the - driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. - - - .. row 4 - - - __u32 - - - ``count`` - - - The number of controls in the controls array. May also be zero. - - - .. row 5 - - - __u32 - - - ``error_idx`` - - - Set by the driver in case of an error. If the error is associated - with a particular control, then ``error_idx`` is set to the index - of that control. If the error is not related to a specific - control, or the validation step failed (see below), then - ``error_idx`` is set to ``count``. The value is undefined if the - ioctl returned 0 (success). - - Before controls are read from/written to hardware a validation - step takes place: this checks if all controls in the list are - valid controls, if no attempt is made to write to a read-only - control or read from a write-only control, and any other up-front - checks that can be done without accessing the hardware. The exact - validations done during this step are driver dependent since some - checks might require hardware access for some devices, thus making - it impossible to do those checks up-front. However, drivers should - make a best-effort to do as many up-front checks as possible. - - This check is done to avoid leaving the hardware in an - inconsistent state due to easy-to-avoid problems. But it leads to - another problem: the application needs to know whether an error - came from the validation step (meaning that the hardware was not - touched) or from an error during the actual reading from/writing - to hardware. - - The, in hindsight quite poor, solution for that is to set - ``error_idx`` to ``count`` if the validation failed. This has the - unfortunate side-effect that it is not possible to see which - control failed the validation. If the validation was successful - and the error happened while accessing the hardware, then - ``error_idx`` is less than ``count`` and only the controls up to - ``error_idx-1`` were read or written correctly, and the state of - the remaining controls is undefined. - - Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is - also no need to handle the validation step in this special way, so - ``error_idx`` will just be set to the control that failed the - validation step instead of to ``count``. This means that if - :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``, - then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the - actual control that failed the validation step. Unfortunately, - there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. - - - .. row 6 - - - __u32 - - - ``reserved``\ [2] - - - Reserved for future extensions. - - Drivers and applications must set the array to zero. - - - .. row 7 - - - struct :c:type:`v4l2_ext_control` * - - - ``controls`` - - - Pointer to an array of ``count`` v4l2_ext_control structures. - - Ignored if ``count`` equals zero. + * - union + - (anonymous) + * - + - __u32 + - ``ctrl_class`` + - The control class to which all controls belong, see + :ref:`ctrl-class`. Drivers that use a kernel framework for + handling controls will also accept a value of 0 here, meaning that + the controls can belong to any control class. Whether drivers + support this can be tested by setting ``ctrl_class`` to 0 and + calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that + succeeds, then the driver supports this feature. + * - + - __u32 + - ``which`` + - Which value of the control to get/set/try. + ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the + control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + value of the control. + + .. note:: + + You can only get the default value of the control, + you cannot set or try it. + + For backwards compatibility you can also use a control class here + (see :ref:`ctrl-class`). In that case all controls have to + belong to that control class. This usage is deprecated, instead + just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old + drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and + that require a control class here. You can test for such drivers + by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the + driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + * - __u32 + - ``count`` + - The number of controls in the controls array. May also be zero. + * - __u32 + - ``error_idx`` + - Set by the driver in case of an error. If the error is associated + with a particular control, then ``error_idx`` is set to the index + of that control. If the error is not related to a specific + control, or the validation step failed (see below), then + ``error_idx`` is set to ``count``. The value is undefined if the + ioctl returned 0 (success). + + Before controls are read from/written to hardware a validation + step takes place: this checks if all controls in the list are + valid controls, if no attempt is made to write to a read-only + control or read from a write-only control, and any other up-front + checks that can be done without accessing the hardware. The exact + validations done during this step are driver dependent since some + checks might require hardware access for some devices, thus making + it impossible to do those checks up-front. However, drivers should + make a best-effort to do as many up-front checks as possible. + + This check is done to avoid leaving the hardware in an + inconsistent state due to easy-to-avoid problems. But it leads to + another problem: the application needs to know whether an error + came from the validation step (meaning that the hardware was not + touched) or from an error during the actual reading from/writing + to hardware. + + The, in hindsight quite poor, solution for that is to set + ``error_idx`` to ``count`` if the validation failed. This has the + unfortunate side-effect that it is not possible to see which + control failed the validation. If the validation was successful + and the error happened while accessing the hardware, then + ``error_idx`` is less than ``count`` and only the controls up to + ``error_idx-1`` were read or written correctly, and the state of + the remaining controls is undefined. + + Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is + also no need to handle the validation step in this special way, so + ``error_idx`` will just be set to the control that failed the + validation step instead of to ``count``. This means that if + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``, + then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the + actual control that failed the validation step. Unfortunately, + there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. + * - __u32 + - ``reserved``\ [2] + - Reserved for future extensions. + + Drivers and applications must set the array to zero. + * - struct :c:type:`v4l2_ext_control` * + - ``controls`` + - Pointer to an array of ``count`` v4l2_ext_control structures. + + Ignored if ``count`` equals zero. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| @@ -380,99 +292,49 @@ still cause this situation. :stub-columns: 0 :widths: 3 1 4 - - - .. row 1 - - - ``V4L2_CTRL_CLASS_USER`` - - - 0x980000 - - - The class containing user controls. These controls are described - in :ref:`control`. All controls that can be set using the - :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and - :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this - class. - - - .. row 2 - - - ``V4L2_CTRL_CLASS_MPEG`` - - - 0x990000 - - - The class containing MPEG compression controls. These controls are - described in :ref:`mpeg-controls`. - - - .. row 3 - - - ``V4L2_CTRL_CLASS_CAMERA`` - - - 0x9a0000 - - - The class containing camera controls. These controls are described - in :ref:`camera-controls`. - - - .. row 4 - - - ``V4L2_CTRL_CLASS_FM_TX`` - - - 0x9b0000 - - - The class containing FM Transmitter (FM TX) controls. These - controls are described in :ref:`fm-tx-controls`. - - - .. row 5 - - - ``V4L2_CTRL_CLASS_FLASH`` - - - 0x9c0000 - - - The class containing flash device controls. These controls are - described in :ref:`flash-controls`. - - - .. row 6 - - - ``V4L2_CTRL_CLASS_JPEG`` - - - 0x9d0000 - - - The class containing JPEG compression controls. These controls are - described in :ref:`jpeg-controls`. - - - .. row 7 - - - ``V4L2_CTRL_CLASS_IMAGE_SOURCE`` - - - 0x9e0000 - - - The class containing image source controls. These controls are - described in :ref:`image-source-controls`. - - - .. row 8 - - - ``V4L2_CTRL_CLASS_IMAGE_PROC`` - - - 0x9f0000 - - - The class containing image processing controls. These controls are - described in :ref:`image-process-controls`. - - - .. row 9 - - - ``V4L2_CTRL_CLASS_FM_RX`` - - - 0xa10000 - - - The class containing FM Receiver (FM RX) controls. These controls - are described in :ref:`fm-rx-controls`. - - - .. row 10 - - - ``V4L2_CTRL_CLASS_RF_TUNER`` - - - 0xa20000 - - - The class containing RF tuner controls. These controls are - described in :ref:`rf-tuner-controls`. + * - ``V4L2_CTRL_CLASS_USER`` + - 0x980000 + - The class containing user controls. These controls are described + in :ref:`control`. All controls that can be set using the + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and + :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this + class. + * - ``V4L2_CTRL_CLASS_MPEG`` + - 0x990000 + - The class containing MPEG compression controls. These controls are + described in :ref:`mpeg-controls`. + * - ``V4L2_CTRL_CLASS_CAMERA`` + - 0x9a0000 + - The class containing camera controls. These controls are described + in :ref:`camera-controls`. + * - ``V4L2_CTRL_CLASS_FM_TX`` + - 0x9b0000 + - The class containing FM Transmitter (FM TX) controls. These + controls are described in :ref:`fm-tx-controls`. + * - ``V4L2_CTRL_CLASS_FLASH`` + - 0x9c0000 + - The class containing flash device controls. These controls are + described in :ref:`flash-controls`. + * - ``V4L2_CTRL_CLASS_JPEG`` + - 0x9d0000 + - The class containing JPEG compression controls. These controls are + described in :ref:`jpeg-controls`. + * - ``V4L2_CTRL_CLASS_IMAGE_SOURCE`` + - 0x9e0000 + - The class containing image source controls. These controls are + described in :ref:`image-source-controls`. + * - ``V4L2_CTRL_CLASS_IMAGE_PROC`` + - 0x9f0000 + - The class containing image processing controls. These controls are + described in :ref:`image-process-controls`. + * - ``V4L2_CTRL_CLASS_FM_RX`` + - 0xa10000 + - The class containing FM Receiver (FM RX) controls. These controls + are described in :ref:`fm-rx-controls`. + * - ``V4L2_CTRL_CLASS_RF_TUNER`` + - 0xa20000 + - The class containing RF tuner controls. These controls are + described in :ref:`rf-tuner-controls`. Return Value |