dt-bindings: clock: Convert fixed-clock binding to json-schema
Subsystems (2)
Rob Herring
maintainerPATCH 1/1 dt-bindings: clock: Convert fixed-clock binding to json-schema
Convert the fixed-clock binding to DT schema format using json-schema.
--- .../devicetree/bindings/clock/fixed-clock.txt | 23 ---------- .../bindings/clock/fixed-clock.yaml | 44 +++++++++++++++++++ 2 files changed, 44 insertions(+), 23 deletions(-) delete mode 100644 Documentation/devicetree/bindings/clock/fixed-clock.txt create mode 100644 Documentation/devicetree/bindings/clock/fixed-clock.yaml
Documentation/devicetree/bindings/clock/fixed-clock.txt deleted +0 -23
@@ -1,23 +0,0 @@ -Binding for simple fixed-rate clock sources. - -This binding uses the common clock binding[1]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt - -Required properties: -- compatible : shall be "fixed-clock". -- #clock-cells : from common clock binding; shall be set to 0. -- clock-frequency : frequency of clock in Hz. Should be a single cell. - -Optional properties: -- clock-accuracy : accuracy of clock in ppb (parts per billion). - Should be a single cell. -- clock-output-names : From common clock binding. - -Example: - clock { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <1000000000>; - clock-accuracy = <100>; - };
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +44 -0
44 lines not on this page · raw message
Signature · 1 line
2.19.1
Stephen Boyd
maintainerQuoting Rob Herring (2019-01-10 14:19:01)
Quoted 2 lines
Convert the fixed-clock binding to DT schema format using json-schema.
Any pointer to the full schema?
Quoted 4 lines
Cc Michael Turquette <[email protected]>Cc Stephen Boyd <[email protected]>Signed-off-by Rob Herring <[email protected]>
[...]
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 7
Quoted 13 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0@@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fixed-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for simple fixed-rate clock sources.
Why does title have a full stop?
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 20
Quoted 13 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +13
-0+ +maintainers: + - Michael Turquette <[email protected]> + - Stephen Boyd <[email protected]> + +properties: + compatible: + const: fixed-clock + + "#clock-cells": + const: 0 + + clock-frequency: true
Why doesn't this need the $ref: /schemas/types.yaml#/... thing?
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 27
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +6
-0+ clock-accuracy: + description: accuracy of clock in ppb (parts per billion). + $ref: /schemas/types.yaml#/definitions/uint32 + + clock-output-names: + maxItems: 1
Is there a schema for strings?
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 34
Quoted 7 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0+ +required: + - compatible + - "#clock-cells" + - clock-frequency + +additionalProperties: false
Does this always have to be specified even if it's false?
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 44
Quoted 11 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +10
-0+ +examples: + - | + clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <1000000000>; + clock-accuracy = <100>; + }; +...
Is the triple dot part of the schema?
Rob Herring
maintainerQuoted 6 lines · Stephen Boyd
Quoting Rob Herring (2019-01-10 14:19:01)
Quoted 2 lines
Convert the fixed-clock binding to DT schema format using json-schema.
Any pointer to the full schema?
https://github.com/robherring/yaml-bindings/blob/master/schemas/
And the clock schema in particular:
https://github.com/robherring/yaml-bindings/blob/master/schemas/clock.yaml
Quoted 5 lines
Quoted 4 lines
Cc Michael Turquette <[email protected]>Cc Stephen Boyd <[email protected]>Signed-off-by Rob Herring <[email protected]>[...]
Quoted 15 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 7
Quoted 13 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0@@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fixed-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for simple fixed-rate clock sources.Why does title have a full stop?
Because it was there in the original. My script to extract just takes the first line of alphanumeric text.
Quoted 7 lines
Quoted 7 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0+ +maintainers: + - Michael Turquette <[email protected]> + - Stephen Boyd <[email protected]> + +properties: + compatible:
Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 20
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +6
-0+ const: fixed-clock + + "#clock-cells": + const: 0 + + clock-frequency: trueWhy doesn't this need the $ref: /schemas/types.yaml#/... thing?
You might want to read bindings/example-schema.yaml which tries to explain some of this.
Standard properties are already defined in the core schemas. So we only have to say "we use this property" and any binding specific constraints. In this case, there aren't any other constraints. It is also needed to be listed here to mark it required and to satisfy 'additionalProperties: false'.
Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 27
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +6
-0+ clock-accuracy: + description: accuracy of clock in ppb (parts per billion). + $ref: /schemas/types.yaml#/definitions/uint32 + + clock-output-names: + maxItems: 1Is there a schema for strings?
Yes. The core already covers that '*-names' properties are a list of strings. So no need to do that again here and we just need to define how many strings are valid.
Quoted 9 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 34
Quoted 7 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0+ +required: + - compatible + - "#clock-cells" + - clock-frequency + +additionalProperties: falseDoes this always have to be specified even if it's false?
Yes, the default defined as true by the json-schema spec. In some cases we don't want to specify it.
Quoted 5 lines
Quoted 5 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +5
-0+ +examples: + - | + clock { + compatible = "fixed-clock";
Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 44
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +5
-0+ #clock-cells = <0>; + clock-frequency = <1000000000>; + clock-accuracy = <100>; + }; +...Is the triple dot part of the schema?
Yes. Well, it is part of YAML. It's optional really as are the 2 lines at the start. It's just good hygiene.
Rob
Stephen Boyd
maintainerQuoting Rob Herring (2019-01-11 10:27:48)
Quoted 6 lines · Stephen Boyd
Quoted 5 lines
Quoting Rob Herring (2019-01-10 14:19:01)
Quoted 2 lines
Convert the fixed-clock binding to DT schema format using json-schema.
Quoted 6 lines
Quoted 1 line
Any pointer to the full schema?
https://github.com/robherring/yaml-bindings/blob/master/schemas/
And the clock schema in particular:
https://github.com/robherring/yaml-bindings/blob/master/schemas/clock.yaml
Awesome. Thanks for the pointers! Is the clock schema posted to the list somewhere?
Quoted 22 lines
Quoted 6 lines
Quoted 5 lines
Cc Michael Turquette <[email protected]>Cc Stephen Boyd <[email protected]>Signed-off-by Rob Herring <[email protected]>[...]
Quoted 15 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 7
Quoted 13 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0@@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fixed-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for simple fixed-rate clock sources.Why does title have a full stop?
Quoted 2 lines
Because it was there in the original. My script to extract just takes the first line of alphanumeric text.
Ok. I think it would be good to treat them like commit subjects that don't have the full stop either, so if the script is able to drop the full stop it would be great.
Quoted 17 lines
Quoted 16 lines
Quoted 4 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +3
-0+ +maintainers: + - Michael Turquette <[email protected]>Documentation/devicetree/bindings/clock/fixed-clock.yaml line 20
Quoted 10 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +10
-0+ - Stephen Boyd <[email protected]> + +properties: + compatible: + const: fixed-clock + + "#clock-cells": + const: 0 + + clock-frequency: trueWhy doesn't this need the $ref: /schemas/types.yaml#/... thing?
Quoted 8 lines
You might want to read
bindings/example-schema.yamlwhich tries to explain some of this.Standard properties are already defined in the core schemas. So we only have to say "we use this property" and any binding specific constraints. In this case, there aren't any other constraints. It is also needed to be listed here to mark it required and to satisfy 'additionalProperties: false'.
Hmm ok. I suppose I'll have to hold that information in my mind when reviewing bindings. Is there any tooling or some script that I can run on json-schema bindings to verify they're correct? Or to find something redundant like this where a standard property is redefined? Grep would work for the redundant problem I suppose.
Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +6
-0+ clock-accuracy: + description: accuracy of clock in ppb (parts per billion). + $ref: /schemas/types.yaml#/definitions/uint32 + + clock-output-names: + maxItems: 1
Quoted 5 lines
Quoted 1 line
Is there a schema for strings?
Yes. The core already covers that '*-names' properties are a list of strings. So no need to do that again here and we just need to define how many strings are valid.
Alright. Thanks for the explanations.
Quoted 28 lines
Quoted 10 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 34
Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0+ +required: + - compatible + - "#clock-cells" + - clock-frequency + +additionalProperties: falseDoes this always have to be specified even if it's false?
Yes, the default defined as true by the json-schema spec. In some cases we don't want to specify it.
Quoted 5 lines
Quoted 5 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +5
-0+ +examples: + - | + clock { + compatible = "fixed-clock";Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 44
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +5
-0+ #clock-cells = <0>; + clock-frequency = <1000000000>; + clock-accuracy = <100>; + }; +...Is the triple dot part of the schema?
Quoted 3 lines
Yes. Well, it is part of YAML. It's optional really as are the 2 lines at the start. It's just good hygiene.
Sounds good.
Rob Herring
maintainerQuoted 10 lines · Stephen Boyd
Quoting Rob Herring (2019-01-11 10:27:48)
Quoted 8 lines · Stephen Boyd
Quoted 6 lines
Quoting Rob Herring (2019-01-10 14:19:01)
Quoted 2 lines
Convert the fixed-clock binding to DT schema format using json-schema.
Any pointer to the full schema?
Quoted 7 lines
Quoted 4 lines
https://github.com/robherring/yaml-bindings/blob/master/schemas/
And the clock schema in particular:
https://github.com/robherring/yaml-bindings/blob/master/schemas/clock.yamlAwesome. Thanks for the pointers! Is the clock schema posted to the list somewhere?
No. Happy to post things, but I'm struggling to find anyone that cares.
Quoted 21 lines
Quoted 21 lines
Quoted 20 lines
Quoted 4 lines
Cc Michael Turquette <[email protected]>Cc Stephen Boyd <[email protected]>Signed-off-by Rob Herring <[email protected]>[...]
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 7
Quoted 13 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0@@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/fixed-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Binding for simple fixed-rate clock sources.Why does title have a full stop?
Quoted 6 lines
Quoted 2 lines
Because it was there in the original. My script to extract just takes the first line of alphanumeric text.
Ok. I think it would be good to treat them like commit subjects that don't have the full stop either, so if the script is able to drop the full stop it would be great.
I can just write a meta-schema to enforce that. :)
Quoted 25 lines
Quoted 16 lines
Quoted 7 lines
Quoted 7 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +7
-0+ +maintainers: + - Michael Turquette <[email protected]> + - Stephen Boyd <[email protected]> + +properties: + compatible:Quoted 8 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml line 20
Quoted 6 lines
Documentation/devicetree/bindings/clock/fixed-clock.yaml new file +6
-0+ const: fixed-clock + + "#clock-cells": + const: 0 + + clock-frequency: trueWhy doesn't this need the $ref: /schemas/types.yaml#/... thing?
Quoted 8 lines
You might want to read
bindings/example-schema.yamlwhich tries to explain some of this.Standard properties are already defined in the core schemas. So we only have to say "we use this property" and any binding specific constraints. In this case, there aren't any other constraints. It is also needed to be listed here to mark it required and to satisfy 'additionalProperties: false'.
Quoted 5 lines
Hmm ok. I suppose I'll have to hold that information in my mind when reviewing bindings. Is there any tooling or some script that I can run on json-schema bindings to verify they're correct? Or to find something redundant like this where a standard property is redefined? Grep would work for the redundant problem I suppose.
Yes, the meta-schema enforces this at least to the extent there is a meta-schema defined for a standard property. Even if not something for a specific property, we limit things to a subset of json-schema keywords. Also, you also can't define something contradicting a core schema (e.g. { reg: { type: string } }), but that wouldn't be found until you check actual DTs.
The meta-schema check is run with:
make dt_binding_check
This is all documented in Documentation/devicetree/writing-schema.md.
Rob
Stephen Boyd
maintainerQuoting Rob Herring (2019-01-11 12:49:04)
Quoted 9 lines · Stephen Boyd
Quoted 8 lines
Quoting Rob Herring (2019-01-11 10:27:48)
Quoted 6 lines · Stephen Boyd
Quoted 2 lines
Any pointer to the full schema?
https://github.com/robherring/yaml-bindings/blob/master/schemas/
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
And the clock schema in particular:
https://github.com/robherring/yaml-bindings/blob/master/schemas/clock.yamlAwesome. Thanks for the pointers! Is the clock schema posted to the list somewhere?
No. Happy to post things, but I'm struggling to find anyone that cares.
Ok. I can review that document too if you post it to the list.
Quoted 11 lines
Quoted 9 lines
Quoted 5 lines
Quoted 2 lines
Why does title have a full stop?
Because it was there in the original. My script to extract just takes the first line of alphanumeric text.
Ok. I think it would be good to treat them like commit subjects that don't have the full stop either, so if the script is able to drop the full stop it would be great.
I can just write a meta-schema to enforce that. :)
Sounds good.
Quoted 8 lines
Yes, the meta-schema enforces this at least to the extent there is a meta-schema defined for a standard property. Even if not something for a specific property, we limit things to a subset of json-schema keywords. Also, you also can't define something contradicting a core schema (e.g. { reg: { type: string } }), but that wouldn't be found until you check actual DTs.
Quoted 5 lines
The meta-schema check is run with:
makedt_binding_checkThis is all documented in
Documentation/devicetree/writing-schema.md.
Ok I'll read that document now. Would be cool if the build robots (and myself) can somehow run the dt_binding_check on a single YAML file so we can quickly validate the binding. Maybe even make C=2 or C=1 do that?
If the robots can then complain if the single file fails to build it will save us tons of time. I just tried to run it but it seems to only care about running on all the YAML files.
Rob Herring
maintainerQuoted 49 lines · Stephen Boyd
Quoting Rob Herring (2019-01-11 12:49:04)
Quoted 9 lines · Stephen Boyd
Quoted 8 lines
Quoting Rob Herring (2019-01-11 10:27:48)
Quoted 6 lines · Stephen Boyd
Quoted 2 lines
Any pointer to the full schema?
https://github.com/robherring/yaml-bindings/blob/master/schemas/
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
And the clock schema in particular:
https://github.com/robherring/yaml-bindings/blob/master/schemas/clock.yamlAwesome. Thanks for the pointers! Is the clock schema posted to the list somewhere?
No. Happy to post things, but I'm struggling to find anyone that cares.
Ok. I can review that document too if you post it to the list.
Quoted 11 lines
Quoted 9 lines
Quoted 5 lines
Quoted 2 lines
Why does title have a full stop?
Because it was there in the original. My script to extract just takes the first line of alphanumeric text.
Ok. I think it would be good to treat them like commit subjects that don't have the full stop either, so if the script is able to drop the full stop it would be great.
I can just write a meta-schema to enforce that. :)
Sounds good.
Quoted 8 lines
Yes, the meta-schema enforces this at least to the extent there is a meta-schema defined for a standard property. Even if not something for a specific property, we limit things to a subset of json-schema keywords. Also, you also can't define something contradicting a core schema (e.g. { reg: { type: string } }), but that wouldn't be found until you check actual DTs.
Quoted 5 lines
The meta-schema check is run with:
makedt_binding_checkThis is all documented in
Documentation/devicetree/writing-schema.md.
Quoted 7 lines
Ok I'll read that document now. Would be cool if the build robots (and myself) can somehow run the
dt_binding_checkon a single YAML file so we can quickly validate the binding. Maybe even make C=2 or C=1 do that?If the robots can then complain if the single file fails to build it will save us tons of time. I just tried to run it but it seems to only care about running on all the YAML files.
make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/file/to/test
It will check only the schema specified and check all the DT files against only that schema (plus any referenced schema if you use a top-level 'allOf'. See the GIC schema patch[2] for an example of that).
I'm running the schema check for patches in the DT patchwork instance. For example, here's this patch[1]. So as long as it has my R-by, then it should be good. I'm not yet running the schema check on DT files because generally there are warnings and I don't intend to fix them for everyone. But maybe I should anyways so we at least have the data.
Rob
[1] https://patchwork.ozlabs.org/patch/1023240/
[2] https://patchwork.ozlabs.org/patch/1023243/
Stephen Boyd
maintainerQuoting Rob Herring (2019-01-11 15:09:58)
Quoted 8 lines
make
dtbs_checkDT_SCHEMA_FILES=Documentation/devicetree/bindings/file/to/testIt will check only the schema specified and check all the DT files against only that schema (plus any referenced schema if you use a top-level 'allOf'. See the GIC schema patch[2] for an example of that).
Quoted 6 lines
I'm running the schema check for patches in the DT patchwork instance. For example, here's this patch[1]. So as long as it has my R-by, then it should be good. I'm not yet running the schema check on DT files because generally there are warnings and I don't intend to fix them for everyone. But maybe I should anyways so we at least have the data.
Ok. I'll apply this patch to clk-next with my small fixes rolled in.