[PATCH 0/2] Improve generic DT binding documentation for media devices

[PATCH 0/2] Improve generic DT binding documentation for media devices

[Sakari Ailus]

Hi folks,

This set improves the DT binding documentation for media devices where
device specific documentation is lacking:

- Port and endpoint numbering
- lane numbering for the data-lanes property

Sakari Ailus (2):
  dt: bindings: media: Document port and endpoint numbering
  dt: bindings: media: Document data lane numbering without lane
    reordering

 .../devicetree/bindings/media/video-interfaces.txt      | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] dt: bindings: media: Document port and endpoint numbering

[Sakari Ailus]

A lot of devices do not need and do not document port or endpoint
numbering at all, e.g. in case where there's just a single port and a
single endpoint. Whereas this is just common sense, document it to make it
explicit.

Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 Documentation/devicetree/bindings/media/video-interfaces.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index 852041a..4e0527d 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -55,6 +55,18 @@ divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
 and data-shift properties can be used to assign physical data lines to each
 endpoint node (logical bus).
 
+Port and endpoint numbering
+---------------------------
+
+While the port and endpoint numbers are ultimately specific to a device,
+most devices have more limited scope than what the interface allows. They
+may, for instance, only support a single endpoint on a port. Or there may
+be only a single port on a device.
+
+Therefore, if ports are not explicitly documented for a device, only port
+number zero shall be used. The same applies to endpoints: if endpoint
+numbers are not explicitly documented, only endpoint number zero shall be
+used.
 
 Required properties
 -------------------
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] dt: bindings: media: Document port and endpoint numbering

[Rob Herring]

On Mon, Sep 18, 2017 at 11:25:04AM +0300, Sakari Ailus wrote:
> A lot of devices do not need and do not document port or endpoint
> numbering at all, e.g. in case where there's just a single port and a
> single endpoint. Whereas this is just common sense, document it to make it
> explicit.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  Documentation/devicetree/bindings/media/video-interfaces.txt | 12 ++++++++++++
>  1 file changed, 12 insertions(+)

This is fine, but bindings should still be explicit. Otherwise, I'm 
wondering if it's a single port/endpoint or they just forgot to document 
it. And I shouldn't have to look at the example to infer that.

Acked-by: Rob Herring <robh@kernel.org>

Re: [PATCH 1/2] dt: bindings: media: Document port and endpoint numbering

[Sakari Ailus]

Hi Rob,

Thanks for the reply.

On Wed, Sep 20, 2017 at 03:53:13PM -0500, Rob Herring wrote:
> On Mon, Sep 18, 2017 at 11:25:04AM +0300, Sakari Ailus wrote:
> > A lot of devices do not need and do not document port or endpoint
> > numbering at all, e.g. in case where there's just a single port and a
> > single endpoint. Whereas this is just common sense, document it to make it
> > explicit.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> > ---
> >  Documentation/devicetree/bindings/media/video-interfaces.txt | 12 ++++++++++++
> >  1 file changed, 12 insertions(+)
> 
> This is fine, but bindings should still be explicit. Otherwise, I'm 
> wondering if it's a single port/endpoint or they just forgot to document 
> it. And I shouldn't have to look at the example to infer that.
> 
> Acked-by: Rob Herring <robh@kernel.org>

The purpose of the patch was to actually document port and endpoint
numbering for devices for which it is not documented, not to suggest that
this would be omitted in in binding documentation. The fact is that I
couldn't find documentation for endpoint numbering for a single device
under Documentation/devicetree/bindings/media/ . Yet I haven't come across
DT source where other than zero would have been used. And the drivers
(mostly?) have ignored endpoint numbers so far.

Some bindings have been omitted on the grounds that they're documented in
video-interfaces.txt.

What would you think of the following? I'm not sure it'd really belong
there, but it'd be a small piece of documentation one can easily refer to.


>From e735979005244eb10597fe5333130b93e41d5a38 Mon Sep 17 00:00:00 2001
From: Sakari Ailus <sakari.ailus@linux.intel.com>
Date: Mon, 18 Sep 2017 11:15:53 +0300
Subject: [PATCH 1/1] dt: bindings: media: Document practices for DT bindings,
 ports, endpoints

Port and endpoint numbering has been omitted in DT binding documentation
for a large number of devices. Also common properties the device uses have
been missed in binding documentation. Make it explicit that these things
need to be documented.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 .../devicetree/bindings/media/video-interfaces.txt        | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index 852041a..3c5382f 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -55,6 +55,21 @@ divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
 and data-shift properties can be used to assign physical data lines to each
 endpoint node (logical bus).
 
+Documenting bindings for devices
+--------------------------------
+
+All required and optional bindings the device supports shall be explicitly
+documented in device DT binding documentation. This also includes port and
+endpoint numbering for the device.
+
+Port and endpoint numbering
+---------------------------
+
+Old binding documentation may have omitted explicitly specifying port and
+endpoint numbers. This often applies to devices that have a single port and a
+single endpoint in that port. In this case, the only valid port number for such
+a device is zero. The same applies for devices for which bindings do not
+document endpoint numbering: only zero is a valid endpoint.
 
 Required properties
 -------------------
-- 
2.7.4

-- 
Sakari Ailus
sakari.ailus@linux.intel.com

Re: [PATCH 1/2] dt: bindings: media: Document port and endpoint numbering

[Rob Herring]

On Thu, Sep 21, 2017 at 4:25 AM, Sakari Ailus
<sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
> Hi Rob,
>
> Thanks for the reply.
>
> On Wed, Sep 20, 2017 at 03:53:13PM -0500, Rob Herring wrote:
>> On Mon, Sep 18, 2017 at 11:25:04AM +0300, Sakari Ailus wrote:
>> > A lot of devices do not need and do not document port or endpoint
>> > numbering at all, e.g. in case where there's just a single port and a
>> > single endpoint. Whereas this is just common sense, document it to make it
>> > explicit.
>> >
>> > Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>> > ---
>> >  Documentation/devicetree/bindings/media/video-interfaces.txt | 12 ++++++++++++
>> >  1 file changed, 12 insertions(+)
>>
>> This is fine, but bindings should still be explicit. Otherwise, I'm
>> wondering if it's a single port/endpoint or they just forgot to document
>> it. And I shouldn't have to look at the example to infer that.
>>
>> Acked-by: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>
> The purpose of the patch was to actually document port and endpoint
> numbering for devices for which it is not documented, not to suggest that
> this would be omitted in in binding documentation. The fact is that I
> couldn't find documentation for endpoint numbering for a single device
> under Documentation/devicetree/bindings/media/ . Yet I haven't come across
> DT source where other than zero would have been used. And the drivers
> (mostly?) have ignored endpoint numbers so far.

That's surprising. I know there are some for display controllers and
it's a common review comment I give.

>
> Some bindings have been omitted on the grounds that they're documented in
> video-interfaces.txt.
>
> What would you think of the following? I'm not sure it'd really belong
> there, but it'd be a small piece of documentation one can easily refer to.

Looks good.

>
>
> From e735979005244eb10597fe5333130b93e41d5a38 Mon Sep 17 00:00:00 2001
> From: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> Date: Mon, 18 Sep 2017 11:15:53 +0300
> Subject: [PATCH 1/1] dt: bindings: media: Document practices for DT bindings,
>  ports, endpoints
>
> Port and endpoint numbering has been omitted in DT binding documentation
> for a large number of devices. Also common properties the device uses have
> been missed in binding documentation. Make it explicit that these things
> need to be documented.
>
> Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> ---
>  .../devicetree/bindings/media/video-interfaces.txt        | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
> index 852041a..3c5382f 100644
> --- a/Documentation/devicetree/bindings/media/video-interfaces.txt
> +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
> @@ -55,6 +55,21 @@ divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
>  and data-shift properties can be used to assign physical data lines to each
>  endpoint node (logical bus).
>
> +Documenting bindings for devices
> +--------------------------------
> +
> +All required and optional bindings the device supports shall be explicitly
> +documented in device DT binding documentation. This also includes port and
> +endpoint numbering for the device.
> +
> +Port and endpoint numbering
> +---------------------------
> +
> +Old binding documentation may have omitted explicitly specifying port and
> +endpoint numbers. This often applies to devices that have a single port and a
> +single endpoint in that port. In this case, the only valid port number for such
> +a device is zero. The same applies for devices for which bindings do not
> +document endpoint numbering: only zero is a valid endpoint.
>
>  Required properties
>  -------------------
> --
> 2.7.4
>
> --
> Sakari Ailus
> sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] dt: bindings: media: Document port and endpoint numbering

[Sakari Ailus]

On Thu, Sep 21, 2017 at 10:58:34AM -0500, Rob Herring wrote:
> On Thu, Sep 21, 2017 at 4:25 AM, Sakari Ailus
> <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
> > Hi Rob,
> >
> > Thanks for the reply.
> >
> > On Wed, Sep 20, 2017 at 03:53:13PM -0500, Rob Herring wrote:
> >> On Mon, Sep 18, 2017 at 11:25:04AM +0300, Sakari Ailus wrote:
> >> > A lot of devices do not need and do not document port or endpoint
> >> > numbering at all, e.g. in case where there's just a single port and a
> >> > single endpoint. Whereas this is just common sense, document it to make it
> >> > explicit.
> >> >
> >> > Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> >> > ---
> >> >  Documentation/devicetree/bindings/media/video-interfaces.txt | 12 ++++++++++++
> >> >  1 file changed, 12 insertions(+)
> >>
> >> This is fine, but bindings should still be explicit. Otherwise, I'm
> >> wondering if it's a single port/endpoint or they just forgot to document
> >> it. And I shouldn't have to look at the example to infer that.
> >>
> >> Acked-by: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> >
> > The purpose of the patch was to actually document port and endpoint
> > numbering for devices for which it is not documented, not to suggest that
> > this would be omitted in in binding documentation. The fact is that I
> > couldn't find documentation for endpoint numbering for a single device
> > under Documentation/devicetree/bindings/media/ . Yet I haven't come across
> > DT source where other than zero would have been used. And the drivers
> > (mostly?) have ignored endpoint numbers so far.
> 
> That's surprising. I know there are some for display controllers and
> it's a common review comment I give.

On V4L2 side we only have started paying attention recently. See e.g.

	Documentation/devicetree/bindings/media/atmel-isc.txt
	Documentation/devicetree/bindings/media/ti,omap3isp.txt
	Documentation/devicetree/bindings/media/qcom,camss.txt

> 
> >
> > Some bindings have been omitted on the grounds that they're documented in
> > video-interfaces.txt.
> >
> > What would you think of the following? I'm not sure it'd really belong
> > there, but it'd be a small piece of documentation one can easily refer to.
> 
> Looks good.

I'll resend the set, replacing the original patch.

> 
> >
> >
> > From e735979005244eb10597fe5333130b93e41d5a38 Mon Sep 17 00:00:00 2001
> > From: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> > Date: Mon, 18 Sep 2017 11:15:53 +0300
> > Subject: [PATCH 1/1] dt: bindings: media: Document practices for DT bindings,
> >  ports, endpoints
> >
> > Port and endpoint numbering has been omitted in DT binding documentation
> > for a large number of devices. Also common properties the device uses have
> > been missed in binding documentation. Make it explicit that these things
> > need to be documented.
> >
> > Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> > ---
> >  .../devicetree/bindings/media/video-interfaces.txt        | 15 +++++++++++++++
> >  1 file changed, 15 insertions(+)
> >
> > diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
> > index 852041a..3c5382f 100644
> > --- a/Documentation/devicetree/bindings/media/video-interfaces.txt
> > +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
> > @@ -55,6 +55,21 @@ divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
> >  and data-shift properties can be used to assign physical data lines to each
> >  endpoint node (logical bus).
> >
> > +Documenting bindings for devices
> > +--------------------------------
> > +
> > +All required and optional bindings the device supports shall be explicitly
> > +documented in device DT binding documentation. This also includes port and
> > +endpoint numbering for the device.
> > +
> > +Port and endpoint numbering
> > +---------------------------
> > +
> > +Old binding documentation may have omitted explicitly specifying port and
> > +endpoint numbers. This often applies to devices that have a single port and a
> > +single endpoint in that port. In this case, the only valid port number for such
> > +a device is zero. The same applies for devices for which bindings do not
> > +document endpoint numbering: only zero is a valid endpoint.
> >
> >  Required properties
> >  -------------------
> > --
> > 2.7.4
> >
> > --
> > Sakari Ailus
> > sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org

-- 
Sakari Ailus
e-mail: sakari.ailus-X3B1VOXEql0@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] dt: bindings: media: Document data lane numbering without lane reordering

[Sakari Ailus]

Most devices do not support lane reordering and in many cases the
documentation of the data-lanes property is incomplete for such devices.
Document that in case the lane reordering isn't supported, monotonically
incremented values from 0 or 1 shall be used.

Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
---
 Documentation/devicetree/bindings/media/video-interfaces.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index 4e0527d..fc1964e 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -111,7 +111,10 @@ Optional endpoint properties
   determines the logical lane number, while the value of an entry indicates
   physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have
   "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0.
-  This property is valid for serial busses only (e.g. MIPI CSI-2).
+  If the hardware does not support lane reordering, monotonically
+  incremented values shall be used from 0 or 1 onwards, depending on
+  whether or not there is also a clock lane. This property is valid for
+  serial busses only (e.g. MIPI CSI-2).
 - clock-lanes: an array of physical clock lane indexes. Position of an entry
   determines the logical lane number, while the value of an entry indicates
   physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;",
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] dt: bindings: media: Document data lane numbering without lane reordering

[Rob Herring]

On Mon, Sep 18, 2017 at 11:25:05AM +0300, Sakari Ailus wrote:
> Most devices do not support lane reordering and in many cases the
> documentation of the data-lanes property is incomplete for such devices.
> Document that in case the lane reordering isn't supported, monotonically
> incremented values from 0 or 1 shall be used.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  Documentation/devicetree/bindings/media/video-interfaces.txt | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)

Acked-by: Rob Herring <robh@kernel.org>