# Crash Handling and Diagnostics

## Fault Handler

The firmware includes a comprehensive ARM Cortex-M4 fault handler that captures processor state for post-mortem analysis.

### Captured Faults

- Hard Fault
- Bus Fault
- Usage Fault
- MemManage Fault

### Captured State

When a fault occurs, the handler saves:

- **Core registers:** R0–R12, SP (stack pointer), LR (link register), PC (program counter), PSR (program status register)
- **FPU registers:** Floating-point unit state (added v0.2.17)
- **Fault status registers:** HFSR (Hard Fault Status), CFSR (Configurable Fault Status), MMFAR, BFAR
- **Memory dump:** Region around the faulting address (added v0.2.17)
- **Stack contents:** Stack frame at time of fault

All crash data is written to a reserved region of Flash for retrieval after reset.

### Recovery

After capturing the crash dump:
- MCU resets into bootloader mode (added v0.2.18)
- Crash data persists in Flash and can be read by host tools

### Deliberate Crash Triggers

Three HID commands intentionally trigger faults for testing the crash handler. All require the safety phrase "CRASHNOW" in bytes 1–8:

| Command | Code | Fault Type |
|---------|------|------------|
| HARDFAULT | `,` (0x2C) | ARM Hard Fault exception |
| UNUSED_IRQ | `.` (0x2E) | Unhandled interrupt |
| STACK_OVERFLOW | `>` (0x3E) | FreeRTOS task stack overflow |

**Source files:** `src/crash_handler/crash_handler.c/h`, `src/crash_handler/crash_handler_asm.S/h`

### Version History

| Version | Change |
|---------|--------|
| v0.2.16 | Created error handler with processor state capture |
| v0.2.17 | Added memory readout, FPU registers, HFSR details |
| v0.2.18 | Added reset-to-bootloader after crash |

## Stack Overflow Detection

### FreeRTOS Stack Watermarks

Every FreeRTOS task has a fixed stack allocation. The firmware monitors stack usage watermarks (minimum free stack ever recorded) for all 12 tasks.

Query via HID command `s` (0x73):
- Returns 4 bytes per task (32-bit unsigned LE)
- Values represent remaining stack words (lower = closer to overflow)

### Stack Size History

Several stack overflows were discovered and fixed during development:

| Version | Task | Fix |
|---------|------|-----|
| v0.2.15 | Tmr Svc | Increased from minimal size; overflowed at 5-min proximity timer |
| v0.2.19 | video_proc | Increased from 512 to 1024; was dangerously low after video start |

### Stack Overflow Handler

FreeRTOS is configured with stack overflow checking. When detected:
- `VIDEOPROC_STACK_OVERFLOW` notification sent to video task
- Crash handler captures state
- MCU resets to bootloader

**Python tool:** `scripts/stack_monitor.py`

## Hardware Self-Test

Seven hardware connectivity tests accessible via HID command `J` (0x4A):

| Sub-command | Test Name | Method |
|-------------|-----------|--------|
| `H` (0x48) | USB Hub | I2C read from USB hub chip registers |
| `L` (0x4C) | RGB LED | I2C read from LED driver |
| `S` (0x53) | USB-C Switch | I2C read from crossbar switch |
| `V` (0x56) | VXR7200 | I2C read from display SoC |
| `P` (0x50) | Proximity | I2C read from TMD2635 |
| `O` (0x4F) | OLED | I2C read + panel ID verification |
| `F` (0x46) | Fan | Command fan on, verify expected behavior |

Response: byte 0 = `J`, byte 1 = 0 (fail) or 1 (pass).

Also accessible over serial UART for factory use (v0.2.0).

**Source files:** `src/hw_test.c/h`

## Debug Interfaces

### UART Serial Console

- **Baud rate:** 115200
- Debug output and hardware test CLI
- Configured in `src/config/conf_uart_serial.h`

**Source files:** `src/usart_interface.c/h`

### Real-Time Terminal (RTT)

Segger RTT for low-overhead debug output:
- Does not require a dedicated UART
- Uses shared memory and a debug probe (J-Link)
- Utility functions in `src/Drivers/rtt_util.c/h`

### Tundra USB-UART Bridge

External debug interface via the Tundra USB-to-UART bridge chip:
- Provides UART access from the host PC through the USB connection
- Activity tracking via `VIDEOPROC_TRACK_UART_ACTIVITY` notification

**Source files:** `src/Devices/tundra_uart.c/h`

## Crash Analysis Tools

| Tool | Purpose |
|------|---------|
| `scripts/crash_handler.py` | Parse and decode crash dump data from Flash |
| `scripts/dump_crash_info.py` | Read raw crash info via HID and display formatted output |

These tools read the crash dump from the MCU's Flash, decode register values, identify the faulting instruction, and provide a formatted report for debugging.