* [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware
@ 2024-02-12 15:05 Krzysztof Kozlowski
2024-02-12 15:05 ` [PATCH 2/3] docs: dt: writing-schema: explain additional/unevaluatedProperties Krzysztof Kozlowski
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Krzysztof Kozlowski @ 2024-02-12 15:05 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley, devicetree, linux-kernel
Cc: Krzysztof Kozlowski
The 'title' and 'description' fields in Devicetree schema is supposed to
describe hardware, not the binding itself.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
Documentation/devicetree/bindings/writing-schema.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 0a6cf19a1459..2e5575e6a4e5 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -31,7 +31,7 @@ $schema
Indicates the meta-schema the schema file adheres to.
title
- A one-line description on the contents of the binding schema.
+ A one-line description of the hardware being described in the binding schema.
maintainers
A DT specific property. Contains a list of email address(es)
@@ -39,7 +39,7 @@ maintainers
description
Optional. A multi-line text block containing any detailed
- information about this binding. It should contain things such as what the block
+ information about this hardware. It should contain things such as what the block
or device does, standards the device conforms to, and links to datasheets for
more information.
--
2.34.1
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH 2/3] docs: dt: writing-schema: explain additional/unevaluatedProperties
2024-02-12 15:05 [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Krzysztof Kozlowski
@ 2024-02-12 15:05 ` Krzysztof Kozlowski
2024-02-13 16:22 ` Rob Herring
2024-02-12 15:05 ` [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS Krzysztof Kozlowski
2024-02-13 16:22 ` [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Rob Herring
2 siblings, 1 reply; 6+ messages in thread
From: Krzysztof Kozlowski @ 2024-02-12 15:05 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley, devicetree, linux-kernel
Cc: Krzysztof Kozlowski
Add to the list of schema contents expected keywords with their
explanation: additionalProperties and unevaluatedProperties.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
.../devicetree/bindings/writing-schema.rst | 20 +++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 2e5575e6a4e5..a35859f3be00 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -71,6 +71,26 @@ required
A list of DT properties from the 'properties' section that
must always be present.
+additionalProperties / unevaluatedProperties
+ Keywords controlling how schema will validate properties not matched by this
+ schema's 'properties' or 'patternProperties'. Each schema is supposed to
+ have exactly one of these keywords in top-level part, so either
+ additionalProperties or unevaluatedProperties. Nested nodes, so properties
+ being objects, are supposed to have one as well.
+
+ * additionalProperties: false
+ Most common case, where no additional schema is referenced or if this
+ binding allows subset of properties from other referenced schemas.
+
+ * unevaluatedProperties: false
+ Used when this binding references other schema whose all properties
+ should be allowed.
+
+ * additionalProperties: true
+ Rare case, used for schemas implementing common set of properties. Such
+ schemas are supposed to be referenced by other schemas, which then use
+ 'unevaluatedProperties: false'. Typically bus or common-part schemas.
+
examples
Optional. A list of one or more DTS hunks implementing the
binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
--
2.34.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS
2024-02-12 15:05 [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Krzysztof Kozlowski
2024-02-12 15:05 ` [PATCH 2/3] docs: dt: writing-schema: explain additional/unevaluatedProperties Krzysztof Kozlowski
@ 2024-02-12 15:05 ` Krzysztof Kozlowski
2024-02-13 16:23 ` Rob Herring
2024-02-13 16:22 ` [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Rob Herring
2 siblings, 1 reply; 6+ messages in thread
From: Krzysztof Kozlowski @ 2024-02-12 15:05 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley, devicetree, linux-kernel
Cc: Krzysztof Kozlowski
Devicetree binding maintainers expect the example DTS in a binding to
show the usage of only this one particular binding, without unrelated
device nodes.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
Documentation/devicetree/bindings/writing-schema.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index a35859f3be00..7e71cdd1d6de 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -92,8 +92,10 @@ additionalProperties / unevaluatedProperties
'unevaluatedProperties: false'. Typically bus or common-part schemas.
examples
- Optional. A list of one or more DTS hunks implementing the
- binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+ Optional. A list of one or more DTS hunks implementing this binding only.
+ Example should not contain unrelated device nodes, e.g. consumer nodes in a
+ provider binding, other nodes referenced by phandle.
+ Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
--
2.34.1
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS
2024-02-12 15:05 ` [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS Krzysztof Kozlowski
@ 2024-02-13 16:23 ` Rob Herring
0 siblings, 0 replies; 6+ messages in thread
From: Rob Herring @ 2024-02-13 16:23 UTC (permalink / raw)
To: Krzysztof Kozlowski
Cc: Krzysztof Kozlowski, devicetree, Conor Dooley, linux-kernel
On Mon, 12 Feb 2024 16:05:24 +0100, Krzysztof Kozlowski wrote:
> Devicetree binding maintainers expect the example DTS in a binding to
> show the usage of only this one particular binding, without unrelated
> device nodes.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
> Documentation/devicetree/bindings/writing-schema.rst | 6 ++++--
> 1 file changed, 4 insertions(+), 2 deletions(-)
>
Applied, thanks!
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware
2024-02-12 15:05 [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Krzysztof Kozlowski
2024-02-12 15:05 ` [PATCH 2/3] docs: dt: writing-schema: explain additional/unevaluatedProperties Krzysztof Kozlowski
2024-02-12 15:05 ` [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS Krzysztof Kozlowski
@ 2024-02-13 16:22 ` Rob Herring
2 siblings, 0 replies; 6+ messages in thread
From: Rob Herring @ 2024-02-13 16:22 UTC (permalink / raw)
To: Krzysztof Kozlowski
Cc: devicetree, Conor Dooley, Krzysztof Kozlowski, linux-kernel
On Mon, 12 Feb 2024 16:05:22 +0100, Krzysztof Kozlowski wrote:
> The 'title' and 'description' fields in Devicetree schema is supposed to
> describe hardware, not the binding itself.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
> Documentation/devicetree/bindings/writing-schema.rst | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
Applied, thanks!
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2024-02-13 16:23 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-02-12 15:05 [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Krzysztof Kozlowski
2024-02-12 15:05 ` [PATCH 2/3] docs: dt: writing-schema: explain additional/unevaluatedProperties Krzysztof Kozlowski
2024-02-13 16:22 ` Rob Herring
2024-02-12 15:05 ` [PATCH 3/3] docs: dt: writing-schema: document expectations on example DTS Krzysztof Kozlowski
2024-02-13 16:23 ` Rob Herring
2024-02-13 16:22 ` [PATCH 1/3] docs: dt: writing-schema: clarify that schema should describe hardware Rob Herring
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®