The existing implementation unconditionally restores owner_orig_prio on
unlock, ignoring other held mutexes that still have high-priority waiters.
This causes incorrect priority restoration in nested mutex scenarios and
requires mutexes to be released in strict reverse acquisition order.
Additionally, priority boosts were not propagated through ownership chains
when the mutex owner was itself blocked on another mutex.
This change adds per-thread held_mutexes tracking and mutex_pended_on
pointer to enable:
- Correct priority recalculation on unlock by scanning all remaining held
mutexes
- Chained priority inheritance through the full ownership chain
- Deadlock detection: assert on K_FOREVER circular ownership where
every cycle member also waits forever; bounded chain walk prevents
livelock on cycles not involving the current thread
- Per-thread orig_prio field records true pre-inheritance priority,
fixing priority floor when mutexes are released in non-LIFO order
struct k_thread grows by three pointers plus a byte in default builds
(held_mutexes, mutex_pended_on, orig_prio).
Signed-off-by: Mayur Salve <msalve@qti.qualcomm.com>
Replace the explanation of the usage of ring_buf_[get|put]_[claim|free]
APIs with the new ring_buf_[get|put]_ptr* APIs as the preferred way to do
zero-copy access to ring buffers. The old APIs are still available but are
now slated to be deprecated and will be removed in the future.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
Describe the generic core on the system timer drivers page, where the
sys_clock_* contract lives, so a driver author finds it alongside
sys_clock_set_timeout() and sys_clock_elapsed(); add the release notes
entry and a migration-guide note steering out-of-tree tickless drivers
toward the header instead of tracking the kernel interface by hand.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
Describe both hooks on the system timer drivers page, where the
sys_clock_* contract lives, and record the two deprecations they replace
in the migration guide and release notes. A table maps the four states,
running or idle crossed with something pending or not, onto the call each
one produces.
Both replaced signals keep working for out-of-tree drivers through the
hooks' default implementations, until removal after the usual
deprecation period.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The kernel timing page mixes two audiences. Most of it is what an
application sees: time units, uptime, timeouts, conversions. The driver
interface, the locking it runs under and the SMP notes are for whoever
writes or ports a timer driver, and that reader has no need of the rest.
Move those three sections to a page of their own and leave a pointer. The
moved text is unchanged but for the section levels and one cross-reference
that used to point further down the same page; each page gains a sentence
introducing the other.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
CONFIG_SMP_BOOT_DELAY was a global, application-level switch that made
the kernel skip starting every secondary CPU at boot, used in-tree only
by two tests and in practice by one platform class (intel_adsp, where
the host or PM policy brings DSP cores up on demand). Boot topology is
a hardware/platform property, and all-or-nothing is needlessly coarse.
Replace it with a per-CPU devicetree flag, zephyr,deferred-start, on
the /cpus children (mirroring zephyr,deferred-init for devices):
z_smp_init() now always runs and simply skips flagged CPUs, which are
brought up at run time with the existing k_smp_cpu_start() (or
k_smp_cpu_resume()). Deferral is per CPU, so asymmetric bring-up
(start some cores at boot, defer others) is now expressible, and the
special-case branch disappears from the boot path.
The flag is declared in the common cpu.yaml binding. The lookup uses
DT_PROP_OR() so cpu nodes whose binding does not cover the property
simply cannot be deferred rather than breaking the build; a binding
for the intel,x86_64 compatible used by qemu_x86_64's cpu nodes was
missing entirely and is added.
The two users are converted: tests/kernel/multiprocessing/
smp_boot_delay marks the secondary CPUs in per-board overlays (both
tests pass on qemu_x86_64) and tests/boards/intel_adsp/smoke gains
overlays for its four platforms (all build). Normal SMP boot is
unaffected (verified on qemu_x86_64, all CPUs online).
Out-of-tree users migrate by dropping CONFIG_SMP_BOOT_DELAY=y and
adding zephyr,deferred-start to the deferred cpu nodes in their board
overlay.
Assisted-by: Claude:claude-fable-5
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This allows to watch k_lifo using k_poll().
No changes were required in kernel/poll.c. The existing logic already
operates on event->queue for K_POLL_TYPE_DATA_AVAILABLE, which is
compatible with both k_fifo and k_lifo since they share the same in-memory
layout (a leading struct k_queue).
In fact, the user was already able to poll k_lifo if he casted it on
k_fifo. This patch only add the required aliases to make the support for
k_lifo official.
Assisted-by: Claude:claude-sonnet-5
Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
Introduces K_MSGQ_DEFINE_TYPE() and K_MSGQ_DEFINE_STATIC_TYPE() helper
macros that let the user define message queues with the correct size and
alignment for given message type.
Signed-off-by: Cesar Vandevelde <cesar.vandevelde@gmail.com>
Introduce a macro to define private (file scope) message queues. The
K_MSGQ_DEFINE() macro cannot be combined with the `static` keyword because
the macro defines 2 variables (unlike e.g. K_SEM_DEFINE or
K_TIMER_DEFINE), so a dedicated macro is necessary.
Signed-off-by: Cesar Vandevelde <cesar.vandevelde@gmail.com>
Remove note comparing current behavior to pre-v2.6.0 behavior. As Zephyr
v2.6.0 was released 5 years ago, this note is no longer relevant.
The last parapgraph is already covered by the best practices section.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
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>
