diff mbox series

[v3,3/8] media: Documentation: v4l: Add TOF class controls

Message ID 01cfeb602d52456bed08c89da356474474361e73.1669381013.git.vkh@melexis.com (mailing list archive)
State New, archived
Headers show
Series media: i2c: mlx7502x ToF camera support | expand

Commit Message

Volodymyr Kharuk Nov. 25, 2022, 1:34 p.m. UTC 
Add description about V4L2_CID_TOF_PHASE_SEQ, V4L2_CID_TOF_FMOD
and V4L2_CID_TOF_TINT.
Also updated MAINTAINERS with new ext-ctrls-tof file.

Signed-off-by: Volodymyr Kharuk <vkh@melexis.com>
---
 .../userspace-api/media/v4l/common.rst        |  1 +
 .../userspace-api/media/v4l/ext-ctrls-tof.rst | 35 +++++++++++++++++++
 MAINTAINERS                                   |  7 ++++
 3 files changed, 43 insertions(+)
 create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst

Comments

Hans Verkuil Nov. 25, 2022, 2:28 p.m. UTC | #1 
On 25/11/2022 14:34, Volodymyr Kharuk wrote:
> Add description about V4L2_CID_TOF_PHASE_SEQ, V4L2_CID_TOF_FMOD
> and V4L2_CID_TOF_TINT.
> Also updated MAINTAINERS with new ext-ctrls-tof file.
> 
> Signed-off-by: Volodymyr Kharuk <vkh@melexis.com>
> ---
>  .../userspace-api/media/v4l/common.rst        |  1 +
>  .../userspace-api/media/v4l/ext-ctrls-tof.rst | 35 +++++++++++++++++++
>  MAINTAINERS                                   |  7 ++++
>  3 files changed, 43 insertions(+)
>  create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> 
> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst
> index ea0435182e44..1ea79e453066 100644
> --- a/Documentation/userspace-api/media/v4l/common.rst
> +++ b/Documentation/userspace-api/media/v4l/common.rst
> @@ -52,6 +52,7 @@ applicable to all devices.
>      ext-ctrls-fm-rx
>      ext-ctrls-detect
>      ext-ctrls-colorimetry
> +    ext-ctrls-tof
>      fourcc
>      format
>      planar-apis
> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> new file mode 100644
> index 000000000000..8902cc7cd47b
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> @@ -0,0 +1,35 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _tof-controls:
> +
> +***************************************
> +Time of Flight Camera Control Reference
> +***************************************
> +
> +The Time of Flight class includes controls for digital features
> +of TOF camera.

You might want to extend this description a bit and give more info
about how they work. Perhaps a link to wikipedia or something
might help too.

> +
> +.. _tof-control-id:
> +
> +Time of Flight Camera Control IDs
> +=================================
> +
> +``V4L2_CID_TOF_CLASS (class)``
> +    The TOF class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for
> +    this control will return a description of this control class.
> +
> +``V4L2_CID_TOF_PHASE_SEQ (dynamic array u16)``
> +    Change the shift between illumination and sampling for each phase
> +    in degrees. A distance/confidence picture is obtained by merging
> +    3..8 captures of the same scene using different phase shifts(some

Space before (

> +    TOF sensors use different frequency modulation).

Either: use -> use a
Or:     modulation -> modulations

It's not clear right now whether "frequency modulation" is meant to be singular
or plural.

> +
> +    The maximum array size is driver specific.
> +
> +``V4L2_CID_TOF_FMOD (dynamic array u8)``
> +    The control sets the modulation frequency(in Mhz) per each phase.

Space before (

per each phase -> for each phase

> +    The maximum array size is driver specific.

What does the maximum array size signify? The number of phases?
It's not clear from the spec (and I have to admit I know very little
about TOF sensors).

> +
> +``V4L2_CID_TOF_TINT (dynamic array u16)``
> +    The control sets the integration time(in us) per each phase.

Add space before (

per each phase -> for each phase

> +    The maximum array size is driver specific.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index aa1974054fce..a2bc2ce53056 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -13111,6 +13111,13 @@ S:	Supported
>  W:	http://www.melexis.com
>  F:	drivers/iio/temperature/mlx90632.c
>  
> +MELEXIS MLX7502X DRIVER
> +M:	Volodymyr Kharuk <vkh@melexis.com>
> +L:	linux-media@vger.kernel.org
> +S:	Supported
> +W:	http://www.melexis.com
> +F:	Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> +
>  MELFAS MIP4 TOUCHSCREEN DRIVER
>  M:	Sangwon Jee <jeesw@melfas.com>
>  S:	Supported

Regards,

	Hans
Volodymyr Kharuk Nov. 25, 2022, 4:01 p.m. UTC | #2 
Thanks for review.

On Fri, Nov 25, 2022 at 03:28:30PM +0100, Hans Verkuil wrote:
> On 25/11/2022 14:34, Volodymyr Kharuk wrote:
> > Add description about V4L2_CID_TOF_PHASE_SEQ, V4L2_CID_TOF_FMOD
> > and V4L2_CID_TOF_TINT.
> > Also updated MAINTAINERS with new ext-ctrls-tof file.
> > 
> > Signed-off-by: Volodymyr Kharuk <vkh@melexis.com>
> > ---
> >  .../userspace-api/media/v4l/common.rst        |  1 +
> >  .../userspace-api/media/v4l/ext-ctrls-tof.rst | 35 +++++++++++++++++++
> >  MAINTAINERS                                   |  7 ++++
> >  3 files changed, 43 insertions(+)
> >  create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> > 
> > diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst
> > index ea0435182e44..1ea79e453066 100644
> > --- a/Documentation/userspace-api/media/v4l/common.rst
> > +++ b/Documentation/userspace-api/media/v4l/common.rst
> > @@ -52,6 +52,7 @@ applicable to all devices.
> >      ext-ctrls-fm-rx
> >      ext-ctrls-detect
> >      ext-ctrls-colorimetry
> > +    ext-ctrls-tof
> >      fourcc
> >      format
> >      planar-apis
> > diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> > new file mode 100644
> > index 000000000000..8902cc7cd47b
> > --- /dev/null
> > +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> > @@ -0,0 +1,35 @@
> > +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> > +
> > +.. _tof-controls:
> > +
> > +***************************************
> > +Time of Flight Camera Control Reference
> > +***************************************
> > +
> > +The Time of Flight class includes controls for digital features
> > +of TOF camera.
> 
> You might want to extend this description a bit and give more info
> about how they work. Perhaps a link to wikipedia or something
> might help too.
I was not sure what to add here. Ok, I will update.
> 
> > +
> > +.. _tof-control-id:
> > +
> > +Time of Flight Camera Control IDs
> > +=================================
> > +
> > +``V4L2_CID_TOF_CLASS (class)``
> > +    The TOF class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for
> > +    this control will return a description of this control class.
> > +
> > +``V4L2_CID_TOF_PHASE_SEQ (dynamic array u16)``
> > +    Change the shift between illumination and sampling for each phase
> > +    in degrees. A distance/confidence picture is obtained by merging
> > +    3..8 captures of the same scene using different phase shifts(some
> 
> Space before (
> 
> > +    TOF sensors use different frequency modulation).
> 
> Either: use -> use a
> Or:     modulation -> modulations
> 
> It's not clear right now whether "frequency modulation" is meant to be singular
> or plural.
> 
> > +
> > +    The maximum array size is driver specific.
> > +
> > +``V4L2_CID_TOF_FMOD (dynamic array u8)``
> > +    The control sets the modulation frequency(in Mhz) per each phase.
> 
> Space before (
> 
> per each phase -> for each phase
> 
> > +    The maximum array size is driver specific.
> 
> What does the maximum array size signify? The number of phases?
> It's not clear from the spec (and I have to admit I know very little
> about TOF sensors).
yes, array size defines the number of phases.
But the maximum number of phases can be different and depend on the sensor.
I'll update the doc.
> 
> > +
> > +``V4L2_CID_TOF_TINT (dynamic array u16)``
> > +    The control sets the integration time(in us) per each phase.
> 
> Add space before (
> 
> per each phase -> for each phase
> 
> > +    The maximum array size is driver specific.
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index aa1974054fce..a2bc2ce53056 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -13111,6 +13111,13 @@ S:	Supported
> >  W:	http://www.melexis.com
> >  F:	drivers/iio/temperature/mlx90632.c
> >  
> > +MELEXIS MLX7502X DRIVER
> > +M:	Volodymyr Kharuk <vkh@melexis.com>
> > +L:	linux-media@vger.kernel.org
> > +S:	Supported
> > +W:	http://www.melexis.com
> > +F:	Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
> > +
> >  MELFAS MIP4 TOUCHSCREEN DRIVER
> >  M:	Sangwon Jee <jeesw@melfas.com>
> >  S:	Supported
> 
> Regards,
> 
> 	Hans
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst
index ea0435182e44..1ea79e453066 100644
--- a/Documentation/userspace-api/media/v4l/common.rst
+++ b/Documentation/userspace-api/media/v4l/common.rst
@@ -52,6 +52,7 @@  applicable to all devices.
     ext-ctrls-fm-rx
     ext-ctrls-detect
     ext-ctrls-colorimetry
+    ext-ctrls-tof
     fourcc
     format
     planar-apis
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
new file mode 100644
index 000000000000..8902cc7cd47b
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
@@ -0,0 +1,35 @@ 
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _tof-controls:
+
+***************************************
+Time of Flight Camera Control Reference
+***************************************
+
+The Time of Flight class includes controls for digital features
+of TOF camera.
+
+.. _tof-control-id:
+
+Time of Flight Camera Control IDs
+=================================
+
+``V4L2_CID_TOF_CLASS (class)``
+    The TOF class descriptor. Calling :ref:`VIDIOC_QUERYCTRL` for
+    this control will return a description of this control class.
+
+``V4L2_CID_TOF_PHASE_SEQ (dynamic array u16)``
+    Change the shift between illumination and sampling for each phase
+    in degrees. A distance/confidence picture is obtained by merging
+    3..8 captures of the same scene using different phase shifts(some
+    TOF sensors use different frequency modulation).
+
+    The maximum array size is driver specific.
+
+``V4L2_CID_TOF_FMOD (dynamic array u8)``
+    The control sets the modulation frequency(in Mhz) per each phase.
+    The maximum array size is driver specific.
+
+``V4L2_CID_TOF_TINT (dynamic array u16)``
+    The control sets the integration time(in us) per each phase.
+    The maximum array size is driver specific.
diff --git a/MAINTAINERS b/MAINTAINERS
index aa1974054fce..a2bc2ce53056 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13111,6 +13111,13 @@  S:	Supported
 W:	http://www.melexis.com
 F:	drivers/iio/temperature/mlx90632.c
 
+MELEXIS MLX7502X DRIVER
+M:	Volodymyr Kharuk <vkh@melexis.com>
+L:	linux-media@vger.kernel.org
+S:	Supported
+W:	http://www.melexis.com
+F:	Documentation/userspace-api/media/v4l/ext-ctrls-tof.rst
+
 MELFAS MIP4 TOUCHSCREEN DRIVER
 M:	Sangwon Jee <jeesw@melfas.com>
 S:	Supported