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 rt/spsc/signal guest C tests, a BCI sample-conversion test, and installer build/acceptance scripts. Use only files committed in this tag.
| Path | Responsibility and reading entry point |
|---|---|
| kernel/ | Linux 7.3.1, mainline PREEMPT_RT and the XTOS integration patch (kernel/patches/xtos-linux-7.3.1.patch), 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, core rootfs, self-test, and cross-architecture guest-check; baremetal/ contains ISO/persistent-root startup and the manual installer. |
| 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/public ISO builders, QEMU and installation checks, cross-compilation, source/ABI checks, and identity/distribution-material generation. |
| README.md, VERSION, LICENSE | Project entry point, public 1.0.2 version metadata, and license boundaries. |
Kernel entry points
kernel/source-pin.json pins the Linux 7.3.1 upstream archive, mainline PREEMPT_RT configuration, and SHA-256 of kernel/patches/xtos-linux-7.3.1.patch. kernel/linux is versioned; mainline real-time support needs no separate RT patch.
scripts/prepare_linux.sh calls scripts/kernel_source.py to validate the source pin, Linux version, mainline RT definitions, required XTOS files, and patch hash; it neither downloads 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 | Sessions, configuration readback, int32 nV→float µV conversion, and versioned views; make test runs test_samples, test_snapshot, test_snapshot_uapi, test_config, and test_frame, not physical-device acceptance. |
| 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. |
python3 tools/xtos-eeg-replay/replay.py \
--input tools/xtos-eeg-replay/fixtures/fixture.csv --checkSources 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
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.shgit show HEAD:path reads committed content, excluding local worktree changes from the public baseline.
verify_source_tree.sh uses scripts/kernel_source.py to check the source pin, mainline PREEMPT_RT, XTOS files, and patch hash, then scans for source contamination. It does not compare every byte with the commit and cannot replace git status.
Distinguish ignored library build artifacts from committed sources when interpreting the scan.
Source references at commit c24e923717670c4724cdaf24c7c105caee8dc2fb: 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.