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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxx>
> >> > ---
> >> >  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@xxxxxxxxxx>
> >
> > 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@xxxxxxxxxxxxxxx>
> > 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@xxxxxxxxxxxxxxx>
> > ---
> >  .../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@xxxxxxxxxxxxxxx

-- 
Sakari Ailus
e-mail: sakari.ailus@xxxxxx



[Index of Archives]     [Linux Input]     [Video for Linux]     [Gstreamer Embedded]     [Mplayer Users]     [Linux USB Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [Yosemite Backpacking]
  Powered by Linux