API oversight. This was meant to be there all along together with
Device.parent, for navigating the devicetree, but since a need for it
never came up in gen_defines.py, it got overlooked.
Devices are just devicetree nodes augmented with binding information and
some interpretation of devicetree properties. I wonder if the name
should be changed to something like edtlib.Node to make that clearer.
Calling something like a flash partition a "device" is a bit weird, as
Galak pointed out.
I think I went with Device originally to avoid confusion with
dtlib.Node, but since edtlib users don't directly interact with dtlib,
it might not be that confusing in practice.
Piggyback some documentation clarifications.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Deprecate 'sub-node:' and add a more general 'child-binding:' mechanism
to bindings. Keep supporting 'sub-node:', but print a deprecation
warning when it's used.
Like 'sub-node:', 'child-binding:' gives a binding to child nodes, but
the binding is required to be a complete binding, and is treated (and
checked) like a normal binding.
'child-binding:' can in turn contain another 'child-binding:', up to any
number of levels. This is automatic from treating it like a normal
binding, and from the code initializing parent Devices before child
Devices.
This lets nodes give bindings to grandchildren.
For example, take this devicetree fragment:
parent {
compatible = "foo";
child-1 {
grandchild-1 {
...
};
grandchild-2 {
...
};
};
child-2 {
grandchild-3 {
...
};
};
};
The binding for 'foo' could provide bindings for grandchild-1/2/3 like
this:
compatible: "foo"
# Binding for children
child-binding:
title: ...
description: ...
...
# Binding for grandchildren
child-binding:
title: ...
description: ...
properties:
...
Due to implementation issues with the old devicetree scripts, only two
levels of 'child-binding:' is supported for now. This limitation will go
away in Zephyr 2.2.
Piggyback shortening 'description:' and 'title:' in some bindings that
provide child bindings. This makes the generated header a bit neater.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Instead of
child:
bus: foo
parent:
bus: bar
, have
child-bus: foo
parent-bus: bar
'bus' is the only key that ever appears under 'child' and 'parent'.
Support the old keys for backwards compatibility, with a deprecation
warning if they're used.
Also add 'child/parent-bus' tests to the edtlib test suite. It was
untested before.
I also considered putting more stuff under 'child' and 'parent', but
there's not much point when there's just a few keys I think. Top-level
stuff is cleaner and easier to read.
I'm planning to add a 'child-binding' key a bit later (like 'sub-node',
but more flexible), and child-* is consistent with that.
Also add an unrelated test-bindings/grandchild-3.yaml that was
accidentally left out earlier.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
When foo.yaml set some property 'required: true' and bar.yaml set the
same property 'required: false', the check for changing
'required: false' to 'required: true' would raise an error for
include: [bar.yaml, foo.yaml]
(with that particular order due to implementation details).
The order files are included in shouldn't matter. To fix it, change the
logic so that 'required' values are ORed together between included files
(so that 'required: true' is always respected), and remove the
'required' true-to-false check when merging included files.
Keep the true-to-false check when merging the (merged) included files
into the main binding (the binding with the 'include:' in it). This
might give a good organization, and the old scripts do it too.
Piggyback two fixes/cleanups:
- 'compatible' should be allowed to appear in included files
- No need to allow an 'inherits' key in _check_binding(), because
it has been removed before then, when merging bindings
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Except for a few special properties like 'interrupts' and '#size-cells',
require all devicetree properties on nodes with bindings to be declared
in the binding.
This will help catch misspellings, and makes refactoring and cleanups
safer.
Suggested by Peter A. Bigot.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
For missing optional properties, it can be handy to generate a default
value instead of no value, to cut down on #ifdefs.
Allow a default value to be specified in the binding, via a new
'default: <default value>' setting for properties in bindings.
Defaults are supported for both scalar and array types. YAML arrays are
used to specify the value for array types.
'default:' also appears in json-schema, with the same meaning.
Include misc. sanity checks, like the 'default' value matching 'type'.
The documentation changes in binding-template.yaml explain the syntax.
Suggested by Peter A. Bigot in
https://github.com/zephyrproject-rtos/zephyr/issues/17829.
Fixes: #17829
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>
Doesn't use 'self'. Fixes this pylint warning:
scripts/dts/edtlib.py:272:4: R0201: Method could be a function
(no-self-use)
Fixing pylint warnings for a CI check.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Having backwards compatibility for !include and 'constraint:' is silly
without also having backwards compatibility for 'category:', because
that forces a binding change anyway.
Add backwards compatibility for 'category:', and just print a
deprecation warning when it's used.
Also move tests for deprecated features into a dedicated
test-bindings/deprecated.yaml binding, instead of piggybacking on other
tests.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Have
include: foo.dts
include: [foo.dts, bar.dts]
instead of
inherits:
!include foo.dts
inherits:
!include [foo.dts, bar.dts]
This is a nicer and shorter and less cryptic syntax, and will make it
possible to get rid of the custom PyYAML constructor for '!include'
later.
'inherits: !include ...' is still supported for backwards compatibility
for now. Later on, I'm planning to mass-replace it, add a deprecation
warning if it's used, and document 'include:'. Then the '!include'
implementation can be removed a bit later.
'!include' has caused issues in the past (see the comment above the
add_constructor() call), gets iffy with multiple EDT instances, and
makes the code harder to follow.
I'm guessing '!include' might've been intended to be useful outside of
'inherits:' originally, but that's the only place where it's used. It's
undocumented that it's possible to put it elsewhere.
To implement the backwards compatibility, the code just transforms
inherits:
!include foo.dts
into
inherits:
- foo.dts
and treats 'inherits:' similarly to 'include:'. Previously, !include
inserted the contents of the included file instead.
Some more sanity checks for 'include:'/'inherits:' are included as well.
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>
Use Galak's idea from
https://github.com/zephyrproject-rtos/zephyr/pull/18313 to read the
'properties: compatible: constraint: "foo"' string from bindings in a
more robust way.
First, check if any of the compatible strings are in the file (needed as
an optimization). If any of them are, do a more careful check for the
'properties: compatible: constraint: ...' value matching a compatible,
to filter out false positives from comments and the like.
This commit a no-op in itself besides making things a bit more robust,
but it'll make later work easier (supporting multiple compatibles for a
binding, in a dt-schema-like way).
Co-authored-by: Kumar Gala <kumar.gala@linaro.org>
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).
Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.
This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.
Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.
Piggyback some indentation consistency nits in binding-template.yaml.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Require either type TYPE_EMPTY ('ranges;') or TYPE_NUMS
('ranges = < 1 2 ... >;').
Putting the check in _check_dt() means it will run for all nodes,
including nodes without bindings, which is handy.
The _split() function already gives a decent error message if 'ranges'
has unexpected length, so skip checking the length.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Deriving the type from looking at Property.val gets awkward e.g. when
there are many types that make Property.val a list. Instead, save the
type as given in the binding in Property.type.
Let Property.type just be a string. This has typo potential, but is nice
and flexible (and easy to print), and errors will probably be pretty
obvious.
Show the type in Property.__repr__() as well. This automatically gives
some test coverage.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add two new type-checked property types 'phandles' and 'phandle-array'
to edtlib.
'phandles' is for pure lists of phandles, with no other data, like
foo = < &bar &baz ... >
'phandle-array' is for lists of phandles and (possibly) numbers, like
foo = < &bar 1 2 &baz 3 4 ... >
dt-schema also has the 'phandle-array' type.
Property.val (in edtlib) is set to an array of Device objects for the
'phandles' type.
For the 'phandle-array' type, no Property object is created. This type
is only used for type checking.
Also refactor how types that do not create a Property object
('phandle-array' and 'compound') are handled. Have _prop_val() return
None for them.
The new types are implemented with two new TYPE_PHANDLES and
TYPE_PHANDLES_AND_NUMS types at the dtlib level. There is also a new
Property.to_nodes() functions for fetching the Nodes for an array of
phandles, with type checking.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The contents of 'sub-node:' was assigned as-is as the binding, bypassing
_check_binding(). This also hid an error in
test-bindings/sub-node-parent.yaml.
Require 'sub-node:' to just have 'properties:' in it, and sanity-check
the properties like for regular bindings.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a 'const' property to bindings for any properties that are expected
to have a specifi known value. For example, #address-cells for an I2C
bus should always be '1'. So we can do something like the following in
the I2C bus binding:
"#address-cells":
type: int
category: required
const: 1
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Move the enum checking before we early out for '#' and '-map' properties
so they can benefit from it. Also make the error messages for failed
'enum' check more informative by including the paths to the .dts file
and the binding for the node.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
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>
This is a direct search-and-replace copy of the PWM code.
The name is chosen to match Linux's iio-bindings.txt.
Signed-off-by: Jim Paris <jim@jtan.com>
Move when we early out for properties that start with # like
"#address-cells" or end with -map like "interrupt-map" to after we do
some error checking. This allows us to check those properties at least
exist if they are required.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
'keys' is really a dictionary of options (like {"type": "int", ...}) for
a property. Calling it 'options' makes it clearer.
Also s/prop/prop_name/.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
dtlib is meant to be general and anything-goes re. property values, but
edtlib can be pickier. Check that all 'status' properties have one of
the values listed in the devicetree specification
(https://www.devicetree.org/specifications/), and error out otherwise.
This will get rid of the 'status = "ok"'s (should be "okay") that keep
cropping up.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
We should only assume a GPIO specifier is either named <FOO>-gpios or
gpios. Any other form like ngpios should not be considered a GPIO
specifier. especially since 'ngpios' is the standard property name for
the number of gpio's that are implemented.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Most of the logic for initializing 'clocks' and 'pwms' is the same and
can be shared. Add an EDT._simple_phandle_val_list() helper function for
initializing 'clocks', 'pwms', and any other properties on the form
<foo>s = <phandle value phandle value ...>
where the nodes pointed at by the phandles are expected to have a
'#<foo>-cells' property.
This should make it easier to add similar properties.
There's still some code duplication in the classes (PWM, Clock, etc.),
but also some differences, so I'm wondering if requiring a class for
each might be okay. Maybe some more class-related stuff could be
factored out later.
Piggyback some related cleanup:
- Have _phandle_val_list() take the name of the #foo-cells property
instead of a function for fetching the value. The pattern is always
the same.
- Have _add_names() just take the "foo" part of "foo-names". Same
pattern everywhere.
- Clean up some redundant comments for stuff that's already documented
in docstrings
- Fix error messages printed by _named_cells() ("GPIOS controller" ->
"GPIO controller", etc.)
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Zephyr codebase standardizes in UTF-8 as file encoding. To
accommodate this, we explicitly pass encoding="utf-8" to Python's
open() function, to be independent of any locale setting of a
particular system (e.g., CI/build systems oftentimes have "C",
i.e. ASCII-only, locale). In a few places, we lacked this parameter,
so add it consistently.
Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
gen_defines.py and edtlib.py were recently added in
commit 62d5741476 ("dts: Add new DTS/binding parser").
The old extract_dts_includes.py script allowed for multiple
dts bindings dirs. Let's add that functionality to the new
scripts as well.
Signed-off-by: Michael Scott <mike@foundries.io>
Add a new DTS/binding parser to scripts/dts/ for generating
generated_dts_board.conf and generated_dts_board_unfixed.h.
The old code is kept to generate some deprecated defines, using the
--deprecated-only flag. It will be removed later.
The new parser is implemented in three files in scripts/dts/:
dtlib.py:
A low-level .dts parsing library. This is similar to devicetree.py in
the old code, but is a general robust DTS parser that doesn't rely on
preprocessing.
edtlib.py (e for extended):
A library built on top of dtlib.py that brings together data from DTS
files and bindings and creates Device instances with all the data for
a device.
gen_defines.py:
A script that uses edtlib.py to generate generated_dts_board.conf and
generated_dts_board_unfixed.h. Corresponds to extract_dts_includes.py
and the files in extract/ in the old code.
testdtlib.py:
Test suite for dtlib.py. Can be run directly as a script.
testedtlib.py (uses test.dts and test-bindings/):
Test suite for edtlib.py. Can be run directly as a script.
The test suites will be run automatically in CI.
The new code turns some things that were warnings (or not checked) in
the old code into errors, like missing properties that are specified
with 'category: required' in the binding for the node.
The code includes lots of documentation and tries to give helpful error
messages instead of Python errors.
Co-authored-by: Kumar Gala <kumar.gala@linaro.org>
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
