Skip to content

VALIDATION.md

Latest commit

 

History

History
131 lines (99 loc) · 4 KB

VALIDATION.md

File metadata and controls

131 lines (99 loc) · 4 KB
Raw

NUCLEO-H563ZI Demo Runbook

Run all commands from core/.

Prerequisites

  1. Rust toolchain available (cargo, required targets installed).
  2. arm-none-eabi-gcc installed (for hardware firmware build).
  3. openocd installed (for board flashing).
  4. NUCLEO-H563ZI connected over ST-Link USB (for hardware steps).

A) Emulator Showcase (Deterministic)

examples/nucleo-h563zi/scripts/run_full_example.sh

Pass criteria:

  1. script exits with code 0
  2. UART smoke contains OK
  3. IO smoke contains LED on/off lines for PB0/PF4/PG4
  4. full-chip smoke contains RCC=1 SYSTICK=1 UART=1 and ALL=1

B) VS Code One-Click Run

  1. Open examples/nucleo-h563zi in VS Code.
  2. Run LabWired: Run in LabWired.

Pass criteria:

  1. build succeeds from example-root Makefile
  2. target/firmware is created under examples/nucleo-h563zi
  3. simulator starts with the built ELF
  4. LabWired output panel contains emulator UART lines like H563-IO

C) Blink+UART in Emulator + Real Board

examples/nucleo-h563zi/scripts/run_blink_uart_dual.sh --port /dev/ttyACM0

Pass criteria:

  1. emulator phase passes io-smoke.yaml
  2. hardware phase flashes firmware successfully
  3. hardware UART output contains:
    • H563-BLINK-UART
    • at least one BLINK ... PB0=1 ...
    • at least one BLINK ... PB0=0 ...
  4. terminal shows both:
    • emulator UART lines (H563-IO, PB0=...)
    • live hardware UART lines during capture window

D) Hardware-Only Run

examples/nucleo-h563zi/scripts/run_blink_uart_hardware.sh --port /dev/ttyACM0

Optional serial autodetect:

examples/nucleo-h563zi/scripts/run_blink_uart_hardware.sh

E) Presentation Flow (3-5 Minutes)

  1. Run run_full_example.sh and show deterministic emulator pass.
  2. Run run_blink_uart_hardware.sh --port /dev/ttyACM0 with board visible.
  3. Point to UART lines and physical LED blinking as proof of parity.
  4. Close with docs/NUCLEO_H563ZI_DEMO.md for capability summary.

F) Recording Flow (Concise Terminal Output)

examples/nucleo-h563zi/scripts/run_video_demo.sh --mode all --port /dev/ttyACM0 --keep-artifacts

Pass criteria:

  1. PASS: uart-smoke
  2. PASS: io-smoke
  3. PASS: fullchip-smoke
  4. Hardware phase prints Hardware blink+UART check passed.

G) Unsupported-Instruction Audit (Code-Driven)

./scripts/unsupported_instruction_audit.sh \
  --firmware target/thumbv7m-none-eabi/release/firmware-h563-io-demo \
  --system configs/systems/nucleo-h563zi-demo.yaml \
  --max-steps 200000 \
  --out-dir out/unsupported-audit/nucleo-h563zi

Pass criteria:

  1. script exits with code 0
  2. out/unsupported-audit/nucleo-h563zi/report.md exists
  3. unsupported counts are reviewed and tracked (or zero)

H) Silicon Reset-State Capture + Smoke Conformance

Reset-state register capture from the real board (ground truth for the chip model's reset values; pinned by crates/core/tests/h563_conformance.rs):

bash scripts/hw-capture-stm32h563.sh

Digital-twin smoke: one ELF on both targets, identical UART bytes expected.

# Build
(cd examples/nucleo-h563zi/silicon-smoke && cargo build --release --target thumbv7m-none-eabi)
ELF=examples/nucleo-h563zi/silicon-smoke/target/thumbv7m-none-eabi/release/h563-silicon-smoke
# Simulator
cargo run -p labwired-cli -- -f $ELF -s configs/systems/nucleo-h563zi-demo.yaml --max-steps 200000
# Real board (probe-rs, STLINK-V3 on-board)
probe-rs download --chip STM32H563ZITx $ELF && \
  stty -F /dev/ttyACM0 115200 raw -echo && \
  (timeout 8 cat /dev/ttyACM0 &) && sleep 1 && probe-rs reset --chip STM32H563ZITx

Pass criteria:

  1. both targets print the same two lines: H563-SMOKE CR=0000002B MODERA=ABFFFFFF CALIB=001003E8 and H563-SMOKE done
  2. green LED PB0 blinks on the board

Troubleshooting

  1. openocd transport errors: use defaults from script (stlink-dap + dapdirect_swd).
  2. No UART output: verify port (/dev/ttyACM*) and ST-Link cable.
  3. Permission errors on serial: add user to dialout group or run with proper device permissions.