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

[Volodymyr Kharuk <vkh@melexis.com>]

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

-- 
--
Volodymyr Kharuk
Embedded Software Engineer
Melexis-Ukraine
Mykhaila Kotel'nykova St, 4, Kyiv
Mobile phone: +38 050 346 5527
www.melexis.com
---
The contents of this e-mail are CONFIDENTIAL AND PROPRIETARY. Please read
our disclaimer at http://www.melexis.com/mailpolicy