Source tree

Directory roles, configuration files, build artifacts, and guest paths.

On this page

Directory roles

All paths below are relative to the OpenXTOS repository root. kernel/linux and userspace/busybox contain upstream sources and are large.

A useful first pass follows scripts→system→sdk/tools→XTOS kernel files rather than reading every Linux file.

The public tree includes C tests required for system builds, not the private development tree’s complete tests, plans, or release tooling.

Path	Responsibility and reading entry point
kernel/	Linux 6.6.0-rt15, PREEMPT_RT and XTOS integration patches, and xtos_defconfig. Read the fragment before the XTOS files it enables.
userspace/busybox/	Upstream BusyBox 1.37.0 sources; system configuration lives under system/, not sdk/.
sdk/	Headers, implementations, Makefiles, and version headers for three user-space libraries; rt and signal include C tests compiled into the guest.
system/	busybox_defconfig, rootfs skeleton, x86 /init, self-test, and cross-architecture guest-check.
tools/	Three functional tools—xtos-eeg-pipeline, xtos-eeg-replay, and xtos-signal-benchmark—and fixtures.
examples/	bci_test.c acquisition-session example; it is not a fake-device simulator or hardware validation report.
scripts/	System/kernel builders, QEMU checks, cross-compilation, source checks, ABI checks, and reproducible-build environment.
README.md, VERSION, LICENSE-NOTICE	Project entry point, public 0.9.0 version metadata, and license boundaries.

Kernel entry points

kernel/patches/preempt-rt-6.6-rt15.patch and kernel/patches/xtos-linux-6.6.patch retain the integration patches; kernel/linux already contains their contents. scripts/prepare_linux.sh checks the Linux version, the -rt15 value in localversion-rt, and XTOS files.

It neither downloads sources nor reapplies patches; REFRESH_BUNDLED_KERNEL=1 is explicitly rejected.

Source entry point	Purpose
kernel/linux/kernel/sched/xtos_sched.c	Optional priority-queue helper; not a Linux sched_class.
kernel/linux/kernel/sched/xtos/Kconfig	Kconfig entry for XTOS scheduling support, enabled by the fragment.
kernel/linux/drivers/xtos/bci/	Character-device core, ring buffer, and devices/openbci_cyton.c driver.
kernel/linux/include/uapi/linux/xtos_bci.h	Integer ioctl structures and command numbers exposed to user space.
kernel/linux/include/linux/xtos.h, xtos_queue.h, xtos_bci.h	Kernel helper types, queue, and BCI framework declarations; not application syscall headers.

The build directory’s .config and include/config/auto.conf contain resolved configuration. CONFIG_XTOS_SCHED=y and CONFIG_XTOS_BCI=m in kernel/xtos_defconfig are default requests. Builders check required options after olddefconfig; ARM/RISC-V initialization checks run only when .config is initially absent. After configuration changes, retain the final configuration and revalidate rather than trusting an old incremental directory.

SDKs and tools

Entry point	Boundary to inspect
sdk/libxtos-rt/src/rt.c, src/spsc.c	Linux scheduling and mlock wrappers, user-space SPSC; tests/test_rt.c and tests/test_spsc.c are public guest tests.
sdk/libxtos-signal/src/signal.c	User-space FFT, filter, and feature APIs; tests/test_signal.c supplies the guest test.
sdk/libxtos-bci/src/session.c	open/read/ioctl/mmap session wrappers; this public commit has no BCI tests directory to rely on, and locally added tests are not used.
tools/xtos-eeg-pipeline/pipeline.c	CSV→SPSC→optional bandpass→JSON/filtered CSV, without kernel BCI acquisition.
tools/xtos-eeg-replay/replay.py	Host Python CSV format and interval validation; not a kernel device driver.
tools/xtos-signal-benchmark/benchmark.c	Generates signals and times FFT, bandpass, SSVEP, and P300; results depend on the execution environment.

Run the public Python replay validator on the host; no guest or real device is required.

python3 tools/xtos-eeg-replay/replay.py \
  --input tools/xtos-eeg-replay/fixtures/fixture.csv --check

Sources and artifacts

BUILD_ROOT defaults to the repository’s .build. x86_64 uses kernel-build, busybox-build, userspace-source, rootfs, and images: SDKs, tools, and examples are copied into userspace-source before compilation so user-space artifacts are not generated in source directories.

ARM64/RISC-V64 kernel and BusyBox builds also use O= output directories, but SDKs run make clean/build inside the source tree and leave libraries for the current architecture.

Do not run two cross builds concurrently.

Role	x86_64	ARM64 / RISC-V64
Editable source	system/rootfs/init, sdk/, tools/	Same sources; boot inittab is generated by cross builders.
Host rootfs output	.build/rootfs/	.build/rootfs-arm64/, .build/rootfs-riscv64/
Guest test location	/usr/libexec/xtos/test_*	/bin/test_rt, /bin/test_spsc, /bin/test_signal
Normal boot /init	The system/rootfs/init shell script.	A link to sbin/init, used with /etc/inittab.

Editing .build/rootfs changes generated output and may be overwritten by the next build. Persistent system changes belong in source files or builders. Guest /run/pipeline.json and /run/signal-benchmark.json live in the in-memory initramfs and are not automatically saved to the host on shutdown; host QEMU logs are a separate output.

Data formats

CSV fixtures have three columns: nanosecond timestamp, channel 0 nanovolts, and channel 1 nanovolts; two channels at 250 Hz imply a 4000000 ns frame interval. The user-space pipeline parses into int32 nanovolts and explicitly converts to double for bandpass processing. The kernel Cyton path instead turns serial bytes into 8-channel s32 nanovolts stored in the kernel buffer. Public sources do not connect these paths automatically.

For hardware issues, follow openbci_cyton.c→xtos_bci_buffer.c→xtos_bci_core.c→bci_uapi.h/session.c. For fixture issues, follow fixtures/valid.csv→pipeline.c→spsc.c/signal.c. This prevents mistaking strict CSV timestamp validation for the same timestamp semantics already being supplied by the driver.

Version check

bash

git rev-parse HEAD
git status --short
git show HEAD:scripts/build_system.sh
git show HEAD:scripts/build_system_arm64.sh
git show HEAD:scripts/build_system_riscv64.sh
git show HEAD:sdk/libxtos-bci/src/session.c
./scripts/verify_source_tree.sh

git show HEAD:path reads committed content, excluding local worktree changes from the public baseline. verify_source_tree.sh checks the Linux version, rt15 marker, required XTOS files, and source-tree contamination.

It is not a byte-for-byte comparison of all files against the commit and cannot replace git status.

Distinguish ignored library build artifacts from committed sources when interpreting the scan.

Source references at commit dd313955ad57542bcd2af8827157d1bbd0cf5e83: README.md, scripts/prepare_linux.sh, scripts/verify_source_tree.sh, scripts/build_system.sh, scripts/build_system_arm64.sh, scripts/build_system_riscv64.sh, system/rootfs/init, system/rootfs/xtos-guest-check, tools/xtos-eeg-pipeline/Makefile and pipeline.c, and tools/xtos-eeg-replay/replay.py.