Threading and timing¶
One lock, one clock and one delay above the platform bind, and one tick rate everywhere. Decision for the tick: ADR-0006.
Who may call the RTOS¶
| Code | RTOS access |
|---|---|
| Drivers | None. Drivers do not lock, sleep or create tasks; they wait only through the port's delay hooks. |
kb-core utils, pincfg |
None. |
kb-core interfaces/base/ |
None directly; MAY use kb::rtos types. mcu/<family>/ classes MAY use the SDK's own primitives internally. |
kb-core rtos/ |
The only code that includes RTOS headers, and only in the selected backend (freertos/, threadx/, none/). |
| Handlers, HALs, products | kb::rtos only. |
bsp_bind/<family>/, product platform/ |
MAY use the SDK and RTOS directly for start-up and family-specific work. |
Raw xTaskCreate, xSemaphoreTake, vTaskDelay, std::mutex or std::thread above the bind is a defect.
KB_RTOS=FREERTOS|THREADX|NONE selects the backend and defines exactly one of KB_RTOS_FREERTOS,
KB_RTOS_THREADX or KB_RTOS_NONE (host tests and bare-metal). Code above kb::rtos MUST work on all three;
anything backend-specific stays inside the backend folder.
One lock¶
- The only mutex above the bind is
RtosMutex, taken withMutexLockGuard(RtosUniqueLock<RtosMutex>):
#include "kb/rtos/RtosMutex.h"
kb::Result<float> Zp100Handler::ReadPressurePa() noexcept {
MutexLockGuard lock(mutex_);
// ...
}
- No other mutex family exists above the bind: no per-HAL mutex wrappers, no private lock inside a protocol
stack. A component that needs a lock takes an
RtosMutex. - Locks are held for the duration of one call. No lock is held across a
DelayMs()longer than the operation requires, across a callback into other code, or across a call into another handler. - Lock order: handler mutex, then bus mutex. Managers call handlers without holding their own lock when they can; when they cannot, the order is manager, handler, bus.
- ISRs never take a mutex. They set an
OsEventFlagsbit or give aSignalSemaphoreand return.
One clock¶
- The only time source above the bind is
kb::MonotonicUs()(kb/interfaces/Time.h): microseconds since boot, 64-bit, monotonic, safe from any task and from ISRs.base/declares it; the selected family'smcu/<family>/folder defines it. esp_timer_get_time(),xTaskGetTickCount(),HAL_GetTick()andstd::chrono::steady_clockare not used above the bind. The bind'sMonotonicMicros()returns the same counter and exists so the host bind can drive a fake clock in tests.- Durations are
uint32_toruint64_twith a unit suffix (timeout_ms,period_us). Deadlines are compared by subtraction, never with>:
const uint64_t deadline_us = kb::MonotonicUs() + timeout_us;
while (static_cast<int64_t>(kb::MonotonicUs() - deadline_us) < 0) { /* poll */ }
Delays¶
A delay waits at least the requested time, never less.
| Delay | Call | Behaviour |
|---|---|---|
| 1 ms and longer | os_delay_msec(ms) (kb::rtos) |
Blocks the task. Converts to ticks rounding up, then adds one tick, because the first tick can arrive at once; at 1 kHz a 1 ms delay waits between 1 and 2 ms |
| Under 1 ms | kb::DelayUs(us) (kb/handlers/common/Delay.h) |
Busy-waits on kb::MonotonicUs() until at least us have passed; no RTOS call |
| In a driver | the port's DelayUs() / DelayMs() hooks |
Implemented by the adapter with the two rows above |
kb::DelayUs()with 1000 µs or more rounds up to whole milliseconds and callsos_delay_msec(), so a datasheet minimum of 2.5 ms never becomes 2 ms.- A delay of 0 returns at once (or yields, on an RTOS backend); it does not wait a tick.
- Busy-waits longer than 100 µs SHOULD be avoided in tasks above idle priority; restructure as a poll with a millisecond delay.
kb::DelayUs()andkb::DelayMs()MUST NOT testESP_PLATFORMor any MCU macro; the MCU-specific part is inkb::MonotonicUs()and the rtos backend.
The 1 kHz tick¶
Every FreeRTOS project runs at 1000 Hz: products, board HALs, kb-core and every driver's examples/esp32 project.
ESP-IDF's default of 100 Hz turns a 1 ms wait into 10 to 20 ms, and the millisecond helpers in kb::rtos assume
1 kHz.
- Set
CONFIG_FREERTOS_HZ=1000insdkconfig.defaults. A generatedsdkconfigis never committed (ADR-0018): a project that still has one deletes it and moves its settings into the defaults files, because a committedsdkconfigoverrides them. - Convert milliseconds with
pdMS_TO_TICKS()(inside the rtos backend) or thekb::rtoshelpers. Never pass a raw tick count that assumes a rate. - At 1 kHz,
pdMS_TO_TICKS()overflows its 32-bit arithmetic above about 71 minutes, and the tick counter wraps after about 49.7 days: compare tick deadlines with(int32_t)(now - deadline) > 0. - The driver and board HAL templates write the setting into new projects. CI SHOULD fail a build whose effective
CONFIG_FREERTOS_HZis not 1000. - ThreadX builds SHOULD use a 1 kHz kernel tick as well, so timing behaves the same on STM32.
Tasks¶
- Tasks are created through
kb::rtos(BaseThread,BaseThreadsManager) by the product or a HAL manager, never by a handler or a driver. - Stack sizes and priorities are named constants in one header per product (
<board>::app::kTaskConfig), not literals at the call site. - Core affinity is a product decision, in that header. HAL code does not assume a dual-core MCU.
- Work that must happen at a fixed rate uses
PeriodicTimeror a task loop onos_delay_msec()with drift correction, not a chain of delays.
What crosses tasks¶
- Data shared between tasks is either protected by one
RtosMutex, passed through anOsQueue, or published withSeqlockSnapshotfor one writer and many readers. - Callbacks from handlers into the product run in the caller's task. A callback that must reach another task posts to a queue.