- Added language info to code-blocks when relevant (ex. for yaml
snippets)
- Formatted grammar for expression language as antlr and added
syntax highlighting
- Fixed various formatting issues with lists, definition lists...
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
In commit commit c19c6fb438
("Revert "scripts: west build: default build.pristine to auto""),
we set the default --pristine value back to 'never', but the
documentation never got updated. Fix it.
Signed-off-by: Martí Bolívar <mbolivar@amperecomputing.com>
There used to be a dedicated style to number headings in a .rst document
but there is currently no actual stylesheet for it, and the added value
is somewhat limited: dropping the associated directive from the GSG.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Generate index of west projects and information about them.
Based on an extension from sdk-nrf repo.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Improves the API documentation including it's structure and integration
into the Zephyr documentation.
Previously the API status of the IEEE 802.15.4 API (and its sub-APIs)
was unclear.
This change adds three APIs in an "unstable" state:
- IEEE 802.15.4 L2 for subsystem developers
- IEEE 802.15.4 drivers for driver developers
- IEEE 802.15.4 net_mgmt for application developers
The corresponding APIs are documented at a group level.
These sub-APIs need to be separately versioned as they have different
audiences, change velocities and levels of stability.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
This migrates the subsys code samples to the new Sphinx code-sample
extension, making it easier to find relevant samples when browsing
API reference.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Document how to use pytest_root keyword. Update docs
with changes in pytest-twister-harness plugin.
Signed-off-by: Grzegorz Chwierut <grzegorz.chwierut@nordicsemi.no>
This adds a few words about using Picolibc without native support
from toolchain, and how to enable this behavior for toolchain.
Signed-off-by: Daniel Leung <daniel.leung@intel.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>
Adds a short stub doc as a placeholder for future documentation in the
charger API.
Signed-off-by: Ricardo Rivera-Matos <rriveram@opensource.cirrus.com>
Add the documentation about I2C_DUMP_MESSAGES and about the
I2C_DUMP_MESSAGES_FILTER in the develop/debug/index.rst doc file.
Signed-off-by: Michał Barnaś <mb@semihalf.com>
Move the chapters about Application Debugging and
Debugging using Eclipse to another file for easier search and
to allow more debugging chapters to be inserted here.
Signed-off-by: Michał Barnaś <mb@semihalf.com>
Fix text that should be linking to the URLs but was missing
the link reference and remove the obsolete links.
Signed-off-by: Michał Barnaś <mb@semihalf.com>
the Test Framework example present in documentation does not work
out of the box and has to be slightly modified. This is an attempt
to fix the example so it would just work directly from documentation.
Signed-off-by: Andrei Hutanu <andrei.hutanu.i@gmail.com>
Now, if the rimage target (meaning rimage configuration and platform name)
is not defined in board.cmake the sign script returns fatal error.
Change this to a warning since there are configurations that are
not using 'west sign' or is used just to glue the headers of the
final image.
Also, update the documentation accordingly.
Signed-off-by: Iuliana Prodan <iuliana.prodan@nxp.com>
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
The puncover tool does not appear to be maintained anymore and it is
affected by multiple issues. Providing it as the first in the list
is a disservice to users as they might get frustrated and not notice
the `ram_report` tool that actually works.
Move the information at the bottom of the section, and add a warning
about the fact that this is a third party tool that might or might
not be working.
(Also make the link consistent to avoid "here" being a hyperlink, it
adds nothing to the reader either in RST or HTML.)
Signed-off-by: Diego Elio Pettenò <flameeyes@meta.com>
We use ZTEST_DMEM and ZTEST_BMEM for running tests with memory shared
between userspace and kernelspace. This ought to be documented.
Document ZTEST_DMEM and ZTEST_BMEM.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
Added the VERSION file to the list of application files.
Added link to the application version management page.
Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
Added several header tags on Application Development.
Edited header hierarchy under Create Application.
Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
Enable the possibility for boards to implement a custom `run` target in
its board.cmake to run any arbitrary commands. This is helpful for devs
who would like to add support for proprietary simulator to their boards
that can't be upstreamed.
Signed-off-by: Yong Cong Sin <ycsin@meta.com>
Linkserver is a utility for launching and managing GDB servers for NXP
debug probes, which also provides a command-line target flash programming
capabilities. Linkserver can be used with NXP MCUXpresso for Visual Studio
Code.
For more information about LinkServer, please visit the LinkServer web
page (link [1] below).
This commit adds a runner to west, supporting debug and flash commands.
Documentation is also added.
[1] - LinkServer web page:
https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/linkserver-for-microcontrollers:LINKERSERVER
Signed-off-by: Yves Vandervennet <yves.vandervennet@nxp.com>
Fix reference to JLink host tools to be located in correct section, so
that output documentation fills in the correct header name when this
section is referenced.
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Add DeviceAbstract class to default imports from pytest-twister-harness
package to simplify importing DUT package, when creating tests.
Signed-off-by: Grzegorz Chwierut <grzegorz.chwierut@nordicsemi.no>
auxdisplay API was introduced in 3.4, not 3.3.
Also update to "experimental" status to better reflect that the API is
new.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Promote DAC API from Experimental to Unstable.
The API is well adopted and used in more than 2 implementations.
Signed-off-by: Martin Jäger <martin@libre.solar>
Promote Task Watchdog API from Experimental to Unstable.
The API has proven to be suitable for its purpose.
Signed-off-by: Martin Jäger <martin@libre.solar>
The docs about how this works are inconsistent. Fix it by
adjusting the docs so they all match the implementation and
are consistent with each other.
Earlier in this page:
Manifest files which appear earlier in the import order have
higher precedence and are therefore concatenated later into the
final group-filter.
Where for "import order" we have:
Importing is done in this order:
1. Manifests from self-import are imported first.
2. The top-level manifest file’s definitions are handled next.
3. Manifests from import-1, …, import-N, are imported in that order.
Therefore, "filter-1 to filter-N" is the wrong precedence order. It
should be "filter-N to filter-1", so that filter-N is lower precedence
than filter-1. That is consistent with import-1 happening before
import-N.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Consolidate information from release-notes.rst into
a new table describing the manifest file format features
which were introduced in each version of west.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Add support for calling the `renode-test` command from west and twister.
Enable running Robot Framework tests suites in Renode.
Signed-off-by: Michał Szprejda <mszprejda@antmicro.com>
Signed-off-by: Mateusz Hołenko <mholenko@antmicro.com>
This commit clarifies that the toolchain-bundled Picolibc in the Zephyr
SDK must also be updated when updating the Picolibc module.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates the link to the "Zephyr SDK Releases" page to point
to the "Tags" page instead of the "Releases" page because:
* "Tags" page is easier to browse by version.
* Download links are not properly rendered on the "Releases" page due
to a GitHub limitation (release body preview content length limit).
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates the documentation to link, instead of the latest,
the specific release of Zephyr SDK referenced in the documentation
because the latest version is subject to change and may not be
compatible with the particular Zephyr release.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit adds "Zephyr SDK version compatibility" section to the
Zephyr SDK documentation, which provides a link to the "Zephyr SDK
Version Compatibility Matrix" and describes the recommended Zephyr SDK
version.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Some 3P logic (Pigweed for example) is already heavily invested in
gTest as a testing framework. Adding the `gtest` harness enables
running the existing 3P tests on various Zephyr platforms and configs.
Signed-off-by: Yuval Peress <peress@google.com>
Update Zephyr modules documentation to use EXTRA_ZEPHYR_MODULES.
This gives a more consistent naming scheme in Zephyr CMake build system.
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>
This commit adds the "Functions" section to the minimal libc
documentation that describes the scope of the C standard library
functions available in the minimal libc.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This was moved to west.configuration in v0.14.0. It happens to work in
the current API docs because the west.manifest module also imports
this class internally, but that's not where it's defined.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit updates the Getting Started Guide and the Zephyr SDK
documentation to point to the Zephyr SDK 0.16.1 release.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Enable the common malloc implementation when using picolibc. Support
existing Picolibc configurations by respecting existing PICOLIBC_HEAP_SIZE
settings.
When PICOLIBC_HEAP_SIZE is set to a value other than -2, then
*always* set COMMON_LIBC_MALLOC_ARENA_SIZE to that value.
Signed-off-by: Keith Packard <keithp@keithp.com>
This will (eventually) permit use of a common malloc implementation with
other C libraries, reducing the amount of Zephyr-specific code required
to support each C library.
Signed-off-by: Keith Packard <keithp@keithp.com>
Adds documentation for the retention subsystem and boot mode
interface. Also marks the retention subsystem as experimental.
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
For users convenience, as it is a typical usecase to
want to see the actual coverage of a set of tests.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
About how do we use it in general, and with lots of links so
people can find more details.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
Since this has been a source of confusion for a while now, add a small
section to clarify the difference between modules and west projects.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
As both C and C++ standards require applications running under an OS to
return 'int', adapt that for Zephyr to align with those standard. This also
eliminates errors when building with clang when not using -ffreestanding,
and reduces the need for compiler flags to silence warnings for both clang
and gcc.
Signed-off-by: Keith Packard <keithp@keithp.com>
- Change "re-run CMake" to "re-run CMake configuration steps" because
`west build -v ...` displays `cmake --build ...` every time which can
confuse non-experts.
- Explain what is the actual issue with re-configuring: it makes the
incremental builds slower. But not much slower:
```
$ west build -b qemu_x86 samples/hello_world/ -DCONFIG_OUTPUT_STAT=y
[133/133] Linking C executable zephyr/zephyr.elf
$ west build -b qemu_x86 samples/hello_world/ -DCONFIG_OUTPUT_STAT=y
[16/16] Linking C executable zephyr/zephyr.elf
```
- Explain that the best solution is to simply skip to the next section
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Invoking `west sign` in `west build` accelerates twister because `west
build` is run in parallel, see rationale in superseded and very
different (CMake-based) PR #52942.
To maximize backwards compatibility:
- `west sign` is optional in `west build`
- `west flash` will sign (again) if any rimage --option is passed
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Use explicit flash command execution timeout at DeviceHandler
instead of the hardcoded value of 60 sec.
When a HW platform executes test cases right after the flash command,
the test case remaining timeout is affected by how much time the flash
operation consumes. Some simulation platforms need to spend significant
amount of time on each 'flash' cycle, usually adding the same delay on
each test case.
This improvement adds two new command line options and device map fields:
--device-flash-timeout - for the flash operation timeout
('flash-timeout' device map field).
--device-flash-with-test - to indicate that the platform flash
command also runs a test case, so the overall timeout should be
calculated as a sum of the flash timeout and the current test case
timeout to receive all console output from the platform
('flash-with-test' device map field).
The device map field values override command line values for the
particular platform where configured.
Default behavior is backward compatible: flash operation fixed timeout
is 60 sec. not including the test case timeout.
Signed-off-by: Dmitrii Golovanov <dmitrii.golovanov@intel.com>
This commit adds the rtc.h header file which contains
API functions for real-time-clocks, which are low power
devices which track and represent broken-down time.
It also changes one line of doxygen documentation in the
maxim_ds3132.h file to place it in its own group.
The handlers for use of the API from userspace is also
added with this commit.
The API is split into one mandatory section, setting and
getting time, and three optional sections, alarms, update
event callback, and clock calibration.
Signed-off-by: Bjarki Arge Andreasen <baa@trackunit.com>
This fixes a typo in the testing framework docs where the
ZTEST_EXPECT_SKIP MACRO seems to be referring to the wrong function.
Signed-off-by: Ivan Herrera Olivares <ivan.herreraolivares@gmail.com>
Clarify the debugging section by adding subsections for the GDB client
and server. Add information about reading the system console while
debugging. Make formatting a bit more consistent generally.
Signed-off-by: Abe Levkoy <alevkoy@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>
WestCommand has no .configuration field, it's .config.
In the same (and cursed!) sentence, also fix the broken link to
west.command.WestCommand by switching the link target from the
unusual `py:class::` to the common `autoclass::` used by all other
classes in the same page. I don't understand why that fixes the
hyperlink but it works and it's consistent.
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Add supplementary header <zephyr/fff_extensions.h>. Add macro
to fff_extensions.h for simplifying definition of custom fake functions
needing call-unique information for producing desired output data.
When an array of custom fake context structures is defined and
the return field within the first structure instance is registered
with the standard SET_RETURN_SEQ() macro of FFF, the
RETURN_HANDLED_CONTEXT() macro provides the inverse logic to
recover the context structure for this called instance. The body of
the custom fake handler is provided to the RETURN_HANDLED_CONTEXT()
macro for appropriate execution and access to the custom fake
parameters.
A test suite is also provided to verify macro implementation and
illustrate usage. It is at:
zephyr/tests/subsys/testsuite/fff_fake_contexts/
This code was verified by:
1. (Pass) west build -p always \
-b unit_testing tests/subsys/testsuite/fff_fake_contexts/ && \
./build/testbinary
2. (Pass) west build -p always \
-b native_posix tests/subsys/testsuite/fff_fake_contexts/ && \
./build/zephyr/zephyr.exe
3. (Pass) ./scripts/twister -p unit_testing \
-T tests/subsys/testsuite/fff_fake_contexts/
4. (Pass) ./scripts/twister -p native_posix \
-T tests/subsys/testsuite/fff_fake_contexts/
5. (Pass) cd doc && build html-fast
Fix#55246
Signed-off-by: Gregory Shue <gregory.shue@legrand.com>
This commit updates the Zephyr SDK installation instructions for the
Zephyr SDK 0.16.0 release.
Note that the distribution bundle archive format has been changed from
`tar.gz` to `tar.xz` for Linux and macOS, and from `zip` to `7z` for
Windows.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Document how sysbuild modules can provide functions that will be invoked
during sysbuild CMake configure time.
The following functions has been documented:
- <module-name>_pre_cmake
- <module-name>_post_cmake
- <module-name>_pre_domains
- <module-name>_post_domains
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
CMake versions <3.20.5 contains the following bug:
https://gitlab.kitware.com/cmake/cmake/-/issues/22310
This bug was fixed in CMake 3.20.5:
https://gitlab.kitware.com/cmake/cmake/-/merge_requests/6232
Generally Zephyr can build with CMake >=3.20.0, however the
`cmake/package_helper.cmake` is impacted by the above issue.
Therefore, specifically request CMake >=3.20.5 for package helper
and update documentation to recommend CMake version 3.20.5 in order
to minimize risk of users being impacted by this bug.
Users invoking package helper with CMake 3.20.0-3.20.4 will see:
> CMake Error at cmake/package_helper.cmake:45 (cmake_minimum_required):
> CMake 3.20.5 or higher is required. You are running version 3.20.x
Rest of Zephyr still builds with CMake versions >=3.20.0.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Fixes#37538 by correctly detecting WSL and blocking bossac from running
on that platform, but allowing it to run on Windows native.
Signed-off-by: João Dullius <joaodullius@bpmrep.com.br>
This page is:
- using literal blocks [1] where it should be using code
blocks [2], which won't produce the desired results [3]
- missing required whitespace between code block directives and their
pygments syntax arguments [4]
In other words, this:
.. code-block::foo
should be:
.. code-block:: foo
- using an incorrect syntax (option:`CONFIG_FOO` or
:kconfig:option:`CONFIG_FOO=y1) to refer to Kconfig
options (should be :kconfig:option:`CONFIG_FOO`, etc)
Fix these issues so we get syntax-highlighted code blocks in the
correct pygments highlight syntax and valid references to Kconfig
options.
Adjust directive content indentation to match the usual .rst style and
make some grammar tweaks as well.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
[2] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
[3] Use of literal blocks can produce the same results if there is a
consistent choice of highlight language specified for the file, but
this file is intermixing code blocks that should be highlighted as
either C or shell commands, so there is no single choice of
highlight syntax that works.
[4] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Twister allows filtering based on kconfigs and dts, however the
filtration is a part of the cmake stage, i.e. the stage has to pass
first and then twister checks if required properties are available.
This causes problems, when the full cmake stage is unable to pass.
If so, other filtration methods had to be used, e.g. platform_allow.
The commit modifies the twister workflow:
if a test defines filters based on kconfig/dts first a cmake package
helper script is used to extract dt and/or kconfigs and if the
conditions are fulfilled it proceeds to a regular cmake stage.
If not, test is skipped.
Co-authored-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Signed-off-by: Maciej Perkowski <Maciej.Perkowski@nordicsemi.no>
We weren't explicit about what we mean by "C++ support" as it relates
to standards versions, and it's been causing some friction in the tree
vs. some of our cruftier toolchains. Add a paragraph to clarify
things.
Fixes#55204
Signed-off-by: Andy Ross <andyross@google.com>
Follow naming pattern in the subsystems(logging or shell) and name
the layer between generic handler and peripheral driver "backend".
The name doesn't suit that well to the SHI backend, because there isn't
SHI API itself and the SHI interface is used only for the host
communication. So the backend code includes the peripheral driver itself.
Signed-off-by: Dawid Niedzwiecki <dawidn@google.com>
Add the zexpect API, inspired by GoogleTest's EXPECT API. This API reports
test failures while allowing test execution to continue. This enables test
reports to show more than a singule failing property on a failing test.
Signed-off-by: Aaron Massey <aaronmassey@google.com>
The release notes are in and west==1.0.0 is installable via pypi.
Move the doc build over to it and fix a typo while we are here.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Document the west v1.0 release, which brings with it stable APIs,
removal of legacy APIs, and other changes.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Briefly explain how a user can change their gdbserver listening device via
the Kconfig option or via shell environment. User is reminded about caveats
regarding using environment variables with CMake systems. Finally, another
invokation of QEMU-with-gdb via west from root directory is presented.
Signed-off-by: Alp Sayin <alpsayin@gmail.com>
This commit adds a deprecation notice for the `xtools` toolchain
variant, which was deprecated in the commit
a9d85ae472.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This describes the capabilities offered by Picolibc along with some of the
requirements applications have when using it.
Signed-off-by: Keith Packard <keithp@keithp.com>
This commit documents the new SCA tool infrastructure.
The existing documentation for sparse are relocated into a dedicated
documentation folder for SCA tools.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
I got a couple of questions about what this command's purpose is and
how to debug 'valid' manifests that aren't working as desired. Add
some information to address this.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
This commit improves the C++ standard library documentation by adding
the list of supported C++ standard libraries.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit reworks the C++ standard library configurations such that:
* the separation between the Zephyr minimal C++ library and the fully
featured C++ standard libraries, such as GNU libstdc++, is clear.
This is done by deprecating the Kconfig `CONFIG_LIB_CPLUSPLUS`
symbol, which implies that the minimal C++ library is selected when
set to `n`, and introducing the `CONFIG_MINIMAL_LIBCPP` symbol.
* the type of the selected C++ standard library is clear. This is done
by introducing a Kconfig choice, `LIBCPP_IMPLEMENTATION`, for the C++
standard library type and providing the choice symbols for each
library type supported, such as `CONFIG_MINIMAL_LIBCPP` and
`CONFIG_GLIBCXX_LIBCPP`.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates all in-tree code to use `CONFIG_CPP_EXCEPTIONS`
instead of `CONFIG_EXCEPTIONS`, which is now deprecated.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates all in-tree code to use `CONFIG_CPP` instead of
`CONFIG_CPLUSPLUS`, which is now deprecated.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit moves the files under `subsys/cpp` directory to the
`lib/cpp` directory because the C++ ABI runtime library and the
standard C++ library components are not a "subsystem" (aka. API) in
conventional sense and is better described as a "library."
Classifying the C++ ABI runtime library and the standard C++ library as
"libraries" instead of "subsystems" also better aligns with how the
existing C standard library implementation (`lib/libc`) is handled.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Adds an option to inform twister a testsuite should only be built and
run for platforms with unique sets of attributes. This enables
for example keying on unique (arch, simulation) platforms to run the test
suite on.
The most common usage may be test suites configured to run once per
(arch, simulation) pair as being enough. Additional information about
platforms may enable running a test once per hardware IP block or once
per soc family or soc avoiding duplicated effort in building and running
tests when once suffices.
Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
We want to be able to have platform or architecture extra configs
without having to duplicate a whole section of the test specification.
This adds support for namespacing of extra configs, for example:
arch:nios2:CONFIG_SYS_CLOCK_TICKS_PER_SEC=1000
or
platform:qemu_x86:CONFIG_FOO=y
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This removes the tinycbor module and replaces references in it
e.g. in sample text to use the zcbor replacement.
Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
The 'Creating an Application' section has existed for several years
and predates the introduction of the example-application repository.
It's still a good reference, but it's not really the easiest way to
make an applications any more. Judging by experience watching users
ask questions and receive support on Discord, the example-application
repository is serving its purpose as a better 'pre-cooked' starting
point.
Adjust the hierarchy so that there's a single, parent section about
creating applications, which has using example-application as one
alternative, and doing it by hand as a less-recommended option. Add
more text on exactly what you need to do with example-application to
get something you can actually use.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The 'Example Application' text is similar to but not the same as the
name of the repository, which is example-application. Use the name of
the repository instead. This is easier to search for and plants seeds
in people's memory about where to find it on GitHub.
Add more cross references.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Add more cross-references to the overview and make a few other
improvements. In particular, adapt to David Kinder's recommended
style (lowercase 'zephyr' for the repository, capitalized 'Zephyr' for
the more general software distribution).
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
A few things are stale or missing:
- Using the term 'kernel' is outdated at this point. It's been years
since Zephyr was just a kernel, and we now include many modules as
well as our internal subsystems and driver layers. Make that clearer
in the overview.
- Devicetree overlays are a basic piece of zephyr applications and
they're worth highlighting at this introductory place as well. Note
that neither app.overlay or prj.conf are actually required to be
present, so if we're mentioning prj.conf here, we might as well
mention app.overlay too.
- Explain the basic purpose of and differences between Kconfig
fragments and DT overlays.
Clean up some other language and provide some more cross references.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
It is well known that putting your application inside the west
workspace where zephyr is installed, i.e. defining a workspace
application, makes it easier to use west build, since you don't have
to juggle setting ZEPHYR_BASE appropriately.
Therefore, recommend doing thing this way, while leaving a hint about
how to do something else.
The current state of affairs where the application is assumed to be in
$HOME/app is longstanding and precedes the introduction of west to
zephyr, and I think it's overdue for the page to get with the times
and use conventions that work well with west: our reference
application has been a workspace application for almost 2 years at
this point.
Create a new meta-variable <app> to describe the location of the
application to keep things short and make it clearer that the actual
location on the file system doesn't matter as long as things are set
up properly.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
When using llvm we need to set the gcov-tool to "llvm-cov gcov" but
the lcov tool is incapable of passing arguments to the gcov-tool. i.e.
the following cannot work:
$ lcov --gcov-tool "llvm-cov gcov" ...
Instead, create a symlink to llvm-cov prefixed as `gcov` which by the
documentation of llvm-cov will alias to `llvm-cov gcov` subcommand.
Signed-off-by: Yuval Peress <peress@google.com>
PlatformIO seems to not keep up with Zephyr (they don't seem to even
support 3.0), so we should not recommend it as an IDE as part of our
official docs. Also, it is frequent to see people reporting problems on
our Discord channels.
Ref. https://github.com/platformio/platform-ststm32/issues/602
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Commit f17630ba75
("doc: application: added description of WARN_EXPERIMENTAL setting")
introduced a new section in the Kconfig settings bit about
experimental features.
This broke the structure of the document, however, because it used the
wrong kind of section underline, resulting in a hierarchy that looks
like this:
Application Configuration
└── Kconfig Configuration
Experimental Features
└── Devicetree Overlays
when it should have looked like this:
Application Configuration
├── Kconfig Configuration
| └── Experimental Features
└── Devicetree Overlays
This falsely make it look like DT overlays are an experimental
feature!
Fix it.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Introduce an API mirroring the CMSIS-DSP's basicmath. If CMSIS_DSP is
enabled, then it will by default be used as a backend. Developers may
opt into a custom backend by setting CONFIG_DSP_BACKEND_CMSIS=n. If
done, the application must provide `zdsp_backend/dsp.h` and optionally
implement the functions in its own .c files.
Signed-off-by: Yuval Peress <peress@google.com>
Update the Getting Started Guide and the Zephyr SDK documentation to
point to the Zephyr SDK 0.15.2 release.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
This commit adds notes about the C++ main() function prototype in the
C++ documentation.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
The modified version information on the API overvirew don't seem very
useful and are updated inconsistently between releases. The release
notes contains much better information about API updates already grouped
by subsystem and release, link to those instead.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
This commit adds the USB-C driver API documentation in peripherals section
of the reference guide. The USB-C VBUS API is declared experimental.
Signed-off-by: Sam Hurst <sbh1187@gmail.com>
The newlib nano variant is currently enabled by default when
`CONFIG_NEWLIB_LIBC=y` and the selected toolchain-architecture
combination includes the newlib nano variant support, even if
`CONFIG_NEWLIB_LIBC_NANO` is not selected by the user.
When `CONFIG_NEWLIB_LIBC=y`, this results in the newlib nano variant
being selected for some architectures (e.g. ARC, ARM and RISC-V), while
the full variant is selected for the rest of the architectures.
The above behaviour is problematic because there exist functional
differences between the newlib full and nano variants (e.g. C99 format
modifiers such as `hh`, `ll`, `z`, `j` and `t` are not available in the
newlib nano variant), and this effectively leads to different level of
C standard support across different architectures when
`CONFIG_NEWLIB_LIBC=y`.
This commit fixes this problem by making the `CONFIG_NEWLIB_LIBC_NANO`
not `default y` and requiring its user to explicitly set this symbol to
`y` when they want to use the newlib nano variant.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This patch introduces a West runner for flashing and debugging with
Lauterbach TRACE32 debuggers. The runner consists of a wrapper around
TRACE32 software, and allows a Zephyr board to execute a custom start-up
script (Practice Script) for the different commands supported, including
the ability to pass extra arguments from CMake. Is up to the board using
this runner to define the actions performed on each command.
The `debug` command launches TRACE32 GUI to allow debug the Zephyr
application, while the `flash` command hides the GUI and executes the
start-up script in a background process.
Signed-off-by: Manuel Arguelles <manuel.arguelles@nxp.com>
Update the Getting Started Guide and the Zephyr SDK documentation to
point to the Zephyr SDK 0.15.1 release.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Add sysbuild flag to twister supported options, with documentation on
how Kconfig and devicetree will be parsed
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
This commit updates the CMake reference file names for custom
toolchains.
The contents of `cmake/generic_toolchain.cmake` and
`cmake/target_toolchain.cmake` were moved
`cmake/modules/FindHostTools.cmake` and
`cmake/modules/FindTargetTools.cmake`, respectively.
Refer to the commit 8d2998d4f9 and
7131d02fa4 for more details.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Update the Sparse documentation to refer to the official Sparse
documentation instead of some random link, which no longeer works.
It also fixes an incorrect inline literal usage.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Use inline literals where applicable -- especially for the words that
contain `@`; otherwise, Sphinx will think it is an email address.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
Describe that using 'HEAD~0' as the revision in manifest files will
cause west to not touch that project.
Signed-off-by: Øyvind Rønningstad <oyvind.ronningstad@nordicsemi.no>
This commit adds "Formatted Output" section to the "C Language Support"
documentation that describes the C library-specific formatted output
support details.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Make code look consistent with other code blocks and remove
double block anchor. Leave code-block to have proper syntax
highlighting.
Signed-off-by: Andrei Emeltchenko <andrei.emeltchenko@intel.com>
Update Modules (External projects) documentation to:
- Recommend explicitly setting the module name in module.yml
- Recommend exposing module-provided headers with an include
pathname beginning with the module-name.
Fixes#49766
Signed-off-by: Gregory SHUE <gregory.shue@legrand.com>
Co-authored-by: Stephanos Ioannidis <root@stephanos.io>
Add note about west boards command to getting started documentation,
to make it easier for users to determine the name of their board when used
with west. Also change "-p auto" to "-p always" in the build step, since
this is more deterministic
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Change default python setup suggested in getting started guide to use
virtual environments. This aligns with the documentation itself, which
suggests that users use virtual environments with Zephyr. The Windows
python setup is also updated with the correct command to create a
virtual environment, as "python3" is not a defined executable in a
windows commandline after installing python with chocolatey
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
Update the Getting Started Guide and the Zephyr SDK documentation to
point to the Zephyr SDK 0.15.0 release.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
In Ubuntu 22.04 there is no need to add any extra repositories
to meet the minimum required versions for tools like cmake and dtc.
In fact, the Kitware repos don't even work in Ubuntu 22.04.
So, instructions updated to explain that step is only required for
Ubuntu versions older than 22.04.
Signed-off-by: Diego Herranz <diegoherranz@diegoherranz.com>
Add the missing piece of documentation for binary blobs: the submission
process. This follows the external source code process relatively close,
but it is relatively simpler.
The proposal includes a new issue template for requesting inclusion of
blob(s) for a particular module.
Fixes#7516.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Given that 3.6 is now several years old and the current and previous
Ubuntu LTS ship with 3.8 or later, upgrade the minimum required Python
version from 3.6 to 3.8.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
:envvar: is currently used to tag environment variables, however,
:envvar: role expects a matching .. envvar:: directive where the
environment variable is defined. This patch fixes some cases by adding
envvar directives and by converting certain cases to literals (it
doesn't make sense to document all env vars in a list, as some are
self-documented by contextual information).
Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/
roles.html#role-envvar
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This page is out of date now that we have blobs infrastructure managed
by west blobs. We need to tell users that they are on their own when
it comes to building applications that require blobs if they aren't
using west.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
From a user perspective, it doesn't really matter that west blobs is
an extension. And again from a user perspective, the fact that the
command is called "blobs" is much more important than knowing that
it's an extension. Similarly, the fact that we host it in zephyr and
why isn't super relevant.
Re-work the docs so that we refer to the command as "west blobs"
instead of "a/the west extension" or "west", for ease of reading.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Extend the existing documentation by documenting the command itself and
the format of the module.yml blobs section.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This is this initial sysbuild guide on what sysbuild is and how to build
a sample using sysbuild.
It provides an architectural overview of sysbuild.
Descriptions on how to use `west build` or `cmake` + `ninja` to build
projects with the sysbuild infrastructure.
Flashing is described through the use of `west flash`.
Extending sysbuild with additional Zephyr based applications are
described, and reference to CMake documentation for including non-Zephyr
based applications are provided.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Devicetree fixup files existed previous to the current stable Devicetree
API. While they served their purpose, they are no longer necessary nor
used in-tree. This patch drops support for this legacy feature.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Updates the ztest_test_fail() function to allow failures in setup.
When executed, a failed assert will fail every test in the suite owning
the setup function. This was verified by adding a suite which asserts
in the setup function and has a test that should pass. During
exeuction, ztest marks the test as failing.
In order to verify exection I also added 2 new APIs:
- ZTEST_EXPECT_FAIL(suite_name, test_name)
- ZTEST_EXPECT_SKIP(suite_name, test_name)
Signed-off-by: Yuval Peress <peress@google.com>
support to use board@revision as platform filter when running
twister, like "twister -p nucleo_f030r8@1 ...".
Signed-off-by: Chen Peng1 <peng1.chen@intel.com>
Add a bunch of missing "zephyr/" prefixes to #include statements in
various test and test framework files.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Update custom test_main example to use updated ZTEST API so
test can either be listed or ran appropriately.
Signed-off-by: Al Semjonovs <asemjonovs@google.com>
This has been removed in:
b710177a27 west: commands: build: Specify source dir without a flag
and hidden from the help, drop it from the documents to avoid confusion.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Documentation now includes:
- How to create a test suite
- How to use predicates
- How to use setup/before/after/teardown
- How to use test rules
- Direct people to use FFF instead of ztest mock
Fixes#47420
Signed-off-by: Yuval Peress <peress@google.com>
Edited the changes added in commit 0a758c3.
The changes aim at including the variable info
in a note before the OS installation procedure for major visibility.
Also added subsections on zephyr_sdk.rst page.
Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
This commit adds the w1 driver API documentation in peripherals section
of the reference guide.
The 1-Wire API is declared as unstable in the API overview.
Signed-off-by: Thomas Stranger <thomas.stranger@outlook.com>
Add an assume API which works like JUnit's. Assumptions can be made
at any point before your test returns (setup, before, and during the
test). If an assumption fails, the test will be marked as skipped.
This helps avoid a cascading affect of failed tests when a base
feature breaks. The feature is expected to have tests and the tests
which depend on it should be skipped (not failed) if that feature
is broken.
Issue #42472
Signed-off-by: Yuval Peress <peress@google.com>
The Python python-magic module that we install for compliance checks
requires libmagic to be installed on the system to work. This requires
extra OS packages on Ubuntu and macOS, and an extra wheel on Windows.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Updates the API and types to match updated I2C terminology. Replaces master
with controller and slave with target.
Updates all drivers to match the changed macros, types, and API signatures.
Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
