Contributing

Create a branch, change source, run checks, and submit a pull request.

On this page

Fork and branch

Fork Aitaide/OpenXTOS, clone the fork as origin, and add the public repository as upstream. Keep one issue per feature branch. Do not commit generated SDK libraries, QEMU logs, or .build output.

Host: replace YOUR-ACCOUNT with your account. This does not commit or create a PR.

git clone https://github.com/YOUR-ACCOUNT/OpenXTOS.git
cd OpenXTOS
git remote add upstream https://github.com/Aitaide/OpenXTOS.git
git fetch upstream
git switch -c fix/guest-validation upstream/main
git rev-parse HEAD
git status --short

SDKs, signal tools, build scripts, verification, kernel integration, and documentation can be focused contributions.
Reproduce the old behavior before describing the trigger and corrected behavior.
Keep commits focused; prefixes such as feat:, fix:, and docs: can identify the change type.

Build baseline

Use a Linux host with about 10 GB free disk. Linux and BusyBox sources are vendored. Before editing, build unmodified source and run the x86_64 QEMU self-test.

Host: Debian/Ubuntu baseline; a slow host can use a 300-second budget.

sudo apt-get update
sudo apt-get install -y build-essential flex bison bc libssl-dev libelf-dev libc6-dev python3 cpio gzip rsync kmod file qemu-system-x86
. ./scripts/reproducible_env.sh
JOBS=$(nproc) ./scripts/build_system.sh
QEMU_TIMEOUT=180 ./scripts/verify_system.sh

reproducible_env.sh uses the HEAD commit time or SOURCE_DATE_EPOCH and sets KBUILD_BUILD_VERSION, USER, HOST, TIMESTAMP, LC_ALL=C, and TZ=UTC. It prevents current time, hostname, and absolute paths from entering artifacts.

Kernel and UAPI

kernel/linux/ is the Linux 6.6.0 tree with PREEMPT_RT rt15 and XTOS integrated. Kernel component changes must stay synchronized with kernel/patches/xtos-linux-6.6.patch. Configuration changes must be checked against kernel/xtos_defconfig, olddefconfig, and the final configuration.

Boundary	Rule
Kernel and drivers	ARM64/RISC-V use -mgeneral-regs-only; do not add floating-point types to kernel drivers or UAPI.
UAPI sync	Check kernel/linux/include/uapi/linux/xtos_bci.h, sdk/libxtos-bci/include/xtos/bci_uapi.h, and the integration patch together.
Integers and units	input_range_mv is __u32/uint32_t in mV; CHECK_IMP is 32 __u32/uint32_t values in kOhm.
ioctl	Check request numbers, layout, field widths, and semantics; equal encoded size can still change semantics.
New user-space files	New files in sdk/, tools/, system/, scripts/, and examples/ should carry SPDX-License-Identifier: Apache-2.0.
GPL files	Follow GPL-2.0 and existing SPDX notices in kernel/linux/, kernel/patches/, and userspace/busybox/.

New XTOS user-space C file; do not replace an existing GPL notice.

/* SPDX-License-Identifier: Apache-2.0 */

The integer-only UAPI rule applies to the kernel boundary, not to double in user-space signal algorithms. LICENSE-NOTICE separately lists kernel/xtos_defconfig as Apache-2.0; do not apply the kernel/linux/ GPL rule to it.

ABI versions

When changing public headers under sdk/<lib>/include/, update the version header and Makefile according to compatibility.

The current baseline version for all three libraries is 1.0.0.

Version headers maintain MAJOR, MINOR, PATCH, and VERSION_STRING; LIB_MAJOR/LIB_MINOR determine filename and SONAME.

Change	Version	Check
Removed symbol, signature, or layout break	Increment MAJOR.	Version header and matching Makefile.
Compatible symbol added	Increment MINOR.	libxtos-*.so.MAJOR.MINOR.
Behavior fix	Increment PATCH.	VERSION_STRING matches PATCH.
Load identity	SONAME is libxtos-*.so.MAJOR.	check_abi.sh compares SONAME, filename, and version header.

Host: build native SDKs first; expect abi_check=pass.

make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all
./scripts/check_abi.sh

Pre-submit validation

Before submission, complete the x86 build, QEMU self-test, and ABI check. Changes to UAPI, kernel, toolchain, or cross-architecture rootfs also need the matching cross build and strict guest check. A CI configuration alone does not constitute a passing result.

Host: run native SDK, ABI, and source checks.

. ./scripts/reproducible_env.sh
JOBS=$(nproc) ./scripts/build_system.sh
QEMU_TIMEOUT=300 ./scripts/verify_system.sh
make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all
./scripts/check_abi.sh
./scripts/verify_source_tree.sh
git diff --check
git status --short

Host: use separate source copies for cross-architecture changes and run architectures serially.

sudo apt-get install -y crossbuild-essential-arm64 libc6-dev-arm64-cross qemu-system-arm
JOBS=2 ./scripts/build_system_arm64.sh
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh

sudo apt-get install -y gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu libc6-dev-riscv64-cross qemu-system-misc opensbi
JOBS=2 ./scripts/build_system_riscv64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh

verify_source_tree.sh checks the Linux version, rt15, required XTOS source, and generated-file contamination.

For generated_or_dependency or generated_in_bundled_kernel, use separate output directories.

The public version has no scripts/test.sh and no libxtos-bci test target.

Commits and pull requests

Use git diff and git diff --check; stage only related source, headers, patches, or documentation.
Describe the trigger, old behavior, corrected behavior, and compatibility impact.
Push the feature branch and open a Pull Request against Aitaide/OpenXTOS main.
List commands actually run, statuses, logs, and markers; distinguish failed, not run, and no hardware.
For public interfaces, include version changes; for kernel changes, include patch synchronization and cross-validation results.

Host: review scope before staging; do not collect unknown artifacts with git add .

git diff --check
git diff --stat
git diff
git status --short

An issue report includes host OS, toolchain, source commit, architecture, exact commands, and full errors. Attach QEMU serial logs for boot failures. For device failures, report node, permissions, driver binding, and physical-hardware status.

Source: CONTRIBUTING.md, README.md, .github/workflows/ci.yml, scripts/reproducible_env.sh, scripts/check_abi.sh, scripts/verify_source_tree.sh, the three SDK Makefiles/version headers, and kernel and SDK BCI UAPI.