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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAL_JsqLd+sXeEtq+chtrCxyDgyBm9s3giCC+ri8oMvfVLjunaA@mail.gmail.com>
Date:	Fri, 10 Jun 2016 16:33:36 -0500
From:	Rob Herring <robh@...nel.org>
To:	Geert Uytterhoeven <geert@...ux-m68k.org>
Cc:	Kieran Bingham <kieran@...uared.org.uk>,
	Laurent Pinchart <laurent.pinchart@...asonboard.com>,
	Pawel Moll <pawel.moll@....com>,
	Mark Rutland <mark.rutland@....com>,
	Ian Campbell <ijc+devicetree@...lion.org.uk>,
	Kumar Gala <galak@...eaurora.org>,
	"open list:MEDIA DRIVERS FOR RENESAS - FCP" 
	<linux-media@...r.kernel.org>,
	"open list:MEDIA DRIVERS FOR RENESAS - FCP" 
	<linux-renesas-soc@...r.kernel.org>,
	"open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS" 
	<devicetree@...r.kernel.org>,
	open list <linux-kernel@...r.kernel.org>
Subject: 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
<geert@...ux-m68k.org> wrote:
> Hi Rob,
>
> On Fri, Jun 10, 2016 at 7:39 PM, Rob Herring <robh@...nel.org> 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@...gham.xyz>
>>> ---
>>>  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