Run a small job server, with short-lived threads and heap-allocated
requests embedding semaphores, mutexes and timers, and next to it a
monitor thread that uses object cores the way a debugging tool would:
every second it redraws the number of objects of each type with the
skipped and dropped counts, and every thread with its state and CPU
share over the last period. A second twister configuration builds it
through CONFIG_TRACING_OBJECT_TRACKING.
Assisted-by: Claude:claude-fable-5-1
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Show the object core framework from a user's point of view: the
inventory of each object type with its skipped and dropped counts,
which objects are reported (static, run-time registered, in stack
storage, in freed memory, aborted threads, explicitly unregistered),
and the thread, memory slab and system statistics read through
k_obj_core_stats_query(). A second twister configuration builds the
same program through CONFIG_TRACING_OBJECT_TRACKING.
Assisted-by: Claude:claude-fable-5-1
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Describe how object types enumerate their permanent objects in place and
the objects initialized at run time from a bounded registry, which
objects are not tracked, when the kernel unregisters objects, and the
build-time and run-time ways of defining an object type. Add the
migration guide and release notes entries for the removed list members,
the object tracking lists and the new options.
Assisted-by: Claude:claude-fable-5-1
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Add a software-backed precision clock sample that demonstrates checked time
arithmetic, mandatory clock operations, and PI-driven rate adjustment.
Signed-off-by: Philipp Steiner <philipp.steiner1987@gmail.com>
Add signed nanosecond arithmetic, protocol-neutral clock operations, a PTP
clock adapter, and an instance-based generic PI controller. Keep
synchronization policy in protocol consumers.
Signed-off-by: Philipp Steiner <philipp.steiner1987@gmail.com>
Move the assertion documentation out of the Fatal Errors page into a
new "Assertions" page and rewrite it around the module-aware ZASSERT()
API.
The page documents ZASSERT as the recommended runtime assertion API.
It covers the following topics:
* ZASSERT macros
* Kconfig options
* Assertion modules and levels (ZASSERT_OFF/TERSE/ON/VERBOSE)
* Customization of the failure behavior through weak hooks
The legacy __ASSERT() family is documented as a deprecated compatibility
layer over the DEFAULT module.
BUILD_ASSERT() is carried over as well.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
CONFIG_ASSERT_CUSTOM_HEADER let an application inject a
"zephyr_custom_assert.h" at the end of <zephyr/sys/__assert.h> to extend
the assert macros at the preprocessor level. It has always been
experimental and explicitly warned that the internal assert API may change,
so it is removed without a deprecation period, per the experimental API
policy.
Applications that need to customize assertion handling should override the
weak assert hooks instead.
Remove the Kconfig option, the __assert.h include hook and the
assert_custom_header test.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
A mutex with threads waiting on it keeps their wait queue nodes in its
own memory, so releasing or reusing that memory while the mutex is in
use has never been safe. Since 1b60add1ac ("kernel: mutex: fix
priority inheritance with multiple held mutexes") the same is true of a
locked mutex with no waiters: freeing it used to leak the lock, and now
leaves the owner tracking a list node in memory that no longer belongs
to it.
Neither the mutex documentation nor the k_mutex_lock() reference says
so. State the rule in both places, next to the description of unlocking
and in the API comment where most readers will look. The rule rather
than the mechanism, because the owner's list only exists when priority
inheritance is enabled and is already described in that section.
Signed-off-by: YunHung Hua <oliverhua.us@gmail.com>
The new implementation provides a full SPSC ring buffer API, reducing the
size of the ring_buffer struct to 12 bytes(on a 32-bit arch), and increases
the throughput of the ring buffers hot path by ~30% (measured on nRF5340).
The default variant drops the claim/finish and item APIs functionality to
reduce the struct size. During the deprecation period, the old APIs are
still reachable through the CONFIG_RING_BUFFER Kconfig option.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
Update the ring buffer documentation to lead with the new
ring_buf_put_ptr/commit and ring_buf_get_ptr/consume zero-copy APIs as
the recommended way to access the ring buffer memory directly. The
legacy ring_buf_*_claim/finish APIs are now noted as deprecated and
slated for removal.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
Extract the spinlock documentation out of the SMP page into its own page
under the kernel synchronization services, and expand it with usage
guidance, examples and rules for correct use.
The SMP page keeps a short summary and links to the new page.
Signed-off-by: Måns Ansgariusson <mansgariusson@gmail.com>
This removes k_futex from the kobject table and allows any address
accessible to userspace to be used as futex and fixes#25497.
Instead of different wait queues per futex, this solution uses a
single wait queue for all threads waiting on any futex. The futex
address is stored in the thread structure. On wake, the kernel
walks through the queue and wakes either the highest priority or
all threads waiting on the specified futex address.
This is more lightweight than #42087 and more efficient for smaller
numbers of threads, but does not scale well to large numbers of
threads waiting on different futexes.
Add a test for the correct order when waking only one thread.
Signed-off-by: Christoph Busold <cbusold@qti.qualcomm.com>
I found this paragraph hard to understand grammatically.
Co-authored-by: Nicolas Pitre <npitre@baylibre.com>
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
I noticed this inconsistency and searched the documented for all uses of
lowercase "isr" in prose, replacing them with "ISR".
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
I found the previous ascii art a little hard to parse.
The pointers to the next level are now directed at the beginning of
a controller. Previously, I was wondering if the higher level somehow
pointed at a specific line in the lower level.
Unfortunately, the monospace font used in the rendered HTML
documentation doesn't perfectly connect the box drawing characters.
It should also be noted that this version is quite a bit wider than
the previous one. For the standard text width of the rendered HTML
documentation, it fits nicely. But, on small screens, the diagram will
overflow the screen width more quickly.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
The fact that ISRs preempt most normal threads (preemptible and
cooperative) doesn't necessarily mean an ISR has a low overhead.
It is more accurate to describe ISRs as having low latency in this
context. The fact that they preempt most threads means there is
usually a very short amount of time between an IRQ being raised
and its associated ISR being executed. This stands in contrast with
normal threads, which, after becoming ready, often have to wait for
higher-priority threads to finish their work or for cooperative threads
to yield.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
The ARCH_*_DIRECT_* hooks that IRQ_DIRECT_CONNECT() and
ISR_DIRECT_DECLARE() expand to are only defined by architectures
implementing direct interrupts. The stubs in arch_interface.h are
documentation only, guarded by __DOXYGEN__, so on every other
architecture the macros are simply undefined and survive preprocessing
untouched. The result is that
ISR_DIRECT_DECLARE(my_isr) { ... }
misparses as a K&R function definition of a function named
ARCH_ISR_DIRECT_DECLARE, and the compiler reports a missing return type
instead of the missing feature. On x86_64 in particular this is easy to
mistake for a mistake in the caller's code.
Define the ARCH_IRQ_DIRECT_CONNECT() and ARCH_ISR_DIRECT_DECLARE()
hooks as BUILD_ASSERT() failures when CONFIG_ARCH_HAS_DIRECT_INTERRUPTS
is not set, so the diagnostic names the feature and points at the
offending line. Only these two API entry points are stubbed: the
HEADER/FOOTER/PM hooks are reachable solely from inside a direct ISR
body created with ISR_DIRECT_DECLARE(), so the assertion there already
covers them, and RX defines ARCH_ISR_DIRECT_HEADER()/_FOOTER() for its
internal ISR accounting without supporting direct interrupts, which
stubbing them would break. The guard has to test the Kconfig symbol
rather than the hooks themselves, because the arch-level irq.h headers
include <zephyr/irq.h> before defining them.
Exclude the block from Doxygen too, so that the documented stubs in
arch_interface.h stay the only visible definitions of the hooks;
otherwise they are reported as new undocumented API by the
documentation coverage check.
Assisted-by: Claude:claude-opus-5
Assisted-by: Claude:claude-fable-5
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
When reading the workqueue documentation, the priority of a workqueue
seemed important to me, so I checked the default priority of the system
workqueue. It being cooperative was unintuitive for me, since I thought
I could use it for low-priority background tasks. I asked about this on
Discord, and people generally confirmed that the system workqueue is not
ideal for this use case.
Link to question on Discord:
https://discord.com/channels/720317445772017664/720317445772017667/1543206806791389214
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
I was reading the scheduling documentation and noticed that mentions
of the CPU idling functions are not links to the relevant API
documentation, as is usually the case.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
I noticed there is no direct link to the API of `k_event_wait_all` while
reading the documentation.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
The structure of this sentence was a little convoluted, I think this one
makes it clearer how events and conditions are related and what a call
to `k_poll` waits for.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
sys_sflist stores flags in unused low bits of node links. The number of
available bits follows the ABI's natural pointer alignment, but the generic
header currently forces pointer-size alignment and globally requires two
bits.
That guarantee does not hold for borrowed nodes such as intrusive k_queue
items, which are caller-owned objects cast to sys_sfnode_t. On ABIs with
four-byte pointers and two-byte pointer alignment, only bit 0 is reliably
free.
Remove the forced alignment, expose SYS_SFLIST_FLAG_BITS, and let consumers
assert their own requirements. k_queue and the MMU free-page list each
require one bit. Make the unit test honor the capacity reported by the ABI
and clarify the intrusive queue alignment documentation.
This preserves generic flagged lists and safely supports one-bit ABIs.
Assisted-by: ChatGPT:gpt-5.6
Signed-off-by: Dimitri Varpusvuori <dimitri.varpusvuori@gmail.com>
This commit introduces a new timeout backend using a
Pugh skip list, which allows for O(log N) insertion
and removal of timeouts. The skip list maintains
a same-tick firing order and has no capacity
limit, making it suitable for systems with many
concurrent timeouts. The implementation includes
necessary Kconfig options and updates to the timeout
management code to support this new backend.
Signed-off-by: Dhruv Menon <dhruvmenon1104@gmail.com>
While reading through the documentation of threads, I cleaned up this
typo I noticed along the way.
Signed-off-by: Remo Senekowitsch <remo@buenzli.dev>
The new pending-state and active-IRQ operations use the k_irq_
namespace, leaving the seven legacy run-time interrupt APIs as the
only unprefixed ones in irq.h. Provide namespaced equivalents so the
API family is uniform and new code has a collision-free spelling:
k_irq_lock(), k_irq_unlock(), k_irq_enable(), k_irq_disable(),
k_irq_is_enabled(), k_irq_connect_dynamic() and
k_irq_disconnect_dynamic(), all ALWAYS_INLINE wrappers with
behaviour identical to the legacy names.
The unprefixed names remain fully supported and are not deprecated:
they have on the order of five thousand call sites in the tree alone
and far more out of tree, so any deprecation decision needs
migration data and belongs to a wider discussion. They also must
stay function-like macros rather than become inline functions:
vendor HAL headers declare functions with these exact names (the
Realtek Ameba ROM ABI declares irq_enable(IRQn_Type)), and a macro
coexists with such a declaration where a function definition would
conflict.
The compile-time constructs (IRQ_CONNECT, IRQ_DIRECT_CONNECT,
ISR_DIRECT_*) are left as they are: they live outside the contested
function namespace, so renaming them would be churn without benefit.
Document the aliases in the interrupts service documentation and the
release notes, and switch the irq_pending and irq_active test
applications to the namespaced spellings so the aliases have
build and runtime coverage on Cortex-M and Cortex-A/R.
Assisted-by: Claude:claude-fable-5
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Stop glob-expanding the entries of a zephyr_code_relocate(FILES ...)
list. Expanding a pattern to several files has been deprecated since
Zephyr 4.2; the supported way is to expand it in CMake with
file(GLOB ...) and pass the resulting file names.
A pattern is now rejected with a named error instead of being silently
accepted, so the failure cannot go unnoticed. Entries without pattern
characters keep their current behaviour, including the "Not found"
warning for a missing file. All in-tree callers already pass explicit
file names.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Assisted-by: Claude:opus-5
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>
