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>
This is joint work with Kumar Gala (see signed-off-by).
Document the changes to the generated node macros in macros.bnf,
moving the old file to legacy-macros.bnf and putting it in its own
section.
The actual generated macros are now a low-level detail, so rewrite the
foregoing sections as examples in terms of the new <devicetree.h> APIs.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Add a page describing the high-level design goals for how Zephyr
should use DT, with examples and counter-examples from current
practice.
Add a TBD section for code generation. It's not clear (to me at least)
where the discussion on that has landed.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The one page on devicetree is too long. Split it into multiple pages
to make it easier to digest and more squintable. This is basically
just moving content around; minimal changes have been made apart from
redoing some transitions and adding a couple of introductory paragraphs.
Rename the 'device-tree' Sphinx :ref: target while we are here.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Add detailed documentation for macros that get generated by
gen_defines.py. Covers properties, interrupts, phandle-arrays, clocks,
buses, flash partitions, SPI, etc.
Should be relatively complete now, though there might be overlooked
details.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Co-Authored-By: Kumar Gala <kumar.gala@linaro.org>
Co-Authored-By: Marti Bolivar <marti.bolivar@nordicsemi.no>
zephyr_dt_inputs_outputs.svg still shows the output from dtc being used,
but dtc is unused (except for finding warnings/errors) after the old
devicetree scripts were removed in commit c8c35f76ab ("scripts: dts:
Remove deprecated extract_dts_includes.py script").
Update zephyr_dt_inputs_outputs.svg to show how things are done now.
Also include the new zephyr.dts debugging aid in it. Tweak the
formatting a bit too.
Add zephyr.dts to the diagram in the build overview section too, and
mention zephyr.dts in the text of the devicetree and build overview
pages.
Remove zephyr_dt_inputs_outputs.png and use zephyr_dt_inputs_outputs.svg
directly. Many other places the documentation include SVGs directly, and
there haven't been any complaints, so it probably works fine. The .png
and .svg versions had also drifted out of sync.
Piggyback a link from the devicetree page to the build overview page, to
make it easier to discover.
(I used draw.io to update the diagrams.)
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
generated_dts_board.h is pretty redundant and confusing as a name. Call
it devicetree.h instead.
dts.h would be another option, but DTS stands for "devicetree source"
and is the source code format, so it's a bit confusing too.
The replacement was done by grepping for 'generated_dts_board' and
'GENERATED_DTS_BOARD'.
Two build diagram and input-output SVG files were updated as well, along
with misc. documentation.
hal_ti, mcuboot, and ci-tools updates are included too, in the west.yml
update.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
'title:' was deprecated in commit 2934ee2cda ("dts: bindings: Remove
'title:' and put all info. into 'description:'"). Overlooked leftover.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Rewrite most of the 'Input and output files' section to add more details
and implementation notes, and to make some description more more
concrete:
- Mention dtlib, edtlib, and gen_defines.py, and explain what they do
- Add an example of how macros get generated from the devicetree, and
explain the DT_<node>_<property> format of the generated identifiers.
Merge the 'Include files generation' section into the 'Input and
output files' section at the same time.
- Explain that the base devicetree and the overlays just get
concatenated, and why this works
- Add more details on how dts_fixup.h files work
- Mention that the C dtc compiler is only run to catch errors and
warnings from it
- Mention that the concatenated devicetree appears in
zephyr/<BOARD>.dts.pre.tmp
- Mention /include/, which is the native DTS mechanism for including
other files
- Misc. other minor tweaks
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Turn the CONFIG_* identifiers in the /chosen table into links to the
Kconfig reference.
Also explain why devicetree information doesn't show up in the Kconfig
reference.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
It's cryptic that some identifiers for devicetree-related stuff start
with DT_*, while others start with CONFIG_*. Explain what's going on,
and link to the Kconfig preprocessor documentation.
Also remove an early mention of bindings that might be confusing.
Bindings are much more about checking devicetree conformance than about
controlling output, though they do some of that too.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Not all /chosen properties were documented. Add the missing ones along
with the macros generated for them.
Found with some grepping for '\<zephyr,.*='.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The *_ON_DEV_NAME macros generated from /chosen properties changed
prefix from DT_* to CONFIG_* in commit 8ce0cf0126 ("kconfig: Convert
device tree chosen properties to new kconfigfunctions"), but the
devicetree documentation still lists the old names. Update the
documentation with the correct anmes.
Also remove an outdated reference to
DT_SRAM_SIZE/DT_SRAM_BASE_REFERENCE, and give a complete list of
generated macros.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
I keep mixing these up, so that's probably a sign that the names are
bad. The root of the problem is that "parent-bus" can be read as both
"this is the parent bus" and as "the parent bus is this".
Use 'bus:' for the bus "provider" and 'on-bus:' for nodes on the bus
instead, which is less confusing.
Support the old keys for backwards compatibility, along with a
deprecation warning.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Commit 27e5dd13 fixed a bunch of uses of "device tree" in the
documentation, but accidentally hit the part of the documentation
that stated that "devicetree" should be preferred over "device tree".
Signed-off-by: Josh Gao <josh@jmgao.dev>
There are two set of code supporting x86_64: x86_64 using x32 ABI,
and x86 long mode, and this consolidates both into one x86_64
architecture and SoC supporting truly 64-bit mode.
() Removes the x86_64:x32 architecture and SoC, and replaces
them with the existing x86 long mode arch and SoC.
() Replace qemu_x86_64 with qemu_x86_long as qemu_x86_64.
() Updates samples and tests to remove reference to
qemu_x86_long.
() Renames CONFIG_X86_LONGMODE to CONFIG_X86_64.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Document why and how we use the devicetree nexus map properties to
preserve devicetree flag specifications.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
DTSpec writes this as a single word, presumably to make it easier to
grep for / more precise. Follow along in the rest of the docs now that
our main DT docs page agrees with this usage.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The K6X example is part of the wrong subsection (devicetree vs
kconfig) currently. Move it up to the right place (the section which
was recently renamed to "input and output files")
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Re-work the introductory sections of the devicetree documentation,
adding several figures and cross-references to other useful parts of
the documentation.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Give an example for an interrupt controller, where 'interrupt-cells'
should be used instead.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Added in 2.0, along with some binding format simplifications in 2.1.
Bunch of other stuff that could be mentioned, but keep it relatively
short.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Instead of
properties:
compatible:
constraint: "foo"
, just have
compatible: "foo"
at the top level of the binding.
For backwards compatibility, the old 'properties: compatible: ...' form
is still accepted for now, and is treated the same as a single-element
'compatible:'.
The old syntax was inspired by dt-schema (though it isn't
dt-schema-compatible), which is in turn a thin wrapper around
json-schema (the idea is to transform .dts files into YAML and then
verify them).
Maybe the idea was to gradually switch the syntax over to dt-schema and
then be able to use unmodified dt-schema bindings, but dt-schema is
really a different kind of tool (a completely standalone linter), and
works very differently from our stuff (see schemas/dt-core.yaml in the
dt-schema repo to get an idea of just how differently).
Better to keep it simple.
This commit also piggybacks some clarifications to the binding template
re. '#cells:'.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
- Explain what it means to enable nodes (and for a node to be disabled)
with some sample code from the .dts(i) files
- Explain the '&foo { ... }' syntax
- Linkify files with :zephyr_path:
- Simplify and shorten wording a bit
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add some information that would've saved me a lot of time:
- Give an overview of how device tree nodes and bindings fit together,
with examples. Assume people might be coming at it without knowing
anything about device tree.
- Explain how 'inherits' works in more detail
- Explain what 'parent/child: bus: ...' does more concretely, and what
problem it solves
- Add more examples to show what things look like in the .dts file
- Clean up the language a bit and make things more consistent
Also fix some errors, like 'properties: compatible: ...' being wrong
(missing 'constraint:' and compatible strings in the wrong place).
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
We use the following commands to rename any
SW._GPIO_{CONTROLLER,PIN,FLAGS} to
DT_ALIAS_SW._GPIOS_{CONTROLLER,PIN,FLAGS}
git grep -l SW._GPIO_CONTROLLER | xargs sed -i 's/SW\(.\)_GPIO_CONTROLLER/DT_ALIAS_SW\1_GPIOS_CONTROLLER/g'
git grep -l SW._GPIO_PIN | xargs sed -i 's/SW\(.\)_GPIO_PIN/DT_ALIAS_SW\1_GPIOS_PIN/g'
git grep -l SW._GPIO_FLAGS | xargs sed -i 's/SW\(.\)_GPIO_FLAGS/DT_ALIAS_SW\1_GPIOS_FLAGS/g'
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Convert DT_.*_GPIO_{CONTROLLER,PIN,FLAGS} ->
DT_.*_GPIOS_{CONTROLLER,PIN,FLAGS)
Used the following commands to make these conversions:
git grep -l DT_.*_GPIO_CONTROLLER | xargs sed -i 's/DT_\(.*\)_GPIO_CONTROLLER/DT_\1_GPIOS_CONTROLLER/g'
git grep -l DT_.*_GPIO_PIN | xargs sed -i 's/DT_\(.*\)_GPIO_PIN/DT_\1_GPIOS_PIN/g'
git grep -l DT_.*_GPIO_FLAGS | xargs sed -i 's/DT_\(.*\)_GPIO_FLAGS/DT_\1_GPIOS_FLAGS/g'
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Linking to API material requires knowing the pecularities of how
doxygen, sphinx, and breathe work. In an attempt to hide some of this
we're preparing the current docs to allow use of configuration defaults
that will let us more simply use a default role that will hunt for a
reference target in the various domains that are available by using a
default "role" of "all". This will let us use the simple notation
`functionname` or `typename` without fully specifying the reference as
:c:func:`functionname`.
This patch cleans up exising docs that were (incorrectly) using single
backtics where double backtics should have been used, and also found
some typos (such as a space between the role name and the reference,
such as :file: `filename`, and a missing colon such as
c:func:`functionname`)
This is a start to address issue #14313
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
There is no symbol called CONFIG_SRAM. Mention CONFIG_SRAM_SIZE and
CONFIG_SRAM_BASE_ADDRESS instead, and also mention that the DT_* values
they're generated from.
This gets rid of a false-positive undefined Kconfig symbol reference
too.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a missing semicolon after /dts-v1/, and a blank line between
/dts-v1/ and the root node.
Use 'code-block:: none' instead of 'code-block:: yaml' as well.
DTS is not YAML.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Update dts documentation.
Rework some parts to provide more clarity and elaborate
yaml bindings usage.
Fixes#10318
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
Replace generating CONFIG_ symbols with DT_ symbols for chosen
properties like 'zephyr,console' or 'zephyr,bt-mon-uart'. We now use a
kconfigfunctions (dt_str_val) to extract the info from dts into Kconfig.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Since we know do DTS before Kconfig we should try and remove dts from
creating Kconfig namespaced symbols and leave that to Kconfig. So
rename CONFIG_CCM_<FOO> to DT_CCM_<FOO>.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Move guides and APIs into separate directories and cleanup naming
introducing index files rather than named section files.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
