[PATCH] vidioc-enumin/output.rst: improve documentation

[PATCH] vidioc-enumin/output.rst: improve documentation

[Hans Verkuil]

The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
hopelessly out of date. Fix this, and also fix a few style issues in these
documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
(only used by the zoran driver).

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
Question: should we perhaps add _TYPE_VIDEO aliases?
---
diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
index 17aaaf939757..266e48ab237f 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -33,7 +33,7 @@ Description

 To query the attributes of a video input applications initialize the
 ``index`` field of struct :c:type:`v4l2_input` and call the
-:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
+:ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
 fill the rest of the structure or return an ``EINVAL`` error code when the
 index is out of bounds. To enumerate all inputs applications shall begin
 at index zero, incrementing by one until the driver returns ``EINVAL``.
@@ -117,8 +117,9 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
       - This input uses a tuner (RF demodulator).
     * - ``V4L2_INPUT_TYPE_CAMERA``
       - 2
-      - Analog baseband input, for example CVBS / Composite Video,
-	S-Video, RGB.
+      - Any non-tuner video input, for example Composite Video,
+	S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
+	today we would have called it ``_TYPE_VIDEO``.
     * - ``V4L2_INPUT_TYPE_TOUCH``
       - 3
       - This input is a touch device for capturing raw touch data.
@@ -209,11 +210,11 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
     * - ``V4L2_IN_CAP_DV_TIMINGS``
       - 0x00000002
       - This input supports setting video timings by using
-	VIDIOC_S_DV_TIMINGS.
+	``VIDIOC_S_DV_TIMINGS``.
     * - ``V4L2_IN_CAP_STD``
       - 0x00000004
       - This input supports setting the TV standard by using
-	VIDIOC_S_STD.
+	``VIDIOC_S_STD``.
     * - ``V4L2_IN_CAP_NATIVE_SIZE``
       - 0x00000008
       - This input supports setting the native size using the
diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
index d7dd2742475a..93a2cf3b310c 100644
--- a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
@@ -33,11 +33,11 @@ Description

 To query the attributes of a video outputs applications initialize the
 ``index`` field of struct :c:type:`v4l2_output` and call
-the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
+the :ref:`VIDIOC_ENUMOUTPUT` with a pointer to this structure.
 Drivers fill the rest of the structure or return an ``EINVAL`` error code
 when the index is out of bounds. To enumerate all outputs applications
 shall begin at index zero, incrementing by one until the driver returns
-EINVAL.
+``EINVAL``.


 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -112,11 +112,12 @@ EINVAL.
       - This output is an analog TV modulator.
     * - ``V4L2_OUTPUT_TYPE_ANALOG``
       - 2
-      - Analog baseband output, for example Composite / CVBS, S-Video,
-	RGB.
+      - Any non-modulator video output, for example Composite Video,
+	S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical,
+	today we would have called it ``_TYPE_VIDEO``.
     * - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
       - 3
-      - [?]
+      - The video output will be copied to a :ref:`video overlay <overlay>`.



@@ -132,11 +133,11 @@ EINVAL.
     * - ``V4L2_OUT_CAP_DV_TIMINGS``
       - 0x00000002
       - This output supports setting video timings by using
-	VIDIOC_S_DV_TIMINGS.
+	``VIDIOC_S_DV_TIMINGS``.
     * - ``V4L2_OUT_CAP_STD``
       - 0x00000004
       - This output supports setting the TV standard by using
-	VIDIOC_S_STD.
+	``VIDIOC_S_STD``.
     * - ``V4L2_OUT_CAP_NATIVE_SIZE``
       - 0x00000008
       - This output supports setting the native size using the

Re: [PATCH] vidioc-enumin/output.rst: improve documentation

[Mauro Carvalho Chehab]

Em Fri, 31 Mar 2017 10:58:39 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
> hopelessly out of date. Fix this, and also fix a few style issues in these
> documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
> (only used by the zoran driver).
> 
> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> ---

Patch looks OK to me, but see below.

> Question: should we perhaps add _TYPE_VIDEO aliases?

IMHO, let's rename it to _TYPE_VIDEO (or STREAM, or V_STREAM), and make 
_TYPE_CAMERA an alias, e. g.:

#define V4L2_INPUT_TYPE_VIDEO 2

#define V4L2_INPUT_TYPE_CAMERA V4L2_INPUT_TYPE_VIDEO

This way, we'll let clearer what's currently preferred. We should also
change it at the documentation, mentioning that V4L2_INPUT_TYPE_CAMERA
is an alias, due to historical reasons.

Thanks,
Mauro

Re: [PATCH] vidioc-enumin/output.rst: improve documentation

[Hans Verkuil]

On 31/03/17 12:05, Mauro Carvalho Chehab wrote:
> Em Fri, 31 Mar 2017 10:58:39 +0200
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
>> hopelessly out of date. Fix this, and also fix a few style issues in these
>> documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
>> (only used by the zoran driver).
>>
>> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
>> ---
> 
> Patch looks OK to me, but see below.
> 
>> Question: should we perhaps add _TYPE_VIDEO aliases?
> 
> IMHO, let's rename it to _TYPE_VIDEO (or STREAM, or V_STREAM), and make 
> _TYPE_CAMERA an alias, e. g.:
> 
> #define V4L2_INPUT_TYPE_VIDEO 2
> 
> #define V4L2_INPUT_TYPE_CAMERA V4L2_INPUT_TYPE_VIDEO
> 
> This way, we'll let clearer what's currently preferred. We should also
> change it at the documentation, mentioning that V4L2_INPUT_TYPE_CAMERA
> is an alias, due to historical reasons.

Does this really make sense to do this now? Everyone is used to the old defines,
wouldn't changing this just increase confusion?

Sorry, playing devil's advocate here.

I'm a bit hesitant of doing this. We've done this in the past for APIs that
were very new or rarely used, but this is everywhere.

I feel fixing the spec is sufficient.

If more people think that adding this aliases is a good idea, then I can do that.

Regards,

	Hans