pub struct Kernel<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> { /* private fields */ }Expand description
The scheduler.
TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS and BYTES are
the geometry: how many tasks, list items, lists, queues, queue item
slots, stream buffers, and stream-buffer bytes this kernel has room
for. See the crate docs and [items_for] / lists_for.
Kernel::new refuses a geometry that does not add up.
Implementations§
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
Sourcepub fn event_group_create(&mut self) -> Result<EventGroupHandle>
pub fn event_group_create(&mut self) -> Result<EventGroupHandle>
Sourcepub fn event_group_delete(&mut self, group: EventGroupHandle) -> Result<()>
pub fn event_group_delete(&mut self, group: EventGroupHandle) -> Result<()>
vEventGroupDelete.
Every waiter is unblocked with a value of zero and the bit-set flag, so each wakes, finds its condition unmet, and reports what the C reports: a timeout.
§Errors
Error::Gone for a stale handle.
Sourcepub fn event_group_bits(&mut self, group: EventGroupHandle) -> Result<u32>
pub fn event_group_bits(&mut self, group: EventGroupHandle) -> Result<u32>
xEventGroupGetBits, which the C defines as
xEventGroupClearBits( xEventGroup, 0 ) — so it costs the same
critical section a clear does.
§Errors
Error::Gone for a stale handle.
Sourcepub fn event_group_bits_from_isr(&self, group: EventGroupHandle) -> Result<u32>
pub fn event_group_bits_from_isr(&self, group: EventGroupHandle) -> Result<u32>
xEventGroupGetBitsFromISR. The Posix port’s interrupt mask costs
nothing, so neither does this.
§Errors
Error::Gone for a stale handle.
Sourcepub fn event_group_clear_bits(
&mut self,
group: EventGroupHandle,
bits: u32,
) -> Result<u32>
pub fn event_group_clear_bits( &mut self, group: EventGroupHandle, bits: u32, ) -> Result<u32>
Sourcepub fn event_group_set_bits(
&mut self,
group: EventGroupHandle,
bits: u32,
) -> Result<u32>
pub fn event_group_set_bits( &mut self, group: EventGroupHandle, bits: u32, ) -> Result<u32>
xEventGroupSetBits: set them, then wake every waiter the new value
satisfies and clear whatever those waiters asked to have cleared.
§Errors
Error::Gone for a stale handle.
Sourcepub fn event_group_set_bits_from_isr(
&mut self,
group: EventGroupHandle,
bits: u32,
) -> Result<(bool, Woken)>
pub fn event_group_set_bits_from_isr( &mut self, group: EventGroupHandle, bits: u32, ) -> Result<(bool, Woken)>
xEventGroupSetBitsFromISR.
An interrupt cannot walk the waiting list, so the C hands the job to
the daemon task through xTimerPendFunctionCallFromISR and answers
whether the daemon took it, not what the bits became.
§Errors
As the queue send behind xTimerPendFunctionCallFromISR.
Sourcepub fn event_group_clear_bits_from_isr(
&mut self,
group: EventGroupHandle,
bits: u32,
) -> Result<(bool, Woken)>
pub fn event_group_clear_bits_from_isr( &mut self, group: EventGroupHandle, bits: u32, ) -> Result<(bool, Woken)>
xEventGroupClearBitsFromISR, deferred the same way.
§Errors
As the queue send behind xTimerPendFunctionCallFromISR.
Sourcepub fn event_group_pended_call(
&mut self,
function: u16,
param1: u64,
param2: u64,
) -> Result<()>
pub fn event_group_pended_call( &mut self, function: u16, param1: u64, param2: u64, ) -> Result<()>
The daemon task’s half of those two: vEventGroupSetBitsCallback
and vEventGroupClearBitsCallback.
A TickHook::pended implementation routes PENDED_SET_BITS and
PENDED_CLEAR_BITS here; every other function is the
application’s own.
§Errors
Error::Gone when the group has been deleted since.
Sourcepub fn event_group_wait_bits(
&mut self,
group: EventGroupHandle,
wait_for: u32,
clear_on_exit: bool,
wait_for_all: bool,
ticks: u64,
) -> Result<Wait<u32>>
pub fn event_group_wait_bits( &mut self, group: EventGroupHandle, wait_for: u32, clear_on_exit: bool, wait_for_all: bool, ticks: u64, ) -> Result<Wait<u32>>
xEventGroupWaitBits.
The C blocks in the middle of this function and finishes it on the
far side of the switch. A kernel with no stacks cannot, so a call
that has to block answers Wait::Blocked and is called again; the
second call is the far side, and starts at
uxTaskResetEventItemValue.
§Errors
Error::Gone for a stale handle.
Sourcepub fn event_group_sync(
&mut self,
group: EventGroupHandle,
set: u32,
wait_for: u32,
ticks: u64,
) -> Result<Wait<u32>>
pub fn event_group_sync( &mut self, group: EventGroupHandle, set: u32, wait_for: u32, ticks: u64, ) -> Result<Wait<u32>>
xEventGroupSync: set some bits, then wait for a set that usually
includes them — the rendezvous every task in a group must reach.
It has its own two trace points, traceEVENT_GROUP_SYNC_BLOCK and
traceEVENT_GROUP_SYNC_END, which the Kairos harness does not hook.
The xEventGroupSetBits inside it traces as itself, and that is the
only line a sync puts in the trace.
§Errors
Error::Gone for a stale handle.
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
Sourcepub const MAX_DELAY: u64 = <C::Tick as TickWidth>::MAX
pub const MAX_DELAY: u64 = <C::Tick as TickWidth>::MAX
portMAX_DELAY at this configuration’s tick width.
Sourcepub const FOOTPRINT: usize
pub const FOOTPRINT: usize
The kernel’s own static size, and the same number size_of gives.
The consts below decompose it. They exist because a footprint you
cannot decompose to the byte is a footprint you cannot optimise: the
arena fields are pub(crate) and their types are private, so nothing
outside this crate can measure them, and a decomposition assembled
from per-dimension SLOPES is not one — ITEMS and LISTS are derived
from TASKS, QUEUES and GROUPS, so the function is not linear and
slopes do not sum to the total. That was tried; it produced 696 bytes
of nonsense.
Every one is size_of on whatever target this is compiled for, which
is the only place the number means anything: a host usize is eight
bytes and rv32’s is four.
FOOTPRINT_ACCOUNTED sums them, and the
difference from FOOTPRINT is padding plus the
scalar tail — print both, never one. bench/kernel-ram does.
Sourcepub const FOOTPRINT_TCBS: usize
pub const FOOTPRINT_TCBS: usize
The task control blocks.
Sourcepub const FOOTPRINT_QUEUES: usize
pub const FOOTPRINT_QUEUES: usize
The queue descriptors, and NOT their item storage.
Sourcepub const FOOTPRINT_LISTS: usize
pub const FOOTPRINT_LISTS: usize
Every intrusive list: ready, delayed, and the per-object waiters.
Sourcepub const FOOTPRINT_SLOTS: usize
pub const FOOTPRINT_SLOTS: usize
Queue item storage, as u64 slots.
Sourcepub const FOOTPRINT_BUFFERS: usize
pub const FOOTPRINT_BUFFERS: usize
The stream-buffer descriptors, and NOT their bytes.
Sourcepub const FOOTPRINT_TIMERS: usize
pub const FOOTPRINT_TIMERS: usize
The software timers.
Sourcepub const FOOTPRINT_GROUPS: usize
pub const FOOTPRINT_GROUPS: usize
The event groups.
Sourcepub const FOOTPRINT_TIMER_MESSAGES: usize
pub const FOOTPRINT_TIMER_MESSAGES: usize
The timer daemon’s command mailbox.
It scales with TIMER_CMDS now, which the geometry check pins to
Config::TIMER_QUEUE_LENGTH. It used to be a hardcoded 32 and so
scaled with nothing — a fixed 768 bytes, 39 % of a two-task kernel.
The line stays separate because that history is worth being able to
read off a decomposition.
Sourcepub const FOOTPRINT_BYTES: usize
pub const FOOTPRINT_BYTES: usize
The byte arena, for stream-buffer contents.
Sourcepub const FOOTPRINT_FREE_LISTS: usize
pub const FOOTPRINT_FREE_LISTS: usize
The two free lists, over the byte arena and the slot arena.
Sourcepub const FOOTPRINT_PER_TASK_SIDE: usize
pub const FOOTPRINT_PER_TASK_SIDE: usize
The seven per-task side arrays, together.
Seven arrays indexed by the same task, five of them [bool; TASKS].
Whether that wants to be one array of a flags byte is a question this
number is here to make askable.
Sourcepub const FOOTPRINT_ACCOUNTED: usize
pub const FOOTPRINT_ACCOUNTED: usize
What the lines above account for.
FOOTPRINT - FOOTPRINT_ACCOUNTED is the unattributed remainder: the
scalar tail (tick, current, the counters) plus whatever padding
the layout inserts. It was 140 bytes of 6,784 when this was written. A
remainder that grows is a field somebody added without adding a line
here.
Sourcepub fn new(port: P, trace: T) -> Result<Self>where
H: Default,
pub fn new(port: P, trace: T) -> Result<Self>where
H: Default,
A kernel with no tasks, ready for Kernel::create_task.
§Errors
Error::InvalidArgument if the configuration is invalid
(Config::validate), if the name capacity cannot hold
MAX_TASK_NAME_LEN, or if the const geometry does not match the
configuration: ITEMS must be [items_for](TASKS) and LISTS
must be lists_for(MAX_PRIORITIES, QUEUES).
Sourcepub fn with_tick_hook(port: P, trace: T, tick_hook: H) -> Result<Self>
pub fn with_tick_hook(port: P, trace: T, tick_hook: H) -> Result<Self>
Sourcepub fn into_trace(self) -> T
pub fn into_trace(self) -> T
Take the trace sink back when the run is over, so a deliverable can flush whatever it was writing to.
Sourcepub fn current(&self) -> TaskHandle
pub fn current(&self) -> TaskHandle
pxCurrentTCB: the task running on the calling core.
No longer const: on an SMP build the answer depends on which core
asks (portGET_CORE_ID()), which is the port’s to say.
Sourcepub fn current_on(&self, core: usize) -> TaskHandle
pub fn current_on(&self, core: usize) -> TaskHandle
pxCurrentTCBs[ core ]: the task running on core, or the null
handle for a core this configuration does not have.
Sourcepub const fn tick_count(&self) -> u64
pub const fn tick_count(&self) -> u64
xTaskGetTickCount.
Sourcepub const fn is_running(&self) -> bool
pub const fn is_running(&self) -> bool
xSchedulerRunning.
Sourcepub const fn task_count(&self) -> usize
pub const fn task_count(&self) -> usize
uxCurrentNumberOfTasks.
Sourcepub const fn scheduler_suspended(&self) -> u32
pub const fn scheduler_suspended(&self) -> u32
uxSchedulerSuspended, for a stepper reporting why a tick pended.
Sourcepub const fn pended_ticks(&self) -> u64
pub const fn pended_ticks(&self) -> u64
xPendedTicks, likewise.
Sourcepub fn ready_items(&self, priority: u8, out: &mut [u16]) -> usize
pub fn ready_items(&self, priority: u8, out: &mut [u16]) -> usize
The item ids in priority’s ready list, in order, into out.
Returns how many were written. The companion to
Kernel::ready_cursor: when a ready task is never chosen, the
cursor says whether the rotation moved and this says what it was
moving THROUGH.
Sourcepub fn ready_cursor(&self, priority: u8) -> u16
pub fn ready_cursor(&self, priority: u8) -> u16
Where the round-robin cursor sits in priority’s ready list.
A diagnostic, paired with Kernel::ready_len: a ready task that
is never chosen is either not in the list the scheduler looks at,
or the cursor is not moving. These two answer both halves.
Sourcepub fn task_at(&self, index: usize) -> Option<TaskHandle>
pub fn task_at(&self, index: usize) -> Option<TaskHandle>
The live handle in arena slot index, if that slot holds a task.
The generation is the point: a bare index names a SLOT, and a slot outlives the tasks that occupy it, so an index is not a task. This answers the handle, which is.
It exists so a diagnostic can walk every task without knowing any
of their names – task_get_handle needs the name it is looking
for, and a crash report is exactly the case where you do not have
one.
Sourcepub fn name_of(&self, task: TaskHandle) -> Result<Name>
pub fn name_of(&self, task: TaskHandle) -> Result<Name>
Sourcepub fn priority_of(&self, task: Option<TaskHandle>) -> Result<u8>
pub fn priority_of(&self, task: Option<TaskHandle>) -> Result<u8>
Sourcepub fn task_priority_get(&mut self, task: Option<TaskHandle>) -> Result<u8>
pub fn task_priority_get(&mut self, task: Option<TaskHandle>) -> Result<u8>
uxTaskPriorityGet: the C API, which takes a critical section.
The distinction matters: on the sim a critical-section exit is where
time passes, so reading a priority through the API costs a tick
sixteen calls later, exactly as it does in C
(portBASE_TYPE_ENTER_CRITICAL is taskENTER_CRITICAL on the Posix
port). The kernel’s own reads use the field directly, as C’s do.
§Errors
Error::Gone for a stale handle.
Sourcepub fn task_state_get(&mut self, task: TaskHandle) -> Result<TaskState>
pub fn task_state_get(&mut self, task: TaskHandle) -> Result<TaskState>
eTaskGetState: the C API, which takes a critical section for any
task but the running one.
§Errors
A list error surfaces as itself.
Sourcepub fn state_of(&self, task: TaskHandle) -> Result<TaskState>
pub fn state_of(&self, task: TaskHandle) -> Result<TaskState>
Sourcepub fn ready_len(&self, priority: u8) -> Result<usize>
pub fn ready_len(&self, priority: u8) -> Result<usize>
How many tasks sit on a priority’s ready list — what the idle task
checks before yielding (configIDLE_SHOULD_YIELD).
§Errors
Error::InvalidPriority for a priority outside the configuration.
Sourcepub const fn stalls(&self) -> u32
pub const fn stalls(&self) -> u32
How many times the scheduler could not choose a task.
Non-zero means an invariant broke. A healthy kernel never stalls: the idle task is always ready. A firmware that prints this alongside its own counters turns a hang into a sentence.
Sourcepub const fn first_stall(&self) -> Stall
pub const fn first_stall(&self) -> Stall
Why the scheduler first failed to choose. Stall::None if it never
has.
Sourcepub fn enter_critical(&mut self)
pub fn enter_critical(&mut self)
taskENTER_CRITICAL().
Sourcepub fn exit_critical(&mut self)
pub fn exit_critical(&mut self)
taskEXIT_CRITICAL().
On the sim this is where time passes: the port raises a tick on
every sixteenth outermost exit and the kernel takes it here, which
is exactly where the C kernel’s SIGALRM handler would have run.
NOT in line, though it is three statements called 118,640 times in
a 20,000-tick StreamBufferDemo. #[inline(always)] was measured:
it saves that scenario 210,292 and costs BlockQ 200,912 and
GenQTest 280,540, for a net loss of 271,962 over six scenarios.
Whatever the hot sites gain, the switch-heavy ones lose more.
§On two cores the outermost exit is a yield point
SMP vTaskExitCritical reads xYieldPendings[ xCoreID ] as the
nesting reaches zero and yields if it is set – whoever set it. A yield
left pending by an interrupt that had no woken pointer to report it
through (xEventGroupClearBitsFromISR, or any FromISR call passed
NULL) is taken at the next task-level exit on that core. Kairos took
it only at the sites that had set it themselves, so the task the
interrupt readied waited for some later switch: the API differential
caught it (two cores, a vTaskSuspend four steps after the ISR).
Sampled BEFORE the port exit, as the C samples before it re-enables
interrupts, and taken after it. One core has no such rule – its
vTaskExitCritical never yields – and compiles none of this.
Sourcepub fn tick_from_isr(&mut self)
pub fn tick_from_isr(&mut self)
vPortSystemTickHandler: the tick, from interrupt context.
A silicon port calls this from its timer interrupt. The sim reaches
it from Kernel::exit_critical – through Kernel::tick_on_exit,
which is where the reason for this attribute is written down – and
from the idle hook.
Sourcepub fn idle_hook_tick(&mut self)
pub fn idle_hook_tick(&mut self)
The idle hook’s tick, vPortKairosTick() on the C side: a critical
section around one unconditional tick. The enclosing section counts
toward rule 3 exactly as the C one does.
Sourcepub fn step_tick(&mut self, ticks_to_jump: u64)
pub fn step_tick(&mut self, ticks_to_jump: u64)
vTaskStepTick: wind the tick count forward over a suppressed period.
Note this does not call the tick hook for each stepped tick, which is the C’s own note and the reason a tickless trace has no heartbeat in it.
The C configASSERTs that the jump does not pass the next unblock
time. This clamps instead: a port that overslept is a port bug, and
winding the clock past a task’s wake would lose the wake entirely,
where losing the extra sleep is recoverable. forbid(unsafe) buys
nothing if the kernel panics on a misbehaving port.
Landing exactly on the next unblock time leaves the last tick pended
rather than stepped, so increment_tick runs it when the scheduler
resumes and the delayed task is woken by the same code that would
have woken it.
Sourcepub fn idle_suppress_ticks(&mut self)
pub fn idle_suppress_ticks(&mut self)
The configUSE_TICKLESS_IDLE block of prvIdleTask.
Compiled away entirely when the configuration leaves tickless idle off, which is the default and is why every existing scenario is byte-identical with this in the tree.
The shape is the C’s, including the part that looks redundant: the expected idle time is sampled once WITHOUT the scheduler suspended, and again with it. The first answer is not necessarily valid and the C takes it anyway, because suspending and resuming the scheduler on every pass of the idle task costs more than a sample that is sometimes wasted.
Sourcepub fn task_yield(&mut self)
pub fn task_yield(&mut self)
taskYIELD() from a task body (the idle task’s yield).
Sourcepub fn create_task(&mut self, name: &str, priority: u8) -> Result<TaskHandle>
pub fn create_task(&mut self, name: &str, priority: u8) -> Result<TaskHandle>
xTaskCreate.
Like the C, the new task becomes current if its priority is at or
above the running one’s. On a hosted firmware that is the sharp
edge: the CPU is still on the caller’s stack, so creating a
higher-priority task hands current to something that is not
running. See Kernel::start_scheduler, which creates the timer
daemon at Config::TIMER_TASK_PRIORITY for exactly this reason and
documents the failure it produces — a clean run reporting zero laps.
§Errors
Error::Full when the task arena is full (the C
errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY).
Sourcepub fn start_scheduler(&mut self) -> Result<StartHandles>
pub fn start_scheduler(&mut self) -> Result<StartHandles>
vTaskStartScheduler, minus the part that never returns.
Creates the idle task, the timer command queue and the timer service
task, fires TASK_SWITCHED_IN for whichever task will run first and
then STARTING_SCHEDULER, and returns the handles so the runner can
attach their bodies.
§★ The timer daemon is created at Config::TIMER_TASK_PRIORITY,
and it will outrank a task you created below it
This is the C’s behaviour and it is deliberate, but on a hosted firmware it has a failure mode that looks like nothing at all.
Tmr Svc is created here unconditionally, and
Kernel::create_task makes the highest-priority task current. So a
firmware whose own main runs below TIMER_TASK_PRIORITY leaves the
kernel believing a stackless task is running: current names the
daemon while the CPU is on main’s stack. Every
Kernel::switch_context then declines as from == to, the workers
never start, and the symptom is a clean run reporting zero laps
rather than a fault.
Nothing here can detect it — a stackless kernel cannot see whose stack the CPU is actually on — so it is a caller’s invariant:
Give the task that owns the CPU a priority at or above
Config::TIMER_TASK_PRIORITY, or lowerTIMER_TASK_PRIORITYbelow it.
Reported from the Janus side, where it cost a board run
(docs/plans/janus-rtos.md §5b), and seen again in the radio cell.
§Errors
Sourcepub fn take_core_yields(&mut self) -> u8
pub fn take_core_yields(&mut self) -> u8
The OTHER cores this kernel has asked to yield since the last call, one bit per core, cleared by the read.
A port calls this on its way out of the kernel lock and raises the inter-processor interrupt of each core named. Always zero on one core.
Sourcepub fn switch_context(&mut self)
pub fn switch_context(&mut self)
vTaskSwitchContext.
Sourcepub fn resume_pending(&mut self) -> bool
pub fn resume_pending(&mut self) -> bool
Pay whatever the running task still owes from a call it was
preempted inside. The runner calls this before stepping a body;
true means work was done and the current task may have changed
again, so nothing else should be assumed.
Sourcepub fn increment_tick(&mut self) -> bool
pub fn increment_tick(&mut self) -> bool
xTaskIncrementTick; true when a context switch is required.
Sourcepub fn notify_wait(
&mut self,
index: usize,
clear_on_entry: u32,
clear_on_exit: u32,
ticks: u64,
) -> Result<Wait<(bool, u32)>>
pub fn notify_wait( &mut self, index: usize, clear_on_entry: u32, clear_on_exit: u32, ticks: u64, ) -> Result<Wait<(bool, u32)>>
xTaskGenericNotifyWait.
true is pdTRUE: a notification was received. Blocked means the
caller must call again — the C blocks inside this function, and a
kernel with no stacks returns instead.
§Errors
Error::InvalidArgument for an index past the configured array.
Sourcepub fn notify_take(
&mut self,
index: usize,
clear_on_exit: bool,
ticks: u64,
) -> Result<Wait<u32>>
pub fn notify_take( &mut self, index: usize, clear_on_exit: bool, ticks: u64, ) -> Result<Wait<u32>>
ulTaskGenericNotifyTake: the notification used as a lightweight
counting semaphore — block until the value is non-zero, then either
zero it or decrement it by one.
This is the half of the notification API the kernel was missing.
notify_wait waits on bits; this waits on a count, and the two
are separate calls in the C with their own trace events. Its
partner, xTaskNotifyGive, needs no method of its own: the C
defines it as xTaskGenericNotify( .., 0, eIncrement, NULL ) and
it traces as an ordinary notify, so
notify(task, index, 0, NotifyAction::Increment) already is it.
§The shape, and why it is not notify_wait’s
The C blocks on ulNotifiedValue == 0, not on the notify
state, and it does no clear-on-entry. Both halves run on the way
out: traceTASK_NOTIFY_TAKE fires whether or not the call ever
blocked, which is what makes a take that finds a count already
waiting still emit one line.
This kernel has no stack, so the block is a return: the first call
answers Wait::Blocked and the caller is entered again when the
scheduler runs it, taking the second half. notify_wait_pending
answers for this call too — a task is only ever inside one of the
two.
§Errors
Error::InvalidArgument for an index past the configured array.
Sourcepub fn task_get_handle(&mut self, name: &str) -> Result<TaskHandle>
pub fn task_get_handle(&mut self, name: &str) -> Result<TaskHandle>
xTaskGetHandle: the task registered under name.
§It is not free, and that is the point
The C walks every ready list, then the delayed lists, then the
suspended and waiting-termination lists, all inside
vTaskSuspendAll / xTaskResumeAll — and xTaskResumeAll takes a
critical section. So a lookup that emits no trace event still
costs one critical-section exit, which under the sim contract is
one unit of time.
That is why this exists rather than a scenario keeping the handle it
was given at creation. AbortDelay’s remake did exactly that, on the
reasoning that a lookup emitting no event could not change the trace,
and the corpus caught it: every event still agreed and the
exit column was one short at the first block.
The arena is searched instead of five lists, which cannot change the answer — a live task is in exactly one of them — and does not change the accounting either, because the cost is the suspend/resume pair.
§Errors
Error::Gone when no live task carries that name.
Sourcepub fn notify(
&mut self,
task: TaskHandle,
index: usize,
value: u32,
action: NotifyAction,
) -> Result<bool>
pub fn notify( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<bool>
Sourcepub fn notify_from_isr(
&mut self,
task: TaskHandle,
index: usize,
value: u32,
action: NotifyAction,
) -> Result<(bool, Woken)>
pub fn notify_from_isr( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<(bool, Woken)>
xTaskGenericNotifyFromISR: the same, without a critical section
that costs anything, and putting a woken task on the pending-ready
list when the scheduler is suspended.
§Errors
As Kernel::notify.
Sourcepub fn notify_and_query(
&mut self,
task: TaskHandle,
index: usize,
value: u32,
action: NotifyAction,
) -> Result<(bool, u32)>
pub fn notify_and_query( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<(bool, u32)>
xTaskGenericNotify with its pulPreviousNotificationValue
out-parameter filled: xTaskNotifyAndQuery.
It exists because the answer has to come out of the SAME critical
section as the notification. Reading Kernel::notify_value first
and then notifying yields the same two numbers and costs a second
critical section – and on the sim a critical-section exit is a
tick opportunity, so the extra one moves the tick and the trace
stops matching the C. TaskNotify.c calls this eleven times.
§Errors
As Kernel::notify.
Sourcepub fn notify_and_query_from_isr(
&mut self,
task: TaskHandle,
index: usize,
value: u32,
action: NotifyAction,
) -> Result<(bool, u32, Woken)>
pub fn notify_and_query_from_isr( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<(bool, u32, Woken)>
Sourcepub fn notify_state_clear(
&mut self,
task: Option<TaskHandle>,
index: usize,
) -> Result<bool>
pub fn notify_state_clear( &mut self, task: Option<TaskHandle>, index: usize, ) -> Result<bool>
Sourcepub fn notify_value(
&mut self,
task: Option<TaskHandle>,
index: usize,
) -> Result<u32>
pub fn notify_value( &mut self, task: Option<TaskHandle>, index: usize, ) -> Result<u32>
ulNotifiedValue[ index ] for a task. None is the calling task.
The C reaches this through xTaskNotifyAndQuery, which hands back
the value a notification is about to REPLACE, and through
ulTaskNotifyValueClear. Neither could be implemented without it:
xTaskNotifyAndQuery is xTaskGenericNotify with a
pulPreviousNotificationValue out-parameter, and TaskNotify.c:373
asserts on what comes back. The field existed; only the way to read
it was missing, which is the kind of gap a C ABI finds and a Rust
face never does.
§Errors
InvalidArgument if index is outside the notification array, or
the resolve error if the handle is stale.
Sourcepub fn notify_value_clear(
&mut self,
task: Option<TaskHandle>,
index: usize,
bits: u32,
) -> Result<u32>
pub fn notify_value_clear( &mut self, task: Option<TaskHandle>, index: usize, bits: u32, ) -> Result<u32>
ulTaskGenericNotifyValueClear: clear bits in the task’s
notification value and answer what it was BEFORE the clear.
§Errors
Sourcepub fn notify_wait_pending(&self, task: TaskHandle) -> bool
pub fn notify_wait_pending(&self, task: TaskHandle) -> bool
Whether task is part-way through a notification wait — it blocked
once and has not yet run the half of xTaskGenericNotifyWait that
happens when a task wakes.
A caller that blocks on a notification needs this: the C’s wait returns after the wake, so its second half always runs, and a stackless caller that decided not to block again would otherwise skip it and leave the slot marked as received for ever.
Sourcepub const fn tick_count_from_isr(&self) -> u64
pub const fn tick_count_from_isr(&self) -> u64
xTaskGetTickCountFromISR.
No critical section, exactly as xTaskGetTickCount takes none: the
Posix port sets portTICK_TYPE_IS_ATOMIC, so reading the count is
a single load on both sides and costs no sim time.
Sourcepub const fn tick_hook(&self) -> &H
pub const fn tick_hook(&self) -> &H
The tick hook, as it now stands.
A scenario’s xAre...StillRunning() reads the status its interrupt
half latched, so the owner of the kernel needs to see it.
Sourcepub const fn tick_hook_mut(&mut self) -> &mut H
pub const fn tick_hook_mut(&mut self) -> &mut H
The tick hook, to install or reset one after construction.
Sourcepub fn abort_delay(&mut self, task: TaskHandle) -> Result<bool>
pub fn abort_delay(&mut self, task: TaskHandle) -> Result<bool>
xTaskAbortDelay: pull a task out of the Blocked state early.
true is pdPASS — the task really was blocked and is now ready.
A task that was not blocked is left alone and false comes back,
which is the C’s pdFAIL.
The shape matters as much as the effect: the whole thing runs with
the scheduler suspended, the event list is touched inside a critical
section of its own because an interrupt can reach it, and a yield
that the higher priority of the woken task calls for is pended
rather than taken, so it happens on the way out of xTaskResumeAll.
§Errors
Error::Gone for a stale handle.
Sourcepub fn resume(&mut self, task: TaskHandle) -> Result<()>
pub fn resume(&mut self, task: TaskHandle) -> Result<()>
Sourcepub fn task_delete(&mut self, task: Option<TaskHandle>) -> Result<()>
pub fn task_delete(&mut self, task: Option<TaskHandle>) -> Result<()>
vTaskDelete. None deletes the calling task.
§Two paths, and the C picks between them for a reason
Deleting another task frees its TCB on the spot. Deleting the
running task cannot: the caller is still executing out of it. The
C parks such a task on xTasksWaitingTermination and lets the idle
task reclaim it, which is what prvCheckTasksWaitingTermination is
for — so Kernel::check_tasks_waiting_termination is where the
deferred half lands here, called from the idle body at the same point
in the same loop.
§The frees are outside the critical section, and they cost exits
prvDeleteTCB runs after taskEXIT_CRITICAL() and frees twice —
vPortFreeStack( pxStack ) then vPortFree( pxTCB ). On the oracle’s
heap every free suspends the scheduler, so a delete is one exit for
its own section plus two for the frees, in that order. Folding the
frees into the section, or forgetting them, moves every later tick.
§Errors
Error::Gone for a stale handle.
Sourcepub fn check_tasks_waiting_termination(&mut self)
pub fn check_tasks_waiting_termination(&mut self)
prvCheckTasksWaitingTermination, called from the idle task.
§This must cost NOTHING when nothing is pending
The C’s body is while( uxDeletedTasksWaitingCleanUp > 0 ), so an
idle loop with no deleted task takes no critical section and pays no
exit. That is what lets this be wired into the idle body without
disturbing a single scenario in the corpus — and it is the property
the corpus is checking when it stays byte-identical.
MORE than one task can be pending, which this used to deny: a task that deletes itself yields to the next ready task, not to idle, and that task can delete itself too before idle ever runs. Each waits, in order, as on the C’s list.
Sourcepub fn set_priority(
&mut self,
task: Option<TaskHandle>,
new_priority: u8,
) -> Result<()>
pub fn set_priority( &mut self, task: Option<TaskHandle>, new_priority: u8, ) -> Result<()>
vTaskPrioritySet. None is the calling task. /// vTaskPrioritySet. None is the calling task.
§Errors
Error::Gone for a stale handle.
Sourcepub fn suspend_all(&mut self)
pub fn suspend_all(&mut self)
vTaskSuspendAll.
Sourcepub fn resume_all(&mut self) -> bool
pub fn resume_all(&mut self) -> bool
xTaskResumeAll; true when it yielded on the caller’s behalf.
Out of line for the cold callers; the body is Kernel::resume_all_inline.
Sourcepub fn delay_until(
&mut self,
previous_wake: &mut u64,
period: u64,
) -> Result<bool>
pub fn delay_until( &mut self, previous_wake: &mut u64, period: u64, ) -> Result<bool>
xTaskDelayUntil: wake at *previous_wake + period, whatever the
task did in between. false when the deadline has already passed,
in which case nothing blocks — exactly as the C returns pdFALSE.
§Errors
A list error surfaces as itself.
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
Sourcepub fn queue_create(&mut self, length: usize) -> Result<QueueHandle>
pub fn queue_create(&mut self, length: usize) -> Result<QueueHandle>
xQueueCreate.
§Errors
Error::Full when the queue arena or the shared slot pool is
exhausted; Error::InvalidArgument for a zero length.
Sourcepub fn queue_delete(&mut self, queue: QueueHandle) -> Result<()>
pub fn queue_delete(&mut self, queue: QueueHandle) -> Result<()>
vQueueDelete, and vSemaphoreDelete, which the C defines as the
same function.
§It traces nothing and still costs time
vQueueDelete takes no critical section of its own — but it ends in
vPortFree( pxQueue ), and every heap_N.c wraps free in
vTaskSuspendAll / xTaskResumeAll exactly as it wraps malloc. So
a delete costs one outermost critical-section exit, which under
the sim contract is one unit of time, while emitting no trace line
at all (this harness defines no traceQUEUE_DELETE).
AbortDelay’s remake left the deletes out on the reasoning that an
event-less call cannot move the trace. Every event still agreed and
the exit column was one short from the first delete onwards. The
sibling event_group_delete already carried this note; the queue
had no delete at all.
§Errors
Error::Gone for a stale handle.
Sourcepub fn semaphore_create_binary(&mut self) -> Result<QueueHandle>
pub fn semaphore_create_binary(&mut self) -> Result<QueueHandle>
Sourcepub fn semaphore_create_counting(
&mut self,
max: usize,
initial: usize,
) -> Result<QueueHandle>
pub fn semaphore_create_counting( &mut self, max: usize, initial: usize, ) -> Result<QueueHandle>
xSemaphoreCreateCounting.
§Errors
As Kernel::queue_create; Error::InvalidArgument if the
initial count exceeds the maximum.
Sourcepub fn mutex_create(&mut self) -> Result<QueueHandle>
pub fn mutex_create(&mut self) -> Result<QueueHandle>
Sourcepub fn mutex_create_recursive(&mut self) -> Result<QueueHandle>
pub fn mutex_create_recursive(&mut self) -> Result<QueueHandle>
Sourcepub fn queue_messages_waiting(&mut self, queue: QueueHandle) -> Result<usize>
pub fn queue_messages_waiting(&mut self, queue: QueueHandle) -> Result<usize>
Sourcepub fn queue_is_full_from_isr(&self, queue: QueueHandle) -> Result<bool>
pub fn queue_is_full_from_isr(&self, queue: QueueHandle) -> Result<bool>
xQueueIsQueueFullFromISR, which takes NO critical section.
The C compares uxMessagesWaiting against uxLength and returns,
with nothing around it — it is meant to be called from an interrupt,
where a critical section would be the wrong thing. That is why this
takes &self and Kernel::queue_messages_waiting takes &mut self: the borrow is the proof that this one cannot charge the
clock, and on the sim a charged section is a sixteenth of a tick.
§Errors
Error::Gone for a stale handle.
Sourcepub fn semaphore_count(&mut self, semaphore: QueueHandle) -> Result<usize>
pub fn semaphore_count(&mut self, semaphore: QueueHandle) -> Result<usize>
Sourcepub fn mutex_holder_from_isr(
&mut self,
mutex: QueueHandle,
) -> Result<TaskHandle>
pub fn mutex_holder_from_isr( &mut self, mutex: QueueHandle, ) -> Result<TaskHandle>
xSemaphoreGetMutexHolderFromISR, which is
xQueueGetMutexHolderFromISR: the same answer, read without a
critical section because an ISR is already inside one.
§Errors
Error::Gone for a stale handle.
Sourcepub fn mutex_holder(&mut self, mutex: QueueHandle) -> Result<TaskHandle>
pub fn mutex_holder(&mut self, mutex: QueueHandle) -> Result<TaskHandle>
Sourcepub fn queue_send(
&mut self,
queue: QueueHandle,
value: u64,
ticks: u64,
) -> Result<Wait<()>>
pub fn queue_send( &mut self, queue: QueueHandle, value: u64, ticks: u64, ) -> Result<Wait<()>>
xQueueSend / xQueueSendToBack.
§Errors
Error::Full when the block time expires with the queue still
full; Error::Gone for a stale handle.
Sourcepub fn queue_reset(&mut self, queue: QueueHandle) -> Result<()>
pub fn queue_reset(&mut self, queue: QueueHandle) -> Result<()>
xQueueReset, which is xQueueGenericReset( q, pdFALSE ): empty
the queue and unlock it, waking one waiting sender if there is one.
The event lists survive — only a brand-new queue re-initialises those — so a task blocked on this queue stays blocked, and the one woken here is woken because the reset made room.
§Errors
Error::Gone for a stale handle.
Sourcepub fn queue_spaces_available(&mut self, queue: QueueHandle) -> Result<usize>
pub fn queue_spaces_available(&mut self, queue: QueueHandle) -> Result<usize>
Sourcepub fn queue_create_set(&mut self, length: usize) -> Result<QueueHandle>
pub fn queue_create_set(&mut self, length: usize) -> Result<QueueHandle>
Sourcepub fn queue_add_to_set(
&mut self,
queue: QueueHandle,
set: QueueHandle,
) -> Result<bool>
pub fn queue_add_to_set( &mut self, queue: QueueHandle, set: QueueHandle, ) -> Result<bool>
xQueueAddToSet.
false is the C’s pdFAIL: the target is not a set, the queue is
already in one, or it has items waiting that the set never saw.
§Errors
Error::Gone for a stale handle.
Sourcepub fn queue_remove_from_set(
&mut self,
queue: QueueHandle,
set: QueueHandle,
) -> Result<bool>
pub fn queue_remove_from_set( &mut self, queue: QueueHandle, set: QueueHandle, ) -> Result<bool>
Sourcepub fn queue_select_from_set(
&mut self,
set: QueueHandle,
ticks: u64,
) -> Result<Wait<Option<QueueHandle>>>
pub fn queue_select_from_set( &mut self, set: QueueHandle, ticks: u64, ) -> Result<Wait<Option<QueueHandle>>>
xQueueSelectFromSet: which member queue has something on it.
The C is one line — xQueueReceive( xQueueSet, &xReturn, xTicksToWait )
— so this blocks, traces and costs exactly what a receive does, and
None is the C’s NULL.
§Errors
Sourcepub fn queue_select_from_set_from_isr(
&mut self,
set: QueueHandle,
) -> Result<Option<QueueHandle>>
pub fn queue_select_from_set_from_isr( &mut self, set: QueueHandle, ) -> Result<Option<QueueHandle>>
xQueueSelectFromSetFromISR: which queue in set has data, from
an interrupt.
The C is three lines – xQueueReceiveFromISR on the set itself,
with a NULL handle meaning “none” – because a set IS a queue of
member handles. This is that, and it takes no critical section for
the same reason the rest of the FromISR surface does not.
§Errors
Error::Gone for a stale handle.
Sourcepub fn queue_overwrite(
&mut self,
queue: QueueHandle,
value: u64,
) -> Result<Wait<()>>
pub fn queue_overwrite( &mut self, queue: QueueHandle, value: u64, ) -> Result<Wait<()>>
xQueueOverwrite: write to a length-one queue whether or not it
already holds something.
The C is xQueueGenericSend( q, item, 0, queueOVERWRITE ) — a send
with no block time, because a queue that is always writable can
never make the caller wait.
§Errors
Sourcepub fn queue_send_generic_from_isr(
&mut self,
queue: QueueHandle,
value: u64,
position: Position,
) -> Result<Woken>
pub fn queue_send_generic_from_isr( &mut self, queue: QueueHandle, value: u64, position: Position, ) -> Result<Woken>
xQueueGenericSendFromISR.
§Errors
Error::Full when the queue is full and this is not an overwrite;
Error::Gone for a stale handle.
Sourcepub fn queue_send_from_isr(
&mut self,
queue: QueueHandle,
value: u64,
) -> Result<Woken>
pub fn queue_send_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>
Sourcepub fn queue_send_to_front_from_isr(
&mut self,
queue: QueueHandle,
value: u64,
) -> Result<Woken>
pub fn queue_send_to_front_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>
Sourcepub fn queue_overwrite_from_isr(
&mut self,
queue: QueueHandle,
value: u64,
) -> Result<Woken>
pub fn queue_overwrite_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>
xQueueOverwriteFromISR. Only for a queue of length one.
§Errors
Sourcepub fn semaphore_give_from_isr(
&mut self,
semaphore: QueueHandle,
) -> Result<Woken>
pub fn semaphore_give_from_isr( &mut self, semaphore: QueueHandle, ) -> Result<Woken>
Sourcepub fn queue_receive_from_isr(
&mut self,
queue: QueueHandle,
) -> Result<(u64, Woken)>
pub fn queue_receive_from_isr( &mut self, queue: QueueHandle, ) -> Result<(u64, Woken)>
xQueueReceiveFromISR: the value, and whether a waiting sender that
this made room for outranks the interrupted task.
§Errors
Error::Empty when the queue is empty; Error::Gone for a
stale handle.
Sourcepub fn queue_peek_from_isr(&mut self, queue: QueueHandle) -> Result<u64>
pub fn queue_peek_from_isr(&mut self, queue: QueueHandle) -> Result<u64>
xQueuePeekFromISR: the head without removing it.
It wakes nobody and traces nothing — the C has no hook for it —
which is why it returns a bare value rather than a Woken.
§Errors
Error::Empty when the queue is empty; Error::Gone for a
stale handle.
Sourcepub fn queue_send_to_front(
&mut self,
queue: QueueHandle,
value: u64,
ticks: u64,
) -> Result<Wait<()>>
pub fn queue_send_to_front( &mut self, queue: QueueHandle, value: u64, ticks: u64, ) -> Result<Wait<()>>
Sourcepub fn semaphore_give(&mut self, semaphore: QueueHandle) -> Result<Wait<()>>
pub fn semaphore_give(&mut self, semaphore: QueueHandle) -> Result<Wait<()>>
xSemaphoreGive: a send with no data.
§Errors
Error::Full when the semaphore is already at its maximum count.
Sourcepub fn queue_send_generic(
&mut self,
queue: QueueHandle,
value: u64,
ticks: u64,
position: Position,
) -> Result<Wait<()>>
pub fn queue_send_generic( &mut self, queue: QueueHandle, value: u64, ticks: u64, position: Position, ) -> Result<Wait<()>>
xQueueGenericSend, one pass of its for(;;).
§Errors
Error::Full on timeout; Error::Gone for a stale handle.
In line on purpose, for the same reason as
Kernel::queue_take: seven instructions of prologue and ten of
epilogue on every one of khot-ir’s 48,000 sends, so that xQueueSend
and its siblings could pass four arguments through unchanged. This
one pays on every instrument, kernel-ir included.
But only the HOT site wants it. With the flash probe fixed so that real bodies link at all (2026-09-24), this was inlined at five places and cost about 1,666 bytes of duplicate.
RE-PRICED 2026-09-25, because that figure was taken at FIVE inline sites and there is now one. Dropping the hint today measures:
- flash 19,302 -> 18,704, i.e. -598 B, with
mv-31,andi-7,slli-8 and 221 fewer instructions; - rv32 work rows +118 instructions over seven of them —
queue_roundtrip122 -> 169,block_cycle983 -> 1022,send_full36 -> 62, and +1 or +2 on four more.
That is 5.07 bytes of flash per instruction, a worse rate than the
queue_peek trade declined at 7.3 and than the 10.7 this hint was
originally kept at. So it stays — but the K3 flash row is the one
FAILING its target while the work rows are absolutes with no C
comparison, so if that priority ever inverts this is the single largest
item in the send path and the numbers are here. rusty-compiler-leverage A4: a function has one
body, so one inlining decision serves callers who want different
things – give it two names instead of averaging them.
Kernel::send_generic_outlined is the out-of-line handle, and the
four colder wrappers call that.
Sourcepub fn queue_receive(
&mut self,
queue: QueueHandle,
ticks: u64,
) -> Result<Wait<u64>>
pub fn queue_receive( &mut self, queue: QueueHandle, ticks: u64, ) -> Result<Wait<u64>>
xQueueReceive.
§Errors
Error::Empty when the block time expires with the queue still
empty; Error::Gone for a stale handle.
Sourcepub fn queue_peek(
&mut self,
queue: QueueHandle,
ticks: u64,
) -> Result<Wait<u64>>
pub fn queue_peek( &mut self, queue: QueueHandle, ticks: u64, ) -> Result<Wait<u64>>
Sourcepub fn semaphore_take(
&mut self,
semaphore: QueueHandle,
ticks: u64,
) -> Result<Wait<()>>
pub fn semaphore_take( &mut self, semaphore: QueueHandle, ticks: u64, ) -> Result<Wait<()>>
xSemaphoreTake, which is xQueueSemaphoreTake: a receive with no
data, and — on a mutex — with priority inheritance while it waits.
§Errors
Error::Empty on timeout; Error::Gone for a stale handle.
Sourcepub fn mutex_take_recursive(
&mut self,
mutex: QueueHandle,
ticks: u64,
) -> Result<Wait<()>>
pub fn mutex_take_recursive( &mut self, mutex: QueueHandle, ticks: u64, ) -> Result<Wait<()>>
Sourcepub fn mutex_give_recursive(&mut self, mutex: QueueHandle) -> Result<()>
pub fn mutex_give_recursive(&mut self, mutex: QueueHandle) -> Result<()>
Sourcepub fn wait_for_message_restricted(
&mut self,
queue: QueueHandle,
ticks: u64,
wait_indefinitely: bool,
) -> Result<()>
pub fn wait_for_message_restricted( &mut self, queue: QueueHandle, ticks: u64, wait_indefinitely: bool, ) -> Result<()>
vQueueWaitForMessageRestricted: what the timer service task does
when it has no timer to run — block on the command queue without
suspending the scheduler.
wait_indefinitely is the C third argument: when set the wait
becomes portMAX_DELAY and the task goes to the suspended list
rather than a delayed one. The queue locks around it are C’s
prvLockQueue and prvUnlockQueue — three critical sections, and
therefore three sixteenths of a tick’s worth of sim time.
§Errors
A list error surfaces as itself.
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
Sourcepub const MESSAGE_LENGTH_BYTES: usize = C::MESSAGE_LENGTH_BYTES
pub const MESSAGE_LENGTH_BYTES: usize = C::MESSAGE_LENGTH_BYTES
How many bytes a message buffer spends on each message’s length.
Sourcepub fn stream_buffer_create(
&mut self,
size: usize,
trigger: usize,
) -> Result<StreamBufferHandle>
pub fn stream_buffer_create( &mut self, size: usize, trigger: usize, ) -> Result<StreamBufferHandle>
xStreamBufferCreate.
A trigger level of zero becomes one, as the C does: a reader that woke on nothing would spin.
§Errors
Error::Full when the buffer arena or the byte arena is full;
Error::InvalidArgument for a zero-length buffer.
Sourcepub fn message_buffer_create(
&mut self,
size: usize,
) -> Result<StreamBufferHandle>
pub fn message_buffer_create( &mut self, size: usize, ) -> Result<StreamBufferHandle>
xMessageBufferCreate.
§Errors
As Kernel::stream_buffer_create; a message buffer must also be
longer than one length prefix.
Sourcepub fn stream_buffer_delete(&mut self, buffer: StreamBufferHandle) -> Result<()>
pub fn stream_buffer_delete(&mut self, buffer: StreamBufferHandle) -> Result<()>
vStreamBufferDelete: the handle goes stale and the ring’s bytes go
back to the arena.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_bytes_available(
&self,
buffer: StreamBufferHandle,
) -> Result<usize>
pub fn stream_buffer_bytes_available( &self, buffer: StreamBufferHandle, ) -> Result<usize>
xStreamBufferBytesAvailable. No critical section, as in the C.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_spaces_available(
&self,
buffer: StreamBufferHandle,
) -> Result<usize>
pub fn stream_buffer_spaces_available( &self, buffer: StreamBufferHandle, ) -> Result<usize>
xStreamBufferSpacesAvailable. No critical section, as in the C.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_is_empty(&self, buffer: StreamBufferHandle) -> Result<bool>
pub fn stream_buffer_is_empty(&self, buffer: StreamBufferHandle) -> Result<bool>
Sourcepub fn stream_buffer_is_full(&self, buffer: StreamBufferHandle) -> Result<bool>
pub fn stream_buffer_is_full(&self, buffer: StreamBufferHandle) -> Result<bool>
xStreamBufferIsFull: no room for another message.
For a message buffer “another message” means at least one more byte than its length prefix, so a buffer with exactly a prefix’s worth of room left is already full. A stream buffer compares against zero.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_set_trigger_level(
&mut self,
buffer: StreamBufferHandle,
trigger: usize,
) -> Result<bool>
pub fn stream_buffer_set_trigger_level( &mut self, buffer: StreamBufferHandle, trigger: usize, ) -> Result<bool>
Sourcepub fn stream_buffer_reset(
&mut self,
buffer: StreamBufferHandle,
) -> Result<bool>
pub fn stream_buffer_reset( &mut self, buffer: StreamBufferHandle, ) -> Result<bool>
xStreamBufferReset: empty it, unless a task is waiting on it.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_next_message_length(
&self,
buffer: StreamBufferHandle,
) -> Result<usize>
pub fn stream_buffer_next_message_length( &self, buffer: StreamBufferHandle, ) -> Result<usize>
Sourcepub fn stream_buffer_send(
&mut self,
buffer: StreamBufferHandle,
data: &[u8],
ticks: u64,
) -> Result<Wait<usize>>
pub fn stream_buffer_send( &mut self, buffer: StreamBufferHandle, data: &[u8], ticks: u64, ) -> Result<Wait<usize>>
xStreamBufferSend, with the contract-v2 bracket around it.
§Errors
Sourcepub fn stream_buffer_send_from_isr(
&mut self,
buffer: StreamBufferHandle,
data: &[u8],
) -> Result<(usize, Woken)>
pub fn stream_buffer_send_from_isr( &mut self, buffer: StreamBufferHandle, data: &[u8], ) -> Result<(usize, Woken)>
Sourcepub fn stream_buffer_receive(
&mut self,
buffer: StreamBufferHandle,
out: &mut [u8],
ticks: u64,
) -> Result<Wait<usize>>
pub fn stream_buffer_receive( &mut self, buffer: StreamBufferHandle, out: &mut [u8], ticks: u64, ) -> Result<Wait<usize>>
xStreamBufferReceive: bytes into out, and how many arrived.
§Errors
Error::Gone for a stale handle.
xStreamBufferReceive, with the contract-v2 bracket around it.
See Kernel::blind_call.
§Errors
Sourcepub fn stream_buffer_receive_from_isr(
&mut self,
buffer: StreamBufferHandle,
out: &mut [u8],
) -> Result<(usize, Woken)>
pub fn stream_buffer_receive_from_isr( &mut self, buffer: StreamBufferHandle, out: &mut [u8], ) -> Result<(usize, Woken)>
Sourcepub fn send_completed_from_isr(
&mut self,
buffer: StreamBufferHandle,
) -> Result<Woken>
pub fn send_completed_from_isr( &mut self, buffer: StreamBufferHandle, ) -> Result<Woken>
xStreamBufferSendCompletedFromISR / sbSEND_COMPLETED_FROM_ISR.
Public because an application that replaced TickHook::send_completed
has to be able to do the notify itself, later and from interrupt
context — which is exactly what MessageBufferAMP does once its
stand-in interrupt has read the handle back off the control buffer.
§Errors
Error::Gone for a stale handle.
Sourcepub fn stream_buffer_send_completed_from_isr(
&mut self,
buffer: StreamBufferHandle,
) -> Result<(bool, Woken)>
pub fn stream_buffer_send_completed_from_isr( &mut self, buffer: StreamBufferHandle, ) -> Result<(bool, Woken)>
xStreamBufferSendCompletedFromISR with the C’s ANSWER: whether a task
was waiting to receive (and so was notified), and whether waking it
wants a switch.
Kernel::send_completed_from_isr does the same work but answers
only the second, which is all a sbSEND_COMPLETED replacement needs;
the C function’s own return value had no Rust spelling until the API
differential (P1.6) asked for it.
§Errors
Error::Gone for a stale handle.
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
Sourcepub fn timer_create(
&mut self,
name: &str,
period: u64,
auto_reload: bool,
id: u64,
callback: u16,
) -> Result<TimerHandle>
pub fn timer_create( &mut self, name: &str, period: u64, auto_reload: bool, id: u64, callback: u16, ) -> Result<TimerHandle>
xTimerCreate.
callback names which of the application’s timer callbacks this
timer runs; id is pvTimerID.
§Errors
Error::Full when the timer arena is full;
Error::InvalidArgument for a zero period, which the C asserts on.
Sourcepub fn timer_id(&mut self, timer: TimerHandle) -> Result<u64>
pub fn timer_id(&mut self, timer: TimerHandle) -> Result<u64>
Sourcepub fn timer_set_id(&mut self, timer: TimerHandle, id: u64) -> Result<()>
pub fn timer_set_id(&mut self, timer: TimerHandle, id: u64) -> Result<()>
Sourcepub fn timer_period(&self, timer: TimerHandle) -> Result<u64>
pub fn timer_period(&self, timer: TimerHandle) -> Result<u64>
Sourcepub fn timer_is_active(&mut self, timer: TimerHandle) -> Result<bool>
pub fn timer_is_active(&mut self, timer: TimerHandle) -> Result<bool>
Sourcepub fn timer_expiry_time(&self, timer: TimerHandle) -> Result<u64>
pub fn timer_expiry_time(&self, timer: TimerHandle) -> Result<u64>
Sourcepub fn timer_auto_reload(&mut self, timer: TimerHandle) -> Result<bool>
pub fn timer_auto_reload(&mut self, timer: TimerHandle) -> Result<bool>
Sourcepub fn timer_set_auto_reload(
&mut self,
timer: TimerHandle,
auto: bool,
) -> Result<()>
pub fn timer_set_auto_reload( &mut self, timer: TimerHandle, auto: bool, ) -> Result<()>
Sourcepub fn timer_command(
&mut self,
timer: TimerHandle,
command: Command,
value: u64,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_command( &mut self, timer: TimerHandle, command: Command, value: u64, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_start(
&mut self,
timer: TimerHandle,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_start( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_stop(
&mut self,
timer: TimerHandle,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_stop( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_reset(
&mut self,
timer: TimerHandle,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_reset( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_change_period(
&mut self,
timer: TimerHandle,
period: u64,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_change_period( &mut self, timer: TimerHandle, period: u64, ticks: u64, ) -> Result<Wait<bool>>
xTimerChangePeriod.
A period of zero is refused. The C asserts against one, which on this harness ends the run; refusing is the same answer without ending it, and it matters because a zero-period auto-reload timer would reload for ever without the clock moving.
§Errors
Error::InvalidArgument for a zero period; otherwise as
Kernel::timer_command.
Sourcepub fn timer_delete(
&mut self,
timer: TimerHandle,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_delete( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_start_from_isr(
&mut self,
timer: TimerHandle,
) -> Result<(bool, Woken)>
pub fn timer_start_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>
Sourcepub fn timer_stop_from_isr(
&mut self,
timer: TimerHandle,
) -> Result<(bool, Woken)>
pub fn timer_stop_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>
Sourcepub fn timer_reset_from_isr(
&mut self,
timer: TimerHandle,
) -> Result<(bool, Woken)>
pub fn timer_reset_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>
Sourcepub fn timer_change_period_from_isr(
&mut self,
timer: TimerHandle,
period: u64,
) -> Result<(bool, Woken)>
pub fn timer_change_period_from_isr( &mut self, timer: TimerHandle, period: u64, ) -> Result<(bool, Woken)>
Sourcepub fn timer_command_from_isr(
&mut self,
timer: TimerHandle,
command: Command,
value: u64,
) -> Result<(bool, Woken)>
pub fn timer_command_from_isr( &mut self, timer: TimerHandle, command: Command, value: u64, ) -> Result<(bool, Woken)>
xTimerGenericCommandFromISR: the raw command, value and all.
Prefer the four wrappers above. They exist because the C’s public
from-ISR API does not let a caller choose the value: a start or a
reset always carries xTaskGetTickCountFromISR(). A value from
somewhere else is a command time the daemon will believe, and a
command time far enough in the future makes prvReloadTimer reload
without ever landing in the future — a loop the C has too, and
reaches the same way.
§Errors
Error::Gone for a stale handle.
Sourcepub fn timer_pend_function_call(
&mut self,
function: u16,
param1: u64,
param2: u64,
ticks: u64,
) -> Result<Wait<bool>>
pub fn timer_pend_function_call( &mut self, function: u16, param1: u64, param2: u64, ticks: u64, ) -> Result<Wait<bool>>
Sourcepub fn timer_pend_function_call_from_isr(
&mut self,
function: u16,
param1: u64,
param2: u64,
) -> Result<(bool, Woken)>
pub fn timer_pend_function_call_from_isr( &mut self, function: u16, param1: u64, param2: u64, ) -> Result<(bool, Woken)>
xTimerPendFunctionCallFromISR.
This is how xEventGroupSetBitsFromISR does its work: an interrupt
cannot walk an event group’s waiting list, so it hands the job to
the daemon.
§Errors
As the queue send.
Sourcepub fn timer_next_expire(&self) -> (u64, bool)
pub fn timer_next_expire(&self) -> (u64, bool)
prvGetNextExpireTime: when the head of the current list is due, and
whether there is a head at all.
Sourcepub fn overflow_timer_list_is_empty(&self) -> bool
pub fn overflow_timer_list_is_empty(&self) -> bool
Whether pxOverflowTimerList is empty, which is the second half of
the daemon’s “may I wait for ever?” test.
Sourcepub fn timer_sample_time_now(&mut self) -> Result<(u64, bool)>
pub fn timer_sample_time_now(&mut self) -> Result<(u64, bool)>
prvSampleTimeNow: the tick, and whether reading it swapped the two
timer lists because it wrapped.
§Errors
As the list operations.
Sourcepub fn process_expired_timer(&mut self, expire_at: u64, now: u64) -> Result<()>
pub fn process_expired_timer(&mut self, expire_at: u64, now: u64) -> Result<()>
prvProcessExpiredTimer: take the head off, reload it if it is an
auto-reload, and run its callback.
§Errors
As the list operations.
Sourcepub fn insert_timer_in_active_list(
&mut self,
timer: TimerHandle,
expiry: u64,
now: u64,
command_time: u64,
) -> Result<bool>
pub fn insert_timer_in_active_list( &mut self, timer: TimerHandle, expiry: u64, now: u64, command_time: u64, ) -> Result<bool>
prvInsertTimerInActiveList: true when the timer is already due
and the daemon should run it now rather than wait for it.
§Errors
As the list operations.
Sourcepub fn process_one_timer_command(&mut self, ticks: u64) -> Result<Wait<bool>>
pub fn process_one_timer_command(&mut self, ticks: u64) -> Result<Wait<bool>>
prvProcessReceivedCommands: drain the queue, one command per call.
The C loops until the queue is empty; a kernel with no stacks does one and says whether there is more, because a callback in the middle of that loop can block and the daemon has to be able to come back.
§The block time is not a convenience
ticks is how long the daemon is willing to WAIT on the queue, and
passing zero has a consequence beyond promptness: a daemon that
polls is never on the queue’s receive list, so a task posting a
command finds no waiter to remove and queue_send_generic does not
call port_yield. The daemon is higher priority and still does not
run, because nothing asked for a switch.
That is visible from the C. TimerDemo.c stops a timer and asserts
on the next line that it is inactive, and its comment says it may:
“this will appear to happen immediately to this task because this
task is running at a priority below the timer service task”. With a
polling daemon the assertion fails, and nothing else in the corpus
notices.
So a caller acting as the daemon should pass what
prvProcessTimerOrBlockTask computes — the time to the next expiry,
or the maximum delay when no timer is active. Zero is correct only
for a caller that is draining the queue rather than serving it, such
as a trace-exact state machine that schedules the wait itself.
§Errors
As the queue receive.
Sourcepub fn timer_receive_command(
&mut self,
ticks: u64,
) -> Result<Wait<Option<Message>>>
pub fn timer_receive_command( &mut self, ticks: u64, ) -> Result<Wait<Option<Message>>>
The first half of Kernel::process_one_timer_command: the
xQueueReceive of prvProcessReceivedCommands’s loop: the message,
for Kernel::timer_execute_command, or None for an empty queue.
A COPY of the message, as the C copies it into the daemon’s local
xMessage: the receive frees the ring slot it sat in, and a post
between the two halves – the tick hook’s, say – can reuse it.
The halves are separate for a daemon that has to stop BETWEEN them.
On two cores the receive is a top-level call that leaves a critical
section, so it ends the daemon’s turn (the two-core contract), and
what the command then does – a callback, the vPortFree a delete
costs – happens in the turns after. One call for both put the
daemon a turn ahead of the C (two-core TaskNotify, a delete).
§Errors
As the queue receive.
Sourcepub fn timer_execute_command(&mut self, message: Message) -> Result<()>
pub fn timer_execute_command(&mut self, message: Message) -> Result<()>
The second half of Kernel::process_one_timer_command: carry out
the command Kernel::timer_receive_command took.
§Errors
As the list operations.
Trait Implementations§
Source§impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Raw for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
The Rust face’s raw surface: see crate::typed.
impl<C: Config, P: Port, T: Trace, H, const TASKS: usize, const ITEMS: usize, const LISTS: usize, const QUEUES: usize, const SLOTS: usize, const BUFFERS: usize, const BYTES: usize, const TIMERS: usize, const GROUPS: usize, const TIMER_CMDS: usize> Raw for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>where
H: TickHook<Self>,
The Rust face’s raw surface: see crate::typed.
Every method here is one of the kernel’s own calls under another name.
The one that is not — [Raw::raw_queue_has_room] — is the kernel
reading its own queue rather than a task asking, so it takes no
critical section and costs no sim time, which is what lets the typed
face be free.
Source§fn raw_queue_create(&mut self, length: usize) -> Result<QueueHandle>
fn raw_queue_create(&mut self, length: usize) -> Result<QueueHandle>
xQueueCreate, in items. Read moreSource§fn raw_queue_send(
&mut self,
queue: QueueHandle,
value: u64,
ticks: u64,
) -> Result<Wait<()>>
fn raw_queue_send( &mut self, queue: QueueHandle, value: u64, ticks: u64, ) -> Result<Wait<()>>
xQueueSendToBack. Read moreSource§fn raw_queue_receive(
&mut self,
queue: QueueHandle,
ticks: u64,
) -> Result<Wait<u64>>
fn raw_queue_receive( &mut self, queue: QueueHandle, ticks: u64, ) -> Result<Wait<u64>>
xQueueReceive. Read moreSource§fn raw_queue_messages_waiting(&mut self, queue: QueueHandle) -> Result<usize>
fn raw_queue_messages_waiting(&mut self, queue: QueueHandle) -> Result<usize>
uxQueueMessagesWaiting, which takes a critical section and so
costs sim time — this is the API call, not a peek at the field. Read moreSource§fn raw_queue_has_room(&self, queue: QueueHandle) -> bool
fn raw_queue_has_room(&self, queue: QueueHandle) -> bool
uxQueueSpacesAvailable would take. Read moreSource§fn raw_in_isr(&self) -> bool
fn raw_in_isr(&self) -> bool
xPortIsInsideInterrupt.Source§fn raw_queue_send_from_isr(
&mut self,
queue: QueueHandle,
value: u64,
) -> Result<Woken>
fn raw_queue_send_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>
xQueueSendToBackFromISR. Read moreSource§fn raw_mutex_create(&mut self) -> Result<QueueHandle>
fn raw_mutex_create(&mut self) -> Result<QueueHandle>
xSemaphoreCreateMutex. Read moreSource§fn raw_mutex_take(&mut self, mutex: QueueHandle, ticks: u64) -> Result<Wait<()>>
fn raw_mutex_take(&mut self, mutex: QueueHandle, ticks: u64) -> Result<Wait<()>>
xSemaphoreTake. Read moreSource§fn raw_mutex_give(&mut self, mutex: QueueHandle) -> Result<()>
fn raw_mutex_give(&mut self, mutex: QueueHandle) -> Result<()>
xSemaphoreGive. Read more