When debugging devicetree related issues, it may be useful to turn macro
expansion tracking off. Let's document this in the troubleshooting
section.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This is an FAQ and we don't have a satisfactory page that describes
the current state of the world for how to troubleshoot. This leads
to frustrated users and duplicated support efforts. Try to improve
this by at least writing down what people have to do today.
If we ever improve the situation by adding a machine-readable map
between drivers, Kconfig options, and DT compatibles, we can hopefully
do better than this, but at least it's a start.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Fixes misspelling of `scans` in the description of `CONFIG_GEN_ISR_TABLES`
in the build system documentation.
Signed-off-by: Daniel Mangum <georgedanielmangum@gmail.com>
Adds "fragment" to the Kconfig text, this is because these files
are known as Kconfig fragments, and when searching the
documentation for this, all you get are irrelevant results instead
of this page - which is by far the most important one.
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
Update the save-temps instruction to mention the new kconfig option
instead of setting EXTRA_CFLAGS directly.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Document this new build system feature.
Since its purpose is customizing application builds, the logical place
for the main body of documentation is in a new snippets/ directory in
doc/build/. Create that directory and add its initial documentation.
Like boards and samples, however, we expect people to write
documentation for each snippet within the directory that defines the
snippet itself. Therefore, add a new top-level snippets/ directory and
stub out the documentation needed to document individual snippets as
well.
Add documentation and cross-references in other required places as
well.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Existence of enabled GPIO hog nodes cannot be determined using any of the
existing kconfig functions. Add custom kconfig helper function to determine
whether any GPIO hogs nodes are enabled.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
GPIO hog nodes contain a "gpios" property, but unlike other "*-gpios"
properties, these are not phandle-arrays as they only carry the data part
(e.g. pin, flags) but lack the phandles to the (parent) GPIO controller.
Add special devicetree tooling to handle the "gpios" property of GPIO hog
nodes and generate special devicetree helper macros as if they were phandle
arrays.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Since SHIELD_DIRS gets added to DTS_ROOT in dts.cmake, any shield
directories are also places where we look for bindings by default.
This feature is not used in upstream Zephyr, but it is supported,
so document it.
Suggested-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
We have established a convention that the zephyr, prefix in property
names indicates some sort of zephyr-specific extension to a common
binding, or a zephyr-specific driver configuration knob. We also have
established a convention that compatibles which begin with "zephyr,"
are specific to our operating system. Document these facts.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Splitting up the 'general rules' section into subsections makes it
possible to link directly to a particular rule. This is useful when
pointing out an issue during code review, sharing with another
colleague, etc. Adding a local table of contents makes the page
skimmable (it's buried too deeply in the toctree to have sections
listed in the HTML sidebar).
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Now that this information is in a separate page instead of buried at
the bottom of the DT bindings documentation, it's more convenient to
split it up into subsections for readability.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
There's been some confusion about what we mean by hardware
description. We're really talking about the user-facing inputs that
need to be configured per SoC, application, etc. It's fine to do
things like use ifdeffery on a CMSIS header in an aarch32 support file
to decide if the current target has some feature, for instance -- that
sort of thing doesn't *have* to come from DT.
At the same time, we don't want to encourage vendor-specific hardware
configuration languages from creeping into upstream zephyr, so keep
the language strong in an effort to avoid that misinterpretation.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Phandles, specifier spaces, and cell names are simultaneously
extremely common and woefully underdocumented. Address that by:
- reworking our existing documentation on these subjects in
bindings-syntax.rst, fixing missing information in the
property syntax template as well
- adding a standalone guide which describes how all the pieces
fit together, providing a bridge for the gap between
DTS/bindings and C APIs
My goal is not to eventually make this a comprehensive place
where *all* specifier spaces are documented. It would be better (more
scalable, more discoverable) to improve the individual API pages to
cover the devicetree-related conventions that apply in each case.
That's a problem for someone else and another day, but we do need a
few concrete references in the DTS guides to keep the motivation
clear.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The devicetree introduction page is too big. Split it up to improve
readability and restore maintainability. Add more section headers and
do some other rearranging now that it's more convenient to do so.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Generic improvements:
- clean up some language that needs adjusting
- rename some section headers and reorder some content to
improve readability
- add a table of contents to ease search
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The bindings.rst page has gotten too big. Split it up into
sub-documents to improve readability and restore maintainability.
As part of this effort, move the /zephyr,user node documentation into
its own page in the guide. This page has proven extremely difficult
for users to spot in my experience, and it's meant as a convenience,
so let's make the documentation more convenient as well.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Expands kconfigfunctions to include checks for value existence in
an array property by nodelabel, or a chosen's boolean prop value.
Signed-off-by: Stephen Stauts <stephen.stauts@nordicsemi.no>
Add description of how relative devicetree overlay files are picked up
from the application configuration directory.
Also add a link to detailed description of application configuration
directory.
This aligns the devicetree overlays with the description found for
Kconfig configuration files.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Kconfig uses commas to separate macro arguments.
Improve Kconfig documentation by describing to users how this can be
handled when using devicetree Kconfig macros when using devicetree names
which may have commas in them.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Add dt_node_has_compat kconfig function, to check if a node path has a
given compatible string while parsing kconfig files
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Add dt_node_parent kconfig function, to get parent path for a given
devicetree path when parsing kconfig files
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Aside from base properties (maybe for documentation purposes),
`required: false` should not be encouraged.
Signed-off-by: Chris Friedt <cfriedt@meta.com>
DT_CHOSEN_ZEPHYR_FLASH_CONTROLLER_LABEL and
DT_CHOSEN_ZEPHYR_ENTROPY_LABEL were deprecated a couple of releases ago,
so it is time to remove them. Note that the zephyr/devicetree/zephyr.h
is also removed, since both macros were its last content.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The sysbuild documentation refers to CMakeLists.txt which can lead the
user to believe this call can be added to the <sample>/CMakeLists.txt
file.
This file is sourced as part of the Zephyr CMake build and not sysbuild
CMake build.
Therefore change the description to sysbuild.cmake.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
This commit introduces the possibility of a sample to locate
configuration files for extra images that are used when building with
MCUboot.
This allows use-cases where a sample, A, want to include MCUboot but has
adjustments to the default MCUboot configuration.
By adding a Kconfig fragment `<sample>/sysbuild/mcuboot.conf`, then that
fragment will be used together with the default configuration for
MCUboot.
It is also possible to completely replace the MCUboot configuration.
This is done by creating `<sample>/sysbuild/mcuboot/` folder.
This folder will then be used as the `APPLICATION_CONFIG_DIR` when
building MCUboot.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Support referencing module directories by name in CONF_FILE,
OVERLAY_CONFIG, and DTC_OVERLAY_FILE so that projects can reference
overlay files in arbitrary modules.
Verified by passing all the following tests:
./scripts/twister -T tests/cmake/overlays/
Fixes#41830
Signed-off-by: Gregory Shue <gregory.shue@legrand.us>
Follow up to 5b5aa6ebba adding model name
and existence macros for all compatibles of a node that match an entry
in vendor prefixes.
Signed-off-by: Maureen Helm <maureen.helm@intel.com>
Add a new set of helpers for expanding property entries with a
separator. These macros complement DT(_INST)FOREACH_PROP_ELEM(_VARGS) by
adding the capability to expand with a custom separator between property
entries. This allows, in some cases, to re-use existing macros (e.g.
DT_PROP_BY_IDX) without creating an auxiliary macro that just appends a
separator. Example:
```dts
n: node {
...
my-gpios = <&gpioa 0 GPIO_ACTIVE_HIGH>,
<&gpiob 1 GPIO_ACTIVE_HIGH>;
};
```
Before:
```c
#define GPIO_DT_SPEC_BY_IDX_AND_COMMA(node_id, prop, idx) \
GPIO_DT_SPEC_BY_IDX(node_id, prop, idx),
struct gpio_dt_spec specs[] = {
DT_FOREACH_PROP_ELEM(DT_NODELABEL(n), my_gpios,
GPIO_DT_SPEC_BY_IDX_AND_COMMA)
};
```
After:
```c
struct gpio_dt_spec specs[] = {
DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), my_gpios,
GPIO_DT_SPEC_BY_IDX, (,))
};
```
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This commit updates the outdated links to the Kconfig documentation in
the Linux kernel repository with those from the official documentation.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Use inline literals where applicable -- especially for the words that
contain `@`; otherwise, Sphinx will think it is an email address.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Commit 6e9a43be79 ("doc: move DTS under Build/Configuration systems
section") made it so that the internal organization of the API
reference page is no longer visible to users. This means users have to
scroll around looking for macros they need, instead of being able to
look for a section that looks relevant and reading just that.
Fix it by restoring the independent toctree for DT reference material
with an appropriate maxdepth, and adding a local table of contents in
the reference page.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
For a single bus that supports multiple protocols, e.g. I3C and I2C,
the single value "bus:" setting is no longer sufficient, as a I3C bus
cannot be matched to a device having "on-bus: I2C". This commit
extends the "bus:" setting so that it can accept a list of values.
This change allows corresponding devicetree macros to be generated
so that DT_ON_BUS() can work properly in this scenario.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Adds vendor name and existence macros for all compatibles of a node that
match an entry in the vendor prefixes file.
Signed-off-by: Maureen Helm <maureen.helm@intel.com>
It is frequent to see in Devicetree code constructs like:
```c
#define NAME_AND_COMMA(node_id) DT_NODE_FULL_NAME(node_id),
const char *child_names[] = {
DT_FOREACH_CHILD(DT_NODELABEL(n), NAME_AND_COMMA)
};
```
That is, an auxiliary macro to append a separator character in
DT_FOREACH* macros. Non-DT API, e.g. FOR_EACH(), takes a separator
argument to avoid such intermediate macros.
This patch adds DT_FOREACH_CHILD_SEP (and instance/status okay/vargs
versions of it). They all take an extra argument: a separator. With this
change, the example above can be simplified to:
```c
const char *child_labels[] = {
DT_FOREACH_CHILD(DT_NODELABEL(n), DT_NODE_FULL_NAME, (,))
};
```
Notes:
- Other DT_FOREACH* macros could/should be extended as well
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Allow for having array types (array, uint8-array, string-array) be const.
This would allow for something like:
properties:
reg-names:
const: ["foo", "bar"]
To be supported.
Renamed function _check_prop_type_and_default to _check_prop_by_type
as part of this change and Moved the check for 'const' types into
_check_prop_by_type as its similar to the prop_type check and it was
easier to implement in _check_prop_by_type as we already extract
prop_type from the option in that function.
Signed-off-by: Kumar Gala <galak@kernel.org>
Many device pointers are initialized at compile and never changed. This
means that the device pointer can be constified (immutable).
Automated using:
```
perl -i -pe 's/const struct device \*(?!const)(.*)= DEVICE/const struct
device *const $1= DEVICE/g' **/*.c
```
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Update the documentation on the files in the two zephyr cmake packages
we have in tree to remove references to obsolete files, and add
references to missing files.
Fixes: #48047
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Removes references to the label property in devicetree, replacing
them with node label where appropriate.
Signed-off-by: Kevin Townsend <kevin.townsend@linaro.org>
