The 4.5 migration guide already tells out-of-tree system-timer drivers to
absorb the recent interface churn by hand: make sys_clock_set_timeout()
unsigned, drop its idle argument, and move counter-stop handling into
sys_clock_unused(). Many in-tree tickless drivers now instead build on
drivers/timer/system_timer_generic.h, which owns the tick accounting and
emits those entry points, so a driver built on it no longer defines them
and none of that hand-porting applies.
Lead the migration guide's Timer section with the core and encourage
drivers not to carry their own tick handling at all, reframing the
individual interface notes as the residual cases where the hardware cannot
be expressed through the core. Add a release-notes entry pointing to it.
Add a "Generic Tickless Core" subsection to the Kernel Timing manual
(the Timer Drivers page), which otherwise only describes hand-rolling the
sys_clock_* contract, so a driver author discovers the core there too.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
Collect the out-of-tree timer-driver migration notes for the sloppy
idle and idle-handoff rework in one place: sys_clock_unused() replaces
the SYS_CLOCK_MAX_WAIT stop sentinel under sloppy idle, and
sys_clock_set_timeout() loses its idle argument in favour of the new
sys_clock_idle_enter() hook.
Also document the two new optional hooks in the Timer Drivers manual
(the Kernel Timing page), which describes the sys_clock_* driver
contract, so that sys_clock_unused() and sys_clock_idle_enter() are
discoverable there alongside sys_clock_set_timeout() and
sys_clock_elapsed(), not only in the migration guide.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The "Timeout Queue" section described the queue as a fixed sorted delta
list and stated that no scalable alternative existed. The timeout
backend abstraction makes the queue data structure a build-time choice,
so update the section to cover the CONFIG_TIMEOUT_BACKEND selection, the
default delta list, and the experimental min-heap, timer-wheel and
bucketed backends, with guidance on when each applies and their
limitations.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The existing min_heap stores elements by value in a contiguous buffer
and supports content search plus remove-by-index, which suits priority
queues of small values looked up by content.
Add min_heap_ref, a sibling that instead stores pointers to caller-owned
nodes that embed a struct min_heap_handle. This gives zero-copy
insertion and O(log n) removal by the handle the caller already holds,
without any search. It suits long-lived objects that are removed by
identity rather than by content (for example kernel timeouts, which
embed the node in an already-allocated structure and abort a specific
known entry).
The two are complementary, not interchangeable: the value heap cannot
remove by identity in better than O(n), and the reference heap is a poor
fit for value-with-search use. min_heap_ref is header-only (all static
inline), so it needs no Kconfig or library build. A dedicated test
mirrors the value-heap test against the new API.
Co-authored-by: Sayooj K Karun <sayooj@aerlync.com>
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
Document starting a deferred thread with k_thread_start(), thread naming
via CONFIG_THREAD_NAME, the thread introspection routines (current,
priority, state, foreach, stack space and pending timeouts), and runtime
statistics control under CONFIG_SCHED_THREAD_USAGE.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Document ticket spinlock fairness via CONFIG_TICKET_SPINLOCKS, the
memory coherence model under CONFIG_KERNEL_COHERENCE, deferred secondary
CPU bring-up via CONFIG_SMP_BOOT_DELAY with k_smp_cpu_start() /
k_smp_cpu_resume(), and directed IPI scheduling.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Document per-thread time slicing via k_thread_time_slice_set() under
CONFIG_TIMESLICE_PER_THREAD, forcing a scheduling decision with
k_reschedule(), and querying the current context with
k_is_preempt_thread() and k_can_yield().
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe k_usermode_string_copy() and k_usermode_string_alloc_copy(),
which safely validate and copy a NUL-terminated string supplied by user
mode into kernel-controlled memory before it is used.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe the timer observer feature gated by CONFIG_TIMER_OBSERVER,
including K_TIMER_OBSERVER_DEFINE() and the on_init, on_start, on_stop
and on_expiry callbacks used by tracing, profiling and power-management
code to react to timer lifecycle events.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Note that k_condvar_wait() always returns with the associated mutex
re-locked by the caller, regardless of whether the wait completed due to
a signal, a timeout, or a non-blocking request.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe k_float_enable() and k_float_disable() for managing a thread's
participation in floating point context preservation at run time,
including the K_FP_REGS / K_SSE_REGS options and the -ENOTSUP / -EINVAL
return values.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe CONFIG_STACK_CANARIES_TLS, which gives each thread its own
stack canary in thread-local storage, and CONFIG_STACK_POINTER_RANDOM,
which randomizes each thread's initial stack pointer as a hardening
measure.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe k_queue_cancel_wait() and its k_fifo_cancel_wait() /
k_lifo_cancel_wait() counterparts, which release a thread blocked in
k_queue_get() with a NULL return, and the corresponding k_poll() -EINTR
behavior.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe the runtime usage query routines k_mem_slab_num_used_get(),
k_mem_slab_num_free_get(), k_mem_slab_max_used_get() and
k_mem_slab_runtime_stats_get(), including the peak-utilization tracking
gated by CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Document k_heap_aligned_alloc(), k_heap_calloc() and k_heap_realloc()
for aligned, zeroed and resized allocations, and k_heap_array_get() for
enumerating statically defined heaps for instrumentation purposes.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe k_mem_pin() and k_mem_unpin(), which keep a region resident in
physical memory and exclude it from the eviction algorithm. Explain how
pinning differs from k_mem_page_in() and how it relates to unpinning and
subsequent page-out.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Document how device drivers can use existing PM policy constraints for
paths that can produce zero-latency interrupts. A ZLI handler cannot
call PM APIs, but the normal driver path can hold a device power policy
lock while the interrupt-producing path is active.
Add cross-references between the ZLI documentation and the PM device
policy constraint section so users have a concrete mitigation for
interrupt sources that are not safe in some system power states.
Signed-off-by: Holt Sun <holt.sun@nxp.com>
Commit c08905ecc9 added the thread runtime stack safety feature
(CONFIG_THREAD_RUNTIME_STACK_SAFETY) but did not document it. Add a
"Runtime Stack Safety" section to the threads service documentation
describing the per-thread unused-stack threshold, the percentage and
byte-based setters and getter, the full and abbreviated check routines,
the stack safety handler type, and a usage example. Also list the
related Kconfig options in the configuration options section.
Assisted-by: Claude:claude-opus-4-8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
* doc/kernel/memory_management/demand_paging.rst gains an opening
paragraph stating that the kernel image is always resident and that
demand paging applies only to k_mem_map() and __ondemand_* regions,
plus a note explaining the rationale for removing the previous
__pinned_* selective-pinning model and a pointer to the original
analysis (issue #108773).
* doc/releases/release-notes-4.4.rst adds a Kernel subsection to the
"Removed APIs and options" list, covering the dropped Kconfig
options, attribute macros, and stack-definition macros.
* doc/releases/migration-guide-4.4.rst adds a Kernel item describing
the steps out-of-tree code needs to take: dropping the Kconfig
overrides, removing __pinned_* attributes, switching PINNED_*
assembly aliases to plain TEXT/RODATA/DATA/BSS/NOINIT, renaming
the K_*_PINNED_STACK_* macros, folding custom pinned linker
sections back into the regular output sections, and removing
lnkr_pinned_* / app_smem_pinned* / --pinoutput dependencies.
Issue: #108773
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
PM_STATE_SET_IRQ_LOCKED is removed when IRQ-locked PM hooks become the
default behavior. Keep the ZLI PM-resume documentation phrased in terms
of the behavior instead of referencing the removed migration symbol.
This fixes the undefined Kconfig symbol compliance failure.
Validated with git diff --check and a git grep check for the removed
symbol.
Signed-off-by: Holt Sun <holt.sun@nxp.com>
Use behavior-first wording in the PM API notes when describing the
locked-resume contract. This keeps the durable text focused on the
case where system PM keeps interrupts locked across resume, while
keeping CONFIG_PM_STATE_SET_IRQ_LOCKED as the current selector.
Shorten duplicated zero-latency interrupt details in the system PM
page and Kconfig help by referring readers to the ZLI documentation.
Also keep the ARM IRQ comment focused on the PM-wake-safe contract.
No behavior change. Validated with git diff --check.
Signed-off-by: Holt Sun <holt.sun@nxp.com>
The locked-resume ordering guarantee covers only interrupts that
arch_irq_lock() can mask. On Cortex-M Mainline that lock is a BASEPRI
threshold, so zero-latency interrupts (IRQ_ZERO_LATENCY) run above it
and are outside that ordering.
Document that a zero-latency ISR used with PM must be PM-wake-safe, or
that its interrupt source must be masked or disabled while the system
state does not allow the ISR to execute.
No behavior change. Validated with git diff --check.
Signed-off-by: Holt Sun <holt.sun@nxp.com>
This reverts commit ff508efd6a.
This is causing breakages across the tree. We should fix all issues and
retry. Nothing wrong with the change itself, but the tree was not
prepared for this change.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Add a uintptr_t magic field (K_MUTEX_MAGIC = K_OBJ_TYPE_MUTEX_ID) to
struct k_mutex under CONFIG_ASSERT, written by k_mutex_init() and
Z_MUTEX_INITIALIZER. Assert the sentinel in lock/unlock to catch
use-before-init, and assert the mutex is not held before re-init.
Zero-initialize dynamically allocated objects in dynamic_object_create()
under CONFIG_ASSERT for a known starting state. Fix test bugs where
k_mutex_init() was called on a held mutex. Add assertion path tests.
Signed-off-by: Mayur Salve <msalve@qti.qualcomm.com>
Add entries to both the release notes and migration guide covering the
two CPU mask changes made in this release cycle:
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Two documentation gaps left by the removal of 'depends on SCHED_SIMPLE'
from CONFIG_SCHED_CPU_MASK:
smp.rst: The note that CPU mask processing is 'available only when
SCHED_SIMPLE is the selected backend' was stale. Replace it with an
accurate description of the performance characteristics for all three
backends (SCHED_SIMPLE, SCHED_SCALABLE, SCHED_MULTIQ) and for
PIN_ONLY mode. Also document which API calls are incompatible with
PIN_ONLY mode (clear, enable_all, disable) because they can produce a
mask that violates the one-CPU-bit invariant.
kernel.h: Add @note entries to the Doxygen for k_thread_cpu_mask_clear,
k_thread_cpu_mask_enable_all, and k_thread_cpu_mask_disable explaining
that they assert in PIN_ONLY mode and directing users to
k_thread_cpu_pin as the correct alternative.
Assisted-by: GitHub Copilot:claude-sonnet-4-5
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Context switching while holding the IRQ lock is illegal and will in fact
trigger a kernel panic most of the time (there are some configurations
under which this error will be silently ignored because the kernel is
not able to reliably detect it).
Update the relevant documentation page which presented the IRQ lock in
a completely different (and misleading) manner to reflect the actual
behavior: you can't hold it upon context switch, so you must not call
any `sleep` function while it is held.
Signed-off-by: Mathieu Choplain <mathieu.choplain-ext@st.com>
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>
