The 'zephyr,memory-region-mpu' property was addede gqas a
convenient way to create and configure MPU regions using information
coming from DT. It has been used a lot since it was introduced so I
guess we can consider it a Zephyr success story ™ .
Unfortunately it has been proved to be a bit limited and with some
important limitations:
1. It was introduced as a property of the compatible
zephyr,memory-region that is used to create linker regions and
sections from DT data. This means that we can actually create MPU
regions only for DT-defined regions and sections.
2. The naming is unfortunate because it is implying that it is used only
for MPU.
3. It is misplaced being in include/zephyr/linker/devicetree_regions.h
and still it has nothing to do with the linker at all.
4. It is exporting a function called LINKER_DT_REGION_MPU that again has
nothing to do with the linker.
Point (1) is also particularly limiting because it is preventing us to
characterize memory regions that are not generated using the
'zephyr,memory-region' compatible, like generic mmio-sram regions.
While we fix all the issues, we also want to extend a bit the range of
usefulness of this property. We are renaming it 'zephyr,memory-attr' and
it is now carrying information about the type of memory the property is
attached to (cacheable, non-cacheable, IO, eXecutable, etc...). The user
can use this property and the DT API coming with it to act on the memory
node it is accompanied by.
We are still providing the DT_MEMORY_ATTR_APPLY() macro that can be used
to create the MPU regions as before, but we are adding also a
DT_MEMORY_ATTR_FOREACH_NODE() macro that can be used to cycle through
the memory nodes and act on those.
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
Rename the gen_handles script and all of its references/associated files
to gen_device_deps. The new new makes things more clear, because the
script just take care of generating, for each device, an array of device
dependencies. While device handles are used internally to store this
information, it is in reality an implementation detail.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This commit clarifies the snippet processing order when multiple
snippets are specified.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Add a reference to the check_init_priorities script in the cmake
"Supporting Scripts and Tools" section.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
This commit adds change snippets to use the new EXTRA_DTC_OVERLAY_FILE
and EXTRA_CONF_FILE Zephyr build system variables instead of
DTC_OVERLAY_FILE and OVERLAY_CONFIG.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Introduce EXTRA_CONF_FILE and EXTRA_DTC_OVERLAY_FILE and remove old
references to OVERLAY_CONFIG.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
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>
