Skip to main content

Kernel

Struct Kernel 

Source
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>,

Source

pub fn event_group_create(&mut self) -> Result<EventGroupHandle>

xEventGroupCreate.

§Errors

Error::Full when the arena is full, which is NULL in the C.

Source

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.

Source

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.

Source

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.

Source

pub fn event_group_clear_bits( &mut self, group: EventGroupHandle, bits: u32, ) -> Result<u32>

xEventGroupClearBits: the bits as they were, then cleared.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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>,

Source

pub const MAX_DELAY: u64 = <C::Tick as TickWidth>::MAX

portMAX_DELAY at this configuration’s tick width.

Source

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.

Source

pub const FOOTPRINT_TCBS: usize

The task control blocks.

Source

pub const FOOTPRINT_QUEUES: usize

The queue descriptors, and NOT their item storage.

Source

pub const FOOTPRINT_LISTS: usize

Every intrusive list: ready, delayed, and the per-object waiters.

Source

pub const FOOTPRINT_SLOTS: usize

Queue item storage, as u64 slots.

Source

pub const FOOTPRINT_BUFFERS: usize

The stream-buffer descriptors, and NOT their bytes.

Source

pub const FOOTPRINT_TIMERS: usize

The software timers.

Source

pub const FOOTPRINT_GROUPS: usize

The event groups.

Source

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.

Source

pub const FOOTPRINT_BYTES: usize

The byte arena, for stream-buffer contents.

Source

pub const FOOTPRINT_FREE_LISTS: usize

The two free lists, over the byte arena and the slot arena.

Source

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.

Source

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.

Source

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).

Source

pub fn with_tick_hook(port: P, trace: T, tick_hook: H) -> Result<Self>

Kernel::new with vApplicationTickHook installed.

§Errors

As Kernel::new.

Source

pub const fn port(&self) -> &P

The port, for a runner that needs its counters.

Source

pub const fn trace(&self) -> &T

The trace sink.

Source

pub const fn trace_mut(&mut self) -> &mut T

The trace sink, mutably.

Source

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.

Source

pub const fn overflows(&self) -> u64

xNumOfOverflows, for a scenario that reports counters.

Source

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.

Source

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.

Source

pub const fn tick_count(&self) -> u64

xTaskGetTickCount.

Source

pub const fn is_running(&self) -> bool

xSchedulerRunning.

Source

pub const fn task_count(&self) -> usize

uxCurrentNumberOfTasks.

Source

pub const fn scheduler_suspended(&self) -> u32

uxSchedulerSuspended, for a stepper reporting why a tick pended.

Source

pub const fn pended_ticks(&self) -> u64

xPendedTicks, likewise.

Source

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.

Source

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.

Source

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.

Source

pub fn name_of(&self, task: TaskHandle) -> Result<Name>

A task’s name.

§Errors

Error::Gone for a stale or null handle.

Source

pub fn priority_of(&self, task: Option<TaskHandle>) -> Result<u8>

uxTaskPriorityGet. None means the current task, as in C.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

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.

Source

pub fn state_of(&self, task: TaskHandle) -> Result<TaskState>

eTaskGetState, derived from the list the task is in.

§Errors

A list error surfaces as itself.

Source

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.

Source

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.

Source

pub const fn first_stall(&self) -> Stall

Why the scheduler first failed to choose. Stall::None if it never has.

Source

pub fn enter_critical(&mut self)

taskENTER_CRITICAL().

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn task_yield(&mut self)

taskYIELD() from a task body (the idle task’s yield).

Source

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).

Source

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 lower TIMER_TASK_PRIORITY below 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

As Kernel::create_task.

Source

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.

Source

pub fn switch_context(&mut self)

vTaskSwitchContext.

Source

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.

Source

pub fn increment_tick(&mut self) -> bool

xTaskIncrementTick; true when a context switch is required.

Source

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.

Source

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.

Source

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.

Source

pub fn notify( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<bool>

xTaskGenericNotify.

§Errors

Error::InvalidArgument for a bad index; Error::Gone for a stale handle.

Source

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.

Source

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.

Source

pub fn notify_and_query_from_isr( &mut self, task: TaskHandle, index: usize, value: u32, action: NotifyAction, ) -> Result<(bool, u32, Woken)>

xTaskGenericNotifyAndQueryFromISR.

§Errors

As Kernel::notify.

Source

pub fn notify_state_clear( &mut self, task: Option<TaskHandle>, index: usize, ) -> Result<bool>

xTaskGenericNotifyStateClear. None is the calling task.

§Errors

As Kernel::notify.

Source

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.

Source

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

As Kernel::notify_value.

Source

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.

Source

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.

Source

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.

Source

pub const fn tick_hook_mut(&mut self) -> &mut H

The tick hook, to install or reset one after construction.

Source

pub fn delay(&mut self, ticks: u64) -> Result<()>

vTaskDelay.

§Errors

A list error surfaces as itself.

Source

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.

Source

pub fn suspend(&mut self, task: Option<TaskHandle>) -> Result<()>

vTaskSuspend. None suspends the calling task.

§Errors

Error::Gone for a stale handle.

Source

pub fn resume(&mut self, task: TaskHandle) -> Result<()>

vTaskResume.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

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.

Source

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.

Source

pub fn suspend_all(&mut self)

vTaskSuspendAll.

Source

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.

Source

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>,

Source

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.

Source

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.

Source

pub fn semaphore_create_binary(&mut self) -> Result<QueueHandle>

xSemaphoreCreateBinary: a one-deep semaphore, created empty.

§Errors

As Kernel::queue_create.

Source

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.

Source

pub fn mutex_create(&mut self) -> Result<QueueHandle>

xSemaphoreCreateMutex: created available, unlike a semaphore.

§Errors

As Kernel::queue_create.

Source

pub fn mutex_create_recursive(&mut self) -> Result<QueueHandle>

xSemaphoreCreateRecursiveMutex.

§Errors

As Kernel::queue_create.

Source

pub fn queue_messages_waiting(&mut self, queue: QueueHandle) -> Result<usize>

uxQueueMessagesWaiting, which takes a critical section.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

pub fn semaphore_count(&mut self, semaphore: QueueHandle) -> Result<usize>

uxSemaphoreGetCount, which is the same thing.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

pub fn mutex_holder(&mut self, mutex: QueueHandle) -> Result<TaskHandle>

xSemaphoreGetMutexHolder, which takes a critical section.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

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.

Source

pub fn queue_spaces_available(&mut self, queue: QueueHandle) -> Result<usize>

uxQueueSpacesAvailable: how many more items would fit.

§Errors

Error::Gone for a stale handle.

Source

pub fn queue_create_set(&mut self, length: usize) -> Result<QueueHandle>

xQueueCreateSet: a set that can hold length announcements.

§Errors

As Kernel::queue_create.

Source

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.

Source

pub fn queue_remove_from_set( &mut self, queue: QueueHandle, set: QueueHandle, ) -> Result<bool>

xQueueRemoveFromSet.

§Errors

Error::Gone for a stale handle.

Source

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

As Kernel::queue_receive.

Source

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.

Source

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

As Kernel::queue_send.

Source

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.

Source

pub fn queue_send_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>

xQueueSendToBackFromISR.

§Errors

As Kernel::queue_send_generic_from_isr.

Source

pub fn queue_send_to_front_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>

xQueueSendToFrontFromISR.

§Errors

As Kernel::queue_send_generic_from_isr.

Source

pub fn queue_overwrite_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>

xQueueOverwriteFromISR. Only for a queue of length one.

§Errors

As Kernel::queue_send_generic_from_isr.

Source

pub fn semaphore_give_from_isr( &mut self, semaphore: QueueHandle, ) -> Result<Woken>

xSemaphoreGiveFromISR.

§Errors

As Kernel::queue_send_generic_from_isr.

Source

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.

Source

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.

Source

pub fn queue_send_to_front( &mut self, queue: QueueHandle, value: u64, ticks: u64, ) -> Result<Wait<()>>

xQueueSendToFront.

§Errors

As Kernel::queue_send.

Source

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.

Source

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_roundtrip 122 -> 169, block_cycle 983 -> 1022, send_full 36 -> 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.

Source

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.

Source

pub fn queue_peek( &mut self, queue: QueueHandle, ticks: u64, ) -> Result<Wait<u64>>

xQueuePeek: read the head without removing it.

§Errors

As Kernel::queue_receive.

Source

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.

Source

pub fn mutex_take_recursive( &mut self, mutex: QueueHandle, ticks: u64, ) -> Result<Wait<()>>

xSemaphoreTakeRecursive.

§Errors

Error::Empty on timeout; Error::Gone for a stale handle.

Source

pub fn mutex_give_recursive(&mut self, mutex: QueueHandle) -> Result<()>

xSemaphoreGiveRecursive.

§Errors

Error::NotActive when the caller does not hold the mutex.

Source

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>,

Source

pub const MESSAGE_LENGTH_BYTES: usize = C::MESSAGE_LENGTH_BYTES

How many bytes a message buffer spends on each message’s length.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn stream_buffer_is_empty(&self, buffer: StreamBufferHandle) -> Result<bool>

xStreamBufferIsEmpty: head and tail in the same place.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

pub fn stream_buffer_set_trigger_level( &mut self, buffer: StreamBufferHandle, trigger: usize, ) -> Result<bool>

xStreamBufferSetTriggerLevel.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

pub fn stream_buffer_next_message_length( &self, buffer: StreamBufferHandle, ) -> Result<usize>

xStreamBufferNextMessageLengthBytes.

§Errors

Error::Gone for a stale handle.

Source

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

As Kernel::stream_buffer_send_inner.

Source

pub fn stream_buffer_send_from_isr( &mut self, buffer: StreamBufferHandle, data: &[u8], ) -> Result<(usize, Woken)>

xStreamBufferSendFromISR.

§Errors

Error::Gone for a stale handle.

Source

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

As Kernel::stream_buffer_receive_inner.

Source

pub fn stream_buffer_receive_from_isr( &mut self, buffer: StreamBufferHandle, out: &mut [u8], ) -> Result<(usize, Woken)>

xStreamBufferReceiveFromISR.

§Errors

Error::Gone for a stale handle.

Source

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.

Source

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>,

Source

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.

Source

pub fn timer_id(&mut self, timer: TimerHandle) -> Result<u64>

pvTimerGetTimerID.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_set_id(&mut self, timer: TimerHandle, id: u64) -> Result<()>

vTimerSetTimerID.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_period(&self, timer: TimerHandle) -> Result<u64>

xTimerGetPeriod.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_is_active(&mut self, timer: TimerHandle) -> Result<bool>

xTimerIsTimerActive.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_expiry_time(&self, timer: TimerHandle) -> Result<u64>

xTimerGetExpiryTime.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_auto_reload(&mut self, timer: TimerHandle) -> Result<bool>

xTimerGetReloadMode.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_set_auto_reload( &mut self, timer: TimerHandle, auto: bool, ) -> Result<()>

vTimerSetReloadMode.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_command( &mut self, timer: TimerHandle, command: Command, value: u64, ticks: u64, ) -> Result<Wait<bool>>

xTimerGenericCommandFromTask.

§Errors

Error::Gone for a stale handle.

Source

pub fn timer_start( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>

xTimerStart.

§Errors

As Kernel::timer_command.

Source

pub fn timer_stop( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>

xTimerStop.

§Errors

As Kernel::timer_command.

Source

pub fn timer_reset( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>

xTimerReset.

§Errors

As Kernel::timer_command.

Source

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.

Source

pub fn timer_delete( &mut self, timer: TimerHandle, ticks: u64, ) -> Result<Wait<bool>>

xTimerDelete.

§Errors

As Kernel::timer_command.

Source

pub fn timer_start_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>

xTimerStartFromISR.

§Errors

As Kernel::timer_command_from_isr.

Source

pub fn timer_stop_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>

xTimerStopFromISR.

§Errors

As Kernel::timer_command_from_isr.

Source

pub fn timer_reset_from_isr( &mut self, timer: TimerHandle, ) -> Result<(bool, Woken)>

xTimerResetFromISR.

§Errors

As Kernel::timer_command_from_isr.

Source

pub fn timer_change_period_from_isr( &mut self, timer: TimerHandle, period: u64, ) -> Result<(bool, Woken)>

xTimerChangePeriodFromISR.

§Errors

As Kernel::timer_command_from_isr.

Source

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.

Source

pub fn timer_pend_function_call( &mut self, function: u16, param1: u64, param2: u64, ticks: u64, ) -> Result<Wait<bool>>

xTimerPendFunctionCall: run function on the daemon task.

§Errors

As the queue send.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

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>

xQueueCreate, in items. Read more
Source§

fn raw_queue_send( &mut self, queue: QueueHandle, value: u64, ticks: u64, ) -> Result<Wait<()>>

xQueueSendToBack. Read more
Source§

fn raw_queue_receive( &mut self, queue: QueueHandle, ticks: u64, ) -> Result<Wait<u64>>

xQueueReceive. Read more
Source§

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 more
Source§

fn raw_queue_has_room(&self, queue: QueueHandle) -> bool

Whether the queue could take one more item, without the critical section uxQueueSpacesAvailable would take. Read more
Source§

fn raw_in_isr(&self) -> bool

Whether the kernel is in interrupt context — xPortIsInsideInterrupt.
Source§

fn raw_queue_send_from_isr( &mut self, queue: QueueHandle, value: u64, ) -> Result<Woken>

xQueueSendToBackFromISR. Read more
Source§

fn raw_mutex_create(&mut self) -> Result<QueueHandle>

xSemaphoreCreateMutex. Read more
Source§

fn raw_mutex_take(&mut self, mutex: QueueHandle, ticks: u64) -> Result<Wait<()>>

xSemaphoreTake. Read more
Source§

fn raw_mutex_give(&mut self, mutex: QueueHandle) -> Result<()>

xSemaphoreGive. Read more

Auto Trait Implementations§

§

impl<C, P, T, 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> Freeze for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>
where P: Freeze, T: Freeze, H: Freeze, [u8; TASKS]: Freeze, [bool; TASKS]: Freeze, ListsOf<u64, ITEMS, LISTS>: Freeze, Arena<Task, Tcb, TASKS>: Freeze, [u32; TASKS]: Freeze, [OwedTrace; TASKS]: Freeze, Arena<Queue, Queue, QUEUES>: Freeze, Arena<Timer, Timer, TIMERS>: Freeze, Arena<EventGroup, EventGroup, GROUPS>: Freeze, Arena<StreamBuffer, StreamBuffer, BUFFERS>: Freeze, [(usize, usize); BUFFERS]: Freeze, [(usize, usize); QUEUES]: Freeze, [Message; TIMER_CMDS]: Freeze, [u64; SLOTS]: Freeze, [u8; BYTES]: Freeze, PhantomData<C>: Freeze,

§

impl<C, P, T, 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> RefUnwindSafe for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>

§

impl<C, P, T, 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> Send for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>
where P: Send, T: Send, H: Send, [u8; TASKS]: Send, [bool; TASKS]: Send, ListsOf<u64, ITEMS, LISTS>: Send, Arena<Task, Tcb, TASKS>: Send, [u32; TASKS]: Send, [OwedTrace; TASKS]: Send, Arena<Queue, Queue, QUEUES>: Send, Arena<Timer, Timer, TIMERS>: Send, Arena<EventGroup, EventGroup, GROUPS>: Send, Arena<StreamBuffer, StreamBuffer, BUFFERS>: Send, [(usize, usize); BUFFERS]: Send, [(usize, usize); QUEUES]: Send, [Message; TIMER_CMDS]: Send, [u64; SLOTS]: Send, [u8; BYTES]: Send, PhantomData<C>: Send,

§

impl<C, P, T, 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> Sync for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>
where P: Sync, T: Sync, H: Sync, [u8; TASKS]: Sync, [bool; TASKS]: Sync, ListsOf<u64, ITEMS, LISTS>: Sync, Arena<Task, Tcb, TASKS>: Sync, [u32; TASKS]: Sync, [OwedTrace; TASKS]: Sync, Arena<Queue, Queue, QUEUES>: Sync, Arena<Timer, Timer, TIMERS>: Sync, Arena<EventGroup, EventGroup, GROUPS>: Sync, Arena<StreamBuffer, StreamBuffer, BUFFERS>: Sync, [(usize, usize); BUFFERS]: Sync, [(usize, usize); QUEUES]: Sync, [Message; TIMER_CMDS]: Sync, [u64; SLOTS]: Sync, [u8; BYTES]: Sync, PhantomData<C>: Sync,

§

impl<C, P, T, 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> Unpin for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>
where P: Unpin, T: Unpin, H: Unpin, [u8; TASKS]: Unpin, [bool; TASKS]: Unpin, ListsOf<u64, ITEMS, LISTS>: Unpin, Arena<Task, Tcb, TASKS>: Unpin, [u32; TASKS]: Unpin, [OwedTrace; TASKS]: Unpin, Arena<Queue, Queue, QUEUES>: Unpin, Arena<Timer, Timer, TIMERS>: Unpin, Arena<EventGroup, EventGroup, GROUPS>: Unpin, Arena<StreamBuffer, StreamBuffer, BUFFERS>: Unpin, [(usize, usize); BUFFERS]: Unpin, [(usize, usize); QUEUES]: Unpin, [Message; TIMER_CMDS]: Unpin, [u64; SLOTS]: Unpin, [u8; BYTES]: Unpin, PhantomData<C>: Unpin,

§

impl<C, P, T, 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> UnsafeUnpin for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>

§

impl<C, P, T, 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> UnwindSafe for Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.