Contributing
Β§1How this project works
Rux is developed by multiple AI agents in parallel β one worktree per task β while humans set goals, review and hold merge authority. Two constitutional principles:
- 100% external compatibility: full POSIX semantics + an ABI aligned with Linux (syscall numbers, ELF/auxv, futex, the ext4 on-disk format, the procfs layout). Any upstream software runs unmodified β the first constraint on every decision.
- Internal freedom, registered divergences: an internal divergence survives only behind the triple gate β external compatibility intact, affected LTP families green, zero upstream breakage β and is registered in
docs/architecture/design-divergences.md(D-numbered, 19 entries). Example: a single global run queue instead of per-CPU queues + balancing.
Β§2The standard development flow
- Create the task's worktree under
/home/william/rux-agents/<name>/(git worktree add) β never develop in the main repository. - Build the kernel in place; commit fixes on a branch with English commit messages.
- Pass the merge gates locally (Β§3) before review.
- The main session cherry-picks into main β builds β smoke-boots (push only if it reaches the login screen) β pushes.
- Merges touching the same files (e.g. the virtio completion path) need semantic reconciliation, not mechanical conflict resolution.
Five background agents run concurrently by default; the quota-death recovery flow: inventory each worktree's uncommitted work/unmerged branches β land them (build + smoke first) β clean up orphaned QEMUs by PID β restore the full queue.
Β§3The merge gate (binding for all kernel-code changes)
Every merge is reviewed on two dimensions: functional correctness and performance. A functionally correct change that regresses performance does not merge until fixed or justified with numbers.
- Dual-arch build:
PLATFORM=x86_64 make build, thenrm build/.config && make buildβ both rc=0. - riscv64 regression boot: scripted serial on the minimal rootfs (cd/proc, rc=0, zero panics).
- The full suite: riscv64
make testall green. - The performance gate: in-tree debug tooling (syscost / census probes / pbench) against
docs/development/perf-gate-baseline.md.
Performance-gate tiers
| Tier | Applies to | Extra requirement |
|---|---|---|
| Tier 1 | all kernel changes | one quiet syscost boot: census in band, ticks β₯99.5/s, zero new panic/OOM classes, syscall volume Β±10%, per-op averages Β±20% or better |
| Tier 2 | hot paths: mm/ sched/ fs/ ipc/ binder/ timer/ arch trap | plus one pbench boot: P1βP7 medians within Β±20% or better |
| Tier 3 | allocator or IRQ paths | plus an IF=0 measurement (the EFLAGS-pair probe) |
Notes: the census band = TERM-DESCHED 8Β±2, WAKE-REFUSED 32Β±4, no grid strands; per-op averages = read/write/clock_gettime/nanosleep. The current bands are itemized on the performance section's internal-microbenchmarks page.
The six guarded domains (touching any requires an explicit report of that domain's check)
| Domain | Guarded metrics |
|---|---|
| Memory allocation / reclaim | small_alloc class-lock sections β€ ~25M/boot, REST share β€10%, no reclaim slow-path emergence, zone free floor unchanged |
| Scheduler | GRQ critical section β60 ns (production) / 75β80 ns (minimal bracket), IF=0 span avg 2786 ns (measured 2786), census / wakeβpick / context-switch cost in band |
| Filesystem hot paths | pbench fs rows (stat/mkdir+rmdir/unlink/write+fsync) within the allowed band, no new sync-write classes, buffer-cache hit rate β₯ baseline |
| Interrupts / IRQ paths | IF=0 share within the allowed band (currently 20.4%Β±3pp), closed cli segments 3β7 ms class, no new IRQ-OFF print classes |
| IPC | pipe / unix round-trip medians within the allowed band, truesize/writev path not regressed, connect-storm volumes within the allowed band |
| binder | SLOW-TXN classes stable, transaction throughput not regressed on standard loads |
Notes: the scheduler domain's in-lock figure is the exact-probe basis; the 70β84 ns lock wait is the KVM cross-vCPU locked-instruction tax (not the GRQ's own cost); the IF=0 span average is the call-site basis including acquisition wait.
Β§4Platform priority: x86_64 + KVM first
x86 + KVM is the fastest x86 virtualization on the host (near-native). Our own A/B: the p1_null probe on Linux: 0.040 Β΅s (KVM) vs 0.240 Β΅s (TCG) β 6Γ; IO/timer paths diverge more. Therefore:
- The primary dev/test/perf loop = x86_64 + KVM; all functional, performance, LTP and compatibility testing runs there first.
- riscv64 / aarch64 remain three-architecture build + suite regression gates (TCG boots β KVM cannot emulate them on an x86 host) with no perf/compat duty for now.
- ~90% of the kernel (fs/mm/ipc/sched/syscall) is arch-independent β optimizations measured on x86/KVM carry to every arch; only entry/TLB/context-switch hot paths are x86-first.
- The fair-comparison rule: when comparing two kernels, both sides use the same accelerator.
Β§5Code and repository discipline
- R-numbered comments: ext4 read/write coherence, virtio completion ordering and wakeup-path lifetimes are historically bug-dense β read the R-numbered comments before changing them.
- Lock ordering: read
docs/architecture/lock-ordering.md(INV-LOCK-*) before any lock nesting. - Observability policy: new kernel observability goes through the unified trace-event framework as tracepoints (
kernel/src/trace/, tracefs at/sys/kernel/tracing); the legacydebug=switch table is frozen and must not grow. - The probe-tarball policy: guest test-case sources are archived only as
userspace/probes/probes.tar.gz+ an extract script β loose guest sources are never committed; host-side boot drivers (.py/.sh) stay intest//scripts/. - Standing ledgers: every merge round appends its safety properties, performance numbers and eliminated bug classes to
docs/architecture/safety-and-performance.md; architectural advantages with measured evidence go intodocs/architecture/rust-native-register.md(no number = placeholder). - The main repository root stays clean: no scratch scripts, drivers, logs or images β not even gitignored ones; boot drivers and temp scripts live in your worktree's
run/.
Β§6Image and resource discipline
- All disk images live in
/home/william/rux-images/(outside every repo/worktree); worktrees reference them by symlink only β real image bytes never enter a worktree. - Shared images boot only with
-snapshot+file.locking=off. - Only kill QEMU processes you started (
pkill qemuis forbidden); test runs default to-smp 2 -m 1G, SMP4/2G for final validation. - Long scans run detached (
setsid); if QEMU fails to start under memory pressure, wait and retry instead of piling on.
Β§7The debugging toolbox (full treatment in the Debugging section)
Logs and panics
- The serial console is the primary log (
console=ttyS0). printk levels 0β7 match Linux; everything prints to UART during boot, dropping to emerg once the scheduler runs; userspace reopens withdmesg -n 7. All messages enter a 1 MB kmsg ring buffer, readable via/proc/kmsg,syslog(2),dmesg. - Kernel panic output includes file:line, CSRs (sstatus/scause/stval/sepc), all 31 GPRs, and a Call trace of up to 32 frames along the fp chain. Symbolize with
riscv64-linux-gnu-addr2line -e <kernel> <addr>. - Offline forensics: extract guest logs from a copied image with
debugfsβ no boot required.
Runtime switches
- debug= boot flags (legacy but functional):
debug=taskdump,watchdogperiodic task dumps + the spinlock-deadlock watchdog;debug=memwatchheap/page accounting for leak hunts. The authoritative table iskernel/src/debug/switches.rs. - The unified tracepoint framework (the new standard): a tracefs tree aligned exactly with Linux's β
tracing_on,trace,trace_pipe,available_events,set_event,snapshot,events/<group>/<event>/enable; two-level gating, an unarmed site pays one relaxed load. - hunt-wedge:
./test/hunt-wedge.shcaptures deadlocks/hangs (a holder-annotated build + stress injection + on-site capture, paired with addr2line). - GDB:
make debug.
Β§8A newcomer's first task
- Environment verification: finish Getting started, then explore
/procand/devin the mrsh shell. - Run the tests: watch make test's 1584 assertions go green; run one LTP quick set (
./run_quick.sh). - Read one module:
kernel/src/sched/is recommended (11 files: the stop/deadline/rt/fair/idle class framework, the main loopschedule()β__schedule()βcontext_switch()) against the scheduler design page. - Implement a small probe: model it on an existing C probe in
test/, cross-compile, drop it into the rootfs/test/, verify in the shell. - Claim a small fix: pick a failing LTP case or a small bug and walk the full Β§2/Β§3 flow from branch to merge gate.
Β§9Required-reading index
AGENTS.mdβ the binding development workflow (the source of this page's rules)docs/architecture/lock-ordering.mdβ required before virtio or any lock nestingdocs/architecture/design-divergences.mdβ the divergence register (D-numbers)docs/architecture/safety-and-performance.mdβ the safety/performance evidence ledgerdocs/development/perf-gate-baseline.mdβ the performance gate baselinedocs/test/README.mdβ the test-report index (every report carries its test platform and date)