Add any useful information from 'title:' to the 'description:' strings
(e.g. explanations of acronyms), and remove 'title:' as well as any
copy-pasted "this binding gives a ..." boilerplate.
Also clean some description strings up a bit.
Some other things could probably be cleaned up (replacing 'GPIO node'
with 'GPIO controller' on controllers for consistency, for example), but
I kept things close to the original to avoid accidentally messing up.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
With https://github.com/zephyrproject-rtos/zephyr/pull/20185, multi-line
descriptions will be formatted nicely, but using '>' breaks it, because
it removes internal newlines (including between paragraphs).
See https://yaml-multiline.info/.
Replace 'description: >' with 'description: |' to encourage '|'. That'll
prevent '>' from getting copied around and messing up long descriptions.
This will lead to some extra newlines in the output, but it's fine.
Line-wrapping messes up any manual formatting.
The replacement was done with
$ git ls-files 'dts/bindings/*.yaml' | \
xargs sed -i 's/description:\s*>/description: |/'
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Instead of
properties:
compatible:
constraint: "foo"
, just have
compatible: "foo"
at the top level of the binding.
For backwards compatibility, the old 'properties: compatible: ...' form
is still accepted for now, and is treated the same as a single-element
'compatible:'.
The old syntax was inspired by dt-schema (though it isn't
dt-schema-compatible), which is in turn a thin wrapper around
json-schema (the idea is to transform .dts files into YAML and then
verify them).
Maybe the idea was to gradually switch the syntax over to dt-schema and
then be able to use unmodified dt-schema bindings, but dt-schema is
really a different kind of tool (a completely standalone linter), and
works very differently from our stuff (see schemas/dt-core.yaml in the
dt-schema repo to get an idea of just how differently).
Better to keep it simple.
This commit also piggybacks some clarifications to the binding template
re. '#cells:'.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The 'category: required/optional' setting for properties is just a
yes/no thing. Using a boolean makes it clearer, so have
'required: true/false' instead.
Print a clear error when 'category:' is used:
edtlib.EDTError: please put 'required: true' instead of 'category:
required' in 'properties: foo: ...' in
test-bindings/sub-node-parent.yaml - 'category' has been removed
The old scripts in scripts/dts/ ignore this setting, and only print a
warning if 'category: required' in an inherited binding is changed to
'category: optional'. Remove that code, since the new scripts already
have the same check.
The replacement was done with
git ls-files 'dts/bindings/*.yaml' | xargs sed -i \
-e 's/category:\s*required/required: true/' \
-e 's/category:\s*optional/required: false/'
dts/binding-template.yaml is updated as well.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Property type-checking has been pretty rudimentary until now, only
checking things like the length being divisible by 4 for 'type: array',
and strings being null-terminated. In particular, no checking was done
for 'type: uint8-array', letting
jedec-id = < 0xc8 0x28 0x17 >;
slip through when
jedec-id = [ 0xc8 0x28 0x17 ];
was intended.
Fix it by adding a syntax-based type checker:
1. Add Property.type, which gives a high-level type for the property,
derived from the markers added in the previous commit.
This includes types like TYPE_EMPTY ('foo;'),
TYPE_NUM ('foo = < 3 >;'), TYPE_BYTES ('foo = [ 01 02 ];'),
TYPE_STRINGS ('foo = "bar", "baz"'),
TYPE_PHANDLE ('foo = < &bar >;'), and TYPE_COMPOUND (everything not
recognized).
See the Property.type docstring in dtlib for more info.
2. Use the high-level type in
Property.to_num()/to_string()/to_node()/etc. to verify that the
property was assigned in an expected way for the type.
If the assignment looks bad, give a helpful error:
expected property 'nums' on /foo/bar in some.dts to be assigned
with 'nums = < (number) (number) ... >', not 'nums = "oops";'
Some other related changes are included as well:
- There's a new Property.to_bytes() function that works like accessing
Property.bytes, except with an added check for the value being
assigned like 'foo = [ ... ]'.
This function solves problems like the jedec-id one.
- There's a new Property.to_path() function for fetching the
referenced node for assignments like 'foo = &node;', with type
checking. (Strings are accepted too, as long as they give the path
to an existing node.)
This function is used for /chosen and /aliases.
- A new 'type: phandle' type can now be given in bindings, for
properties that are assigned like 'foo = < &node >;'.
- Property.__str__() now displays phandles and path references as they
were written (e.g. '< &foo >' instead of '< 0x1 >', if the
allocated phandle happened to be 1).
- Property.to_num() and Property.to_nums() no longer take a 'length'
parameter, because it makes no sense with the type checking.
- The global dtlib.to_string() and dtlib.to_strings() functions were
removed, because they're not that useful.
- More tests were added, along with misc. minor cleanup in various
places.
- Probably other stuff I forgot.
The more strict type checking in dtlib indirectly makes some parts of
edtlib more strict as well (wherever Property.to_*() is used).
Fixes: #18131
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
No binding has anything but 'version: 0.1', and the code in scripts/dts/
never does anything with it except print a warning if it isn't there.
It's undocumented what it means.
I suspect it's overkill if it's meant to be the binding format version.
If we'd need to tell different versions from each other, we could change
some other minor thing in the format, and it probably won't be needed.
Remove the 'version' fields from the bindings and the warning from the
scripts/dts/ scripts.
The new device tree script will give an error when unknown fields appear
in bindings.
The deletion was done with
git ls-files 'dts/bindings/*.yaml' | xargs sed -i '/^\s*version: /d'
Some blank lines at the beginning of bindings were removed as well.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This patch populates "clocks" property in stm32 usb nodes
for clock related usb configuration code of each dtsi files
Signed-off-by: Francois Ramu <francois.ramu@st.com>
Now that the generation script doesn't look at the "generation" in the
YAML, we can remove it from the binding files.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
YAML document separators are needed e.g. when doing
$ cat doc1.yaml doc2.yaml | <parser>
For the bindings, we never parse concatenated documents. Assume we don't
for any other .yaml files either.
Having document separators in e.g. base.yaml makes !include a bit
confusing, since the !included files are merged and not separate
documents (the merging is done in Python code though, so it makes no
difference for behavior).
The replacement was done with
$ git ls-files '*.yaml' | \
xargs sed -i -e '${/\s*\.\.\.\s*/d;}' -e 's/^\s*---\s*$//'
First pattern removes ... at the end of files, second pattern clears a
line with a lone --- on it.
Some redundant blank lines at the end of files were cleared with
$ git ls-files '*.yaml' | xargs sed -i '${/^\s*$/d}'
This is more about making sure people can understand why every part of a
binding is there than about removing some text.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Move common properties like 'compatible', 'reg', 'reg-names',
'interrupts', 'interrupt-names', and 'label' into one common base.yaml
that all the other yaml's can inherit from. This removes both
duplication and inconsistent definition.
The device specific yamls just need to say if a property is 'required'
or not.
NOTE: due to some generation conflicts we did not covert
'soc-nv-flash.yaml' to use base.yaml.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
After commit 'scripts/dts: Never ignore properties in
generate_node_defines()', pointless entries for 'interrupt-names'
properties show up in generated_dts_board.conf and
generated_dts_board_fixups.h, because many bindings specify
'generate: define' for 'interrupt-names'.
If 'generation: define' is taken as "generate #define's for this
particular property", then only the 'interrupts' property ought to have
'generation: define'. Having it on both 'interrupts' and
'interrupt-names' makes you wonder what it would mean to only have it on
one of them.
Things get a bit confusing since 'interrupt-names' is still used when
determining the macro names generated for 'interrupts', but it's
probably best to have 'generation: define' work in a consistent way
still (and never be a no-op).
Remove 'generation: define' from all 'interrupt-names' bindings.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The 'id' field was never used and tended to just have the compat of the
node. Lets remove it and removed some code in extract_dts_includes.py
related to it. Added a warning if 'id' is set in a yaml so we can
remove it going forward.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>