| # AST10x0 Test Infrastructure | |
| ## Overview | |
| Tests for the AST10x0 target are firmware images that run identically under | |
| QEMU or on a physical board. Pass/fail is signalled by writing a sentinel | |
| string to UART: | |
| ``` | |
| TEST_RESULT:PASS\n | |
| TEST_RESULT:FAIL\n | |
| ``` | |
| The same `system_image_test` target is used for both execution environments — | |
| no separate hardware-only test targets exist. | |
| ## Running Tests | |
| ### QEMU (no hardware required) | |
| ``` | |
| bazel test --config=virt_ast10x0 //target/ast10x0/tests/... | |
| ``` | |
| ### Physical AST1060 EVB via Raspberry Pi SSH fixture | |
| ``` | |
| AST1060_EVB_PI_HOST=<pi-hostname> bazel test --config=k_ast1060_evb //target/ast10x0/tests/... | |
| ``` | |
| or inline without modifying the shell environment: | |
| ``` | |
| bazel test --config=k_ast1060_evb --test_env=AST1060_EVB_PI_HOST=<pi-hostname> //target/ast10x0/tests/... | |
| ``` | |
| Key-based SSH auth is required (`ssh-copy-id <user>@<pi-host>`). The Pi runs | |
| `pi_test_runner.py`, which handles GPIO reset sequencing, firmware upload over | |
| the UART bootloader, and sentinel detection. UART output is streamed back to | |
| the host for detokenization and display. Tests no longer use cortex_m_semihosting. | |
| ### Physical AST1060 EVB wired (not yet implemented) | |
| A wired mode — where the host connects to the Pi fixture over a local serial | |
| port rather than SSH — is not yet implemented. The physical connection type | |
| between the host and the Pi has not been defined (e.g. Pi serial console over | |
| UART, USB serial gadget, or USB networking), so the host-side protocol cannot | |
| be specified. Omitting `AST1060_EVB_PI_HOST` should default to using a wired | |
| connection, but currently logs an unimplemented error. | |
| ## Hardware Tests | |
| | Test | Description | | |
| |------|-------------| | |
| | [`mctp/server`](mctp/server/README.md) | MCTP echo stress test between two AST1060 EVBs over I2C | | |
| | [`flash`](flash/README.md) | QEMU and EVB: the flash HAL erases, programs and reads back CS1 in the kernel, without IPC | | |
| | [`flash_service`](flash_service/README.md) | QEMU and EVB: flash client erases, programs and reads back CS1 through the flash server over a kernel IPC channel | | |
| | `mctp/multi_protocol` | QEMU: one MCTP server as the messaging layer for two protocol tasks (SPDM/PLDM echo stand-ins), each on its own IPC channel | | |
| ## Test Results (2026-05-12) | |
| | Test | QEMU | Physical board | | |
| |------|------|----------------| | |
| | `interrupts/kernel:interrupts_test` | PASSED | TIMEOUT — see note below | | |
| | `interrupts/user:interrupts_test` | PASSED | PASSED | | |
| | `ipc/user:ipc_test` | FAILED (hangs at `object_set_peer_user_signal`) | PASSED | | |
| | `threads/kernel:threads_test` | PASSED | PASSED | | |
| | `unittest_runner:unittest_runner` | PASSED | SKIPPED (qemu_only) | | |
| | `usart:usart_test` | PASSED | SKIPPED (qemu_only) | | |
| | `*/no_panics_test` (×5) | SKIPPED (host-only) | SKIPPED | | |
| ### `interrupts/kernel:interrupts_test` — times out on physical board | |
| The firmware produces no UART output after upload, indicating a crash before | |
| UART initialisation. The same binary passes in QEMU. The `interrupts/user` | |
| variant (which manages IRQ 42 through the kernel IPC abstraction rather than | |
| raw NVIC manipulation) passes on both. | |
| The suspected cause is the `interrupt_table` entry in `system.json5`: the | |
| codegen for that entry installs an NVIC handler via `early_init()`, which runs | |
| before UART is initialised. If `early_init()` faults (e.g. invalid vector table | |
| layout, bad IRQ number on hardware), the firmware crashes with no UART output | |
| and no way to signal failure. This cannot be verified without a hardware | |
| debugger (GDB via OpenOCD or J-Link) attached to the board. | |
| ## How Pass/Fail Signalling Works | |
| Firmware writes the sentinel via `console_backend_write_all`, which calls | |
| `Usart::write_all` directly, bypassing `pw_log` and the tokenizer. This means | |
| the sentinel is always plain ASCII regardless of whether the rest of the log | |
| output is tokenized, and it can be detected without an ELF for detokenization. | |
| ### QEMU | |
| `qemu_runner.py` starts QEMU with `-serial mon:stdio` and redirects the QEMU | |
| stdout into a temporary file, which holds the raw byte stream. A sentinel | |
| watcher thread scans that file; when the thread finds a sentinel it kills | |
| QEMU and the runner exits 0 or 1. A 30-second watchdog kills QEMU if no sentinel arrives. | |
| ### Physical board | |
| `pi_test_runner.py` (running on the Raspberry Pi) sequences the GPIO reset | |
| lines to enter UART bootloader mode, uploads the firmware binary, then streams | |
| raw UART bytes to stdout while scanning for the sentinel. It exits 0 (PASS) or | |
| 1 (FAIL/timeout). `test_runner.py` on the host SCP's the script to the Pi, | |
| streams the output back for detokenization and display, and reports the Pi's | |
| exit code to Bazel. | |
| Because the Pi is a shared fixture, `test_runner.py` holds an atomic noclobber | |
| lock file at `/tmp/ast1060_evb.lock` on the Pi for the duration of each test, | |
| preventing multiple users from driving the board over SSH simultaneously. The | |
| lock is touched every 10 seconds by a background thread and considered stale | |
| after 60 seconds of inactivity (e.g. after a crash). If the lock cannot be | |
| acquired within 120 seconds the run is aborted. | |
| ## Semihosting Migration | |
| This infrastructure previously used ARM semihosting to signal pass/fail. On | |
| real hardware with no attached debugger, a semihosting trap causes a HardFault, | |
| so hardware testing was impossible. Replacing semihosting with UART sentinels | |
| removed that constraint and enabled the Pi SSH test fixture. | |
| ## `uart_upload_test` Targets (removed) | |
| The five `*_uart_upload_test` targets that previously existed in these BUILD | |
| files have been removed. They used an earlier harness (`uart_upload_test.bzl`) | |
| that predated the `run_under` approach. The `system_image_test` targets cover | |
| both QEMU and hardware execution; no separate hardware-only test rule is needed. |