Each controller node in a phandle-array may set the number of cells in
a specifier as any nonnegative integer. Currently, we don't allow
this in edtlib in the case where there are multiple controllers in a
phandle-array property all of which have 0 cells in the relevant
specifier, which is not correct. Fix this, add a regression test, and
improve the error message while we are here.
Fixes: #28709
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Add a lookup table for finding a node by its dependency ordinal.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Make the scc_order method a property instead. This is in keeping with
the "General biased advice" at the top of file.
The actual order is therefore lazily initialized in this commit and
the order is not computed by the time __init__() returns. The next
commit will invoke scc_order by the time the constructor returns.
This is preparation work for adding a lookup table from dependency
ordinals to nodes. The combination of these two changes will make
intializing that lookup table a bit easier.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Use the pytest test framework in the dtlib.py and edtlib.py test
suites (testdtlib.py and testedtlib.py respectively).
The goal here is not to change what is being tested. The existing test
suite is excellent and very thorough.
However, it is made up of executable scripts where all of the tests
are run using a hand-rolled framework in a single function per file.
This is a bit all-or-nothing and prevents various nice features
available in the de-facto standard pytest test framework from being
used.
In particular, pytest can:
- drop into a debugger (pdb) when there is a problem
- accept a pattern which specifies a subset of tests to run
- print very detailed error messages about the actual and expected
results in various traceback formats from brief to very verbose
- gather coverage data for the python scripts being tested (via plugin)
- run tests in parallel (via plugin)
- It's easy in pytest to run tests with temporary directories
using the tmp_path and other fixtures. This us avoid
temporarily dirtying the working tree as is done now.
Moving to pytest lets us leverage all of these things without any loss
in ease of use (in fact, some things are nicer in pytest):
- Any function that starts with "test_" is automatically picked up and
run. No need for rolling up lists of functions into a test suite.
- Tests are written using ordinary Python 'assert'
statements.
- Pytest magic unpacks the AST of failed asserts to print details on
what went wrong in really nice ways. For example, it will show you
exactly what parts of two strings that are expected to be equal
differ.
For the most part, this is a pretty mechanical conversion:
- extract helpers and test cases into separate functions
- insert temporary paths and adjust tests accordingly to not match
file names exactly
- use 'assert CONDITION' instead of 'if not CONDITION: fail()'
There are a few cases where making this happen required slightly
larger changes than that, but they are limited.
Move the checks from check_compliance.py to a new GitHub workflow,
removing hacks that are no longer needed.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Clean up of devicetree tooling removed generation of information
present in devicetree in nodes that have no compatible, or for extra
properties not defined by a binding. Discussion proposed that these
properties should be allowed, but only in a defined node /zephyr,user.
For that node infer bindings based on the presence of properties.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
We only have one use of _binding_compat and it doesn't need self, so
just fold it into _init_compat2binding.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
We deprecated a number of aspects of the DTS binding syntax in Zephyr
2.1. Remove the support for the deprecated syntax. Remove from docs
about the deprecated syntax as well.
Removed reference in release-notes-2.1.rst to legacy_binding_syntax
since that anchor doesn't exist anymore.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
We have a use case for saving the EDT object to be able to open it up
again later. It would be convenient to be able to do this with the
pickle module from stdlib.
The only thing stopping us from doing that appears to be the open
reference to sys.stderr that's held the edt object even after
EDT.__init__ exits. However, there doesn't seem to be a need to keep
holding on to this object, and in fact it would be a little bit nicer
to drop the reference in case something else (even in the same Python
process that created it originally) wants the EDT object around, but
might want the warn file closed if its refcount zeroes out.
Just drop the reference at the end of __init__ and make EDT._warn()
throw an exception if it's attempted to be used after the constructor
exits.
Make pickle-ability an API guarantee so we can treat any regressions
as bugs going forward.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
I can't see a good reason to be doing this in the Node class's
unit_addr accessor. Move it up to the edtlib initialization so it only
happens once.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Some updates to the reference page for the "core" APIs, and associated
follow-ups in the guides:
- centralize documentation of chosen zephyr nodes in a non-legacy
file, provide a reference to them from the intro page in the guide
- review doxygen docstrings and correct errors for generic APIs
- add introductory text to each section in the API reference
- add missing hardware-specific pages
Documentation for layers built on top of these is mostly left to future
commits, but I do have a smattering of fixes in the guides that I
noticed while I was doing this.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
If we have a fixed-partition on a flash device that is for example on
a spi controller we will not get a binding match currently. This is
because we expect a match between both the compatible and the fact that
fixed-partition node is a decendant of the spi bus.
To address this we treat fixed-partitions as if they are on no bus.
This has the effect of causing a binding match as well as ensuring that
when we process the fixed-partition node we will do anything special to
it because of the bus it happens to be under (for example SPI CS_GPIO
processing).
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Setup node.compats right after we create the Node. This allows access
to the compats information in _bus_node.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
These look up tables generalize the compat2enabled map in a way we
will need to make the API more flexible in Zephyr.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Let's get the actual node status, instead of relying on enabled.
Leave enabled in place for gen_legacy_defines.py's sake.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
If a devicetree node doesn't have a matching binding we will at least
populate a common standard set of properties for that node. The list of
standard properties is:
compatible
status
reg
reg-names
label
interrupt
interrupts-extended
interrupt-names
interrupt-controller
This allows us to handle cases like memory nodes that don't have any
compatible property, we can still generate the reg values.
We limit this to known properties as for any other property we can not
fully determine the property type without a binding and thus we can't
ensure the generation for that property is correct or may not change.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
It's a common operation to want to find a node based on its label. Add
a lookup table to make this easier.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
If the #address-cells property for a register is 0 than we set the addr
value of the reg to None. Similar, if #size-cells is 0 than we set the
size value to None for the reg.
Fixup kconfigfunctions.py to handle reg.size and reg.addr being None.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This returns the entire logical {name: Node} dictionary which is
currently being accessed element by element via chosen_node(name).
It will be used in a new gen_defines.py for moving the handling of
chosen nodes into C from Python.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
spi_dev_cs_gpio() takes a Node and returns the chip select GPIO for it.
Having that information available directly from Node is neater, so turn
it into a Node.spi_cs_gpio property instead.
That gets rid of the only public global function in edtlib, which might
make the API design clearer too.
Tested with the sensortile_box board, which uses SPI chip select.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
It's better to allow per-instance EDT configuration than to set a global
variable on the edtlib module. Enable/disable the warning for reg/unit
address mismatches via a flag to EDT.__init__(), instead of via a global
variable. That makes it consistent too.
Another option would be to pass the 'dtc' flags to EDT.__init__(), but
it makes the interface a bit ugly. Maybe if it needs to emulate lots of
other flags later.
Clarify that edtlib itself isn't meant to have any state in the comment
at the top of the module.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Single-bus warning in python parsing of device tree is suppressed if
this is also suppresed in the device tree compiler.
Signed-off-by: Andrei Gansari <andrei.gansari@nxp.com>
Add an EDT.compat2enabled attribute that maps compatibles to enabled
devicetree nodes that implement them. For example,
EDT.compat2enabled["foo"] is a list of all enabled nodes with "foo" in
the 'compatible' property.
The old Node.instance_no functionality can be implemented in terms of
EDT.compat2enabled, so remove Node.instance_no. EDT.compat2enabled is
more flexible and easier to understand.
Simplify main() in gen_defines.py by using EDT.compat2enabled to
generate the DT_COMPAT_<compatible> existence macros. The behavior is
slightly different now, as DT_COMPAT_<compatible> is generated for
enabled nodes that don't have a binding as well, but that might be an
improvement overall. It probably doesn't hurt at least.
EDT.compat2enabled simplifies the implementation of the new
$(dt_compat_get_str) preprocessor function in
https://github.com/zephyrproject-rtos/zephyr/pull/21560. That was the
original motivation.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Show how the element size was calculated in the error message when a
'reg', 'ranges', or 'interrupts' property has the wrong size. This
should help with debugging. Also mention that #*-cells properties come
from the parent node, which can be subtle.
Came up in https://github.com/zephyrproject-rtos/zephyr/issues/21607
(though it seems the comment disappeared).
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add binding support for a 'path' property type, for properties that are
assigned node paths. Usually, paths are assigned with path references
like 'foo = &label' (common in /chosen), but plain strings are accepted
as well as long as they're valid paths.
The 'path' type is mostly for completeness at this point, but might be
useful for https://github.com/zephyrproject-rtos/zephyr/issues/21623.
The support is there already in dtlib.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
For the following devicetree, view 'nested' as being on the bus.
Previously, only 'node' was considered to be on the bus.
some-bus {
compatible = "foo,bus-controller";
node {
nested {
compatible = "foo,device-on-bus";
};
};
};
In practice, this means that a 'bus:' key in the binding for
'foo,bus-controller' will now get matched up to an 'on-bus:' key in the
binding for 'foo,device-on-bus'.
Change the meaning of Node.bus and add two new attributes Node.on_bus
and Node.bus_node, with these meanings:
Node.bus:
The bus type (as a string) if the node is a bus controller, and
None otherwise
Node.on_bus:
The bus type (as a string) if the node appears on a bus, and None
otherwise. The bus type is determined from the closest parent
that's a bus controller.
Node.bus_node:
The node for the bus controller if the node appears on a bus, and
None otherwise
It's a bit redundant to have both Node.bus_node and Node.on_bus, since
Node.on_bus is the same as Node.bus_node.bus, but Node.on_bus is pretty
handy to save some None checks.
Also update gen_defines.py to use Node.on_bus and Node.bus_node instead
of Node.parent wherever the code deals with buses.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
I keep mixing these up, so that's probably a sign that the names are
bad. The root of the problem is that "parent-bus" can be read as both
"this is the parent bus" and as "the parent bus is this".
Use 'bus:' for the bus "provider" and 'on-bus:' for nodes on the bus
instead, which is less confusing.
Support the old keys for backwards compatibility, along with a
deprecation warning.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Most bindings look something like this:
title: Foo
description: This binding provides a base representation of Foo
That kind of description doesn't add any useful information, as it's
just the title along with some copy-pasted text. I'm not sure what "base
representation" was supposed to mean originally either.
Many bindings also put something that's closer to a description in the
title, because it's not clear what's expected or how the title is used.
In reality, the title isn't used anywhere. 'description:' on the other
hand shows up as a comment in the generated header.
Deprecate 'title:' and generate a long informative warning if it shows
up in a binding.
Next commits will clean up the 'description:' strings (bringing them
closer to 'title:' in most cases) and remove 'title:' from all bindings.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
A property may be optional with a default in a base yaml, then
overridden to be required in a subordinate file. Don't prevent this
by complaining about having a default on a required property.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Erroring out for 'status = "ok"' broke backwards compatibility for a
downstream project. Accept it instead.
Maybe the error could be selectively re-enabled later.
The rest of the code only checks for 'status = "disabled"' (like the old
scripts), so no other updates are needed.
(It's a bit weird that we duplicate the property check in base.yaml.
Thinking of including base.yaml implicitly. Could clean things up then.)
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Python 3.5 and earlier do not preserve dictionary insertion order when
iterating over dictionaries, and do not give the same order between
runs. This broke the dtlib and edtlib test suites and made the output
jump around randomly between runs. It also made device INST_<n> numbers
non-deterministic, which broke some code on Python 3.5 (though
hardcoding device instance numbers in the code might be a bit shaky).
Fix it by using collections.OrderedDict instead of plain dict wherever
order matters. This makes the output identical on all supported Python
versions. It also allows testdtlib.py and testedtlib.py to run in CI,
which uses Python 3.5.
Fixes: #20571
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
edtlib is a library, and modifying yaml.(C)Loader directly interferes
with any binding loading in edtlib clients. To avoid that, add a custom
loader for bindings.
Internally, PyYAML does this, which is why defining a separate class
works:
@classmethod
def add_constructor(cls, tag, constructor):
if not 'yaml_constructors' in cls.__dict__:
cls.yaml_constructors = cls.yaml_constructors.copy()
cls.yaml_constructors[tag] = constructor
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Turns
edt.required_by(node)
edt.depends_on(node)
into
node.required_by
node.depends_on
which might be a bit more readable.
One drawback is that @property hides that there's some slight overhead
in accessing them, but I suspect it won't be meaningful. Caching could
be added if it ever turns out to be.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
(pinctrl-<index> is documented in
Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt in
Linux.)
Add a new Node.pin_states property, derived from any pinctrl-<index>
properties on the node. Node.pin_states holds a list of PinState
objects, where each PinState represents a single pinctrl-<index>
property.
For example, Node.pin_states will have two elements for the 'device'
node below:
device {
pinctrl-0 = <&state_0>;
pinctrl-1 = <&state_1 &state_2>;
pinctrl-names = "default", "sleep";
};
pincontroller {
state_0: state_0 {
...
};
state_1: state_1 {
...
};
state_2: state_2 {
...
};
};
Each PinState holds the list of configurations nodes in
PinState.conf_nodes. For the node above, node.pin_states[1].conf_nodes
will contain the pincontroller/state_1 and pincontroller/state_2 nodes,
for example.
The new functionality isn't used by gen_defines.py yet, so this change
is a no-op in itself, except it adds some error checking for
pinctrl-<index> properties.
If needed, support for #pinctrl-cells and 'pinmux' (not the same thing
as the 'pinmux' properties in Zephyr I think) could be added separately
later. Not sure what belongs in edtlib.py there yet.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Device tree nodes have a dependency on their parents, as well as other
nodes. To ensure driver instances are initialized in the proper we
need to identify these dependencies and construct a total order on
nodes that ensures no node is initialized before something it depends
on.
Add a Graph class that calculates a partial order on nodes, taking
into account the potential for cycles in the dependency graph.
When generating devicetree value headers calculate the dependency
graph and document the order and dependencies in the derived files.
In the future these dependencies may be expressed in binding data.
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
Multi-line comments were stuck as-is between /* and */ in the generated
header, which looks ugly and confusing e.g. for multi-line
binding/property descriptions.
Use this format for multi-line comments in the header instead:
/*
* First line
* Second line
*
* Line after blank line
*/
Also clean up the output a bit by turning some things that were separate
comments into a single multi-line comment. Add some air and reduce line
lengths too.
Before:
/* Generated by gen_defines.py */
/* DTS input file: hifive1.dts.pre.tmp */
/* Directories with bindings: $ZEPHYR_BASE/dts/bindings */
/* Devicetree node: /cpus/cpu@0/interrupt-controller */
/* Binding (compatible = riscv,cpu-intc): $ZEPHYR_BASE/... */
/* Binding description: This binding describes the RISC-V ...
Some extra lines
for testing */
#define DT_INST_0_RISCV_CPU_INTC 1
After:
/*
* Generated by gen_defines.py
*
* DTS input file:
* hifive1.dts.pre.tmp
*
* Directories with bindings:
* $ZEPHYR_BASE/dts/bindings
*/
/*
* Devicetree node:
* /cpus/cpu@0/interrupt-controller
*
* Binding (compatible = riscv,cpu-intc):
* $ZEPHYR_BASE/dts/bindings/interrupt-controller/...
*
* Description:
* This binding describes the RISC-V CPU Interrupt Controller
*
* Some extra lines
* for testing
*/
#define DT_INST_0_RISCV_CPU_INTC 1
Also tweak Node.description and Property.description in edtlib to be
strip()ed instead of rstrip()ed. There's probably no reason to
preserving leading whitespace in them either.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Use the LibYAML-based yaml.CLoader if available instead of yaml.Loader,
which is written in Python and slow. See
https://pyyaml.org/wiki/PyYAMLDocumentation.
This speeds up gen_defines.py from 0.2s to 0.07s on my system, for
-DBOARD=hifive1. It should also make scripts/kconfig/kconfig.py faster,
because it indirectly uses edtlib via
scripts/kconfig/kconfigfunctions.py.
yaml.CLoader seems to be available out of the box when installing with
pip on Ubuntu at least.
Helps with https://github.com/zephyrproject-rtos/zephyr/issues/20104.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Previously, if two bindings had the same 'compatible:'/'parent-bus:'
values, the binding that happened to be loaded last would get used.
Turn it into an error instead. This avoids tricking people into thinking
that bindings get loaded in a defined order.
Maybe overriding bindings could be allowed later, if we need it.
Fixes: #19536
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Simplifies the code a bit.
Looks like the description wasn't rstrip()ed when it came from a
'child-binding:' either. This also indirectly fixes that.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Node._prop_val() returned too early for non-existent booleans, letting
missing 'required: true' booleans slip through without an error.
Fix it by rearranging the code to always do the 'required' check before
returning.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
verify_eq() can be used instead of verify_streq(), since
warnings.getvalue() already returns a string.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a 'warn_file' parameter to EDT.__init__() that gives a 'file' object
to write warnings to. Use it to capture and verify warnings generated
for deprecated features in testedtlib.py. This indirectly gets rid of
possibly broken-looking output when running it.
Because any function that writes warnings now needs to use EDT._warn()
(as self._warn()), some functions were moved into the EDT class.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Implement a nice generalization suggested by Bobby Noelte.
Instead of having a generic #cells key in bindings, have source-specific
*-cells keys. Some examples:
interrupt-cells:
- irq
- priority
- flags
gpio-cells:
- pin
- flags
pwm-cells:
- channel
- period
This makes bindings a bit easier to read, and allows a node to be a
controller for many different 'phandle-array' properties.
The prefix before *-cells is derived from the property name, meaning
there's no fixed set of *-cells keys. This is possible because of the
earlier 'phandle-array' generalization.
The older #cells key is supported for backwards compatibility, but
generates a deprecation warning.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
