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>
Similar to edtlib._err(). Just saves a bunch of 'raise DTError'.
Also add tests for some errors from the global to_num() and to_nums()
functions that were untested.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The public DT.get_node() function was used during parsing to look up
paths in references like &{/foo/bar}, along with an ugly
'DT._is_parsing' flag to adapt its behavior (to not mention aliases in
error messages).
Split out common node lookup code needed during parsing and by
get_node() instead, and stop using get_node() during parsing. This
allows '_is_parsing' to be removed and untangles things a bit.
Piggyback some other small reference-related cleanups, and fix an issue
with the filename/linenr being given twice in some error messages.
This commit also removes the index of path components from error
messages, but just the string is probably good enough.
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>
Previously, Property.to_node() would allow assignments like
x = < 1 >;
as long as 1 happened to be a valid phandle. This was deliberate, but
might hide errors, and would make the planned 'phandles' (list of
phandles) and 'phandle-array' (list of phandles and numbers) types a bit
too similar to 'type: array'.
Change Property.to_node() to only accept
x = < &foo >;
This is probably all we need, and if you really need to accept manually
specified phandles, it can be worked around in other ways.
Piggyback some consistency nits in error messages from the
Property.to_*() functions.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
dtlib.py and guiconfig.py do some hackery to build token and image
variable names, which triggers spurious pylint warnings like
scripts/dts/dtlib.py:243:28: E0602: Undefined variable '_T_LABEL'
(undefined-variable)
Suppress the warning for those files. The generated names get used in
lots of places.
Also suppress some warnings in doc/conf.py ('tags' is from Sphinx), and
fix a legitimate issue in scripts/dts/testdtlib.py.
This pylint check is useful enough to want enabled in the upcoming CI
check.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This was allowed due to a misunderstanding:
foo = 'x';
In reality, 'x' works like an integer literal, and is used like this:
foo = < 'x' >;
Fix character literal parsing to match the C tools.
Also fix backslash escape parsing to match the C tools exactly
(get_escape_char() in util.c): \<char> should be turned into <char> if
<char> isn't recognized as a special escape character, instead of being
left alone. This fixes parsing of e.g. '\'' (a character literal with a
single quote in it).
Piggyback some more tests for weird property/node names.
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>
Previously, dtlib just stored the raw 'bytes' value for each property,
along with some markers in Property._markers for phandle and path
references.
Extend Property._markers to also remember where different data blocks
start, so that e.g.
foo = <1 2 3>, "bar", [00 01];
can be reproduced as written.
Use the new information to reproduce properties as written in
Property.__str__(). This gives good test coverage as well, since the
test suite checks literal __str__() output.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
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>
