From eef51a895832535059ff9d1d357eebc3d29387a5 Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Mon, 23 Aug 2021 17:41:01 -0400 Subject: [PATCH] doc: kernel: move meta-irq doc to threads Move this to where priorities are being discussed to keep things in context and to have all priority types documented in 1 place. Fixes #21648 Signed-off-by: Anas Nashif --- doc/reference/kernel/scheduling/index.rst | 32 ----------------------- doc/reference/kernel/threads/index.rst | 32 +++++++++++++++++++++++ 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/reference/kernel/scheduling/index.rst b/doc/reference/kernel/scheduling/index.rst index e1e8c4f0f38..7032d404553 100644 --- a/doc/reference/kernel/scheduling/index.rst +++ b/doc/reference/kernel/scheduling/index.rst @@ -203,38 +203,6 @@ becomes the current thread, its non-preemptible status is maintained. Locking out the scheduler is a more efficient way for a preemptible thread to prevent preemption than changing its priority level to a negative value. -.. _metairq_priorities: - -Meta-IRQ Priorities -=================== - -When enabled (see :kconfig:`CONFIG_NUM_METAIRQ_PRIORITIES`), there is a special -subclass of cooperative priorities at the highest (numerically lowest) -end of the priority space: meta-IRQ threads. These are scheduled -according to their normal priority, but also have the special ability -to preempt all other threads (and other meta-irq threads) at lower -priorities, even if those threads are cooperative and/or have taken a -scheduler lock. - -This behavior makes the act of unblocking a meta-IRQ thread (by any -means, e.g. creating it, calling k_sem_give(), etc.) into the -equivalent of a synchronous system call when done by a lower -priority thread, or an ARM-like "pended IRQ" when done from true -interrupt context. The intent is that this feature will be used to -implement interrupt "bottom half" processing and/or "tasklet" features -in driver subsystems. The thread, once woken, will be guaranteed to -run before the current CPU returns into application code. - -Unlike similar features in other OSes, meta-IRQ threads are true -threads and run on their own stack (which must be allocated normally), -not the per-CPU interrupt stack. Design work to enable the use of the -IRQ stack on supported architectures is pending. - -Note that because this breaks the promise made to cooperative -threads by the Zephyr API (namely that the OS won't schedule other -thread until the current thread deliberately blocks), it should be -used only with great care from application code. These are not simply -very high priority threads and should not be used as such. .. _thread_sleeping: diff --git a/doc/reference/kernel/threads/index.rst b/doc/reference/kernel/threads/index.rst index 8f3a38c2686..8947feab944 100644 --- a/doc/reference/kernel/threads/index.rst +++ b/doc/reference/kernel/threads/index.rst @@ -260,6 +260,38 @@ ranges: For example, configuring 5 cooperative priorities and 10 preemptive priorities results in the ranges -5 to -1 and 0 to 9, respectively. +.. _metairq_priorities: + +Meta-IRQ Priorities +=================== + +When enabled (see :kconfig:`CONFIG_NUM_METAIRQ_PRIORITIES`), there is a special +subclass of cooperative priorities at the highest (numerically lowest) +end of the priority space: meta-IRQ threads. These are scheduled +according to their normal priority, but also have the special ability +to preempt all other threads (and other meta-irq threads) at lower +priorities, even if those threads are cooperative and/or have taken a +scheduler lock. + +This behavior makes the act of unblocking a meta-IRQ thread (by any +means, e.g. creating it, calling k_sem_give(), etc.) into the +equivalent of a synchronous system call when done by a lower +priority thread, or an ARM-like "pended IRQ" when done from true +interrupt context. The intent is that this feature will be used to +implement interrupt "bottom half" processing and/or "tasklet" features +in driver subsystems. The thread, once woken, will be guaranteed to +run before the current CPU returns into application code. + +Unlike similar features in other OSes, meta-IRQ threads are true +threads and run on their own stack (which must be allocated normally), +not the per-CPU interrupt stack. Design work to enable the use of the +IRQ stack on supported architectures is pending. + +Note that because this breaks the promise made to cooperative +threads by the Zephyr API (namely that the OS won't schedule other +thread until the current thread deliberately blocks), it should be +used only with great care from application code. These are not simply +very high priority threads and should not be used as such. .. _thread_options_v2: