Replaced incorrect rst link references in the description
of traversing ancestor nodes, along with some conflicting
descriptions.
Signed-off-by: James Roy <rruuaanng@outlook.com>
Add a note to status property that disabled parent nodes do not
implicitly disable child nodes.
Issue #82040
Signed-off-by: Andreas Rudolf <andreas.rudolf@husqvarnagroup.com>
This updates the documentation of all the Qemu boards
to use the new `zephyr:board::` directive.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This adds zephyr,touch property to boards with touch controllers, analogous
to `zephyr,display`.
Signed-off-by: Dominik Lau <dlau@internships.antmicro.com>
Signed-off-by: Filip Kokosinski <fkokosinski@antmicro.com>
The Linux binding DO's and DONT's about designing DT bindings
pretty much all apply to Zephyr as well, and a lot of these issues
come up in reviews in Zephyr, which is the reason that Linux has
this page in the first place, to list common binding review topics.
Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
Adds missing code-sample directive to the Hello World sample in
preparation for upcoming changes to the Zephyr documentation that will
be leveraging the provided description and metadata.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Dangling hyphens at the end of a line are usually a problem, ie. you
have an "hyphenated-word" and breaking it on two line will render it as
"hyphenated- word".
This commit fixes the few occurences of such dangling hyphens.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The current driver contains assembly code which is specific for the nRF51
SOC which makes it incompatible with other SOC's. This patch adds support
for other nRF SOC's as well. The timing is calucated based on the CPU clock
frequency, but can be configured manually as well if needed.
Changes have been verified on a Adafruit Feather nRF52840 Express board,
which contains a single NeoPixel RGB LED. Timings have been verified using
a scope connected to the WS1812 data line.
Signed-off-by: Chaim Zax <chaim.zax@zaxx.pro>
Describe the samples using code-sample directive in preparation for
upcoming changes to the Zephyr documentation that will be leveraging
the provided description and metadata.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add the following new macros:
- DT_FOREACH_NODELABEL
- DT_FOREACH_NODELABEL_VARGS
- DT_INST_FOREACH_NODELABEL
- DT_INST_FOREACH_NODELABEL_VARGS
These are for-each helpers for iterating over the node labels of a
devicetree node. Since node labels are unique in the entire
devicetree, their token representations can be useful as unique IDs in
code as well.
As a first user of these, add:
- DT_NODELABEL_STRING_ARRAY
- DT_INST_NODELABEL_STRING_ARRAY
The motivating use case for these macros is to allow looking up a
struct device by devicetree node label in Zephyr shell utilities.
The work on the shells themselves is deferred to other patches.
To make working with the string array helpers easier, add:
- DT_NUM_NODELABELS
- DT_INST_NUM_NODELABELS
Signed-off-by: Martí Bolívar <mbolivar@amperecomputing.com>
Update references to devicetree chosen properties and how devicetree nodes
should be defined in order to enable the new HCI drivers.
Signed-off-by: Johan Hedberg <johan.hedberg@silabs.com>
Namespaced the generated headers with `zephyr` to prevent
potential conflict with other headers.
Introduce a temporary Kconfig `LEGACY_GENERATED_INCLUDE_PATH`
that is enabled by default. This allows the developers to
continue the use of the old include paths for the time being
until it is deprecated and eventually removed. The Kconfig will
generate a build-time warning message, similar to the
`CONFIG_TIMER_RANDOM_GENERATOR`.
Updated the includes path of in-tree sources accordingly.
Most of the changes here are scripted, check the PR for more
info.
Signed-off-by: Yong Cong Sin <ycsin@meta.com>
Commit 5871ff010b
added support for generated DT macros to get the number
of child nodes of a node, but we forgot to update
the documentation of the augmented Backus–Naur form
of the DT macros to reflect this addition.
Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
Adds details about Kconfig fragments and devicetree overlay files
that will be included in a build if they are found in the
``socs`` folder
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
Currently it is tedious to know the level of an interrupt for
a node in C. One would have to go through a very complex and
error prone macros to check if there's a parent interrupt
controller & if the controller has an interrupt number and thus
not a pseudo interrupt controller like the one found in
`rv32m1`. The level of a node is required to encode the
Zephyr's multi-level interrupt number
Since it is easier to do it in the `gen_defines` script, let's
do the heavy lifting there so that we can introduce new DT
macros to get the interrupt level very easily later.
Signed-off-by: Yong Cong Sin <ycsin@meta.com>
Extend the gen_defines.py write_interrupts(node) function to
generate macros to get the interrupt controller for an
interrupt specifier by idx and by name.
The information is already generated by edtlib.py and stored in
node.interrupts[].controller. This addition uses the node pointed
to by the controller member to generate the following example output
define DT_N_S_device1_IRQ_IDX_0_CONTROLLER \
DT_N_S_gpio_800
define DT_N_S_device1_IRQ_NAME_test4_CONTROLLER \
N_S_device1_IRQ_IDX_0_CONTROLLER
Signed-off-by: Bjarki Arge Andreasen <bjarki@arge-andreasen.me>
Another round of repeated words cleanup. This commit tries to keep the
diff minimal and line wrapping was mostly left intact in the touched
files, as having them consistent across the documentation is probably
the topic of a future tree-wide cleanup (or not)
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Update the inter-node dependencies documentation to clarify the child
node dependency inheritance recently introduced in 403640b75e.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Make sure devicetree code blocks all have proper pygments language set.
Fixed a few other "none" code blocks as well.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This is the final step in making the `zephyr,memory-attr` property
actually useful.
The problem with the current implementation is that `zephyr,memory-attr`
is an enum type, this is making very difficult to use that to actually
describe the memory capabilities. The solution proposed in this PR is to
use the `zephyr,memory-attr` property as an OR-ed bitmask of memory
attributes.
With the change proposed in this PR it is possible in the DeviceTree to
mark the memory regions with a bitmask of attributes by using the
`zephyr,memory-attr` property. This property and the related memory
region can then be retrieved at run-time by leveraging a provided helper
library or the usual DT helpers.
The set of general attributes that can be specified in the property are
defined and explained in
`include/zephyr/dt-bindings/memory-attr/memory-attr.h` (the list can be
extended when needed).
For example, to mark a memory region in the DeviceTree as volatile,
non-cacheable, out-of-order:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_VOLATILE |
DT_MEM_NON_CACHEABLE |
DT_MEM_OOO )>;
};
The `zephyr,memory-attr` property can also be used to set
architecture-specific custom attributes that can be interpreted at run
time. This is leveraged, among other things, to create MPU regions out
of DeviceTree defined memory regions on ARM, for example:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-region = "NOCACHE_REGION";
zephyr,memory-attr = <( DT_ARM_MPU(ATTR_MPU_RAM_NOCACHE) )>;
};
See `include/zephyr/dt-bindings/memory-attr/memory-attr-mpu.h` to see
how an architecture can define its own special memory attributes (in
this case ARM MPU).
The property can also be used to set custom software-specific
attributes. For example we can think of marking a memory region as
available to be used for memory allocation (not yet implemented):
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_NON_CACHEABLE |
DT_MEM_SW_ALLOCATABLE )>;
};
Or maybe we can leverage the property to specify some alignment
requirements for the region:
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_CACHEABLE |
DT_MEM_SW_ALIGN(32) )>;
};
The conventional and recommended way to deal and manage with memory
regions marked with attributes is by using the provided `mem-attr`
helper library by enabling `CONFIG_MEM_ATTR` (or by using the usual DT
helpers).
When this option is enabled the list of memory regions and their
attributes are compiled in a user-accessible array and a set of
functions is made available that can be used to query, probe and act on
regions and attributes, see `include/zephyr/mem_mgmt/mem_attr.h`
Note that the `zephyr,memory-attr` property is only a descriptive
property of the capabilities of the associated memory region, but it
does not result in any actual setting for the memory to be set. The
user, code or subsystem willing to use this information to do some work
(for example creating an MPU region out of the property) must use either
the provided `mem-attr` library or the usual DeviceTree helpers to
perform the required work / setting.
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
- Updated basic samples READMEs to use the new zephyr:code-sample::
directive. Dropped "-sample" suffix that's not required anymore now
that samples have their own namespace.
- Updated all references to the samples to use the :zephyr:code-sample:
role. Checked and updated the wording of said references to account
for the fact that samples should not have "... sample" in their name
anymore.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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>
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>
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>
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>
