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

[Sakari Ailus <sakari.ailus@linux.intel.com>]

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