In particular, try to demystify Kconfig.defconfig files, and provide
guidelines on whether configuration settings should go in
BOARD_defconfig or Kconfig.defconfig.
The board porting section seems to be the most relevant one here, so put
the documentation there, with some "see also" links from elsewhere.
Things could be reorganized later if needed.
Give a general overview of visible and invisible Kconfig symbols as
well, as that ties in with the configuration scheme.
This is reverse-engineering on my part. The configuration scheme doesn't
seem to be documented anywhere prior.
Fixes: #7159
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
The NFFS partition at the end of flash is also useful for any other
file system or even the Flash Circular Buffer (FCB). Rename the
partition from 'nffs_partition' to 'storage_partition' and make it
depend on a new hidden Kconfig entry which the relevant users will
select (such as NFFS and FCB).
Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
Adding a new kernel object type or driver subsystem requires changes
in various different places. This patch makes it easier to create
those devices by generating as much as possible in compile time.
No behavior change.
Signed-off-by: Leandro Pereira <leandro.pereira@intel.com>
Driver APIs might not implement all operations, making it possible for
a user thread to get the kernel to execute a function at 0x00000000.
Perform runtime checks in all the driver handlers, checking if they're
capable of performing the requested operation.
Fixes#6907.
Signed-off-by: Leandro Pereira <leandro.pereira@intel.com>
The only difference between this call and k_thread_abort() (beyond
some minor performance deltas) is that "cancel" will act as a noop in
cases where the thread has begun execution and will return an error.
"Abort" always succeeds, of course. That is inherently racy when used
as a "stop the thread" API: there's no way in general (or at all in
SMP situations) to know that you're calling this function "early
enough" to catch the thread before it starts.
Effectively, all k_thread_cancel() gives you that k_thread_abort()
doesn't is an indication about whether or not a thread has started.
There are many other ways to get that information that don't require
dangerous kernel APIs.
Deprecate this function. Zephyr's own code never used it except for
its own unit test.
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
The documentation doesn't give the format for listing multiple files in
CONF_FILE (space-separated list).
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
The current application configuration documentation makes it a bit
unclear that configuration files are merged. Rewrite the documentation
to explicitly talk about merging, which I think is less confusing.
Remove the following section from the introduction as well, as I think
it might make people wonder how they can have an existing kernel
configuration when they haven't created one. The updated configuration
section (which the introduction now has a forward reference to)
clarifies the zephyr/.config bit anyway.
If omitted, the application's existing kernel configuration option
values are used; if no existing values are provided, the kernel's
default configuration values are used.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Pressing Y/N to configure boolean configuration symbols probably won't
be supported in the upcoming Python menuconfig implementation, and Space
is much smoother anyway. '?' is smoother than tabbing to '< Help >' too.
Also remove this part, which I couldn't make sense of:
When a non-default entry is selected for options that are
non-numerical, an asterisk :kbd:`*` appears between the square
brackets in the display. There is nothing added added the display
when you select the option's default.
[*] just means the current symbol value is 'y'.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Expand information about the ModemManager issues (spurious AT commands)
and instructions on adding Segger USB devices to the ModemManager
blacklist.
Signed-off-by: Iván Sánchez Ortega <ivan@sanchezortega.es>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
A recent LF change to the Zephyr mailing list hosting software changed
the mailing list names and links to the message archives.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The search result from Sphinx displays raw ReST file snippets showing
the context of the search hit. While we could generate text versions of
the ReST files just for the search results, it would potentially double
the time to generate docs (run once to generate txt files, run again to
generate HTML).
Instead, this patch does a poor man's cleanup of the ReST markup on the
fly when the search summary snippets are written out. Not perfect, but
looks much better.
It does expose a problem that some of our ReST content is not actually
written out into a .rst file. Content that's dynamically generated by
extensions, such as the sample code from zephyr-app-commands, can
yield a search result hit, but there's no hits in the .rst file content
itself.
Line 552-558 are the modified lines from the Sphinx-provided
searchtools.js that does the pattern match/replace.
Addresses: #7032
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
It has been observed that users might "default" to Python2 and pip
will therefore install packages for the wrong Python. pip3 appears to
always be installed when Python3 is installed, so we invoke pip3
instead of pip2 to be safe.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
The logic for walking reverse dependencies (from 'select's and 'imply's)
is a bit tricky to read (and write), and was essentially duplicated in a
few different spots (including in the upcoming menuconfig
implementation).
Use a new split_expr() helper function that's been added to Kconfiglib
to reduce code duplication and make the code more readable.
This also has another nice side effect: The list of symbols that select
a particular symbol now has the symbols in the order that they appear in
the Kconfig files.
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Several users have reported confusion about whether one should stop at
the 'Using MSYS2' guide, or continue following the guide.
To resolve this we title the three options as Option 1,2,3, and change
the wording of the second guide to make it clear that it is an
alternative, not an additional step.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
At the moment "USB Vendor and Product identifiers" is hanging
inside "Subsystem" section.
Signed-off-by: Andrei Emeltchenko <andrei.emeltchenko@intel.com>
Clean up the text, add an important warning, and add a self-contained
example rather than referring to the internal test code.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
Provide board porting guidelines to help achieving a coherent
board library to ease work for people developing application
not board specific and define clear objective to help board
porting reviews.
Signed-off-by: Erwan Gouriou <erwan.gouriou@linaro.org>
This patch introduce doc for settings subsystem
with FCB and File System beck-ends.
Signed-off-by: Andrzej Puzdrowski <andrzej.puzdrowski@nordicsemi.no>
Noticed a typo in the first sentence, then some missing articles further
down, and some other clarity and grammar edits came along.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Modernize macOS instructions to fit the latest packages offered by
Homebrew and macOS High Sierra.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add documentation for two closely-related subystems: dfu and mgmt, which
are currently undocumented.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add a reference to the MCUboot flash partition doc so we can link to it
from other documentation pages.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Using QEMU host on a Zephyr application using IPv4 to access Internet
requires IPv4 forwarding, so show a command to enable IPv4 forwarding.
Signed-off-by: Stig Bjørlykke <stig.bjorlykke@nordicsemi.no>
The new version of the reference page for a symbol lists the following
essential and generally useful information at the top of the page:
- Prompt
- Type
- Help text
- Direct dependencies (from 'depends on', and inherited from if's and
menus)
- Defaults
- Other symbols selecting or implying the symbol
The current symbol value and visibility are no longer displayed. They
don't make much sense in a reference document, as they depend on user
values from configuration files.
The bottom of the reference page also includes the symbol represented in
Kconfig format (including propagated dependencies).
All references to defined symbols appearing in expressions are turned
into links, which can be clicked on to jump to the reference page for
that symbol.
The following (slightly outdated) screenshot gives an idea of the
format:
https://www.dropbox.com/s/a34tlk2ncyus8po/promptandtype.png?dl=0
This commit also removes Kconfiglib 1, since it is no longer used.
Fixes#5622Fixes#6821
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Running 'make html' in doc/ when doc.log is missing or empty gives the
following error if sphinx-build doesn't write anything on stdout/stderr:
Error in ./scripts/filter-doc-log.sh: logfile "doc.log" not found.
Makefile:84: recipe for target ”html” failed
make: *** [html] Error 1
The problem is that scripts/filter-doc-log.sh tests for the existence of
the log file with [ -s ${LOG_FILE} ], which requires it to be nonempty.
Fix it by using -e instead, which only checks if the log file exists.
scripts/filter-known-issues.py ($KI_SCRIPT) seems to be able to deal
with empty files (and runs quickly).
Fixes#6854
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
When sphinx-build is run under Python 2, running e.g. 'make html' in
doc/ currently causes the following error:
Exception occurred:
File "conf.py", line 128, in <module>
from lexer.DtsLexer import DtsLexer
ImportError: No module named lexer.DtsLexer
The problem is that doc/extensions/lexer/ contains no __init__.py file,
which prevents Python 2 from finding submodules in it[1].
The problem does not occur for Python 3, due to implicit namespaces
packages:
https://www.python.org/dev/peps/pep-0420/
Add an empty __init__.py to doc/extensions/lexer/ to fix building when
sphinx-build uses Python 2 (2.7 is still the version recommended on the
Sphinx homepage). This won't alter the behavior for Python 3.
(doc/extensions is added to the search path at the beginning of conf.py
and so doesn't need an __init__.py. doc/extensions/zephyr already has an
empty __init__.py.)
[1] https://docs.python.org/2/tutorial/modules.html#packagesFixes#6851
Signed-off-by: Ulf Magnusson <ulfalizer@gmail.com>
Add a sample that demonstrates a custom board definition. This proves
that BOARD_ROOT works and can be a useful reference when creating a
custom board definition.
Instead of spending time making up a board, the nrf52840_pca10056
board has been copied as-is. And the hello world sample has been used
as the basis for the application.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
In order to avoid duplication, move all information relating to QEMU and
BlueZ from samples to subsystems, and expand to cover BlueZ installation
and usage of Controllers with BlueZ and QEMU in detail.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The documentation is referencing the macro SYS_INIT_PM, but
SYS_INIT_PM does not exist, the correct name is SYS_DEVICE_DEFINE.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
There are several references to config_info in this documentation, but
no introduction to what it is. Including this declaration makes it
possible to understand the documentation.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
The paragraphs on error handling are out-of-place, as they are
abruptly explained in the middle of a section that is about the cruft
involved in declaring and implementing drivers.
This commit moves them into their own section.
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Since commit a792a3d410, adding an ini
file in scripts/sanity_chk/arches/ to support a new board is no longer
needed.
Signed-off-by: Reto Schneider <code@reto-schneider.ch>
Single backslashes outside of a code-block are treated as escape
characters, so need to double up to get a single backslash rendered in
the generated HTML.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Decode Kconfig sources as UTF-8 instead of decoding them according to
the system locale (which might be ascii-only).
Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
Adding missing dependency to the "getting started" documentations.
Without the python3-wheel package, running "pip3 -r requirements.txt"
on a Debian system will fail.
Signed-off-by: Iván Sánchez Ortega <ivan@sanchezortega.es>
