The usage section previously documented only the linker script-based
declaration of iterable sections, which is toolchain-specific.
The rewrite documents the CMake-side declaration of iterable sections, in
addition to the linker script-based declaration and explains why both are
needed as of now.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
Fix typos and improve wording in the memory blocks allocator
documentation for grammar and clarity.
Closes: #109408
Signed-off-by: Ian Gough <igough57@gmail.com>
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
Update the wording for DEVICE_API usage, that it is mandatory for device
driver instances to be put in their respective iterable sections.
Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>
Replace the hedged "shouldn't be needed" wording in the ring buffer
Concurrency section with an explicit guarantee: a single producer and a
single consumer running in separate execution contexts (two threads, or
one thread and one ISR) may use the same ring buffer without additional
locking, because the producer side only updates the put indices and the
consumer side only updates the get indices.
Also note that on SMP systems the producer and consumer must ensure
proper memory ordering between data writes and the index updates that
publish them; in practice this happens for free when the two sides
coordinate via a kernel synchronization primitive such as k_sem, since
those primitives include the necessary memory barriers.
Add a matching @note at the @defgroup level of the header so the
Doxygen-rendered API reference carries the same guarantee without
duplicating the warning across every API entry.
Fixes#69403
Signed-off-by: Andrii Anoshyn <anoshyn.andrii@gmail.com>
Documentation for the item API for ring buffers has been removed due to it
has been deprecated and an alternative (<zephyr/sys/ringq.h>) has been
provided for similar functionality. This change aims to prevent future use
of the item API by obscuring it until it can be fully retired.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
This is can be used to revoke access from all but the current
thread, which is useful when reassigning an object without having
to worry about previous permissions.
Signed-off-by: Christoph Busold <cbusold@qti.qualcomm.com>
There is no memory region named "SRAM" in the document
section "Additional Configurations". Update examples to use
"SRAM1" or "SRAM2".
Signed-off-by: Yiren Guo <guoyr_2013@hotmail.com>
On SMP systems with tickless kernels, a race condition exists between
timer driver ISRs and the kernel's tick accounting. The driver updates
its hardware cycle baseline under a private lock, then calls
sys_clock_announce() which updates curr_tick under the separate
timeout_lock. In the gap between these two lock releases, any kernel
code calling sys_clock_elapsed() sees the new driver baseline but the
old curr_tick, producing inconsistent time values that can go backwards.
This affects every code path using the internal elapsed() helper:
uptime queries, timeout scheduling, timeout cancellation, remaining
time queries, and next-expiry calculations.
The root cause is two separate locks protecting state that must be
mutually consistent. Fix this by exposing the kernel's timeout_lock
to timer drivers via sys_clock_lock()/sys_clock_unlock(), and
providing sys_clock_announce_locked() which assumes the lock is
already held.
Timer drivers can now acquire the single lock, update their hardware
state, and announce ticks all under the same lock — eliminating the
race window entirely. The key is passed to sys_clock_announce_locked()
which consumes it (releasing the lock when it returns).
The existing sys_clock_announce() becomes a backward-compatible wrapper,
allowing incremental driver migration with no flag day.
Document that sys_clock_set_timeout(), sys_clock_elapsed(), and
sys_clock_idle_exit() are called by the kernel with the timer lock
held. Update the timer driver guide in clocks.rst accordingly.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The original slab documentation was written with only 32-bit platforms
in mind. Since then support for 64-bit platforms have been added, but
the documented minimum values for alignment (and block sizes too) had
not been updated. This makes it clear that the minimum alignment
required for 32-bit platforms is 4 bytes, and 8 bytes for 64-bit
platforms.
Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
Add information about the introduced cleanup classes, with usage examples.
An explicit warning is added that toolchain support is required.
Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>
Drop a note about prefixing device specific api naming with the full
normalized compatible for the device. Nothing in tree adopted this and
it would be unnecessarily verbose, the standard "keep the coding style
coherent" works just fine for this.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Add documentation for the runtime system timer frequency
update mechanism introduced by
CONFIG_SYSTEM_CLOCK_HW_CYCLES_PER_SEC_RUNTIME_UPDATE.
Update the Hardware Cycles section to clarify that:
- The system timer frequency is typically fixed but can be runtime-variable
on some platforms
- sys_clock_hw_cycles_per_sec() returns a runtime value when runtime
frequency updates are enabled
- Application code must not assume a single immutable frequency when
runtime updates are enabled
Add a new "Runtime System Timer Frequency" section documenting:
- The typical fixed-frequency behavior on most platforms
- Use cases for runtime frequency (hardware discovery or dynamic changes)
- Requirements for platforms that change frequency at runtime:
- Enable CONFIG_SYSTEM_CLOCK_HW_CYCLES_PER_SEC_RUNTIME_UPDATE
- Call z_sys_clock_hw_cycles_per_sec_update() after clock changes
- Optionally override z_sys_clock_hw_cycles_per_sec_update() if the
timer driver needs to update cached state or reprogram hardware
- Limitation: not compatible with per-CPU frequency scaling
Signed-off-by: Zhaoxiang Jin <Zhaoxiang.Jin_1@nxp.com>
There is no need to include the k_mutex priority inheritance code
when CONFIG_PRIORITY_CEILING is set to a priority level that is at
or below that of the idle thread.
Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
Update the kernel timer docs to specify the differences between the
duration and period of a timer, and specifying that the period of
a periodic timer can be shorter or longer than the specified period,
and that it does not drift relative to the system timer.
Signed-off-by: Bjarki Arge Andreasen <bjarki.andreasen@nordicsemi.no>
Correct the description in the "What Cannot be Expected to Work" section
to state that the listed functionality fails when CONFIG_MULTITHREADING
is **disabled**, as the previous wording implied the opposite.
Fixeszephyrproject-rtos/zephyr#101718
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Updates the time slicing image in the associated documentation to ...
1. Show the resetting of a time slice after scheduling a new thread
2. Indicate that it is specific for UP scheduler
It also adds a note to the documentation describing how the ordering
of the threads would change with the SMP scheduler.
Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
Fixes documents where blocks where indented to the right of their parent
causing them to render as definition lists.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Adds a note to the meta-IRQ thread documentation indicating that
that when a cooperative thread resumes after being preempted by
a meta-IRQ thread it will resume on the same CPU from which it was
preempted.
On a UP system such behavior is a given. However, this behavior becomes
relevant on an SMP system to ensure that both schedule-locked and
cooperative threads are not accidentally shuffled to another CPU while
querying the properties associated with their current CPU.
Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
Similar to logging and shell, allow application to override and
extend the ASSERT macros globally. This enables intercepting log strings
at the macro level for things like string tokenizations.
Signed-off-by: Kevin Zeng <zengk@google.com>
Sphinx has a built-in `:rfc:` role for referencing RFC documents.
This commit updates documentation pages referencing RFCs to use this role.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Remove the note about time_t being 64-bit in Zephyr, since that is
generally not accurate and depends on the configuration of the C library.
Signed-off-by: Chris Friedt <cfriedt@tenstorrent.com>
Apply `:file:` markup to file names in the "Files generated by the script"
section under "Implementation Details" to improve clarity and readability.
Signed-off-by: Yasushi SHOJI <yashi@spacecubics.com>
The k_pipe_get and k_pipe_put APIs have been retired in Zephyr 4.2, this
commit removes references to these APIs in the documentation that was
missed in the original rework of thhe k_pipe API.
Signed-off-by: Måns Ansgariusson <Mansgariusson@gmail.com>
This is variation of the PR to handle phantom events and hopefully
this get merged into the PR to land.
See-also: https://github.com/zephyrproject-rtos/zephyr/pull/89624
Signed-off-by: Charles Hardin <ckhardin@gmail.com>
Minor cosmetic update so that the notes in the "Data Passing" summary
table are actual interactive footnotes.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit introduces the new test ram_context_for_isr that shows
how to configure an application (prj.conf, CMakeLists.txt, etc.) in
order to enable full ISR execution with a RAM context.
It resolves the issue of flash latency affecting real-time constraints
during ISR execution.
Signed-off-by: Martin Hoff <martin.hoff@silabs.com>
This commit introduces the SRAM_SW_ISR_TABLE option which is selected by
DYNAMIC_INTERRUPT. It allows splitting the DYNAMIC_INTERRUPT option into
two parts:
- One for the relocation of the ISR vector table in RAM
- One for the inclusion of functions needed to install ISRs dynamically
The goal is to later only select the relocation of the ISR vector table in
RAM and not all the associated functions from the dynamic interrupt
mechanism.
Signed-off-by: Martin Hoff <martin.hoff@silabs.com>
Commit a0b746 deleted 2 deprecated driver init levels (EARLY,
APPLICATION), but didn't update the number mentioned in the doc.
Signed-off-by: Nabil Elqatib <nabilelqatib@gmail.com>
The `zephyr_code_relocate` now supports the NOINIT memory type in addition
to DATA, TEXT and BSS. This patch documents its usage.
Signed-off-by: Joel Holdsworth <jholdsworth@nvidia.com>
This patch improves the formatting of the "Additional Configurations"
section of the "Code And Data Relocation" document.
Signed-off-by: Joel Holdsworth <jholdsworth@nvidia.com>
Includes explanation of the min-heap’s properties, constraints and
explains about the uses cases of min-heap. It also contains references
to Sample Application and min-heap API
Signed-off-by: Sayooj K Karun <sayooj@aerlync.com>
The documentation did not state clearly that any zero-latency IRQ must
also be declared as a direct ISR. This is critical because failure to do
so may cause race conditions between the ZLI and regular ISRs when
executing the preable/postamble code in regular interrupts.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Add documentation in the timeutil group for recently added functions
for validating, comparing, and manipulating `struct timespec`
objects as well as functions for converting between representation
of time durations as either `struct timespec` or `k_timeout_t`.
Signed-off-by: Chris Friedt <cfriedt@tenstorrent.com>
