The mempool implementation doesn't require specific sizes and can
support arbitrary sizes up to the limit of available memory. The
Kconfig documentation on this configuration was confusing user.
Fixes#20418
Signed-off-by: David Leach <david.leach@nxp.com>
Adds a high-level documentation page for the Bluetooth Mesh Shell
subsystem, documenting all available commands and their parameters.
Signed-off-by: Trond Einar Snekvik <Trond.Einar.Snekvik@nordicsemi.no>
Fixing issues with recent versions of breathe 4.19.2:
WARNING: Unparseable C cross-reference: 'struct device'
Invalid C declaration: Expected identifier in nested name, got keyword:
struct [error at 6]
struct device
------^
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Added a link to IEEE GET program web page to suggest
an option of downloading the specification to the users.
Signed-off-by: Uma Praseeda <uma.praseeda@nordicsemi.no>
The generic SPI GPIO chip select support now respects devicetree flags
for signal active level. Update all cs-gpios properties to specify
active low.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Device objects in Zephyr are currently placed into an array by linker
scripts, making it easy to iterate over all devices if the array
address and size can be obtained. This has applications in device
power management, but the existing API for this was available only
when that feature was enabled. It also uses a signed type to hold the
device count.
Provide a new API that is generally available, but marked as internal
since normally applications should not iterate over all devices. Mark
the PM API approach deprecated.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
DEVICE_AND_API_INIT and DEVICE_DEFINE are identical except that
DEVICE_DEFINE adds a parameter providing the device pm control
function, while DEVICE_AND_API_INIT does not. This requires duplicate
implementations where if CONFIG_DEVICE_POWER_MANAGEMENT is enabled
then DEVICE_AND_API_INIT delegates to DEVICE_DEFINE with a dummy pm
control function, and if it is not enabled then DEVICE_DEFINE discards
the parameter and delegates to DEVICE_AND_API_INIT.
DEVICE_INIT is like DEVICE_AND_API_INIT but doesn't provide an API.
Clean this up by refactoring so that DEVICE_DEFINE is the core
implementation, providing with and without device power management
right next to each other where they can be compared and maintained.
Redefine DEVICE_INIT and DEVICE_AND_API_INIT delegate to
DEVICE_DEFINE.
Also remove duplicate code by extracting the variations due to
enabling device power management into macros.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
This file contains definitions for macros which are integral to
significant Zephyr use cases, such as CONTAINER_OF() and various
macros used by devicetree.h internally.
As such, in practice we expect at least advanced (if not intermediate)
users to understand it, so the fact that it's not formally documented
as an API with a stability level is a problem.
Fix that by giving the docstrings a once-over and adding new ones
where they are missing. Move all the remaining non-API macros to
util_internal.h.
Add a Sphinx API page for this header, and include it in the API
overview at "experimental" stability level.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
It was not clear that hexdump messages does not support prepending
with function name. Added clarification.
Signed-off-by: Krzysztof Chruscinski <krzysztof.chruscinski@nordicsemi.no>
The driver API should be assigned at the time the device is defined.
Assigning in the init function is redundant and prevents moving the
pointer to a immutable driver structure.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Now there's an audio reference section move the i2s docs there
as the audio section is a better fit.
Signed-off-by: Peter Robinson <pbrobinson@gmail.com>
K_THREAD_DEFINE can no longer use K_NO_WAIT to specify the delay after
the timer API rework. Fix the documentation to use 0 and add a note.
Fixes#25697.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add some introductory text to these driver helpers which makes it more
clear how they are defined in terms of the generic APIs, which allows
removing some boilerplate from doxygen. This also gives us a chance to
call out the exceptional cases and add some more documentation to those.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Some updates to the reference page for the "core" APIs, and associated
follow-ups in the guides:
- centralize documentation of chosen zephyr nodes in a non-legacy
file, provide a reference to them from the intro page in the guide
- review doxygen docstrings and correct errors for generic APIs
- add introductory text to each section in the API reference
- add missing hardware-specific pages
Documentation for layers built on top of these is mostly left to future
commits, but I do have a smattering of fixes in the guides that I
noticed while I was doing this.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The sidebar for User Mode wasn't set up correctly and
it wasn't obvious that there are linked sub-pages with
design details about memory domains, system calls, kernel
objects, and so forth.
Split the introductory material into its own overview
page and set up the table of contents properly.
The text of the threat model, high level policy details,
and constraints sections is unchanged.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
The device structure definition in the code has drifted from the
displayed version in the documentation. Update the documentation to
match.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
The underlying structure is not suitable for use in API invoked from
user threads for the reasons explained in the edit.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Extend the provided template with annotated examples of API based on
whether the functions must be invokable from user mode threads, since
there are currently no in-tree examples of the specific techniques
required.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Several reviewers agreed that DT_HAS_NODE_STATUS_OKAY(...) was an
undesirable API for the following reasons:
- it's inconsistent with the rest of the DT_NODE_HAS_FOO names
- DT_NODE_HAS_FOO_BAR_BAZ(node) was agreed upon as a shorthand
for macros which are equivalent to
DT_NODE_HAS_FOO(node) && DT_NODE_HAS_BAR(node) &&
- DT_NODE_HAS_BAZ(node), and DT_HAS_NODE_STATUS_OKAY is an odd duck
- DT_NODE_HAS_STATUS(..., okay) was viewed as more readable anyway
- it is seen as a somewhat aesthetically challenged name
Replace all users with DT_NODE_HAS_STATUS(..., okay), which is
semantically equivalent.
This is mostly done with sed, but a few remaining cases were done by
hand, along with whitespace, docs, and comment changes. These special
cases include the Nordic SOC static assert files.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
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>
init_fn is not anymore part of struct device, so let's test instead the
driver's API structure pointer which is also unique per device driver.
Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
This commit renames the Kconfig `FP_SHARING` symbol to `FPU_SHARING`,
since this symbol specifically refers to the hardware FPU sharing
support by means of FPU context preservation, and the "FP" prefix is
not fully descriptive of that; leaving room for ambiguity.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
We have a new heap implementation replacing mem_pool. Add docs on its
API and internals, and add a deprecation note to the mem_pool section.
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
The recent work with k_timeout_t has invalidated much of the existing
timing documentation. Rewrite the section focusing on the new API,
adding details on the internals and driver-facing API. Includes a
porting guide for legacy applications and subsystems.
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
Add some documentation and diagrams for OS library data structures:
dlist/slist, rbtree and ring buffer.
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
The DS3231 is an I2C real-time clock with internal temperature
compensated oscillator, maintaining civil time to 1 s precision with
nominal 2 ppm accuracy from 0-40 Cel.
The basic functionality is exposed as a counter that is always running
at 1 Hz. Much more functionality is exposed as driver-specific API,
including the ability to translate between the time scale of the DS3231
and the time scale of the Zephyr uptime clock. This allows correlation
of events in the system clock to UTC, TAI, or whatever time scale is
used to maintain the DS3231.
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
Rename DT_HAS_NODE to DT_HAS_NODE_STATUS_OKAY so the semantics are
clear. As going forward DT_HAS_NODE will report if a NODE exists
regardless of its status.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This library supports stream writes to flash with
optinal progressive erase.
This module is a direct copy of the functionality found in
subsys/dfu/img_util/flash_img.c
Signed-off-by: Håkon Øye Amundsen <haakon.amundsen@nordicsemi.no>
We did not have any reference to queues and doxygen information were not
linked correctly. Add a placeholder and pull in doxygen data so whenever
someone adds a reference, a link is created.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Struct members are not always documented in the zephyr online HTML
documentation. Enable it for all Bluetooth related documentation
groups.
Signed-off-by: Joakim Andersson <joakim.andersson@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 documentation is well-intentioned but not good advice.
The reason why we have a vtable-like API abstraction at the
driver subsystem level is to introduce object orientation.
The subsystem defintions implement an abstract class that
specific driver implementations all implement, providing
a common interface for end users. Multiple drivers may be
written for a subsystem that are interchangeable to the end
user.
However, there is no point in introducing a vtable-like
abstraction for APIs which are specific to a single driver.
We are not trying to present an interface abstraction which
could support multiple implementations. There is just one.
Simply declare a function in a header, and implement it in
the driver's C file.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
Rename internal macros to use Z_ prefix instead of _K..
Those macros were missed when we did the global renaming activities.
Fixes#24645
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This change adds full shared floating point support for the RISCV
architecture with minimal impact on threads with floating point
support not enabled.
Signed-off-by: Corey Wharton <coreyw7@fb.com>
The original description for isr-ok allowed the function to return an
error if called from an interrupt context, rather than doing its job.
This led to complex descriptions like "isr-ok but not sleep" to
indicate that the function could be called from thread or interrupt
context without visible behavior changes, including returning an
error based on calling context.
Remove the special terminology for cases where a function returns an
error (rather than causing undefined behavior) when invoked from an
interrupt or pre-kernel. Redefine isr-ok to indicate that the call
does what it's supposed to do regardless of interrupt or thread
context, delegating the description of allowed behaviors to the API
documentation (which should explicitly note when it's allowed to fail
to perform in non-thread context).
This also makes more clear that isr-ok applies to functions regardless
of whether they can cause an invoking thread to context switch.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
The previous architecture proved unable to support user expectations,
so the API has been rebuilt from first principles. Backward
compatibility cannot be maintained for this change.
Key changes include:
* Formerly the service-provided transition functions were allowed to
sleep, and the manager took care to not invoke them from ISR
context, instead returning an error if unable to initiate a
transition. In the new architecture transition functions are
required to work regardless of calling context: it is the service's
responsibility to guarantee the transition will proceed even if it
needs to be transferred to a thread. This eliminates state machine
complexities related to calling context.
* Constants identifying the visible state of the manager are exposed
to clients through both notification callbacks and a new monitor API
that allows clients to be notified of all state changes.
* Formerly the release operation was async, and would be delayed for the
last release to ensure a client would exist to be notified of any
failures. It is now synchronous.
* Formerly the cancel operation would fail on the last client associated
with a transition. The cancel operation is now synchronous.
* A helper function is provided to safely synchronously release a
request regardless of whether it has completed or is in progress,
satisfying the use case underlying #22974.
* The user-data parameter to asynchronous notification callbacks has
been removed as user data can be retrieved from the CONTAINER_OF
the client data.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
This adds USB_PID_BLE_HCI_H4_SAMPLE along with it driver which uses H4
over bulk endpoints.
Signed-off-by: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
DAC (digital to analog converter) peripheral driver with a generic API
suitable for most MCUs (only basic DAC features considered).
Signed-off-by: Martin Jäger <martin@libre.solar>
