Contributing

Workflow Β· merge gates Β· the debugging toolbox β€” the binding spec is AGENTS.md in the repository

Β§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.
The repository is English-only: commit messages, comments, docs and code. Reports use plain engineering language with concrete numbers.

Β§2The standard development flow

  1. Create the task's worktree under /home/william/rux-agents/<name>/ (git worktree add) β€” never develop in the main repository.
  2. Build the kernel in place; commit fixes on a branch with English commit messages.
  3. Pass the merge gates locally (Β§3) before review.
  4. The main session cherry-picks into main β†’ builds β†’ smoke-boots (push only if it reaches the login screen) β†’ pushes.
  5. 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.

  1. Dual-arch build: PLATFORM=x86_64 make build, then rm build/.config && make build β€” both rc=0.
  2. riscv64 regression boot: scripted serial on the minimal rootfs (cd/proc, rc=0, zero panics).
  3. The full suite: riscv64 make test all green.
  4. The performance gate: in-tree debug tooling (syscost / census probes / pbench) against docs/development/perf-gate-baseline.md.

Performance-gate tiers

TierApplies toExtra requirement
Tier 1all kernel changesone 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 2hot paths: mm/ sched/ fs/ ipc/ binder/ timer/ arch trapplus one pbench boot: P1–P7 medians within Β±20% or better
Tier 3allocator or IRQ pathsplus 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)

DomainGuarded metrics
Memory allocation / reclaimsmall_alloc class-lock sections ≀ ~25M/boot, REST share ≀10%, no reclaim slow-path emergence, zone free floor unchanged
SchedulerGRQ 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 pathspbench fs rows (stat/mkdir+rmdir/unlink/write+fsync) within the allowed band, no new sync-write classes, buffer-cache hit rate β‰₯ baseline
Interrupts / IRQ pathsIF=0 share within the allowed band (currently 20.4%Β±3pp), closed cli segments 3–7 ms class, no new IRQ-OFF print classes
IPCpipe / unix round-trip medians within the allowed band, truesize/writev path not regressed, connect-storm volumes within the allowed band
binderSLOW-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.

Principle: every subsystem that can affect performance must be under gate measurement β€” if no existing tool measures it, add a debug observability tool for it (gated off by default). Measurement is part of the change, not an afterthought. Baselines move only through merges that passed their own tier.

Β§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 legacy debug= 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 in test/ / 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 into docs/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 qemu is 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 with dmesg -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,watchdog periodic task dumps + the spinlock-deadlock watchdog; debug=memwatch heap/page accounting for leak hunts. The authoritative table is kernel/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.sh captures deadlocks/hangs (a holder-annotated build + stress injection + on-site capture, paired with addr2line).
  • GDB: make debug.

Β§8A newcomer's first task

  1. Environment verification: finish Getting started, then explore /proc and /dev in the mrsh shell.
  2. Run the tests: watch make test's 1584 assertions go green; run one LTP quick set (./run_quick.sh).
  3. Read one module: kernel/src/sched/ is recommended (11 files: the stop/deadline/rt/fair/idle class framework, the main loop schedule() β†’ __schedule() β†’ context_switch()) against the scheduler design page.
  4. 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.
  5. 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 nesting
  • docs/architecture/design-divergences.md β€” the divergence register (D-numbers)
  • docs/architecture/safety-and-performance.md β€” the safety/performance evidence ledger
  • docs/development/perf-gate-baseline.md β€” the performance gate baseline
  • docs/test/README.md β€” the test-report index (every report carries its test platform and date)