Translation pending. This page is currently available in Chinese.
A20OS 1.0 成对比较协议¶
本协议与 tools/release/v1_compare.py 提供一个小的 G0 验收 runner。它们不确立 C0 基线、不为 v0.18 标签背书,也不宣称任何子系统或平台已通过。最初的 NET 切片用同一批包 fixture 与 guest 负载比较 C 与 Rust 的 netfilter_rewrite 实现。host oracle 结果只说明本地功能行为;只有 guest 结果才走内核数据路径,而单靠 NAT 微基准不能确立整机无回退。
身份与输入¶
每个协议文件记录三个显式身份:固定的 C0、最近一次通过验证的 Cn,以及候选。每个身份包含 id、 revision、validated 布尔值与可追溯的引用。标签或一次成功构建都不等于验证。基线尚未验证时可以照常采集结果,但在 C0 与 Cn 有依据并被标为已验证之前,其状态一直是 EVIDENCE_INSUFFICIENT。
协议还为确切的共享输入记录一个 SHA-256,并记录一张环境表。每个身份必须使用同一用例、同一组负载参数、fixture、guest 配置与计量单位;允许不同的只有实现 selector,以及必然标识该实现的那部分构建输入。大镜像放在输出目录之外,记录其哈希,并为每次调用使用独立的可写 overlay 或快照。runner 会创建彼此独立的运行目录,但它不是沙箱:配置的命令可以写到宿主账号允许的任何位置。请只使用可信命令,并把可变镜像与状态隔离好。
runner 接受 argv 数组,不经过 shell。它向每个命令提供 A20_COMPARE_RUN_DIR、A20_COMPARE_CASE、A20_COMPARE_ITERATION 与 A20_COMPARE_VERSION。命令必须在 stdout 或 stderr 上恰好输出一行:
A20_COMPARE_JSON: {"schema":1,"case":"nat-rewrite/csum","contract":{"input_sha256":"…","output_sha256":"…","errors":0},"metrics":{"packet_ns":123.4}}
contract 会作为精确的 JSON 数据与协议里**独立**给出的 expected_contract 比对。这防止 C 与 Rust 实现因为"答错成同一个样子"而通过。一个用例声明的每个指标名都必须在结果对象里恰好出现一次,取值必须是有限正数。纯功能结果使用空的 metrics。在跑候选之前,先把指标的方向、单位以及任何真实的硬件或资源上限写进协议:硬上限用 budget_max(配合越小越好的指标),硬下限用 budget_min(配合越大越好的指标)。
每个性能指标还要固定 calibration_sha256、calibration_evidence、resolution_ratio 与noninferiority_bound_ratio。标定哈希标识一份单独采集、经过复核的基线自控数据集;非劣界必须等于那个固定的分辨率比。runner 永不从候选时期的测量里推导或放宽这个界。当前重复的 C0/Cn 自控只是质量检查:若其测得的 95% 上界超出预先登记的分辨率,结果即为证据不足。噪声运行不能给自己争取更宽的容忍度。
示例形状(命令是刻意的占位符;真实协议必须在执行前固定身份、fixture、命令与环境):
schema_version = 1
[comparison]
id = "V1-NET-rewrite"
requirement_id = "V1-NET"
protocol_id = "nat-rewrite-v1"
inputs_sha256 = "<不可变 fixture 与共享配置的 64 位十六进制摘要>"
order_seed = 71
environment = { host = "Linux", guest = "riscv64 QEMU", toolchain = "记录精确版本" }
[versions.c0]
id = "fixed-c0"
revision = "<提交与补丁身份>"
validated = false
evidence = "pending: C0 功能与性能验证"
[versions.cn]
id = "last-accepted-c"
revision = "<提交与补丁身份>"
validated = false
evidence = "pending: Cn 验收记录"
[versions.candidate]
id = "rust-netfilter-rewrite"
revision = "<候选提交与补丁身份>"
validated = false
evidence = "受测候选"
[[cases]]
id = "nat-rewrite/csum"
kind = "functional_performance"
repetitions = 6
timeout_seconds = 120
expected_contract = { input_sha256 = "<fixture 摘要>", output_sha256 = "<oracle 摘要>", errors = 0 }
[cases.metrics.packet_ns]
direction = "lower"
unit = "ns/packet"
calibration_sha256 = "<已复核基线自控数据的 64 位十六进制摘要>"
calibration_evidence = "<保留的标定记录>"
resolution_ratio = 1.0
noninferiority_bound_ratio = 1.0
[cases.commands.c0]
argv = ["<可信适配器>", "--impl", "c"]
artifact_paths = ["<本次运行产生/使用的内核或测试二进制>"]
cwd = "."
env = { }
[cases.commands.cn]
argv = ["<可信适配器>", "--impl", "c"]
artifact_paths = ["<本次运行产生/使用的内核或测试二进制>"]
cwd = "."
env = { }
[cases.commands.candidate]
argv = ["<可信适配器>", "--impl", "rust"]
artifact_paths = ["<本次运行产生/使用的内核或测试二进制>"]
cwd = "."
env = { }
重复次数与状态规则¶
每次重复里,runner 执行两次 C0、两次 Cn 与一次候选,用预先登记的 comparison.order_seed 打乱顺序,并给每个进程一个全新目录。实际观测到的调度顺序保留在报告里。两次基线运行用于对照独立标定的固定分辨率检查自控噪声。性能用例至少需要六次重复。runner 为中位数计算精确的、不依赖分布的次序统计量置信区间;观测数不足以支撑 95% 区间时,它报 EVIDENCE_INSUFFICIENT。它不假设 5% 或 10% 的容忍度:预先登记的分辨率来自独立的基线标定,既不是选定的默认值,也不是候选运行本身。只有当候选的退化比上界落在该固定分辨率之内时,指标才通过。确认超出即为 FAIL;区间重叠或对照噪声大则为EVIDENCE_INSUFFICIENT,需要更好的测量或更多重复。
每个命令的完整 stdout、stderr、argv、工作目录、退出状态、耗时、超时状态、marker 与 fatal 文本审计都写在其运行目录下。报告包含 stdout/stderr 哈希、实际 argv 与配置环境哈希、构建/受测产物哈希、宿主运行时,以及协议文件本身的副本与哈希。超时会终止该进程组,宽限期之后包括残余后代。panic/fatal 命中、非零退出、结果 marker 缺失/重复/格式错误、契约不匹配、指标缺失以及硬预算越界都会让该次运行失败。失败的轮次保留在报告里,绝不会被静默排除在一个通过的聚合之外。输出目录必须不存在,因此重跑无法覆盖先前的失败。
只有当所有用例通过、且 C0 与 Cn 都被标为已验证时,聚合才是 PASS。缺执行、基线未验证、观测太少,或被噪声淹没的置信区间都是 EVIDENCE_INSUFFICIENT。这个首次落地的 runner 只处理声明的用例与指标,它不关闭更广的 V1 工作包、不为每一条 ISA 或板级背书,也不取代 1.0 验收 中的完整功能/性能矩阵。
运行 hermetic runner 自检:
运行真实协议:
源码版本、fixture 与产物哈希、原始日志与生成的 report.json 属于工具的输出,留在仓库之外的输出目录;不要把它们、大镜像或凭据提交进仓库。仓库只保留结论。