On 09/25/2018 12:14 PM, Sakari Ailus wrote:
> Document V4L2 control exponential bases, units and prefixes, as well as
> the control flag telling a control value is an exponent.
>
> Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
> ---
> Documentation/media/uapi/v4l/extended-controls.rst | 2 +
> Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 152 ++++++++++++++++++++-
> Documentation/media/videodev2.h.rst.exceptions | 22 +++
> 3 files changed, 175 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
> index 9f7312bf33651..8461fd92d1b9e 100644
> --- a/Documentation/media/uapi/v4l/extended-controls.rst
> +++ b/Documentation/media/uapi/v4l/extended-controls.rst
> @@ -3460,6 +3460,8 @@ Image Process Control IDs
> by selecting the desired horizontal and vertical blanking. The unit
> of this control is Hz.
>
> +.. _v4l2_cid_pixel_rate:
> +
> ``V4L2_CID_PIXEL_RATE (64-bit integer)``
> Pixel rate in the source pads of the subdev. This control is
> read-only and its unit is pixels / second.
> diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
> index ff2d131223b84..472378f5d7566 100644
> --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
> @@ -269,8 +269,22 @@ See also the examples in :ref:`control`.
> - ``dims[V4L2_CTRL_MAX_DIMS]``
> - The size of each dimension. The first ``nr_of_dims`` elements of
> this array must be non-zero, all remaining elements must be zero.
> + * - __u8
> + - ``base``
> + - The exponential base of the control value. Valid only if the
> + :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` control flag is
> + set. This is an enumeration.
> + * - __u8
> + - ``prefix``
> + - Prefix of the unit. This is an enumeration.
> + * - __u16
> + - ``unit``
> + - Unit of the value. Together with the ``prefix`` as well as the ``base``
> + field (if :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` is set),
> + defines the relation between the control value and the property of the
> + hardware being controlled. This is an enumeration.
> * - __u32
> - - ``reserved``\ [32]
> + - ``reserved``\ [31]
> - Reserved for future extensions. Applications and drivers must set
> the array to zero.
>
> @@ -523,6 +537,142 @@ See also the examples in :ref:`control`.
> streaming is in progress since most drivers do not support changing
> the format in that case.
>
> + * .. _FLAG_EXPONENTIAL:
> +
> + - ``V4L2_CTRL_FLAG_EXPONENTIAL``
> + - 0x00000800
> +
> + - The value of the control has an exponential relation to the feature
> + being controled instead of a linear relation. In other words, the value
controled -> controlled
> + of the control is an exponent of the base specified in the
> + base field in &struct v4l2_query_ext_ctrl.
It would be nice if you can add some math here. See colorspaces-details.rst
for examples of that.
> +
> +
> +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
> +
> +.. _control-bases:
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: Control Exponential Bases
> + :header-rows: 1
> + :stub-columns: 0
> + :widths: 3 1 4
> +
> + * - Base Name
> + - Value
> + - Description
> +
> + * - ``V4L2_CTRL_BASE_UNDEFINED``
> + - 0
> + - The control exponential base is not defined.
> +
> + * - ``V4L2_CTRL_BASE_LINEAR``
> + - 1
> + - The control is linear.
> +
> + * - ``V4L2_CTRL_BASE_2``
> + - 2
> + - The base of the control is 2.
> +
> + * - ``V4L2_CTRL_BASE_10``
> + - 10
> + - The base of the control is 10.
> +
> +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
> +
> +.. _control-prefixes:
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: Control Prefixes
> + :header-rows: 1
> + :stub-columns: 0
> + :widths: 3 1 4
> +
> + * - Prefix Name
> + - Value
> + - Description
> +
> + * - ``V4L2_CTRL_PREFIX_NANO``
> + - -9
> + - Nano
> +
> + * - ``V4L2_CTRL_PREFIX_MICRO``
> + - -6
> + - Micro
> +
> + * - ``V4L2_CTRL_PREFIX_MILLI``
> + - -3
> + - Milli
> +
> + * - ``V4L2_CTRL_PREFIX_1``
> + - 0
> + - \-
> +
> + * - ``V4L2_CTRL_PREFIX_KILO``
> + - 3
> + - Kilo
> +
> + * - ``V4L2_CTRL_PREFIX_MEGA``
> + - 6
> + - Mega
> +
> + * - ``V4L2_CTRL_PREFIX_GIGA``
> + - 9
> + - Giga
> +
> +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
> +
> +.. _control-units:
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: Control Units
> + :header-rows: 1
> + :stub-columns: 0
> + :widths: 3 1 4
> +
> + * - Unit Name
> + - Value
> + - Description
> +
> + * - ``V4L2_CTRL_UNIT_UNDEFINED``
> + - 0
> + - The unit of the control is not defined.
> +
> + * - ``V4L2_CTRL_UNIT_NONE``
> + - 1
> + - The control has no unit.
> +
> + * - ``V4L2_CTRL_UNIT_SECOND``
> + - 2
> + - Second
> +
> + * - ``V4L2_CTRL_UNIT_AMPERE``
> + - 3
> + - Ampère
> +
> + * - ``V4L2_CTRL_UNIT_LINE``
> + - 4
> + - A line of pixels in sensor's pixel matrix. This is a unit of time
> + commonly used by camera sensors in e.g. exposure control, i.e. the time
> + it takes for a sensor to read a line of pixels from the sensor's pixel
> + matrix. See :ref:`V4L2_CID_PIXEL_RATE <V4L2_CID_PIXEL_RATE>`.
That's a bad name. I'd call it a PIXEL_LINE or FRAME_LINE or something like that.
When I first saw the define I thought it applied to a gpio line or a bus line or
something like that.
> +
> + * - ``V4L2_CTRL_UNIT_PIXEL``
> + - 5
> + - A pixel in sensor's pixel matrix. This is a unit of time commonly used
> + by camera sensors in e.g. exposure control, i.e. the time it takes for
> + a sensor to read a pixel from the sensor's pixel matrix.
> +
> + * - ``V4L2_CTRL_UNIT_PIXEL``
Duplicate name as above. You meant PIXELS_PER_SECOND.
I use this technique these days to avoid having to add defines to the videodev2.h.rst.exceptions
file:
* .. _`V4L2-CTRL-UNIT-PIXEL`:
- ``V4L2_CTRL_UNIT_PIXEL``
- 5
- A pixel in sensor's pixel matrix. This is a unit of time commonly used
by camera sensors in e.g. exposure control, i.e. the time it takes for
a sensor to read a pixel from the sensor's pixel matrix.
> + - 6
> + - Pixels per second
> +
> + * - ``V4L2_CTRL_UNIT_HZ
> + - 7
> + - Hertz
>
> Return Value
> ============
> diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions
> index 63fa131729c09..8183a4f3554b0 100644
> --- a/Documentation/media/videodev2.h.rst.exceptions
> +++ b/Documentation/media/videodev2.h.rst.exceptions
> @@ -343,11 +343,33 @@ replace define V4L2_CTRL_FLAG_VOLATILE control-flags
> replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags
> replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags
> replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags
> +replace define V4L2_CTRL_FLAG_EXPONENTIAL control-flags
>
> replace define V4L2_CTRL_FLAG_NEXT_CTRL control
> replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control
> replace define V4L2_CID_PRIVATE_BASE control
>
> +# V4L2 control bases, prefixes and units
> +replace define V4L2_CTRL_BASE_UNDEFINED control-bases
> +replace define V4L2_CTRL_BASE_LINEAR control-bases
> +replace define V4L2_CTRL_BASE_2 control-bases
> +replace define V4L2_CTRL_BASE_10 control-bases
> +
> +replace define V4L2_CTRL_PREFIX_NANO control-prefixes
> +replace define V4L2_CTRL_PREFIX_MICRO control-prefixes
> +replace define V4L2_CTRL_PREFIX_MILLI control-prefixes
> +replace define V4L2_CTRL_PREFIX_1 control-prefixes
> +replace define V4L2_CTRL_PREFIX_KILO control-prefixes
> +replace define V4L2_CTRL_PREFIX_MEGA control-prefixes
> +replace define V4L2_CTRL_PREFIX_GIGA control-prefixes
> +
> +replace define V4L2_CTRL_UNIT_UNDEFINED control-units
> +replace define V4L2_CTRL_UNIT_NONE control-units
> +replace define V4L2_CTRL_UNIT_SECOND control-units
> +replace define V4L2_CTRL_UNIT_AMPERE control-units
> +replace define V4L2_CTRL_UNIT_LINE control-units
> +replace define V4L2_CTRL_UNIT_PIXEL control-units
You need to add PIXELS_PER_SECOND here as well.
> +
> # V4L2 tuner
>
> replace define V4L2_TUNER_CAP_LOW tuner-capability
>
Regards,
Hans
