[v3,3/8] media: Documentation: v4l: Add TOF class controls
Commit Message
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
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
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
@@ -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
new file mode 100644
@@ -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.
@@ -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