XTOS / OPEN SOURCE REAL-TIME SYSTEMOPEN SOURCE · 1.0.2 · PRERELEASE · IMAGES & SOURCE
DocsQuickstart

Quickstart

Download the v1.0.2 installer ISO or ARM64 QEMU bundle and follow Installation, or build matching source on Linux.

On this page

Build environment

For first use, download the OpenXTOS v1.0.2 x86_64 ISO or ARM64 QEMU bundle and follow Installation. The steps below describe source builds and QEMU for the same version; compile from source when modifying the system.

This first-run path assumes an x86_64 Linux host and Debian/Ubuntu apt package names. It boots a QEMU guest without writing the host boot disk. Linux 7.3.1 (mainline PREEMPT_RT) and BusyBox 1.37.0 sources are vendored. Networking is needed to install dependencies and obtain the repository, not to download these sources during the build. Reserve disk space for source, kernel output, rootfs, and images. Multiple architectures, an ISO, acceptance-test virtual disks, and corresponding-source archives need additional space; check df -h before building.

bash
sudo apt-get update
sudo apt-get install -y \
  bash git build-essential libc6-dev flex bison bc libssl-dev libelf-dev \
  cpio gzip rsync python3 kmod binutils file patch perl pkg-config \
  coreutils findutils grep sed diffutils qemu-system-x86

build-essential/libc6-dev supply the native C toolchain and static-link development files. flex, bison, bc, Perl, and OpenSSL/ELF development packages support kernel building; cpio/gzip pack initramfs; kmod supplies depmod; binutils supplies readelf; coreutils/findutils/grep/sed support scripts.

Install libncurses-dev additionally for manual menuconfig.

Build and QEMU run as a normal user; only apt installation needs sudo.

Host preflight: in particular, confirm GNU cpio supports --reproducible.
command -v gcc make cpio gzip depmod python3 readelf qemu-system-x86_64
cpio --help | grep -- --reproducible
df -h .

Get source

bash
git clone https://github.com/Aitaide/OpenXTOS.git
cd OpenXTOS
git checkout --detach c24e923717670c4724cdaf24c7c105caee8dc2fb
git rev-parse HEAD
git status --short
./scripts/prepare_linux.sh
./scripts/verify_source_tree.sh

Pinning the commit keeps these commands aligned with the documented sources; it does not require long-term work on detached HEAD. Create a branch from this baseline for development. prepare_linux.sh validates kernel/source-pin.json through scripts/kernel_source.py (version 7.3.1, mainline PREEMPT_RT, and the XTOS patch with its SHA-256); verify_source_tree.sh should report source_tree=pass. These check source prerequisites, not successful boot.

Build x86_64

bash
JOBS=$(nproc) ./scripts/build_system.sh

The script builds the kernel and modules, then static BusyBox, copies SDKs/tools/examples into .build/userspace-source for compilation, installs the rootfs and module dependency indexes, and packs initramfs. build_system.sh defaults JOBS to 2. nproc explicitly selects the visible CPU count, not a guarantee of sufficient memory. If compiler processes are killed by memory limits, lower JOBS to 2 or less and rebuild.

Host artifactPurpose
.build/images/xtos-bzImagex86_64 kernel image loaded by QEMU -kernel.
.build/images/xtos-rootfs.cpio.gzInitramfs containing static userland, modules, SDKs, and tests.
.build/images/kernel.configSnapshot of the final kernel configuration for this build.
.build/rootfs/Unpacked root filesystem for inspecting installed content.

A successful build ends with system_build=pass.

To use a custom directory, export an absolute path such as BUILD_ROOT="$PWD/.build-demo" and keep that value for every subsequent build, verify, and run call; otherwise verification returns to the default .build.

Do not treat generated files under .build as editable source.

Run self-test

bash
QEMU_TIMEOUT=180 ./scripts/verify_system.sh

This command boots a pc virtual machine with 512 MiB memory, 2 vCPUs, and a ttyS0 serial console, passing xtos.selftest=1 to /init.

The guest confirms realtime=1 with xtos-rt-status, checks configuration and modules; runs test_rt, test_spsc, test_signal, the CSV pipeline, and a 20-iteration signal benchmark; then powers off.

Host output is saved to .build/system-qemu.log.

Markers to inspect on success; not a complete transcript of a particular run.
system_qemu=pass
realtime=1
xtos_modules=pass
guest_userspace=pass
XTOS_SYSTEM_TEST=PASS

Success requires verify_system.sh to exit 0, QEMU to exit normally, an exact XTOS_SYSTEM_TEST=PASS line in the log, and no XTOS_SYSTEM_TEST=FAIL or Kernel panic. system_build=pass, a Linux boot banner, or realtime=1 alone does not replace these conditions.

The default timeout is 120 seconds; this page explicitly uses 180.

A timeout calls for log inspection, not a pass declaration.

Interactive checks

Run on the host; this starts x86_64 QEMU, not a hardware installation.
./scripts/run_system.sh

Without the self-test parameter, /init displays the local development console and enters a BusyBox shell. After the # prompt appears, execute the following commands in the guest. Do not run these guest paths in the host shell or mistake the post-self-test shutdown state for an interactive terminal.

Execute inside the x86_64 guest shell.
uname -r
/usr/bin/xtos-rt-status
zcat /proc/config.gz | grep '^CONFIG_PREEMPT_RT='
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/usr/libexec/xtos/test_rt
/usr/libexec/xtos/test_spsc
/usr/libexec/xtos/test_signal
xtos-eeg-pipeline --input /usr/share/xtos/fixtures/valid.csv
xtos-signal-benchmark --iterations 20 --output /run/signal-benchmark.json
cat /run/signal-benchmark.json

uname -r should report a 7.3.1-series release string (follow the kernelrelease your build actually produces), xtos-rt-status should return 1, and the CSV pipeline should return status="ok". Timings vary with the host and QEMU environment; they need not match website examples. Use poweroff -f in the guest to shut down, or QEMU Ctrl+a followed by x to exit. /run outputs are in memory and are not automatically persisted on shutdown.

Cross architectures

After x86_64, cross-build the same public sources. Install the additional packages below and build and verify each architecture sequentially. Install libc6-dev-riscv64-cross explicitly: GCC commonly lists it only as Recommends, so disabling recommended packages can omit static libc and development headers and break BusyBox or static test links. libc6-dev-arm64-cross is also listed explicitly for ARM64.

bash
sudo apt-get install -y \
  crossbuild-essential-arm64 libc6-dev-arm64-cross qemu-system-arm \
  gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu \
  libc6-dev-riscv64-cross qemu-system-misc opensbi
bash
JOBS=$(nproc) ./scripts/build_system_arm64.sh
QEMU_TIMEOUT=180 ./scripts/verify_system_arm64.sh
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh

JOBS=$(nproc) ./scripts/build_system_riscv64.sh
QEMU_TIMEOUT=300 ./scripts/verify_system_riscv64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh

The Debian/Ubuntu RISC-V QEMU installation entry is generally qemu-system-misc, not an apt package named qemu-system-riscv64; newer Debian pulls in qemu-system-riscv as a dependency. Scripts require /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin to exist. Cross-architecture guest checks require realtime=1, xtos_modules=pass, guest_test_rt/test_spsc/test_signal=pass, guest_userspace=pass, and XTOS_GUEST_CHECK=DONE. See Build and Run for details.

Limits and source

Command references at commit c24e923717670c4724cdaf24c7c105caee8dc2fb: scripts/prepare_linux.sh, scripts/verify_source_tree.sh, scripts/build_system.sh, scripts/run_system.sh, scripts/verify_system.sh, system/rootfs/init, system/rootfs/usr/bin/xtos-selftest, and architecture-specific build_system/verify_system/verify_guest scripts. Dependencies cover the tools those scripts call; RISC-V static libc comes from libc6-dev-riscv64-cross.