参与开发

工作流 · 合并门禁 · 调试工具箱 —— 绑定性规范见仓库 AGENTS.md

§1开发组织与核心原则

Rux 由多个 AI 代理并行开发:每个任务在独立的工作树里进行,人类负责设定目标、评审与最终合并权。两条不可动摇的宪法级原则:

  • 外部 100% 兼容:完整 POSIX 语义 + ABI 完全对齐(系统调用号、ELF/auxv、futex、ext4 在盘格式、procfs 布局)。任何上层软件不作修改即可运行,是每个设计决定的第一约束。
  • 内部自由,分歧在册:内部分歧于主流的实现只要同时满足"外部兼容不变、LTP 受影响族通过、上层软件不受损"三重门,就保留并登记进 docs/architecture/design-divergences.md(带 D 编号,当前 18 项)。例:调度采用单一全局运行队列而非 per-CPU 队列 + 负载均衡。
仓库为全英文:提交信息、注释、文档、代码一律英文。汇报风格要求平实工程语言 + 具体数字。

§2标准开发流程

  1. 在 /home/william/rux-agents/<name>/ 建立本任务的工作树(git worktree add),不在主仓库直接开发。
  2. 就地构建内核,在分支上以英文提交信息提交修复。
  3. 本地先过合并门禁(见 §3),再交主会话 review。
  4. 主会话 cherry-pick 进 main → 构建 → smoke 启动(到达登录界面才推)→ 推送。
  5. 碰同一文件的合并(如 virtio 完成路径)需要语义调和,不是机械解冲突。

多个后台代理默认并发 5;配额耗尽导致的自动恢复流程:盘点各工作树未提交改动/未合并分支 → 合入(先构建 + smoke)→ 按 PID 清理无主 QEMU → 恢复全并发队列。

§3合并门禁(对所有内核代码改动绑定)

每次合并审查两个维度:功能正确性 + 性能。功能对但性能回退的改动,修复或带数字书面论证之前不合并。

  1. 双架构构建:PLATFORM=x86_64 make build,再 rm build/.config && make build,两者 rc=0。
  2. riscv64 回归启动:最小根文件系统脚本化串口(cd/proc,rc=0,零 panic)。
  3. 全套件:riscv64 make test 全绿。
  4. 性能门:用树内 debug 工具(syscost、调度事件普查 —— 启动期调度事件的计数器、pbench)对照 docs/development/perf-gate-baseline.md 基线。

性能门分层

层级适用额外要求
Tier 1所有内核改动syscost 安静启动:普查带内、tick ≥99.5/s、零新增 panic/OOM、系统调用量 ±10%、单次平均 ±20% 或更优
Tier 2热路径:mm/ sched/ fs/ ipc/ binder/ timer/ arch trap加一次 pbench 启动:P1–P7 中位数全部在基线 ±20% 内或更优
Tier 3分配器或 IRQ 路径再加 IF=0 中断关闭份额测量(EFLAGS 对探针)

注:普查带 = TERM-DESCHED 8±2、WAKE-REFUSED 32±4、无网格滞留;单次平均 = read/write/clock_gettime/nanosleep。现行允许带逐项见性能栏目「内部微基准」页。

六大看护域(改动碰到任何一项,必须显式报告该域检查结果)

域守护指标
内存分配 / 回收small_alloc 类锁分段每次启动 ≤ 约 2500 万、REST 占比 ≤10% 机器、无回收慢路径、zone 余量不变
调度GRQ 临界区 ≈60 ns(生产)/75–80 ns(最小括号)、IF=0 段均值 2786 ns、普查/唤醒→拾取/上下文切换在基准范围内
文件系统热路径pbench fs 行(stat/mkdir+rmdir/unlink/write+fsync)在基准范围内、无新同步写类、buffer cache 命中率 ≥ 基线
中断 / IRQ 路径IF=0 份额在基准范围内(现行基准范围 20.4%±3pp)、关中断段 3–7 ms 类、无新 IRQ-OFF 打印类
IPCpipe / unix 往返中位在基准范围内、truesize/writev 路径不回退、连接风暴量级在基准范围内
binderSLOW-TXN 类稳定、标准负载事务吞吐不回退

注:调度域锁内为精确探针口径;锁等待 70–84 ns 为 KVM 跨 vCPU locked 指令税(非 GRQ 自身成本);IF=0 段均值为调用点口径、含获取等待。

总原则:任何可能影响性能的子系统都必须处于门禁测量范围之内 —— 如果现有工具测不了它,应为其新增 debug 观测工具(默认关闭)。测量是变更的组成部分,而非事后补充。基线只能由通过了自身层级的合并来更新。

§4平台优先级:x86_64 + KVM 先行

宿主 x86 + KVM 是 x86 guest 的最快虚拟化(近原生)。自家同台 A/B:基线探针 p1_null 0.040 µs(KVM)vs 0.240 µs(TCG),6 倍;IO/定时器路径差距更大。因此:

  • 主要开发/测试/性能循环 = x86_64 + KVM;所有功能、性能、LTP、兼容性测试先跑 x86_64+KVM。
  • riscv64 / aarch64 保留三架构构建 + 套件回归门(TCG 启动 —— KVM 无法在 x86 宿主上模拟它们),暂不承担性能/兼容性测试职责。
  • 约 90% 内核代码(fs/mm/ipc/sched/syscall)架构无关 —— 在 x86/KVM 上测得的优化天然惠及全部架构;只有入口/TLB/上下文切换等 arch 热路径是 x86 优先。
  • 公平对比规则:比较两个内核时,两侧必须使用相同加速器。

§5代码与仓库纪律

  • R 编号注释:ext4 读写一致性、virtio 完成顺序、唤醒路径生命周期是历史上 bug 最密集的区域 —— 改前先读代码里的 R 编号注释。
  • 锁序:触碰锁嵌套前必读 docs/architecture/lock-ordering.md(INV-LOCK-*)。
  • 观测性政策:新增内核观测一律走统一 trace-event 框架加 tracepoint(kernel/src/trace/,tracefs 挂载于 /sys/kernel/tracing);旧 debug= 开关表已冻结为遗留,不得增长。
  • 探针 tarball 政策:guest 测试用例源码只以 userspace/probes/probes.tar.gz + 解压脚本形式归档,绝不提交散的 guest 源文件;宿主侧启动驱动(.py/.sh)留在 test/ / scripts/。
  • 台账:每轮合并落地的安全属性、性能数字、bug 类消除,同改动内记入 docs/architecture/safety-and-performance.md;架构优势带实测证据记入 docs/architecture/rust-native-register.md(无数字 = 占位符,不算条目)。
  • 主仓库根保持干净:不落任何 scratch 脚本、驱动、日志、镜像(gitignored 的也不行);启动驱动与临时脚本放自己工作树的 run/。

§6镜像与资源纪律

  • 所有磁盘镜像住 /home/william/rux-images/(仓库之外),工作树只用符号链接引用;绝不把镜像字节放进工作树。
  • 共享镜像启动一律 -snapshot + file.locking=off。
  • 只杀自己启动的 QEMU 进程(pkill qemu 禁止);测试默认 -smp 2 -m 1G,SMP4/2G 留给最终验证。
  • 长扫描用 setsid 脱离会话;宿主内存紧张导致 QEMU 启动失败时等待重试,不堆积。

§7调试工具箱(完整专题见调试专栏)

日志与 panic

  • 串口是首要日志(console=ttyS0)。printk 级别 0–7 与Linux 内核一致;启动期全量打 UART,调度器起来后降为 emerg,用户态 dmesg -n 7 重开。全部消息进 1 MB kmsg 环形缓冲,可经 /proc/kmsg、syslog(2)、dmesg 读取。
  • Kernel panic 输出 file:line、CSR(sstatus/scause/stval/sepc)、全部 31 个通用寄存器、按帧链回溯最多 32 帧的调用栈。符号化:riscv64-linux-gnu-addr2line -e <kernel> <addr>。
  • 离线取证:对拷贝出来的磁盘镜像用 debugfs 抽取 guest 日志,不需要启动。

运行时开关

  • debug= 启动旗标(遗留但可用):debug=taskdump,watchdog 周期任务转储 + 自旋锁死锁看门狗;debug=memwatch 堆/页记账查泄漏。权威表在 kernel/src/debug/switches.rs。
  • 统一 tracepoint(新标准):tracefs 文件树完整对齐 Linux 语义 —— tracing_on、trace、trace_pipe、available_events、set_event、snapshot、events/<group>/<event>/enable 等;两级门控,未武装站点只付一次 relaxed load。
  • hunt-wedge:./test/hunt-wedge.sh 死锁/挂死捕获(自动带持有者信息的构建 + 轰炸 + 现场抓取,配合 addr2line 定位)。
  • GDB:make debug。

§8新手第一个任务

  1. 环境验证:按快速入门完成构建,在 mrsh shell 里检查 /proc、/dev。
  2. 运行测试:make test 看 1584 项断言全绿;挑一个域跑 LTP 快速集(./run_quick.sh)。
  3. 阅读一个模块:推荐 kernel/src/sched/(11 个文件:调度类框架 stop/deadline/rt/fair/idle,主循环 schedule() → __schedule() → context_switch()),对照调度器设计页。
  4. 实现一个小探针:仿照 test/ 下现成 C 探针写一个系统调用探针,交叉编译后放进 rootfs 的 /test/,在 shell 里验证。
  5. 认领一个小修复:挑一个失败 LTP 用例或小 bug,在工作树里走完 §2/§3 流程,体验从分支到合并门禁的完整链路。

§9必读文档索引

  • AGENTS.md —— 绑定性开发工作流(本页的规范源头)
  • docs/architecture/lock-ordering.md —— 动 virtio / 任何锁嵌套前必读
  • docs/architecture/design-divergences.md —— 内部分歧登记册(D 编号)
  • docs/architecture/safety-and-performance.md —— 安全/性能双优证据台账
  • docs/development/perf-gate-baseline.md —— 性能门禁基线
  • docs/test/README.md —— 测试报告总入口(每份带测试环境与日期)