linux-kernel - Re: [PATCH v2 2/4] docs: dt: writing-bindings: Document compatible and filename naming

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: <20250714-espionage-overexert-c12cee88d1f4@spud>
Date: Mon, 14 Jul 2025 18:20:02 +0100
From: Conor Dooley <conor@...nel.org>
To: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Cc: Rob Herring <robh@...nel.org>, Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>, devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 2/4] docs: dt: writing-bindings: Document compatible
 and filename naming

On Sun, Jul 13, 2025 at 02:46:37PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practices:
> 
> 1. Compatibles should not use bus suffixes to encode the type of
>    interface, because the parent bus node defines that interface, e.g.
>    "vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".
> 
> 2. If the compatible represents the device as a whole, it should not
>    contain the type of device in the name.
> 
> 3. Filenames should match compatible.  The best if match is 100%, but if
>    binding has multiple compatibles, then one of the fallbacks should be
>    used.  Alternatively a genericish name is allowed if it follows
>    "vendor,device" style.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>

Reviewed-by: Conor Dooley <conor.dooley@...rochip.com>

> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
> index a2d2afd099c0bd922cf12dcf49f5dffe6da748f1..e63de88385b5bc5859d8d9fca82bcf30380f3e73 100644
> --- a/Documentation/devicetree/bindings/writing-bindings.rst
> +++ b/Documentation/devicetree/bindings/writing-bindings.rst
> @@ -52,6 +52,10 @@ Properties
>       fallback if appropriate. SoC-specific compatibles are also preferred for
>       the fallbacks.
>  
> +   - DON'T use bus suffixes to encode the type of interface device is using.
> +     The parent bus node already implies that interface.  DON'T add the type of
> +     device, if the device cannot be anything else.
> +
>  - DO use a vendor prefix on device-specific property names. Consider if
>    properties could be common among devices of the same class. Check other
>    existing bindings for similar devices.
> @@ -101,6 +105,10 @@ Typical cases and caveats
>  - "syscon" is not a generic property. Use vendor and type, e.g.
>    "vendor,power-manager-syscon".
>  
> +- Bindings files should be named like compatible: vendor,device.yaml. In case
> +  of multiple compatibles in the binding, use one of the fallbacks or a more
> +  generic name, yet still matching compatible style.
> +
>  Board/SoC .dts Files
>  ====================
>  
> 
> -- 
> 2.43.0
> 

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)