Refactor best practices from the API refactoring issue and integrate
them into the existing documentation.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Reference the helper macro used to obtain the containing context
structure from a work item pointer within a work handler. Also
document the proper way to do this for delayable work items.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Point out that this macro can be used to avoid the need to initialize
a work item. This is still of limited use since it can't statically
initialize a work item within another structure.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Use queued uniformly when referring to items that are in a work queue,
rather than "pending" which includes items that are scheduled or
running.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Move out of misc/ and put in own folder and add the grouping to doxygen
to be able to reference the doxygen docs into RST.
Move each item into their own file to reduce clutter and to make it
less crowded in one single page.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The clock/timer APIs are not application facing APIs, however, similar
to arch_ and a few other APIs they are available to implement drivers
and add support for new hardware and are documented and available to be
used outside of the clock/kernel subsystems.
Remove the leading z_ and provide them as clock_* APIs for someone
writing a new timer driver to use.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The xtensa atomics layer was written with hand-coded assembly that had
to be called as functions. That's needlessly slow, given that the low
level primitives are a two-instruction sequence. Ideally the compiler
should see this as an inline to permit it to better optimize around
the needed barriers.
There was also a bug with the atomic_cas function, which had a loop
internally instead of returning the old value synchronously on a
failed swap. That's benign right now because our existing spin lock
does nothing but retry it in a tight loop anyway, but it's incorrect
per spec and would have caused a contention hang with more elaborate
algorithms (for example a spinlock with backoff semantics).
Remove the old implementation and replace with a much smaller inline C
one based on just two assembly primitives.
This patch also contains a little bit of refactoring to address the
scheme has been split out into a separate header for each, and the
ATOMIC_OPERATIONS_CUSTOM kconfig has been renamed to
ATOMIC_OPERATIONS_ARCH to better capture what it means.
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
Revise the description of queues, work items, and delayable work items
to reflect the terminology and API provided by the new implementation.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
This adds X86 keyword to the kconfigs to indicate these are
for x86. The old options are still there marked as
deprecated.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Fixes a typo in the condition variable documentation.
Also fixes two numbered lists not rendering correctly.
Signed-off-by: Alex Martens <alexander.martens@intel.com>
Update the documentation for Lazy Stacking in Cortex-M, to
reflect the functionality changes (activate the lazy stacking
dynamically when building with MPU stack guards).
Make a note that the FP sharing mode is now default in Cortex-M.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Adds API reference for sys_mutex and futex to mutex documentation,
adds Doxygen documentation for SYS_MUTEX_DEFINE and fixes typo in
futex documentation.
Fixes#27829
Signed-off-by: Lauren Murphy <lauren.murphy@intel.com>
The scheduler documentation was updated before to define a reschedule
point, but the related term sleep was not clearly described. Add a
definition, and link to it from the API terminology.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
The documentation example was giving the impression that time slices are
not reset when a thread is scheduled.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Discussion about how to re-spawn threads led to the discovery that our
documentation on exactly when that was legal was ambiguous and
confusing. Rewrite it to be explicit.
Fixes#28970
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
Describe the role of these APIs, key concepts that they depend on, and
expose the low-level API.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
First, the maximum heap size must fit in 31 bits worth of chunks
because the internal 32-bit field holding the size is shared with
the `used` bit.
Then the mention of a 256-byte block in the doc is no longer
relevant. That pertained to the previous allocator implementation.
And ditto for the HEAP_MEM_POOL_MIN_SIZE kconfig option.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
We need to loop while `end` is still in the future and thus larger
than the current uptime, not smaller. Also fix indentation.
Signed-off-by: Stephan Walter <stephan.walter@swissphone.com>
Mark all k_mem_pool APIs deprecated for future code. Remaining
internal usage now uses equivalent "z_mem_pool" symbols instead.
Fixes#24358
Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This change adds full shared floating point support for the SPARC
architecture.
All SPARC floating point registers are scratch registers with respect
to function call boundaries. That means we only have to save floating
point registers when switching threads in ISR. The registers are
stored to the corresponding thread stack.
FPU is disabled when calling ISR. Any attempt to use FPU in ISR
will generate the fp_disabled trap which causes Zephyr fatal error.
- This commit adds no new thread state.
- All FPU contest save/restore is synchronous and lazy FPU context
switch is not implemented.
Signed-off-by: Martin Åberg <martin.aberg@gaisler.com>
Clarify that while any number of kernel objects can be created, there is
a limit which is set by the available RAM.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Add new function to mem_slab API that enables user
to get maximum number of slabs used so far.
Signed-off-by: Kamil Lazowski <Kamil.Lazowski@nordicsemi.no>
Previously, ring buffer had capacity of provided buffer size - 1. This
trick was used to distinguish between empty and full states. It had one
drawback: ring buffer could not be used as a pool of equal sized buffers
(using ring_buf_put_claim and ring_buf_get_claim).
Reworked internals to use non wrapping head and tail. Since they are
non wrapping, there is no issue with distinguishing between empty and
full. Since this appraoch would be vulnerable to wrapping on 32 bit
boundary, added a mechanism which periodically reduces all indexes to
avoid 32 bit wrapping.
After this rework, buffer has one byte more capacity. Simple test shows
slight performance improvement.
Updated tests to reflect increased capacity and added test to check if
it is possible to continuesly allocated 2 buffers of half ring buffer
size.
Signed-off-by: Krzysztof Chruscinski <krzysztof.chruscinski@nordicsemi.no>
Add description how to enable zero-latency interrupt in the application
code. Previous docs described only the Kconfig and not the flag.
Signed-off-by: Martin Jäger <martin@libre.solar>
The delayed work API has been changed to allow cancellation in
conditions not previously documented, but this feature can cause both
submission and cancellation to fail in the general case. Summarize
the conditions and highlight the importance of checking result codes
for these functions.
Also explicitly note that no kernel API can reliably indicate that a
work item has been completed, and that doing so is the responsibility
of the code that provides the work handler.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
- use sizeof(struct data_item_type) instead of sizeof(data_item_type)
- use struct data_item_type instead of invalid reference data_item_t
- add aligned typedef struct data_item_type example implemenation
- add note about checking return value for error message
Fixes#19684
Signed-off-by: Jennifer Williams <jennifer.m.williams@intel.com>
Some macros were using :c:func: and :cpp:func: which forbids Breathe
from resolving those symbols. Update to :c:macro: for proper resolution.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
`NULL` is not defined in the Zephyr sources, but rather a C definition
which is not resolved when building the documentation and generates a
warning. Fall back to using just emphasis.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Sphinx>=3.0 includes the `struct` role in the C domain, which provides a
specific way to link to structs, while the old :c:type: role should be
primary used to typedefs. Update existing references, using :c:type:,
:cpp:type: or emphasized symbols that point to structs to use the new
role.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Following the change to use the C domain for parsing, update all
existing :cpp:func: references to :c:func:. Remove the parentheses as
well, if used, because they are not needed, this is already known to be
a function, and how it is displayed in the documentation later is a
semantic decision done by the output builder.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
This is covered in the porting guide, and we have complete docstrings
for these macros, but having discussion here helps new users understand
how to use these and why they exist.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
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>
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>
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>
