Run

Boot with QEMU, run self-tests, and inspect logs.

On this page

Check scope

Level	Entry point	What it establishes	What it does not establish
Build	build_system*.sh	Images, modules, and user-space artifacts are produced.	That the kernel boots or tests were executed.
Interactive boot	run_system.sh or the QEMU commands on this page.	The selected images reach a development shell.	That full module and SDK checks passed.
Automated system checks	x86 verify_system.sh; ARM/RISC-V verify_system_*.	x86 includes self-tests; basic cross checks mainly inspect boot text.	That cross-architecture boot PASSED equals all guest tests passing.
Cross-architecture guest checks	verify_guest_arm64.sh, verify_guest_riscv64.sh	Markers for runtime flags, configuration, modules, and rt/spsc/signal tests.	Real-device acquisition, hardware end-to-end latency, or model accuracy.

run_system.sh actually execs qemu-system-x86_64. It is not a direct hardware boot script and neither installs a bootloader nor flashes a disk. Every command requires the corresponding architecture build to be completed first; retain any custom BUILD_ROOT for run and verification commands.

x86_64 boot

bash

./scripts/run_system.sh

The script fixes -machine pc, -cpu max, -m 512, and -smp 2; loads images/xtos-bzImage and images/xtos-rootfs.cpio.gz; and uses console=ttyS0 rdinit=/init loglevel=4, -nographic, and -no-reboot. Extra arguments are forwarded through the script’s trailing "$@", but it exposes no QEMU_MEM/QEMU_SMP environment variables. Understand QEMU arguments before adjusting them; cross-verifier environment variables are not global options.

Guest shell: a manually invoked self-test does not make the outer /init automatically print XTOS_SYSTEM_TEST=PASS.

uname -r
cat /sys/kernel/realtime
cat /proc/cmdline
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/usr/bin/xtos-selftest

Manual xtos-selftest uses set -eu and exits nonzero on failure.

It checks runtime/configuration, loads three modules, runs three SDK tests, the CSV pipeline, and a signal benchmark; on success it prints xtos_modules=pass and guest_userspace=pass.

XTOS_SYSTEM_TEST=PASS is the final marker printed by /init in its automated branch, not text produced by every manual invocation.

Exit with poweroff -f in the guest or Ctrl+a followed by x in QEMU. x86 /init restarts an exited shell, so exit alone does not shut down the virtual machine. The development console is a local root shell with no default network service, not a hardened multi-user production system.

x86_64 self-test

bash

QEMU_TIMEOUT=180 ./scripts/verify_system.sh

verify_system.sh requires nonempty kernel, initramfs, and kernel.config files, starts QEMU through timeout --foreground, adds panic=1 xtos.selftest=1, and saves serial output to system-qemu.log. /init prints PASS or FAIL after the guest checks, then syncs and powers off. This flow leaves no shell for further commands.

QEMU exit status is 0; timeout, abnormal exit, or host startup failure cannot pass.
An exact XTOS_SYSTEM_TEST=PASS line exists after removing serial CR characters.
The log contains neither XTOS_SYSTEM_TEST=FAIL nor Kernel panic, and the host command exits 0.

The self-test writes CSV JSON to /run/pipeline.json and the benchmark to /run/signal-benchmark.json. The former is printed into the serial log; the latter is only checked for nonempty existence and is not automatically copied to the host in full. To preserve benchmark contents, display and record them in an interactive session. Fixture results and benchmark timings are not hardware acquisition reports.

Cross-architecture self-test

bash

QEMU_TIMEOUT=180 ./scripts/verify_system_arm64.sh
QEMU_TIMEOUT=300 QEMU_MEM=2G QEMU_SMP=2 ./scripts/verify_guest_arm64.sh

QEMU_TIMEOUT=300 ./scripts/verify_system_riscv64.sh
QEMU_TIMEOUT=360 QEMU_MEM=2G QEMU_SMP=2 ./scripts/verify_guest_riscv64.sh

verify_guest_* copies the normal rootfs, replaces /init with system/rootfs/xtos-guest-check in a validation-only initramfs, and boots the matching QEMU.

ARM64 uses virt/cortex-a57 and ttyAMA0; RISC-V uses virt/rv64, ttyS0, and the fixed OpenSBI firmware path.

Default QEMU_TIMEOUT is 300/360 seconds respectively, QEMU_MEM is 2G, and QEMU_SMP is 2.

The normal boot image is not changed by replacing /init in the validation copy.

Required key markers; RISC-V additionally needs OpenSBI, and neither guest may show Kernel panic.

XTOS_GUEST_CHECK=START
realtime=1
preempt_rt=y
xtos_sched=y
module_xtos_bci_core=ok
module_xtos_bci_buffer=ok
module_openbci_cyton=ok
xtos_modules=pass
guest_test_rt=pass
guest_test_spsc=pass
guest_test_signal=pass
guest_userspace=pass
XTOS_GUEST_CHECK=DONE

The strict parsers contain 14 ARM64 checks and 15 RISC-V64 checks, with the latter adding OpenSBI.

Inspect every marker rather than only DONE. test_rt tests scheduling and memory-lock permission-failure boundaries and accepts specified errno values, so guest_test_rt=pass does not prove every thread successfully switched to SCHED_FIFO.

Cross guest checks do not cover the x86 EEG pipeline and benchmark.

Cross-architecture shell

The public baseline only supplies run_system.sh for x86_64. For ARM64/RISC-V64 interactive mode, boot the normal images directly with QEMU. Do not use guestcheck initramfs files, which run tests and power off. The commands below use the default build directory; set B to the same absolute custom BUILD_ROOT if applicable.

Host: ARM64 normal boot images.

B="$PWD/.build"
qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2G -smp 2 \
  -kernel "$B/kernel-install-arm64/Image" \
  -initrd "$B/initramfs-arm64.cpio.gz" \
  -append 'console=ttyAMA0 panic=1 init=/sbin/init' \
  -nographic -no-reboot

Host: RISC-V64 normal boot images.

B="$PWD/.build"
qemu-system-riscv64 -machine virt -cpu rv64 -m 2G -smp 2 \
  -bios /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin \
  -kernel "$B/kernel-install-riscv64/Image" \
  -initrd "$B/initramfs-riscv64.cpio.gz" \
  -append 'console=ttyS0 panic=1 init=/sbin/init' \
  -nographic -no-reboot

Guest: cross-architecture tests live under /bin, not /usr/libexec/xtos.

uname -m
uname -r
cat /sys/kernel/realtime
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/bin/test_rt
/bin/test_spsc
/bin/test_signal
poweroff -f

A can’t access tty or job-control warning can come from BusyBox console setup; basic verifiers treat this as optional shell text. Confirm actual command execution, runtime flags, and full guest checks before deciding whether boot succeeded. Do not change kernel configuration or declare system failure based on that warning alone.

Logs and diagnosis

Check	Log relative to BUILD_ROOT
x86_64 system self-test	system-qemu.log
ARM64 basic boot	qemu-arm64-output.txt
ARM64 guest checks	qemu-arm64-guestcheck-output.txt
RISC-V64 basic boot	qemu-riscv64-output.txt
RISC-V64 guest checks	qemu-riscv64-guestcheck-output.txt

Missing images: confirm BUILD_ROOT and architecture, and inspect the Image/bzImage and initramfs paths in Build rather than copying another architecture’s image.
Missing OpenSBI: confirm the fixed firmware file exists and install the distribution opensbi/QEMU packages. Scripts expose no OPENSBI path-override environment parameter.
Module fail: use actual module names xtos_bci_core, xtos_bci_buffer, and openbci_cyton; ensure /lib/modules/<uname -r> matches the running kernel and inspect dmesg.
guest_test_*=missing: inspect cross-build compiler warnings and static libc dependencies. Do not skip the check and claim completion.
realtime is not 1: inspect final .config, /proc/config.gz, and the loaded image rather than searching only for PREEMPT_RT in the banner; a 6.6-rt banner may display only PREEMPT.

Hardware scope

QEMU boot, module loading, user-space tests, and fixture pipelines are not real-hardware end-to-end validation. OpenBCI needs separate checks of device tree, serial transport, packet layout, units, SDK raw conversion, timestamps, loss, and overruns. The public baseline’s float-read gap precludes claiming a correct direct hardware-to-DSP path. Hardware performance, board bring-up, model results, and feedback safety each need independent tests and evidence.

Source references at commit dd313955ad57542bcd2af8827157d1bbd0cf5e83: scripts/run_system.sh, scripts/verify_system.sh, scripts/verify_system_arm64.sh, scripts/verify_system_riscv64.sh, scripts/verify_guest_arm64.sh, scripts/verify_guest_riscv64.sh, system/rootfs/init, system/rootfs/usr/bin/xtos-selftest, system/rootfs/xtos-guest-check, sdk/libxtos-rt/tests/test_rt.c, examples/bci_test.c, and sdk/libxtos-bci/src/session.c.