ADR-081: implement Layers 1/2/4 end-to-end + host tests + QEMU hooks

Turns the ADR-081 scaffolding into a working adaptive CSI mesh kernel: Layer 1 radio abstraction has an ESP32 binding and a mock binding; Layer 2 adaptive controller runs on FreeRTOS timers; Layer 4 feature-state packet is emitted at 5 Hz by default, replacing raw ADR-018 CSI as the default upstream. New files: firmware/esp32-csi-node/main/adaptive_controller_decide.c (pure policy) firmware/esp32-csi-node/main/rv_radio_ops_mock.c (QEMU binding) firmware/esp32-csi-node/tests/host/Makefile (host tests) firmware/esp32-csi-node/tests/host/test_adaptive_controller.c firmware/esp32-csi-node/tests/host/test_rv_feature_state.c firmware/esp32-csi-node/tests/host/esp_err.h (shim) firmware/esp32-csi-node/tests/host/.gitignore Modified: adaptive_controller.c — includes pure decide.c; emit_feature_state() wired into fast loop (200 ms = 5 Hz) rv_radio_ops_esp32.c — get_health() fills pkt_yield + send_fail csi_collector.{c,h} — pkt_yield/send_fail accessors (ADR-081 L1) rv_feature_state.h — packed size corrected to 60 bytes (was incorrectly 80 in initial commit) main.c — mock binding registered under mock CSI CMakeLists.txt — rv_radio_ops_mock.c under CSI_MOCK_ENABLED scripts/validate_qemu_output.py — 3 new ADR-081 checks (17/18/19) docs/adr/ADR-081-*.md — status → Accepted (partial); implementation-status matrix; measured benchmarks (decide 3.2 ns, CRC32 614 ns); bandwidth 300 B/s @ 5 Hz (99.7% vs raw); verification section CHANGELOG.md — artifact-level entries Tests (host, gcc -O2 -std=c11): test_adaptive_controller: 18/18 pass, decide() = 3.2 ns/call test_rv_feature_state: 15/15 pass, CRC32(56 B) = 614 ns/pkt, 87 MB/s sizeof(rv_feature_state_t) == 60 asserted IEEE CRC32 known vectors verified Deferred (tracked in ADR-081 roadmap Phase 3/4): Layer 3 mesh-plane message types, role-assignment FSM, Rust-side mirror trait in crates/wifi-densepose-hardware/src/radio_ops.rs.
2026-08-01 19:01:42 +00:00 · 2026-04-19 03:43:08 +00:00
parent 9648a47fdc
commit d53e29506e
18 changed files with 966 additions and 107 deletions
@@ -0,0 +1,4 @@
+# Compiled host-test binaries
+test_adaptive_controller
+test_rv_feature_state
+*.o
@@ -0,0 +1,50 @@
+# Host-side unit tests for ADR-081 pure-C logic.
+#
+# These tests exercise adaptive_controller_decide() and the rv_feature_state
+# helpers (CRC32, finalize) using plain gcc/clang, with a minimal esp_err.h
+# shim. No ESP-IDF, no FreeRTOS, no QEMU required.
+#
+# Usage:
+#   cd firmware/esp32-csi-node/tests/host
+#   make
+#   ./test_adaptive_controller
+#   ./test_rv_feature_state
+
+MAIN_DIR := ../../main
+CC      ?= cc
+CFLAGS  ?= -O2 -std=c11 -Wall -Wextra -Wno-unused-parameter \
+           -D_POSIX_C_SOURCE=199309L \
+           -I. -I$(MAIN_DIR)
+LDLIBS  ?= -lrt
+
+# Pure-C sources under test. We compile only the files that have no
+# ESP-IDF dependency in their bodies: rv_feature_state.c is 100% pure.
+# adaptive_controller.c uses FreeRTOS for the timer plumbing, so for the
+# host test we compile only the decide() portion by isolating it in a
+# small unity file (TEST_ADAPT_PURE below).
+FEATURE_STATE_SRCS := $(MAIN_DIR)/rv_feature_state.c
+
+# adaptive_controller.c pulls in FreeRTOS headers that don't exist on
+# host; we include its decide() function by defining TEST_ADAPT_PURE
+# before including the .c. The decide() body itself has no ESP-IDF deps.
+# Simpler: just recompile decide() here via a small shim.
+
+TESTS := test_adaptive_controller test_rv_feature_state
+
+all: $(TESTS)
+
+test_adaptive_controller: test_adaptive_controller.c $(MAIN_DIR)/adaptive_controller_decide.c $(MAIN_DIR)/adaptive_controller.h $(MAIN_DIR)/rv_radio_ops.h
+	$(CC) $(CFLAGS) test_adaptive_controller.c $(MAIN_DIR)/adaptive_controller_decide.c -o $@ $(LDLIBS)
+
+test_rv_feature_state: test_rv_feature_state.c $(FEATURE_STATE_SRCS) $(MAIN_DIR)/rv_feature_state.h $(MAIN_DIR)/rv_radio_ops.h
+	$(CC) $(CFLAGS) test_rv_feature_state.c $(FEATURE_STATE_SRCS) -o $@ $(LDLIBS)
+
+check: all
+	./test_adaptive_controller
+	@echo ""
+	./test_rv_feature_state
+
+clean:
+	rm -f $(TESTS) *.o
+
+.PHONY: all check clean
@@ -0,0 +1,16 @@
+/* Host test shim for esp_err.h. Allows us to compile the pure-C
+ * portions of the firmware (adaptive_controller_decide, rv_feature_state
+ * CRC + finalize) under plain gcc/clang without the ESP-IDF toolchain. */
+#ifndef HOST_ESP_ERR_SHIM_H
+#define HOST_ESP_ERR_SHIM_H
+
+#include <stdint.h>
+
+typedef int esp_err_t;
+
+#define ESP_OK                0
+#define ESP_FAIL             -1
+#define ESP_ERR_NO_MEM      0x101
+#define ESP_ERR_INVALID_ARG 0x102
+
+#endif
@@ -0,0 +1,216 @@
+/*
+ * Host unit test for adaptive_controller_decide().
+ *
+ * The ADR-081 controller decision function is deliberately pure: it takes
+ * (cfg, current_state, observation) and produces a decision. No FreeRTOS,
+ * no ESP-IDF, no side effects. This test exercises every documented branch
+ * of the policy.
+ *
+ * Build + run (from this directory):
+ *   make -f Makefile
+ *   ./test_adaptive_controller
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "adaptive_controller.h"
+#include "rv_radio_ops.h"
+
+static int g_pass = 0, g_fail = 0;
+
+#define CHECK(cond, msg) do {                                   \
+    if (cond) { g_pass++; }                                     \
+    else { g_fail++; printf("  FAIL: %s (line %d)\n", msg, __LINE__); } \
+} while (0)
+
+static adapt_config_t default_cfg(void) {
+    adapt_config_t c = {
+        .fast_loop_ms = 200,
+        .medium_loop_ms = 1000,
+        .slow_loop_ms = 30000,
+        .aggressive = false,
+        .enable_channel_switch = false,
+        .enable_role_change = false,
+        .motion_threshold = 0.20f,
+        .anomaly_threshold = 0.60f,
+        .min_pkt_yield = 5,
+    };
+    return c;
+}
+
+static adapt_observation_t quiet_obs(void) {
+    adapt_observation_t o = {
+        .pkt_yield_per_sec = 50,
+        .send_fail_count = 0,
+        .rssi_median_dbm = -60,
+        .noise_floor_dbm = -95,
+        .motion_score = 0.01f,
+        .presence_score = 0.0f,
+        .anomaly_score = 0.0f,
+        .node_coherence = 1.0f,
+    };
+    return o;
+}
+
+static void test_degraded_gate_on_pkt_yield_collapse(void) {
+    printf("test: degraded gate on pkt yield collapse\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.pkt_yield_per_sec = 2;  /* below min_pkt_yield=5 */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.change_state, "should change state");
+    CHECK(dec.new_state == ADAPT_STATE_DEGRADED, "new state == DEGRADED");
+    CHECK(dec.new_profile == RV_PROFILE_PASSIVE_LOW_RATE,
+          "profile pinned to PASSIVE_LOW_RATE in degraded");
+    CHECK(dec.suggested_vital_interval_ms == 2000,
+          "cadence relaxed to 2s in degraded");
+}
+
+static void test_degraded_gate_on_coherence_loss(void) {
+    printf("test: degraded gate on coherence loss\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.node_coherence = 0.15f;  /* below 0.20 threshold */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_state == ADAPT_STATE_DEGRADED, "coherence loss → DEGRADED");
+}
+
+static void test_anomaly_trumps_motion(void) {
+    printf("test: anomaly trumps motion\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.9f;  /* high motion */
+    obs.anomaly_score = 0.8f; /* but anomaly is above threshold */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.new_state == ADAPT_STATE_ALERT, "anomaly → ALERT");
+    CHECK(dec.new_profile == RV_PROFILE_FAST_MOTION,
+          "alert uses FAST_MOTION profile");
+    CHECK(dec.suggested_vital_interval_ms == 100, "alert cadence 100ms");
+}
+
+static void test_motion_triggers_sense_active(void) {
+    printf("test: motion → SENSE_ACTIVE\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.new_state == ADAPT_STATE_SENSE_ACTIVE, "motion → SENSE_ACTIVE");
+    CHECK(dec.new_profile == RV_PROFILE_FAST_MOTION, "profile FAST_MOTION");
+    CHECK(dec.suggested_vital_interval_ms == 200,
+          "non-aggressive cadence 200ms");
+}
+
+static void test_aggressive_cadence(void) {
+    printf("test: aggressive cadence is tighter\n");
+    adapt_config_t cfg = default_cfg();
+    cfg.aggressive = true;
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.suggested_vital_interval_ms == 100,
+          "aggressive motion cadence 100ms");
+}
+
+static void test_stable_presence_uses_resp_high_sens(void) {
+    printf("test: stable presence → RESP_HIGH_SENS\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.presence_score = 0.8f;
+    obs.motion_score = 0.01f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_profile == RV_PROFILE_RESP_HIGH_SENS,
+          "stable presence uses respiration profile");
+    CHECK(dec.suggested_vital_interval_ms == 1000,
+          "respiration cadence 1s");
+}
+
+static void test_empty_room_default_is_passive(void) {
+    printf("test: empty room → PASSIVE_LOW_RATE\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_profile == RV_PROFILE_PASSIVE_LOW_RATE,
+          "empty → passive low rate");
+}
+
+static void test_hysteresis_no_flap(void) {
+    printf("test: no change_state when already in target state\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_ACTIVE, &obs, &dec);
+    CHECK(!dec.change_state,
+          "already in SENSE_ACTIVE — no redundant change_state");
+}
+
+static void test_null_safety(void) {
+    printf("test: NULL args are no-ops (no crash)\n");
+    adapt_decision_t dec = {0};
+    adaptive_controller_decide(NULL, ADAPT_STATE_SENSE_IDLE, NULL, &dec);
+    /* if we got here, no segfault — pass */
+    g_pass++;
+    printf("  OK\n");
+}
+
+static void benchmark_decide(void) {
+    printf("bench: adaptive_controller_decide() throughput\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    adapt_decision_t dec;
+
+    const int N = 10000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    for (int i = 0; i < N; i++) {
+        /* Vary input slightly so the compiler can't fold the call. */
+        obs.motion_score = (i & 0xff) / 255.0f;
+        adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    printf("  %d calls, %.1f ns/call\n", N, ns_per_call);
+    /* Sanity: decide() is O(constant) — must be under 10us even on a
+     * slow emulator. Real ESP32 will be ~100-300ns. */
+    CHECK(ns_per_call < 10000.0, "decide() must be under 10us/call");
+}
+
+int main(void) {
+    printf("=== adaptive_controller_decide() host tests ===\n\n");
+
+    test_degraded_gate_on_pkt_yield_collapse();
+    test_degraded_gate_on_coherence_loss();
+    test_anomaly_trumps_motion();
+    test_motion_triggers_sense_active();
+    test_aggressive_cadence();
+    test_stable_presence_uses_resp_high_sens();
+    test_empty_room_default_is_passive();
+    test_hysteresis_no_flap();
+    test_null_safety();
+    benchmark_decide();
+
+    printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail);
+    return g_fail > 0 ? 1 : 0;
+}
@@ -0,0 +1,152 @@
+/*
+ * Host unit test for rv_feature_state_* helpers.
+ *
+ * Validates:
+ *   - Packet layout is exactly 80 bytes
+ *   - IEEE CRC32 matches well-known reference vectors
+ *   - finalize() populates magic/seq/ts/crc correctly
+ *   - CRC32 throughput benchmark
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "rv_feature_state.h"
+#include "rv_radio_ops.h"
+
+static int g_pass = 0, g_fail = 0;
+#define CHECK(cond, msg) do {                                   \
+    if (cond) { g_pass++; }                                     \
+    else { g_fail++; printf("  FAIL: %s (line %d)\n", msg, __LINE__); } \
+} while (0)
+
+static void test_packet_size(void) {
+    printf("test: rv_feature_state_t is 60 bytes on the wire\n");
+    CHECK(sizeof(rv_feature_state_t) == 60, "sizeof == 60");
+}
+
+static void test_crc_known_vectors(void) {
+    printf("test: IEEE CRC32 known vectors\n");
+    /* IEEE CRC32 of "123456789" == 0xCBF43926 (well-known). */
+    uint32_t c1 = rv_feature_state_crc32((const uint8_t *)"123456789", 9);
+    CHECK(c1 == 0xCBF43926u, "CRC32('123456789') == 0xCBF43926");
+
+    /* Empty input → 0x00000000 (before final inversion, 0xFFFFFFFF);
+     * IEEE convention with post-invert → 0x00000000 reversed — but with
+     * our implementation the empty-input CRC is 0x00000000 after post-
+     * invert on ~0xFFFFFFFF = 0x00000000. */
+    uint32_t c2 = rv_feature_state_crc32(NULL, 0);
+    CHECK(c2 == 0x00000000u, "CRC32(empty) == 0");
+
+    /* Single zero byte: IEEE CRC32 of 0x00 = 0xD202EF8D. */
+    uint8_t zero = 0;
+    uint32_t c3 = rv_feature_state_crc32(&zero, 1);
+    CHECK(c3 == 0xD202EF8Du, "CRC32(0x00) == 0xD202EF8D");
+}
+
+static void test_finalize(void) {
+    printf("test: finalize populates required fields\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0, sizeof(pkt));
+    pkt.motion_score    = 0.25f;
+    pkt.presence_score  = 0.75f;
+    pkt.respiration_bpm = 14.5f;
+    pkt.quality_flags   = RV_QFLAG_PRESENCE_VALID | RV_QFLAG_RESPIRATION_VALID;
+
+    rv_feature_state_finalize(&pkt, /*node*/ 7, /*seq*/ 42,
+                              /*ts*/ 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+
+    CHECK(pkt.magic == RV_FEATURE_STATE_MAGIC, "magic");
+    CHECK(pkt.node_id == 7, "node_id");
+    CHECK(pkt.seq == 42, "seq");
+    CHECK(pkt.ts_us == 1234567ULL, "ts_us");
+    CHECK(pkt.mode == RV_PROFILE_RESP_HIGH_SENS, "mode");
+    CHECK(pkt.reserved == 0, "reserved cleared");
+    CHECK(pkt.crc32 != 0, "crc32 populated (non-trivial input)");
+
+    /* Re-finalize must produce identical CRC (deterministic). */
+    uint32_t crc1 = pkt.crc32;
+    rv_feature_state_finalize(&pkt, 7, 42, 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+    CHECK(pkt.crc32 == crc1, "finalize is deterministic");
+
+    /* Changing a payload byte must change the CRC. */
+    pkt.motion_score = 0.26f;
+    rv_feature_state_finalize(&pkt, 7, 42, 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+    CHECK(pkt.crc32 != crc1, "CRC changes when payload changes");
+}
+
+static void test_crc_verifiability(void) {
+    printf("test: receiver can verify CRC\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0, sizeof(pkt));
+    pkt.motion_score   = 0.33f;
+    pkt.presence_score = 0.66f;
+    rv_feature_state_finalize(&pkt, 1, 100, 555ULL, RV_PROFILE_PASSIVE_LOW_RATE);
+
+    /* Receiver recomputes CRC over all bytes except the trailing crc32. */
+    uint32_t expected = rv_feature_state_crc32(
+        (const uint8_t *)&pkt, sizeof(pkt) - sizeof(uint32_t));
+    CHECK(pkt.crc32 == expected, "receiver-side CRC check matches");
+}
+
+static void benchmark_crc(void) {
+    printf("bench: CRC32 over 60-byte packet (56 B hashed, excl trailing crc32)\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0x5A, sizeof(pkt));
+
+    const int N = 5000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    volatile uint32_t sink = 0;
+    for (int i = 0; i < N; i++) {
+        pkt.seq = (uint16_t)i;  /* vary input so compiler can't fold */
+        sink ^= rv_feature_state_crc32(
+            (const uint8_t *)&pkt, sizeof(pkt) - sizeof(uint32_t));
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    (void)sink;
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    double mb_per_sec = (double)(sizeof(pkt) - sizeof(uint32_t)) / ns_per_call
+                        * 1e9 / (1024.0 * 1024.0);
+    printf("  %d calls, %.1f ns/packet, %.1f MB/s\n",
+           N, ns_per_call, mb_per_sec);
+    /* At 10 Hz feature-state cadence, CRC budget is <100us/packet — we
+     * expect bit-by-bit CRC32 to run ~1 MB/s on host, ~100-300 KB/s on
+     * ESP32-S3 Xtensa LX7. 76-byte CRC takes <1 ms either way. */
+    CHECK(ns_per_call < 50000.0, "CRC32(80B) must be under 50us/packet");
+}
+
+static void benchmark_finalize(void) {
+    printf("bench: full finalize() cost\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0x33, sizeof(pkt));
+
+    const int N = 5000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    for (int i = 0; i < N; i++) {
+        rv_feature_state_finalize(&pkt, 1, (uint16_t)i, (uint64_t)i,
+                                  RV_PROFILE_PASSIVE_LOW_RATE);
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    printf("  %d calls, %.1f ns/call (includes CRC)\n", N, ns_per_call);
+}
+
+int main(void) {
+    printf("=== rv_feature_state_* host tests ===\n\n");
+
+    test_packet_size();
+    test_crc_known_vectors();
+    test_finalize();
+    test_crc_verifiability();
+    benchmark_crc();
+    benchmark_finalize();
+
+    printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail);
+    return g_fail > 0 ? 1 : 0;
+}