ayushkadali/firmware-debug-env

1---2title: Firmware Debug Environment3emoji: 🔧4colorFrom: gray5colorTo: red6sdk: docker7app_port: 78608tags:9  - openenv10---11 12# Firmware Debug Environment13 14An OpenEnv environment where AI agents debug **real embedded firmware issues** on a simulated ARM Cortex-M microcontroller (STM32). Agents interact with hardware registers, system logs, peripheral diagnostics, and RTOS task states to diagnose and fix bugs — exactly like a firmware engineer would.15 16## Why This Environment?17 18Firmware debugging is one of the hardest real-world tasks in embedded systems engineering. It requires:19- Decoding hardware register bitfields and cross-referencing datasheets20- Correlating system logs with peripheral state21- Understanding clock trees, baud rate calculations, and protocol timing22- Diagnosing concurrency bugs in RTOS scheduling23- Reasoning about memory hierarchy (cache coherency, DMA)24 25**No toy problems.** Every task in this environment is a real bug that embedded engineers encounter in production — from misconfigured baud rates to priority inversion to DMA cache coherency issues.26 27## Environment Overview28 29The agent connects to a simulated STM32 MCU experiencing a fault. Through systematic debugging actions, the agent must **investigate**, **diagnose**, and **fix** the issue. The simulation is **dynamic** — register writes mutate system state, produce observable consequences, and can cause cascading failures if incorrect.30 31## Action Space32 33| Action | Parameters | Description |34|--------|-----------|-------------|35| `read_register` | `target`, `register` | Read a peripheral register (value + description) |36| `write_register` | `target`, `register`, `value` | Write a value — **mutates system state dynamically** |37| `list_peripherals` | — | List all peripherals and their register maps |38| `read_log` | — | View system boot/runtime logs (new entries appear after writes) |39| `check_connection` | `target` | Physical connection diagnostics (signals, voltages) |40| `analyze_task` | `target` | Inspect RTOS task state (priority, mutexes, blocking) |41| `run_diagnostic` | `target` | Run built-in peripheral/RTOS diagnostic |42| `submit_diagnosis` | `diagnosis`, `root_cause` | Record diagnosis before fixing |43| `apply_fix` | `fix_type`, `target`, ... | Apply a fix to resolve the issue |44 45### Example Actions46```json47{"action_type": "read_register", "target": "USART1", "register": "BRR"}48{"action_type": "write_register", "target": "USART1", "register": "BRR", "value": 417}49{"action_type": "apply_fix", "fix_type": "enable_priority_inheritance", "target": "spi_mutex"}50```51 52## Observation Space53 54| Field | Type | Description |55|-------|------|-------------|56| `done` | bool | Episode ended |57| `reward` | float | Step reward [0.0, 1.0] |58| `message` | str | Human-readable result (register values, diagnostics, logs) |59| `data` | dict | Structured data for programmatic access |60| `system_status` | str | `fault` / `degraded` / `operational` |61| `error` | str? | Error if action was invalid |62 63## Tasks (5 total, easy → hard)64 65### 1. `uart_baud_mismatch` — Easy66**Symptom:** UART receiving corrupted data (CRC failures, overrun errors).67 68The STM32 communicates with an external sensor over USART1. The BRR register is misconfigured, producing 9600 baud instead of the required 19200. The agent must calculate the correct BRR value from the APB2 clock frequency and write it.69 70**Skills tested:** Register reading, baud rate calculation, clock tree understanding.71 72### 2. `i2c_sensor_failure` — Medium73**Symptom:** I2C sensor (IMU) not responding — NACK on every address attempt.74 75Three independent issues must be identified: wrong slave address (AD0 pin routing), I2C clock exceeding 400kHz spec, and GPIO output type set to push-pull instead of open-drain. Agent must fix at least 2 of 3.76 77**Skills tested:** Multi-factor diagnosis, I2C protocol knowledge, GPIO configuration.78 79### 3. `rtos_priority_inversion` — Hard80**Symptom:** High-priority sensor task intermittently misses deadlines.81 82A classic priority inversion: a low-priority task holds a mutex, gets preempted by a medium-priority task, blocking the high-priority task. The mutex was created as a binary semaphore (no priority inheritance). Agent must analyze task states and mutex ownership to identify the pattern.83 84**Skills tested:** RTOS scheduling, mutex semantics, concurrency debugging.85 86### 4. `dma_cache_coherency` — Hard87**Symptom:** CPU reads stale data from DMA buffer despite DMA transferring correctly.88 89On a Cortex-M7 with D-cache enabled, DMA writes to memory bypass the CPU cache. The MPU region is configured as write-back cacheable, so the CPU reads cached (stale) values. Agent must understand the memory hierarchy and either invalidate the cache or reconfigure the MPU.90 91**Skills tested:** Cache architecture, DMA operation, MPU configuration, memory-mapped I/O.92 93### 5. `watchdog_reset_loop` — Medium94**Symptom:** System stuck in boot loop, resetting every ~80ms.95 96The independent watchdog (IWDG) starts early in the boot sequence, but PLL lock + peripheral init takes longer than the configured timeout. Additionally, flash wait states are wrong for the 72MHz clock, causing further delays. Agent must calculate the watchdog timeout and fix the timing.97 98**Skills tested:** Watchdog timer configuration, boot sequence analysis, flash latency.99 100## Reward Function101 102Rewards are shaped across the full debugging trajectory:103 104| Component | Weight | Description |105|-----------|--------|-------------|106| Register exploration | 20% | Reading key diagnostic registers |107| Diagnosis accuracy | 25% | Correct identification of root cause |108| Fix correctness | 40% | Applying the right fix (structural grading) |109| Efficiency | 10% | Fewer steps = higher score |110| Penalties | -5% | Wrong fix attempts degrade score |111 112**Dynamic simulation features:**113- Correct register writes produce success logs and update related registers (e.g., ISR clears error flags)114- Wrong writes produce failure logs and can degrade system status115- Multiple wrong fix attempts increase penalty116- Grading is **structural** — based on actual register values written, not keyword matching117 118## Baseline Scores119 120Simulated optimal agent (reads key registers, submits diagnosis, applies correct fix):121 122| Task | Difficulty | Score | Steps |123|------|-----------|-------|-------|124| `uart_baud_mismatch` | Easy | 0.895 | 11 |125| `i2c_sensor_failure` | Medium | 0.865 | 13 |126| `rtos_priority_inversion` | Hard | 0.850 | 10 |127| `dma_cache_coherency` | Hard | 0.906 | 11 |128| `watchdog_reset_loop` | Medium | 0.869 | 13 |129| **Average** | | **0.877** | |130 131With zero investigation (just spamming read_log until step limit): all tasks score **0.000**.132 133## Setup & Usage134 135### Docker (recommended)136```bash137docker build -t firmware-debug-env .138docker run -p 7860:7860 firmware-debug-env139```140 141### Local Development142```bash143pip install -e ".[dev]"144uvicorn firmware_debug_env.server.app:app --host 0.0.0.0 --port 7860145```146 147### API Endpoints148```bash149# Health check150curl http://localhost:7860/health151 152# List tasks153curl http://localhost:7860/tasks154 155# Start a debugging session156curl -X POST http://localhost:7860/reset \157  -H "Content-Type: application/json" \158  -d '{"task_name": "uart_baud_mismatch"}'159 160# Execute a debugging action161curl -X POST http://localhost:7860/step \162  -H "Content-Type: application/json" \163  -d '{"action": {"action_type": "read_register", "target": "USART1", "register": "BRR"}}'164 165# Get current state166curl http://localhost:7860/state167```168 169### Run Inference170```bash171export HF_TOKEN="your-token"172export ENV_BASE_URL="http://localhost:7860"173python inference.py174```175 176## Technical Details177 178- **Framework:** OpenEnv (Meta PyTorch)179- **Server:** FastAPI + Uvicorn180- **Models:** Pydantic v2 with strict typing181- **Container:** Python 3.11 slim, runs on 2 vCPU / 8GB RAM182- **Inference runtime:** < 5 minutes per task, < 20 minutes total183 184## Author185 186**Ayush Kadali** — Firmware & Embedded Systems Engineer187- B.Tech CSE (AI & Data Science), MIT-WPU Pune188- Every task in this environment is based on real bugs encountered while building and debugging embedded flight systems189