参与开发
工作流 · 合并门禁 · 调试工具箱 —— 绑定性规范见仓库 AGENTS.md
§1开发组织与核心原则
Rux 由多个 AI 代理并行开发:每个任务在独立的工作树里进行,人类负责设定目标、评审与最终合并权。两条不可动摇的宪法级原则:
- 外部 100% 兼容:完整 POSIX 语义 + ABI 完全对齐(系统调用号、ELF/auxv、futex、ext4 在盘格式、procfs 布局)。任何上层软件不作修改即可运行,是每个设计决定的第一约束。
- 内部自由,分歧在册:内部分歧于主流的实现只要同时满足"外部兼容不变、LTP 受影响族通过、上层软件不受损"三重门,就保留并登记进
docs/architecture/design-divergences.md(带 D 编号,当前 18 项)。例:调度采用单一全局运行队列而非 per-CPU 队列 + 负载均衡。
仓库为全英文:提交信息、注释、文档、代码一律英文。汇报风格要求平实工程语言 + 具体数字。
§2标准开发流程
- 在
/home/william/rux-agents/<name>/建立本任务的工作树(git worktree add),不在主仓库直接开发。 - 就地构建内核,在分支上以英文提交信息提交修复。
- 本地先过合并门禁(见 §3),再交主会话 review。
- 主会话 cherry-pick 进 main → 构建 → smoke 启动(到达登录界面才推)→ 推送。
- 碰同一文件的合并(如 virtio 完成路径)需要语义调和,不是机械解冲突。
多个后台代理默认并发 5;配额耗尽导致的自动恢复流程:盘点各工作树未提交改动/未合并分支 → 合入(先构建 + smoke)→ 按 PID 清理无主 QEMU → 恢复全并发队列。
§3合并门禁(对所有内核代码改动绑定)
每次合并审查两个维度:功能正确性 + 性能。功能对但性能回退的改动,修复或带数字书面论证之前不合并。
- 双架构构建:
PLATFORM=x86_64 make build,再rm build/.config && make build,两者 rc=0。 - riscv64 回归启动:最小根文件系统脚本化串口(cd/proc,rc=0,零 panic)。
- 全套件:riscv64
make test全绿。 - 性能门:用树内 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 打印类 |
| IPC | pipe / unix 往返中位在基准范围内、truesize/writev 路径不回退、连接风暴量级在基准范围内 |
| binder | SLOW-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新手第一个任务
- 环境验证:按快速入门完成构建,在 mrsh shell 里检查
/proc、/dev。 - 运行测试:
make test看 1584 项断言全绿;挑一个域跑 LTP 快速集(./run_quick.sh)。 - 阅读一个模块:推荐
kernel/src/sched/(11 个文件:调度类框架 stop/deadline/rt/fair/idle,主循环schedule()→__schedule()→context_switch()),对照调度器设计页。 - 实现一个小探针:仿照
test/下现成 C 探针写一个系统调用探针,交叉编译后放进 rootfs 的/test/,在 shell 里验证。 - 认领一个小修复:挑一个失败 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—— 测试报告总入口(每份带测试环境与日期)