[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <aLmwk/0gqrivgl1U@lizhi-Precision-Tower-5810>
Date: Thu, 4 Sep 2025 11:30:27 -0400
From: Frank Li <Frank.li@....com>
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] docs: dt: writing-schema: Describe defining properties
in top-level
On Thu, Sep 04, 2025 at 04:24:01PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> Properties having differences per each device in the binding, e.g.
> different constraints for lists or different allowed values, should
> still be defined in top-level 'properties' section and only customized
> in 'if:then:'.
'customized' is not easy understand in my view.
only restrict (such as limit number of item, limit data range, disabllow
properties) in 'if: then:' section.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
> ---
> Documentation/devicetree/bindings/writing-schema.rst | 8 ++++++++
> 1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
> index 470d1521fa17..e0859094575d 100644
> --- a/Documentation/devicetree/bindings/writing-schema.rst
> +++ b/Documentation/devicetree/bindings/writing-schema.rst
> @@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar
> values a matrix (in order to define groupings) even when only a single value
> is present. Single entries in schemas are fixed up to match this encoding.
>
> +When bindings cover multiple similar devices that differ in some properties,
> +those properties should be constrained for each device. This usually means:
> +
> + * In top level 'properties' define the property with the broadest constraints.
> + * In 'if:then:' blocks, further narrow the constraints for those properties.
> + * Do not define the properties within an 'if:then:' block (note that
> + 'additionalItems' also won't allow that).
> +
I can understand what your said. I think it would be better if add some
simple examples.
Frank
> Coding style
> ------------
>
> --
> 2.48.1
>
Powered by blists - more mailing lists