Remove mention to DT_DRV_COMPAT in brief since DT_FOREACH_STATUS_OKAY
is not relying on it and is taking "compat" as argument.
Signed-off-by: Aymeric Aillet <aymeric.aillet@iot.bzh>
The DT_ENUM_IDX and DT_ENUM_IDX_OR macros did not have the instance
based equivalents. With them many drivers can be simplified.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This adds the macro public API to handle the DT ranges properties.
This also updates the devicetree/api.rst documentation.
Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
Like reg and interrupts, using DT_PROP_LEN doesn't make sense since
the ranges & dma-ranges block lengths and values depends on the DT
node #address-cells, #size-cells and parents #address-cells value.
Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
This contains accessor macros for getting phandles out of pinctrl
properties by name and index. As usual, the representation in C for a
phandle is a node identifier.
Add these new macros:
- DT_PINCTRL_BY_IDX(node_id, pc_idx, idx): phandle at index idx
in the pinctrl-<pc_idx> property
- DT_PINCTRL_0(node_id, idx): pinctrl-0 convenience for the same
- DT_PINCTRL_BY_NAME(node_id, name, idx): phandle at index idx
in the pinctrl property named 'name'
- DT_PINCTRL_NAME_TO_IDX(node_id, name): convert a pinctrl property
name to its index number
- DT_NUM_PINCTRLS_BY_IDX(node_id, pc_idx): number of phandles in
pinctrl-<pc_idx>
- DT_NUM_PINCTRLS_BY_NAME(node_id, name): number of phandles in a
named pinctrl property
- DT_NUM_PINCTRL_STATES(node_id): total number of pinctrl-<pc_idx>
properties
- DT_PINCTRL_HAS_IDX(node_id, pc_idx): does pinctrl-<pc_idx> exist?
- DT_PINCTRL_HAS_NAME(node_id, name): does a named pinctrl property
exist?
- DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx): convert a pinctrl
index to its name as a token, similar to DT_STRING_TOKEN()
- DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, pc_idx): like
DT_PINCTRL_IDX_TO_NAME_TOKEN, but with an uppercase result
As well as DT_DRV_INST equivalents, which take inst wherever node_id
appears above:
- DT_INST_PINCTRL_BY_IDX()
- DT_INST_PINCTRL_0()
- DT_INST_PINCTRL_BY_NAME()
- DT_INST_PINCTRL_NAME_TO_IDX()
- DT_INST_NUM_PINCTRLS_BY_IDX()
- DT_INST_NUM_PINCTRLS_BY_NAME()
- DT_INST_NUM_PINCTRL_STATES()
- DT_INST_PINCTRL_HAS_IDX()
- DT_INST_PINCTRL_HAS_NAME()
- DT_INST_PINCTRL_IDX_TO_NAME_TOKEN()
- DT_INST_PINCTRL_IDX_TO_NAME_UPPER_TOKEN()
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Add two new for-each macros:
- DT_FOREACH_STATUS_OKAY(compat, fn)
- DT_FOREACH_STATUS_OKAY_VARGS(compat, fn, ...)
These can be used to expand "fn" once for every status "okay" node in
the devicetree which has a given compatible. The intended use case is
to allow doing something in C once for each node of a compatible,
but outside of a device driver.
E.g. an application might want to collect an array of structures for a
compatible, where each structure is initialized from a node.
In such cases we don't want people to be forced into using
DT_DRV_COMPAT and instance numbers, because that's in general a hint
that you're doing something driver-like.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
To be able to get a tokenize DT string without the quotes. Deprecate
also DT_ENUM_TOKEN and DT_ENUM_UPPER_TOKEN.
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
`_FOREACH_` macros do not allow the caller to pass additional arguments
to the `fn`. A series of `_VARGS` variants have been added that allow
the caller to pass arbitrary number of arguments to the `fn`:
```
DT_FOREACH_CHILD_VARGS
DT_FOREACH_CHILD_STATUS_OKAY_VARGS
DT_FOREACH_PROP_ELEM_VARGS
DT_INST_FOREACH_CHILD_VARGS
DT_INST_FOREACH_STATUS_OKAY_VARGS
DT_INST_FOREACH_PROP_ELEM_VARGS
```
Signed-off-by: Arvin Farahmand <arvinf@ip-logix.com>
It can be convenient to "iterate" over the elements of a property, in
the same way it is convenient to "iterate" over enabled instances.
Add a new macro for doing this, along with a DT_INST_FOREACH_PROP_ELEM
variant.
This is likely to be more convenient than UTIL_LISTIFY or FOR_EACH in
some situations because:
- it handles inputs of any length
- compiler error messages will be shorter and more self-contained
- it is easier to use with phandle-array type properties, which
require more complicated macro boilerplate when used with
util_macro.h APIs
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This is a helper which allows you to skip the intricacies of instance
numbers to express the intent of "give me a random enabled node with
this compatible; I don't care which one".
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Our description of 'compat' parameters is all over the place.
Make it consistent by picking one.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This macro returns a node's name with unit-adddress, given its node
identifier.
The node name is useful information for the user to utilize for debug
information, similar to DT_NODE_PATH, or DT_LABEL.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Reimplement DT_PHANDLE_BY_IDX() in a way that defers concatenating its
parameters together until after all of them have been expanded, for
reasons that will be taken advantage of in the next patch.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This returns the node identifier for a node's bus. For example, for a
device on an I2C bus, it would return a node identifier for the I2C
bus controller.
We already have a DT_BUS() and DT_INST_BUS_LABEL(), but there hasn't
been a request or need for DT_INST_BUS() up until now, so it didn't
exist yet.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Move the definition to a within a doxygengroup, so its documentation
appears in the reference page.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
It can be useful to check if an unknown devicetree node identifier
refers to a known node. Add a helper for this. Under the hood, we take
advantage of the ordinals API, which provides the unique identifiers
we need.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This macro returns a node's full path, given its node identifier.
The entire path to a node is useful information for the user which can
be added to build-time error messages.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Make generally available the macro that provides the flash device in
which a particular partition can be found.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Whenever a devicetree binding defines a string property whose
enumerated values are all tokenizable, generate C macros for each
property value that are the corresponding tokens.
Note that "token" is distinct from "identifier": both 'foo' and '123'
are valid tokens, but only 'foo' is a valid identifier. We permit some
strings which are not valid identifiers in anticipation that the
generalization may be useful, e.g. when defining macros that paste the
token onto a prefix that makes the whole thing an identifier.
Fixes: #21273
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
We have a use case for checking the results of a DT_PROP_HAS_IDX()
call with COND_CODE_1(). That won't work because its expansion is an
integer comparison; COND_CODE_1() expects a literal 1 or 0.
Adjust the macro implementation so it expands to a literal 1 or 0.
Make this work even when the index argument needs an expansion while
we're at it.
Fixes: #29833
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Rename the devicetree/adc.h header file to devicetree/io-channels.h to
reflect that io-channels are used for both ADC and DAC devicetree
phandles.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Add the first API functions that directly deal with node dependency
ordinals as determined by edtlib:
- DT_DEP_ORD(node_id): node_id's ordinal
- DT_REQUIRES_DEP_ORDS(node_id): list of dep ordinals for node_id's
direct dependencies
- DT_SUPPORTS_DEP_ORDS(node_id): list of dep ordinals for nodes
depending directly on node_id
- DT_INST_ equivalents
This is not meant to be an exhaustive set of macros related to
dependency ordinals; rather, it's a starting out point meant to enable
initial struct device dependency tracking work. We can add more if
needed.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The legacy macros were first deprecated in Zephyr v2.3. Now that
Zephyr v2.4 has been released, that makes two releases where these
macros have been deprecated, so it's OK to remove them.
This leaves support for legacy binding syntax in place. Removing that
is left to future work.
We need to update various pieces of documentation related to flash
partitions that never got updated when the new API was introduced.
Consolidate this information in the flash_map.h API reference page,
since that's really where users will run into it. This also gives us
the opportunity to improve this documentation.
Adjust a couple of kconfigfunctions.py and sanitycheck bits to use
non-legacy edtlib APIs.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
In case a "required: False" enum binding doesn't mention a
default value, but a default value makes sense to be set in the code,
DT_ENUM_IDX_OR could be used to provide the default idx to be used.
New macro comes with appropriate tests.
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
Add a variety of property and specifier cell accessors that fall back
on a default value supplied by the caller if the devicetree does not
contain the requested data.
This is useful for avoiding use of COND_CODE_1() and similarly tricky
macros in applications and drivers.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Reorder the instance number property access macros. The non-instance
number ones appear in this order: DT_PROP(), DT_PROP_LEN(),
DT_PROP_HAS_IDX(), DT_PROP_BY_IDX(), DT_LABEL().
Improves readability slightly by moving code around so INST versions
appear in the same order as non-INST versions.
No functional changes expected.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Add some introductory text to these driver helpers which makes it more
clear how they are defined in terms of the generic APIs, which allows
removing some boilerplate from doxygen. This also gives us a chance to
call out the exceptional cases and add some more documentation to those.
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>
Add DT_NODE_BY_FIXED_PARTITION_LABEL that given a "label" in any
fixed-partitions map will return the node_id for that partition node.
Add DT_NODE_HAS_FIXED_PARTITION_LABEL that will test if a given
fixed-partitions "label" is valid.
Add DT_FIXED_PARTITION_ID that will return an unique ordinal value for
the partition give a node_id to the partition.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
The macro iterates through the list of child nodes in a DT_DRV_COMPAT
instance and invokes provided macro for each node.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
Several reviewers agreed that DT_HAS_NODE_STATUS_OKAY(...) was an
undesirable API for the following reasons:
- it's inconsistent with the rest of the DT_NODE_HAS_FOO names
- DT_NODE_HAS_FOO_BAR_BAZ(node) was agreed upon as a shorthand
for macros which are equivalent to
DT_NODE_HAS_FOO(node) && DT_NODE_HAS_BAR(node) &&
- DT_NODE_HAS_BAZ(node), and DT_HAS_NODE_STATUS_OKAY is an odd duck
- DT_NODE_HAS_STATUS(..., okay) was viewed as more readable anyway
- it is seen as a somewhat aesthetically challenged name
Replace all users with DT_NODE_HAS_STATUS(..., okay), which is
semantically equivalent.
This is mostly done with sed, but a few remaining cases were done by
hand, along with whitespace, docs, and comment changes. These special
cases include the Nordic SOC static assert files.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Swap this out and make the status a parameter.
Leave a couple of cases of DT_NODE_HAS_COMPAT().
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Usually, we want to operate only on "available" device
nodes ("available" means "status is okay and a matching binding is
found"), but that's not true in all cases.
Sometimes we want to operate on special nodes without matching
bindings, such as those describing memory.
To handle the distinction, change various additional devicetree APIs
making it clear that they operate only on available device nodes,
adjusting gen_defines and devicetree.h implementation details
accordingly:
- emit macros for all existing nodes in gen_defines.py, regardless
of status or matching binding
- rename DT_NUM_INST to DT_NUM_INST_STATUS_OKAY
- rename DT_NODE_HAS_COMPAT to DT_NODE_HAS_COMPAT_STATUS_OKAY
- rename DT_INST_FOREACH to DT_INST_FOREACH_STATUS_OKAY
- rename DT_ANY_INST_ON_BUS to DT_ANY_INST_ON_BUS_STATUS_OKAY
- rewrite DT_HAS_NODE_STATUS_OKAY in terms of a new DT_NODE_HAS_STATUS
- resurrect DT_HAS_NODE in the form of DT_NODE_EXISTS
- remove DT_COMPAT_ON_BUS as a public API
- use the new default_prop_types edtlib parameter
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The macro iterates through the list of child nodes and invokes provided
macro for each node.
Signed-off-by: Dominik Ermel <dominik.ermel@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Make drivers multi-instance wherever possible using DT_INST_FOREACH.
This allows removing DT_HAS_DRV_INST in favor of making drivers just
do the right thing regardless of how many instances there are.
There are a few exceptions:
- SoC drivers which use CMake input files (like i2c_dw.c) or otherwise
would require more time to convert than I have at the moment. For the
sake of expediency, just inline the DT_HAS_DRV_INST expansion for
now in these cases.
- SoC drivers which are explicitly single-instance (like the nRF SAADC
driver). Again for the sake of expediency, drop a BUILD_ASSERT in
those cases to make sure the assumption that all supported SoCs have
at most one available instance is valid, failing fast otherwise.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Rename DT_HAS_NODE to DT_HAS_NODE_STATUS_OKAY so the semantics are
clear. As going forward DT_HAS_NODE will report if a NODE exists
regardless of its status.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This default-y option allows continued use of the legacy devicetree
macros.
There are no functional changes yet, but when this is default n,
old-style DT code won't build. At that point, adding any of these will
be a fix to keep old-style code working:
- "CONFIG_LEGACY_DEVICETREE_MACROS=y" to prj.conf
- "-- -DCONFIG_LEGACY_DEVICETREE_MACROS=y" to the west build command
- "-DCONFIG_LEGACY_DEVICETREE_MACROS=y" to the cmake command
This option can be changed to default n in time for the Zephyr 2.3
release. That will provide users of Zephyr 2.2 with a smooth migration
path to the new devicetree.h API after 2.3 is released, which
nonetheless will alert them immediately that something is wrong due to
build errors.
Unfortunately, __DEPRECATED_MACRO is not sufficient in all cases as a
warning to users. This is because, at least in GCC, macros defined
using __DEPRECATED_MACRO cannot be used in preprocessor lines like
"#if DT_SOME_LEGACY_MACRO".
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
With the generation of DT_N_<node-id>_{REG,IRQ}_IDX_<idx>_EXISTS
defines, we can now use the IS_ENABLED macro to implement DT_REG_HAS_IDX
and DT_IRQ_HAS_IDX. This matches how other DT_*_HAS_* macros are
implemented as well as lets us utilize these macros with COND_CODE_1.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Add a devicetree/zephyr.h header, which is meant to contain
definitions for /chosen properties specific to Zephyr.
Currently, this just deals with zephyr,entropy. We add a
DT_CHOSEN_ZEPHYR_ENTROPY_LABEL macro which expands to the label for the
node pointed to by zephyr,entropy.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Move the include of files from include/devicetree/*.h to the end so that
when those files are processes they have access to all previous defined
macros.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
