SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsfw-emulation

fw-emulation

Testing & quality

View repository

Updated 10-16 08:44

About this skill

Boardless emulation and host-level verification (fw-emulation)

Two levels of boardless verification, with different evidence strength and different conclusions that can be claimed:Host-level unit testsprove logic,system-level QEMU boot smokeproves "the image can boot". Neither level proves hardware behavior—emulation passing = Build/Boot Verification Only, which does not equal hardware being usable.

Determine Task Type

  1. No board: first verify whether the OpenWrt image can boot → Workflow A (QEMU boot smoke), see details in qemu-openwrt。
  2. No device: first verify business logic(OpenWrt user-space scripts / ESP32 firmware logic layer) → Workflow B (host-level mock), see details in host-mocking。
  3. "Is Wi-Fi/eth behavior in QEMU consistent with real hardware?" → refusal stance:inconsistent; peripheral-level issues route to fw-hil-testing。
  4. ESP32 boardless emulation → honest boundary (see Contracts item 4): host-level logic testing can be done; peripheral-level emulation is not promised.

Prerequisites / Preflight

command -v qemu-system-aarch64 qemu-system-x86_64 || true   # QEMU 在不在（macOS 可 brew 安装）
command -v gunzip file || true
ls <your-image>.img.gz 2>/dev/null                          # 待验证镜像（官方下载或自建产物）
  1. Image to be verified comes from one of two sources: the official download site's current-version combined-efi image, or an artifact you built yourself with IB (underbin/targets/armsr/armv8/ ).
  2. UEFI firmware files (edk2's QEMU_EFI.fd family) are located according to distribution/installation method—paths vary by platform, verify at runtime。
  3. Confirm "what is to be proven": boots (this Skill) ≠ configured correctly (uci semantics belong to the runtime configuration skill) ≠ hardware usable (HIL).

Offline Baseline

  • OpenWrt baseline = 25.12.5(read through 2026-09-02, no auto-update); image download paths are based onthe current-version official download site directory, do not recite filenames from memory.
  • This package's QEMU emulation capability for ESP32is not verified: always mark Pending verification, do not describe its capability details.
  • For subsequent version behavior changes, defer to official sources; do not assert from memory.

Contracts (completion honesty contract)

  1. Evidence layering: host unit test < system-level boot smoke < real-hardware HIL. Reports must carry a layer label and must not claim beyond the level.
  2. Emulation passing = Build/Boot Verification Only: reaching a shell prompt in QEMU only proves the image can boot and basic user space is alive; it is forbidden to phrase it as "can be used on real hardware".
  3. Peripheral behavior is out of emulation scope: QEMU emulates the architecture layer such as CPU/memory/block devices; wireless, Ethernet PHY/switch, RF, timing, and eMMC are not truly emulated—peripheral issues always go to HIL.
  4. ESP32 QEMU support is limited(chip/peripheral coverage incomplete): this package marks Pending verification; real-hardware behavior acceptance routes to fw-hil-testing. For host-level alternative paths see host-mocking。
  5. fixture/golden dataindependently generated, not copied from the implementation under test (otherwise the test only parrots the implementation and cannot catch errors).

Capability Boundaries + Hand-off

Not doing: image building (openwrt-image-build), the Linux-root remake pipeline itself (macOS cannot directly run remake—environment constraints route to openwrt-amlogic-remake), flashing and real-hardware acceptance (fw-hil-testing), release artifact gating (fw-release-gate）。

User Intent Skill
Build/customize OpenWrt images, produce combined-efi artifacts openwrt-image-build
Box (N1/Amlogic) remake pipeline and its runtime environment constraints openwrt-amlogic-remake
Real-device acceptance after QEMU smoke passes (Wi-Fi/eth/eMMC/long-run) fw-hil-testing
Cross toolchain hosting and version anchoring fw-toolchain
Artifact naming/checksum/release process fw-release-gate

Workflow A — OpenWrt image QEMU boot smoke (without N1 prior image)

  1. Get the image: official download site releases/<版本>/targets/armsr/armv8/ under the combined-efi image (the filename is subject to the download site directory of the current release), or a self-built artifact bin/targets/armsr/armv8/*combined-efi*.img.gz。
  2. Extract：gunzip -k <image>.img.gz to get .img。
  3. Locate UEFI firmware：edk2 QEMU_EFI.fd(the install path varies by platform; verify at runtime).
  4. Boot(armsr/armv8 baseline form; for parameter semantics see qemu-openwrt）：
qemu-system-aarch64 -M virt -cpu cortex-a57 -m 512M -nographic \
  -bios /path/to/QEMU_EFI.fd \
  -drive file=<image>.img,format=raw,if=none,id=hd0 \
  -device virtio-blk-device,drive=hd0
  1. Smoke criteria: the serial output shows the OpenWrt boot log up to the shell prompt; basic commands can be executed at the prompt (such as uname -a). Archive the boot log as evidence.
  2. Reporting wording: write "Boot Verification Only: the image can boot to a shell in QEMU (virt/AArch64)"; real-device issues such as Wi-Fi/eth/eMMC/performance → fw-hil-testing。
  3. For the one-line version of the x86/64 image and common failure troubleshooting, see qemu-openwrt。

Workflow B — Host-level unit tests (logic-layer mocks)

OpenWrt user-space scripts (env-var fixture injection pattern)：

  1. Make the script under test support "root path/data source environment variable overrides" (the pattern is the TINYNAS_SYSINFO_ROOT / TINYNAS_SHARE_ROOT type of prefix variables in the actual project—pattern reference only, real example tests/run-lint.sh + test-machine-id.sh）。
  2. The test script injects fake data sources into the fixture directory, runs the script under test, and asserts the output: golden expected valueindependently generated(note the generation date and algorithm), format assertions, plus negative test cases (path traversal/bad input must be rejected).
  3. Static gates go side by side into the same entry point:sh -n full syntax check, uci-defaults last line exit 0, prohibition of hardcoding /etc/rc.d/ and other project rules.
  4. Details and skeleton template → host-mocking。

ESP32 firmware logic layer：

  1. Compile the business logic into ahost-compilable unit: abstract the HAL interface, tests inject self-written mocks; peripheral timing is out of assertion scope.
  2. A mock-type component exists in the component registry (search the components registry with the keyword "mock";existence and maintenance status verified at runtime)—use it only if found and usable; if not found, use a self-made mock, do not wait and do not speculate.
  3. All host tests passing still only proves the logic; on-board behavior → fw-hil-testing。

Validation Gates

  1. Workflow A: the boot log archive contains evidence of "booting to the shell prompt"; the report carries the Boot Verification Only annotation.
  2. Workflow B: the host test entry exits 0 with all green; at least 1 negative test case (traversal/bad input) and it passes; golden values note how they were independently generated.
  3. Self-check every conclusion with three questions: which layer does it prove? Which layer is missing? To whom is the missing layer routed (HIL / runtime configuration skill)?
  4. Any final conclusion without real-device evidence must be supplemented with Pending HIL。

Pitfalls

  1. Do notreport a passing QEMU run as "the image is usable on the device"—that is a HIL conclusion, not this Skill's.
  2. Do notuse QEMU to verify/evaluate Wi-Fi, eth throughput, RF, timing, or eMMC behavior—the emulator does not cover them, and the answer is inconsistent.
  3. Do notCarry the official image file names — subject to the version directory on the download site (may change after the baseline date 2026-09-02).
  4. Do notlet the host assert the duplication implementation logic (golden values must be generated independently), otherwise the tests will always be green and always useless.
  5. Do notpromise peripheral-level emulation for ESP32 — support is limited, mark Pending verification, and use HIL on real hardware.
  6. Do nothardcode fixture injection variables into the production path of the script under test — default behavior must match real hardware, injection is only for testing.

Official Sources

Privacy

This Skill only operates on local images, local QEMU, and local test data; it does not collect or send user data externally; real keys/passwords/device serial numbers must not be placed in fixtures, use explicitly constructed fake data; access to official links is subject to the user's environment network policy.