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

[Conor Dooley <conor@kernel.org>]

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

On Mon, Apr 27, 2026 at 06:07:40PM +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.  In the same time
> commit message should clearly explain when the code suggests devices
> are compatible, but the binding does not define them as such.
> 
> Acked-by: Conor Dooley <conor.dooley@microchip.com>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
> 
> ---
> 
> Changes in v2:
> 1. Include Conor's suggestion about commit msg, a bit rephrased.

Ye, it's better than my double use of the same term.

> 2. Add tag
> 3. Drop double-space, because file does not use that format (old habit).
> ---
>  .../devicetree/bindings/writing-bindings.rst         | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
> index 667816dd7d50..1a51764833a1 100644
> --- a/Documentation/devicetree/bindings/writing-bindings.rst
> +++ b/Documentation/devicetree/bindings/writing-bindings.rst
> @@ -53,7 +53,17 @@ 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 use the commit message to explain why devices that may appear
> +     compatible in a diff (e.g. no differences in property use, same handling
> +     by the software) but are not made compatible in the binding, are not
> +     compatible.
>  
>     - DO add new compatibles in case there are new features or bugs.
>  
> -- 
> 2.51.0
> 

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