[PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Sakari Ailus]

The media bus codes to be used on serial busses are documented but there
was no reference from CSI-2 documentation. Add that now.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 Documentation/driver-api/media/csi2.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
index da8b356389f0..1653a51d2a6e 100644
--- a/Documentation/driver-api/media/csi2.rst
+++ b/Documentation/driver-api/media/csi2.rst
@@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
 
 .. _`MIPI alliance`: http://www.mipi.org/
 
+Media bus formats
+-----------------
+
+Always use the media bus pixel code that describes a parallel format that
+transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more
+information.
+
 Transmitter drivers
 -------------------
 
-- 
2.20.1

Re: [PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Hans Verkuil]

On 19/05/2020 10:50, Sakari Ailus wrote:
> The media bus codes to be used on serial busses are documented but there
> was no reference from CSI-2 documentation. Add that now.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  Documentation/driver-api/media/csi2.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
> index da8b356389f0..1653a51d2a6e 100644
> --- a/Documentation/driver-api/media/csi2.rst
> +++ b/Documentation/driver-api/media/csi2.rst
> @@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
>  
>  .. _`MIPI alliance`: http://www.mipi.org/
>  
> +Media bus formats
> +-----------------
> +
> +Always use the media bus pixel code that describes a parallel format that
> +transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more

How about: "transfers the pixel data as a single sample in one clock cycle"

Possibly with an example: "So use e.g. MEDIA_BUS_FMT_SBGGR10_1X10 instead of
MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE."

Regards,

	Hans

> +information.
> +
>  Transmitter drivers
>  -------------------
>  
> 

Re: [PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Sakari Ailus]

Hi Hans,

On Tue, May 19, 2020 at 11:05:31AM +0200, Hans Verkuil wrote:
> On 19/05/2020 10:50, Sakari Ailus wrote:
> > The media bus codes to be used on serial busses are documented but there
> > was no reference from CSI-2 documentation. Add that now.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > ---
> >  Documentation/driver-api/media/csi2.rst | 7 +++++++
> >  1 file changed, 7 insertions(+)
> > 
> > diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
> > index da8b356389f0..1653a51d2a6e 100644
> > --- a/Documentation/driver-api/media/csi2.rst
> > +++ b/Documentation/driver-api/media/csi2.rst
> > @@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
> >  
> >  .. _`MIPI alliance`: http://www.mipi.org/
> >  
> > +Media bus formats
> > +-----------------
> > +
> > +Always use the media bus pixel code that describes a parallel format that
> > +transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more
> 
> How about: "transfers the pixel data as a single sample in one clock cycle"

The text is from mbus format documentation. Note that this might not be
pixel data; it may be metadata as well.

> 
> Possibly with an example: "So use e.g. MEDIA_BUS_FMT_SBGGR10_1X10 instead of
> MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE."

There's an example in mbus format documentation. I'm fine adding one here,
too, but the purpose of this bit is to mainly refer to mbus format
documentation. Mbus format documentation uses MEDIA_BUS_FMT_BGR888_1X24 and
MEDIA_BUS_FMT_BGR888_3X8 as the example.

-- 
Kind regards,

Sakari Ailus

Re: [PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Hans Verkuil]

On 19/05/2020 11:17, Sakari Ailus wrote:
> Hi Hans,
> 
> On Tue, May 19, 2020 at 11:05:31AM +0200, Hans Verkuil wrote:
>> On 19/05/2020 10:50, Sakari Ailus wrote:
>>> The media bus codes to be used on serial busses are documented but there
>>> was no reference from CSI-2 documentation. Add that now.
>>>
>>> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>>> ---
>>>  Documentation/driver-api/media/csi2.rst | 7 +++++++
>>>  1 file changed, 7 insertions(+)
>>>
>>> diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
>>> index da8b356389f0..1653a51d2a6e 100644
>>> --- a/Documentation/driver-api/media/csi2.rst
>>> +++ b/Documentation/driver-api/media/csi2.rst
>>> @@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
>>>  
>>>  .. _`MIPI alliance`: http://www.mipi.org/
>>>  
>>> +Media bus formats
>>> +-----------------
>>> +
>>> +Always use the media bus pixel code that describes a parallel format that
>>> +transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more
>>
>> How about: "transfers the pixel data as a single sample in one clock cycle"
> 
> The text is from mbus format documentation. Note that this might not be
> pixel data; it may be metadata as well.

My problem with 'a sample' is that all parallel media bus formats transfer 'a sample'
in a single clock cycle. It is not clearly defined what 'a sample' is.

Either the text needs to be improved, or an example should be added here as well
since an example clarifies what is meant.

> 
>>
>> Possibly with an example: "So use e.g. MEDIA_BUS_FMT_SBGGR10_1X10 instead of
>> MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE."
> 
> There's an example in mbus format documentation. I'm fine adding one here,
> too, but the purpose of this bit is to mainly refer to mbus format
> documentation. Mbus format documentation uses MEDIA_BUS_FMT_BGR888_1X24 and
> MEDIA_BUS_FMT_BGR888_3X8 as the example.
> 

Ah, I see. But then the reference to v4l2-mbus-format is confusing, I'd
change that to v4l2-mbus-pixelcode. That's where the example is.

Regards,

	Hans

Re: [PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Sakari Ailus]

On Tue, May 19, 2020 at 11:28:48AM +0200, Hans Verkuil wrote:
> On 19/05/2020 11:17, Sakari Ailus wrote:
> > Hi Hans,
> > 
> > On Tue, May 19, 2020 at 11:05:31AM +0200, Hans Verkuil wrote:
> >> On 19/05/2020 10:50, Sakari Ailus wrote:
> >>> The media bus codes to be used on serial busses are documented but there
> >>> was no reference from CSI-2 documentation. Add that now.
> >>>
> >>> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> >>> ---
> >>>  Documentation/driver-api/media/csi2.rst | 7 +++++++
> >>>  1 file changed, 7 insertions(+)
> >>>
> >>> diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
> >>> index da8b356389f0..1653a51d2a6e 100644
> >>> --- a/Documentation/driver-api/media/csi2.rst
> >>> +++ b/Documentation/driver-api/media/csi2.rst
> >>> @@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
> >>>  
> >>>  .. _`MIPI alliance`: http://www.mipi.org/
> >>>  
> >>> +Media bus formats
> >>> +-----------------
> >>> +
> >>> +Always use the media bus pixel code that describes a parallel format that
> >>> +transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more
> >>
> >> How about: "transfers the pixel data as a single sample in one clock cycle"
> > 
> > The text is from mbus format documentation. Note that this might not be
> > pixel data; it may be metadata as well.
> 
> My problem with 'a sample' is that all parallel media bus formats transfer 'a sample'
> in a single clock cycle. It is not clearly defined what 'a sample' is.
> 
> Either the text needs to be improved, or an example should be added here as well
> since an example clarifies what is meant.
> 
> > 
> >>
> >> Possibly with an example: "So use e.g. MEDIA_BUS_FMT_SBGGR10_1X10 instead of
> >> MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE."
> > 
> > There's an example in mbus format documentation. I'm fine adding one here,
> > too, but the purpose of this bit is to mainly refer to mbus format
> > documentation. Mbus format documentation uses MEDIA_BUS_FMT_BGR888_1X24 and
> > MEDIA_BUS_FMT_BGR888_3X8 as the example.
> > 
> 
> Ah, I see. But then the reference to v4l2-mbus-format is confusing, I'd
> change that to v4l2-mbus-pixelcode. That's where the example is.

Ah, that's a better label indeed. I'll use that. With this, do you prefer
having the example here as well?

-- 
Sakari Ailus

Re: [PATCH v2 1/1] Documentation: media: Refer to mbus code documentation from CSI-2 docs

[Hans Verkuil]

On 19/05/2020 12:08, Sakari Ailus wrote:
> On Tue, May 19, 2020 at 11:28:48AM +0200, Hans Verkuil wrote:
>> On 19/05/2020 11:17, Sakari Ailus wrote:
>>> Hi Hans,
>>>
>>> On Tue, May 19, 2020 at 11:05:31AM +0200, Hans Verkuil wrote:
>>>> On 19/05/2020 10:50, Sakari Ailus wrote:
>>>>> The media bus codes to be used on serial busses are documented but there
>>>>> was no reference from CSI-2 documentation. Add that now.
>>>>>
>>>>> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>>>>> ---
>>>>>  Documentation/driver-api/media/csi2.rst | 7 +++++++
>>>>>  1 file changed, 7 insertions(+)
>>>>>
>>>>> diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst
>>>>> index da8b356389f0..1653a51d2a6e 100644
>>>>> --- a/Documentation/driver-api/media/csi2.rst
>>>>> +++ b/Documentation/driver-api/media/csi2.rst
>>>>> @@ -10,6 +10,13 @@ the host SoC. It is defined by the `MIPI alliance`_.
>>>>>  
>>>>>  .. _`MIPI alliance`: http://www.mipi.org/
>>>>>  
>>>>> +Media bus formats
>>>>> +-----------------
>>>>> +
>>>>> +Always use the media bus pixel code that describes a parallel format that
>>>>> +transfers a sample on a single clock cycle. See :ref:`v4l2-mbus-format` for more
>>>>
>>>> How about: "transfers the pixel data as a single sample in one clock cycle"
>>>
>>> The text is from mbus format documentation. Note that this might not be
>>> pixel data; it may be metadata as well.
>>
>> My problem with 'a sample' is that all parallel media bus formats transfer 'a sample'
>> in a single clock cycle. It is not clearly defined what 'a sample' is.
>>
>> Either the text needs to be improved, or an example should be added here as well
>> since an example clarifies what is meant.
>>
>>>
>>>>
>>>> Possibly with an example: "So use e.g. MEDIA_BUS_FMT_SBGGR10_1X10 instead of
>>>> MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE."
>>>
>>> There's an example in mbus format documentation. I'm fine adding one here,
>>> too, but the purpose of this bit is to mainly refer to mbus format
>>> documentation. Mbus format documentation uses MEDIA_BUS_FMT_BGR888_1X24 and
>>> MEDIA_BUS_FMT_BGR888_3X8 as the example.
>>>
>>
>> Ah, I see. But then the reference to v4l2-mbus-format is confusing, I'd
>> change that to v4l2-mbus-pixelcode. That's where the example is.
> 
> Ah, that's a better label indeed. I'll use that. With this, do you prefer
> having the example here as well?
> 

Rather than duplicating text, perhaps it is better to just refer to the
v4l2-mbus-pixelcode section:

+Media bus formats
+-----------------
+
+See :ref:`v4l2-mbus-pixelcode` for details on which media bus formats should
+be used for CSI-2 interfaces.

Regards,

	Hans