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

void ai_rt_start(ai_rt_t *t, int64_t now_us);

the first release at now_us

uint64_t ai_rt_period_us(const ai_rt_t *t, uint8_t level);

int ai_rt_pick(ai_rt_t *t, int n, int64_t now_us, uint8_t level, int64_t *wake_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.

void ai_rt_finish(ai_rt_t *t, int64_t start_us, int64_t end_us, uint8_t level);

the picked job ran from start_us to end_us: response, miss, overrun (skip the next release)

ai_selftest_t ai_selftest_judge(const uint32_t *runs, int k, uint32_t budget_us);

runs[k] microseconds each (UINT32_MAX = the self-test’s own check failed: never admitted); budget 0 = no budget

uint8_t ai_dl_from_os(uint8_t os_level);

the AI level for an OS ladder level: rung 0 normal, rung 1 slowed, rung 2 and up paused

const char *ai_dl_name(uint8_t level);

void ai_rt_worker_load(const ai_rt_t *t, int n, uint32_t *c_us, uint32_t *t_ms, uint32_t *d_ms);

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

void ai_svc_start(void);

board task, at the boot health verdict (os.c health_form)

uint32_t ai_svc_misses(void);

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

void ai_svc_set_os_level(uint8_t os_level);

uint8_t ai_svc_level(void);

AI_DL_*: a step may drop optional work (“learned heads”) when slowed

uint8_t ai_svc_os_level(void);

the OS ladder rung the services last saw (the Health app)

void ai_svc_board_tick(bool shutdown);

board task: every 2 s, and true on the safe-shutdown path

void ai_svc_gauge_publish(const mosaico_gauge_t *g);

board task, after each gauge poll

bool ai_svc_gauge_read(ai_gauge_sample_t *out);

any task, lock-free; false = no sample yet or torn

bool ai_svc_status(ai_svc_status_t *out);

any task, lock-free

int ai_svc_log_line(char *buf, size_t n);

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

static inline void ai_seq_write_begin(ai_seq_t *s)

static inline void ai_seq_write_end(ai_seq_t *s)

static inline bool ai_seq_read(const ai_seq_t *s, void *dst, const void *src, void *tmp, size_t n)

copies n bytes from src to dst only when the copy is consistent; false: dst unchanged (keep the last good copy)

static inline bool ai_ring_push(ai_ring_t *r, const char *text)

static inline const char *ai_ring_peek(ai_ring_t *r)

the oldest line or NULL; ai_ring_pop() after the consumer is done with it

static inline void ai_ring_pop(ai_ring_t *r)

static inline uint32_t ai_ring_count(ai_ring_t *r)