Firmware architecture

Modules and the deadline each carries, the reflex budget split across stages, and the firmware/software interface

Open on GitHub Mở trên GitHub

Snapshot of this document in the GEMs repository. The repository itself is the current version. Bản chụp tài liệu này trong repo GEMs. Bản đang chạy nằm ở chính repo.

The architecture of the body's real-time code: the firmware on the microcontrollers, and the Real-time Control Layer's modules, which are firmware or software according to decision D-3 (spec 07.1). Their deadlines are the same either way. The specification states what this code must guarantee; this document states how the work is divided so that it can, and — the part that is genuinely new here — how the 10 ms reflex budget is spent.

Nothing below fixes a part. Where a figure depends on hardware not yet chosen it is marked ⟦IMPL⟧ and stays marked.

1. Modules and the deadline each owns

One rule across all of them. A module that misses its deadline must say so. A late result delivered silently is worse than a reported miss, because the layer above cannot tell the difference between fresh and stale, and the log will record a decision made on data that was not what it appeared to be.

2. The reflex budget

10 ms is the whole path — stimulus at a sensor to motion at an actuator, not the compute portion of it. A proposed division:

The log write is 0.5% of the budget. This is the number that answers the objection that a context record per reflex (RSIL: traced appraisal) costs too much to run at reflex speed. It does not. What it costs is the discipline of having a place to write to, which is a design constraint rather than a time cost — see 06.7.

The reflex decision stage is not optional and not zero. It still runs, however little it has left to decide; that is what makes the output event re-appraisable from outside, which is what RSIL INV-8 asks. A firmware design that discovers it is over budget and reclaims this millisecond has stopped conforming (protocol C-9).

The split is ⟦IMPL⟧ and will move once real parts exist. The same figures are held, with every task's layer and deadline class, in ../realtime_config/tasks.csv, and python realtime_config/check_timing.py fails if the two disagree. The margin is not spare capacity to be spent later — it absorbs the jitter that measurement will find.

3. The balance loop

500 Hz is a 2 ms period. Within it:

Balance and reflex share sensors and actuators but not deadlines. Where they contend, balance wins: a body that reflexes correctly while falling has failed at the thing that keeps the reflex worth having.

4. The interface to the edge software

The real-time code — firmware, and the Real-time Control Layer whichever layer D-3 puts it in — hands up; the edge AI module's software hands down. What it hands down comes from the one source of commands the unit has at the time: the Main Controller, through the link, or the OBC while it holds command (spec 07.5) — never both. The boundary is narrow on purpose.

Agency tagging is real-time code. It is a hard real-time stage of the reflex path, and it needs the commanded value and the measured value in the same place at the same time (07.3, guarantee 7): once a stream has crossed upward without its tag, the information that would have carried it has already been averaged away.

The edge software sends intent, not commands. The final command belongs to a hard real-time task, so it belongs to the real-time code. Edge software that could write actuator values directly could also miss a deadline while holding them, and nothing on the edge module bounds its latency.

5. Link loss

The OBC is a small computer of its own, standing by while the IPC is online and taking command only on a trigger: a heartbeat missed beyond the threshold, or the Main Controller handing over when the link lags. In command it maintains balance through the Real-time Control Layer, which runs throughout, preserves state and log, continues recording at both tiers, and attempts re-establishment; it gives command back only when the Main Controller takes it.

It does not decide. The boundary is stated at 07.5 and it is architectural: reflexes are loadable, and the interpretation of priorities in an unforeseen situation is not a reflex.

A practical consequence for this layer: the log must not be trimmed to save space during an outage. An outage is exactly when the record matters most, and a body that discards its own unsynchronised history has made the outage unauditable.

6. Open