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 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.

>
> 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@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



[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