[PATCH] docs: dt: writing-bindings: Extend compatible fallbacks guideline

[PATCH] docs: dt: writing-bindings: Extend compatible fallbacks guideline

[Krzysztof Kozlowski]

Extend the guidelines when to use fallback compatibles to cover to
common review responses.  Devices are most likely compatible and should
use fallbacks when having:

1. Compatible programming interface, meaning one is a subset, and Linux
   device drivers can use the subset to correctly match/bind and still
   operate with the subset features.

2. Device variant discovery through some means, like registers.

Devices are incompatible and fallback is not suitable when that
fallback cannot be used by the drivers to match/bind.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
---
 Documentation/devicetree/bindings/writing-bindings.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 667816dd7d50..03e29e2d50af 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -53,7 +53,12 @@ Properties
    - DON'T use wildcards or device-family names in compatible strings.
 
    - DO use fallback compatibles when devices are the same as or a superset of
-     prior implementations.
+     prior implementations.  Fallback compatibles are applicable especially
+     when sharing a programming interface or when able to discover the
+     variants.
+
+   - DON'T add fake fallback compatibles when software cannot use such to match
+     and bind to a device, and still operate correctly.
 
    - DO add new compatibles in case there are new features or bugs.
 
-- 
2.51.0

Re: [PATCH] docs: dt: writing-bindings: Extend compatible fallbacks guideline

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2024 bytes --]

On Wed, Apr 15, 2026 at 10:21:14AM +0200, Krzysztof Kozlowski wrote:
> Extend the guidelines when to use fallback compatibles to cover to
> common review responses.  Devices are most likely compatible and should
> use fallbacks when having:
> 
> 1. Compatible programming interface, meaning one is a subset, and Linux
>    device drivers can use the subset to correctly match/bind and still
>    operate with the subset features.
> 
> 2. Device variant discovery through some means, like registers.
> 
> Devices are incompatible and fallback is not suitable when that
> fallback cannot be used by the drivers to match/bind.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
> index 667816dd7d50..03e29e2d50af 100644
> --- a/Documentation/devicetree/bindings/writing-bindings.rst
> +++ b/Documentation/devicetree/bindings/writing-bindings.rst
> @@ -53,7 +53,12 @@ Properties
>     - DON'T use wildcards or device-family names in compatible strings.
>  
>     - DO use fallback compatibles when devices are the same as or a superset of
> -     prior implementations.
> +     prior implementations.  Fallback compatibles are applicable especially
> +     when sharing a programming interface or when able to discover the
> +     variants.
> +
> +   - DON'T add fake fallback compatibles when software cannot use such to match
> +     and bind to a device, and still operate correctly.
>  
>     - DO add new compatibles in case there are new features or bugs.

Acked-by: Conor Dooley <conor.dooley@microchip.com>

     - DO use the commit message explain why devices that may appear
       compatible in a diff (e.g. no differences in property use) but
       are not compatible, are not compatible.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]