Add more HOWTO information for the two current devicetree-based device
instantiation styles, and a bit more information on how to create
devices that depend on others.
Point to this from the Kconfig tips page, since it is meant as a
replacement for existing Kconfig practice.
Update macros.bnf.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit renames the Kconfig `FLOAT` symbol to `FPU`, since this
symbol only indicates that the hardware Floating Point Unit (FPU) is
used and does not imply and/or indicate the general availability of
toolchain-level floating point support (i.e. this symbol is not
selected when building for an FPU-less platform that supports floating
point operations through the toolchain-provided software floating point
library).
Moreover, given that the symbol that indicates the availability of FPU
is named `CPU_HAS_FPU`, it only makes sense to use "FPU" in the name of
the symbol that enables the FPU.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
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>
Document how whitespace is used in Kconfig sources. This serves as an
authoritative reference in code review.
Signed-off-by: Sebastian Bøe <sebastian.boe@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>
I think a lot of the confusion with promptless symbols being assigned
might come from opening zephyr/.config, seeing that it assigns a bunch
of promptless symbols, and assuming that Kconfig must respect those
assignments, even though it doesn't.
Explain why zephyr/.config assigns promptless symbols (it's because it
doubles as configuration output). That should clarify things a bit.
Also mention what "invisible" means for symbols early on in the page.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Explain a common subtle Kconfig gotcha where it might appear that
symbols with prompts are incorrectly "stuck" to a particular value in
the menuconfig interface. I've seen it come up several times now, e.g.
in the discussion that lead to
https://github.com/zephyrproject-rtos/zephyr/pull/20702. I also suspect
it's what's causing
https://github.com/zephyrproject-rtos/zephyr/issues/20673.
Also give suggestions for how to make things behave as intended.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Put a short Kconfig overview on the index page that links to the other
Kconfig documentation.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a new 'Setting Kconfig configuration values' page in the new Kconfig
section in 'User and Developer Guides'. Move all the information on
setting Kconfig symbols from 'Application Development' and the board
porting guide into it. The same page now covers both configuration files
and Kconfig.defconfig files.
Add links to the new page in various places to make it easy to find.
Also add some more references to the top-level Kconfig page and other
Kconfig pages.
A lot of stuff was rewritten while moving it over (the CONF_FILE
documentation has been cleaned up in particular). Some new information
has been added as well, like a tip re. minimal configurations being
helpful when making Kconfig settings permanent, and a warning re.
dependencies being ORed rather than ANDed when defining a symbol in
multiple locations.
Fixes: #20915
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Move the documentation for the menuconfig and guiconfig interfaces from
Application Development to a new Interactive Kconfig Interfaces page in
User and Developer Guides.
Also tweak Application Development to mention the configuration
interfaces earlier. It's good to encourage people to try things out in
menuconfig, because dependencies often get lost when people seldom run
it and just hand-edit files.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The Kconfiglib Kconfig extensions are documented in the porting guide,
which is a pretty weird place to document them. Document them under a
new page in the Kconfig section of User and Developer Guides instead.
Also remove the section about the old Zephyr Kconfig behavior for
defaults (tried last-to-first instead of first-to-last). The behavior
was changed 16 months ago (and was undocumented before that), so it
might not be that useful to mention anymore.
Piggyback misc. small language cleanups and organization nits.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Touch up the Kconfig preprocessor function documentation a bit and add
some more details to the example. Use the Kconfig preprocessor call
syntax instead of Python syntax in the function synopses.
Also move the preprocessor docs to a separate page, and add a top-level
Kconfig section to User and Developer Guides that links to the Kconfig
tips page and the preprocessor page.
Trying to avoid the Kconfig tips page becoming a dumping ground for
random Kconfig documentation.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a cleaned-up version of a script I used to find a bunch of unused
symbols and some other Kconfig issues. It's set up to be run directly,
with few environment dependencies.
West is required, because the checks need to see Kconfig files and
source code from all modules.
Checks so far:
- Symbols that can never be anything but n/empty
- Symbols that look unused
- menuconfig symbols with empty menus
- Symbols only defined in Kconfig.defconfig files
See the help strings for the command-line flags for more information.
Some of these checks could probably be checked in CI later, though the
always-n and unused-symbol checks are a bit heuristic and might need a
lot of whitelisting.
Another reason I want to get this in is to have a clean standalone
reference for how to set up the environment for parsing the Kconfig
files. It's gotten trickier over time.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add function that will return 'y' or 'n' if a node pointed to by a
chosen property exists and is enabled.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Replace:
dt_chosen_reg_addr
dt_chosen_reg_size
dt_node_reg_addr
dt_node_reg_size
with:
dt_chosen_reg_addr_int
dt_chosen_reg_size_int
dt_chosen_reg_addr_hex
dt_chosen_reg_size_hex
dt_node_reg_addr_int
dt_node_reg_size_int
dt_node_reg_addr_hex
dt_node_reg_size_hex
So that we get the proper formatted string for the type of symbol.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
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>
Like for other choices, it's the prompt that gets displayed within the
parentheses, not the symbol name.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Takes a while to figure out what it's there for, so explain what it does
and give an example of a good use for it.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Update the files which contain no license information with the
'Apache-2.0' SPDX license identifier. Many source files in the tree are
missing licensing information, which makes it harder for compliance
tools to determine the correct license.
By default all files without license information are under the default
license of Zephyr, which is Apache version 2.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Some people never use the menuconfig, but it makes a good sanity check
when making Kconfig changes, so encourage it for that. Mention a few
things that can be checked in it.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Add a section on how 'if' works to the 'Kconfig - Tips and Best
Practices' page, especially when combined with 'source'.
There seems to have been some confusion here that lead to a bunch of
duplicated dependencies. It's probably simpler than most people assume.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Documentation for kconfigfunctions, mentions they look up elements
in "the DTS generated "conf" style database". This indication
could be cryptic for new zephyr users. Adding the exact name and
path of the file for disambiguation.
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
Clarify the docs for dt_str_val that if the name isn't found we return
and empty string. Also cleanup the code slightly as we don't need to
escape the double quote.
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>
