Re: [PATCHv3 2/5] vidioc-g-parm.rst: update the VIDIOC_G/S_PARM documentation

[Michael Tretter <m.tretter@pengutronix.de>]

On Tue, May 26, 2020 at 12:09:29PM +0200, Hans Verkuil wrote:
> This documentation is very outdated. In particular, it is
> not obvious at all that this is used to change the framerate of
> sensors.
> 
> Fix it, and include references to the stateful encoder API where
> this works slightly different.
> 
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> Acked-by: Tomasz Figa <tfiga@chromium.org>
> ---
>  .../userspace-api/media/v4l/vidioc-g-parm.rst | 51 ++++++++++++-------
>  1 file changed, 32 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
> index 42e9f6ee7a59..af3c5863bb87 100644
> --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst
[snip]
> @@ -113,14 +115,21 @@ union holding separate parameters for input and output devices.
>      * - struct :c:type:`v4l2_fract`
>        - ``timeperframe``
>        - This is the desired period between successive frames captured by
> -	the driver, in seconds. The field is intended to skip frames on
> -	the driver side, saving I/O bandwidth.
> +	the driver, in seconds.
> +    * - :cspan:`2`
> +
> +	This will configure the speed at which the video source (e.g. a sensor)
> +	generates video frames. If the speed is fixed, then the driver may
> +	choose to skip or repeat frames in order to achieve the requested
> +	frame rate.
> +
> +        For stateful encoders (see :ref:`encoder`) this represents the

Spaces instead of tab.

> +	frame interval that is typically embedded in the encoded video stream.
>  
>  	Applications store here the desired frame period, drivers return
> -	the actual frame period, which must be greater or equal to the
> -	nominal frame period determined by the current video standard
> -	(struct :c:type:`v4l2_standard` ``frameperiod``
> -	field). Changing the video standard (also implicitly by switching
> +	the actual frame period.
> +
> +	Changing the video standard (also implicitly by switching
>  	the video input) may reset this parameter to the nominal frame
>  	period. To reset manually applications can just set this field to
>  	zero.
> @@ -173,11 +182,15 @@ union holding separate parameters for input and output devices.
>  	:ref:`write() <func-write>` mode (in streaming mode timestamps
>  	can be used to throttle the output), saving I/O bandwidth.
>  
> +        For stateful encoders (see :ref:`encoder`) this represents the

Spaces instead of tab.

Michael

> +	frame interval that is typically embedded in the encoded video stream
> +	and it provides a hint to the encoder of the speed at which raw
> +	frames are queued up to the encoder.
> +
>  	Applications store here the desired frame period, drivers return
> -	the actual frame period, which must be greater or equal to the
> -	nominal frame period determined by the current video standard
> -	(struct :c:type:`v4l2_standard` ``frameperiod``
> -	field). Changing the video standard (also implicitly by switching
> +	the actual frame period.
> +
> +	Changing the video standard (also implicitly by switching
>  	the video output) may reset this parameter to the nominal frame
>  	period. To reset manually applications can just set this field to
>  	zero.
> @@ -216,8 +229,8 @@ union holding separate parameters for input and output devices.
>  
>      * - ``V4L2_CAP_TIMEPERFRAME``
>        - 0x1000
> -      - The frame skipping/repeating controlled by the ``timeperframe``
> -	field is supported.
> +      - The frame period can be modified by setting the ``timeperframe``
> +	field.
>  
>  
>  
> -- 
> 2.25.1
> 
>