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

On Fri, Jun 10, 2016 at 2:11 PM, Geert Uytterhoeven
[off-list ref] wrote:

Hi Rob,

On Fri, Jun 10, 2016 at 7:39 PM, Rob Herring [off-list ref] wrote:

quoted

On Thu, Jun 09, 2016 at 02:41:33PM +0100, Kieran Bingham wrote:

quoted

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