AI services#
Every function each header declares, with the comment the header gives it. The header’s own opening comment is shown as written in the source.
ai_svc_core.h#
Source: main/ai_svc_core.h
ai_svc_core: the pure rules of EdgeOS's small AI services (ESP-Mosaico). No IDF: host-tested in
tests/host/test_ai_svc.c. The firmware glue is ai_svc.c.
1. Release table. Every service is a periodic job: period T, relative deadline D <= T, a WCET budget C. One worker
task per board runs them (ai_svc.c says why one and not one task each). When several are due at once, the one
with the shortest D runs first (deadline-monotonic, Leung and Whitehead 1982; equal to rate-monotonic when D = T).
Steps are short and never block, so inside the worker they do not preempt each other; every other task with a
deadline (UI, models, OBD) has a higher FreeRTOS priority and preempts the worker at any instruction.
2. No pile-up. At most one job of a service is ever outstanding. A worker that comes back late, after k more
releases have passed, runs only the newest one and counts the k older ones as skipped (they are never queued).
A step that runs longer than its budget finishes (it is never killed mid-update), and the service's next release
is skipped, so an overrun cannot push the following jobs into a backlog either.
3. Soft real time. A job whose response time (finish minus release) exceeds D is counted as missed. A miss is never
fatal: it feeds the degradation rule below.
4. Degradation (AI services shed first). The OS ladder (os_core.h section 7) has the AI rung first: at rung 1 every
service runs at period x10 (or at its own slow_factor: the IDS evaluates every 4th window) with its learned
heads off, from rung 2 (UI slowed) up the services are paused. The
services' own deadline misses, the UI's and the AI worker's feed the ladder's AI-side input, which can climb to
rung 1 only; model misses climb every rung. The rungs come back in reverse order, so the services come back last.
Function |
Comment in the header |
|---|---|
|
the first release at now_us |
|
|
|
The due service with the shortest deadline (index), or -1 when none is due. *wake_us: the earliest next release among the active services (now + 1 s while paused). Counts the releases a late worker passed over as skipped. |
|
the picked job ran from start_us to end_us: response, miss, overrun (skip the next release) |
|
runs[k] microseconds each (UINT32_MAX = the self-test’s own check failed: never admitted); budget 0 = no budget |
|
the AI level for an OS ladder level: rung 0 normal, rung 1 slowed, rung 2 and up paused |
|
|
|
the admission candidate of a worker that runs services[0..n) (active ones only): C = the sum of the budgets (all can be released at the same instant), T = the shortest period, D = the shortest deadline |
ai_svc.h#
Source: main/ai_svc.h
ai_svc: OpenCarMind EdgeOS's small AI services on the ESP-Mosaico (CONFIG_OCM_AI_SVC): the battery estimator
(bat_est.c, with the SoH regressor), the battery anomaly detector (bat_anom.c) and the network guard (ids_svc.c). The rules (release table, no pile-up, degrade
order) are in ai_svc_core.h; this file is the firmware side. See the block comment at the top of ai_svc.c for the
scheduling choice and the deadlock-freedom argument.
A service is a table entry: name, period, relative deadline, CPU budget, and four hooks.
step(release_us) the worker task, once per release. Must never block: no lock, no I/O, no queue wait, no
allocation. Reads its inputs from single-writer snapshots (ai_svc_gauge_read), publishes its
result in a single-writer struct the UI reads lock-free, hands rows for storage to a ring.
selftest() board task, once before admission: one timed step on fixed data (us); over the budget = refused.
prepare() board task, once before the worker starts: may read NVS.
board(shutdown) board task, every 2 s and on the safe-shutdown path: may write NVS and files (rate-limited by
the service, except when shutdown is true).
Function |
Comment in the header |
|---|---|
|
board task, at the boot health verdict (os.c health_form) |
|
board task, every OS ladder window: the services’ deadline misses so far (the ladder’s AI-side input, with the ui and ai jobs’), logged once per window when they grew; then the ladder’s new level sets the services’ level |
|
|
|
AI_DL_*: a step may drop optional work (“learned heads”) when slowed |
|
the OS ladder rung the services last saw (the Health app) |
|
board task: every 2 s, and true on the safe-shutdown path |
|
board task, after each gauge poll |
|
any task, lock-free; false = no sample yet or torn |
|
any task, lock-free |
|
the sched summary’s AI line; 0 = nothing to say |
ai_snap.h#
Source: main/ai_snap.h
ai_snap: a single-writer seqlock for the AI service layer (EdgeOS, ESP-Mosaico). Header only, no IDF: host-tested.
One task writes a struct, any number of tasks read it, and nobody ever waits. The writer makes the sequence odd,
writes the data, makes it even again. A reader copies the data between two reads of the sequence and keeps the copy
only when both reads are equal and even, so a copy torn by a write in progress is thrown away (Lamport 1977,
"Concurrent reading and writing"; the fences as in Boehm 2012, "Can seqlocks get along with programming language
memory models?"). A reader gives up after AI_SEQ_TRIES attempts and keeps its previous copy: on one core a reader of
higher priority that preempted the writer mid-write would otherwise spin forever, because the writer cannot run.
So a read is wait-free and bounded, and a stale value is the worst case. No lock, no priority inversion, no deadlock.
Function |
Comment in the header |
|---|---|
|
|
|
|
|
copies n bytes from src to dst only when the copy is consistent; false: dst unchanged (keep the last good copy) |
|
|
|
the oldest line or NULL; ai_ring_pop() after the consumer is done with it |
|
|
|