Re: [PATCH 2/3] dt-bindings: Document Renesas R-Car FCP power-domains usage

[Rob Herring]

On Fri, Jun 10, 2016 at 2:11 PM, Geert Uytterhoeven
<geert@xxxxxxxxxxxxxx> wrote:
> Hi Rob,
>
> On Fri, Jun 10, 2016 at 7:39 PM, Rob Herring <robh@xxxxxxxxxx> wrote:
>> On Thu, Jun 09, 2016 at 02:41:33PM +0100, Kieran Bingham wrote:
>>> The power domain must be specified to bring the device out of module
>>> standby. Document this in the example provided, so that new additions
>>> are not missed.
>>>
>>> Signed-off-by: Kieran Bingham <kieran@xxxxxxxxxxx>
>>> ---
>>>  Documentation/devicetree/bindings/media/renesas,fcp.txt | 1 +
>>>  1 file changed, 1 insertion(+)
>>>
>>> diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt
>>> index 271dcfdb5a76..6a55f5215221 100644
>>> --- a/Documentation/devicetree/bindings/media/renesas,fcp.txt
>>> +++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt
>>> @@ -31,4 +31,5 @@ Device node example
>>>               compatible = "renesas,r8a7795-fcpv", "renesas,fcpv";
>>>               reg = <0 0xfea2f000 0 0x200>;
>>>               clocks = <&cpg CPG_MOD 602>;
>>> +             power-domains = <&sysc R8A7795_PD_A3VP>;
>>
>> This needs to be documented above too, not just the example.
>
> Why? Power domains are an optional feature, whose presence depends
> on the platform, not on the device.

Examples are not documentation. The binding should stand on its own
without the example.

How did I know this is optional unless you document it as optional?
How many power domains does the device have?

> Hence "power-domains" properties may appear in any device node.
> Having to document them in every single binding document is overkill.

We do it for everything else pretty much. There's some exceptions like "status".

I agree that we get a bunch of redundancy with random text describing
the properties. I'm all for a structured syntax that can distill the
device bindings down to the pertainent information. If only someone
proposed using yaml or something...

Rob