amos 2f32624d3b Batch 18 (20261026-C-hwe-codegen-18): add 100 calibrated HWE code-gen tasks; pause production for rollout
100 tasks from the HWE arm-linux code-gen pool (outside the lk/man/pth
range given to batch 22), each with at least one independent
contract-edge defect and plain public docs. Claude reviewed 100/100
USABLE against current digests; no ID or source overlap with main or
batch 22. Difficulty is unmeasured.

progress.md records the wrap-up: all Codex sessions and Qwen schedulers
stopped for the user's rollout, Qwen results so far (57 HARD of 373),
and what is left on each batch branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 17:52:13 +08:00

68 lines
8.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 共享中断路由模型合同 v1
本工程是 C++17 Linux 用户态、确定性软件模型;不使用内核、板卡、真实 IRQ、线程或真实时间。实现必须符合本文件全部条款。所有整数和计数均精确,不允许误差;运行序列足够短,计数不超过 uint64_t。
## 1. API、表示与错误
交付 `irq_router.hpp` 和 `irq_router.cpp`,保留 `docs/api.md` 列出的 `irq::Router`、公开结构体、方法签名和公开常量。可以改变私有表示、算法和辅助函数。构造后等同 reset;snapshot 返回值拷贝,修改返回值不得改变路由器。析构不产生输出。
设备 ID 为 0..7,线路为 0..3,位集为 0..65535,布尔参数仅为 0 或 1。所有 API 标量参数为 int64_t,超范围返回 RANGE。`Change` 的 device/value 也是 int64_t。状态码:OK=0、RANGE=1、EXISTS=2、NOENT=3、BUSY=4、DUP=5。
除 reset 外,每个成功调用使 accepted 加 1,每个失败调用使 rejected 加 1。失败除 rejected 外完全原子:设备、线路、accepted、last_line、last_result 和 deliveries 均不变。错误优先级先所有参数范围,再操作特有条件;各操作的额外优先级见下文。只检查相关操作的参数。
reset 无参数,清空全部状态、accepted/rejected。每个未注册设备:present=0、line=-1,其余字段为0。每条线路 cursor=0,其余计数为0。last_line=-1、last_result=0、deliveries为空。reset 自身不计 accepted。重复 reset 合法。
## 2. 注册与管理
attach(device,line,shared,mask):范围后先检查该设备已注册(EXISTS),再检查目标线共享冲突(BUSY)。同线超过一个设备时,所有设备 shared 必须为1;独占设备和任何其他设备不能同线。成功注册 enabled=1、pending=0、所有设备计数=0,mask/shared/line取参数,present=1。注册不改变任何线路状态或最近投递记录。
detach(device):范围后未注册返回 NOENT。成功使该槽恢复未注册默认值,丢弃 pending 和设备计数;其他设备及所有线路计数/游标/最近记录不变。可以随后重用同一ID,设备计数从零开始。不存在设备的重复 detach 返回 NOENT。
set_mask(device,mask):范围后未注册 NOENT。成功只替换 mask;不会清除 pending、投递或修改设备计数。相同 mask 合法。mask=0 表示全部屏蔽。
enable(device,enabled):范围后未注册 NOENT。成功只改 enabled;禁用期间保留 pending,可接受 raise/clear/transfer/move。重复设相同值合法。
move(device,line):范围后先 NOENT,再按 attach 的共享规则检测目标线,忽略当前设备自身;冲突 BUSY。成功只改该设备 line,保留所有其他状态和最近记录。移动到原线路合法,线路游标和统计不迁移。
## 3. 待处理位与事务
raise(device,bits):范围后未注册 NOENT。成功执行 pending |= bits,并使该设备 raises 加1;bits=0 也计一次。相同位重复到达合并,不排队多次。
clear(device,bits):范围后未注册 NOENT。成功只清除 pending 与 bits 的交集,cleared_bits 增加实际清除位的 popcount,重复清除不再累计。忽略 mask/enabled;不算处理,不增加 raises。
batch_raise(changes):列表长度 0..8,每项 device 为有效ID、value为有效位集。先检查长度和所有项范围(RANGE),再检查重复device(DUP),再检查任一设备未注册(NOENT)。全部通过后对每项原子执行 raise 的设备变化;整个批次只增加一次 accepted。空批次成功,顺序不影响结果。长度9..16可由观察协议传入并应返回 RANGE。
transfer(source,target,bits):先检查两个ID和位集范围(RANGE),再检查任一设备未注册(NOENT)。选择 source.pending & bits;source与target不同则从source清除这些位并 OR 到target.pending。两ID相同则成功但状态不变。忽略路由、mask、enabled;不改变任何设备计数,也不触发投递。零位合法。整个操作原子。
rebind(changes):列表长度0..8,value是目标线路。与 batch_raise 相同,先全部范围、再DUP、再NOENT。然后计算全部修改完成后的最终线路布局,违反共享规则返回BUSY,否则同时改列出设备的line。只看最终布局,允许两个独占设备交换不同线路。空列表成功;同线路重绑定合法;设备其余状态、线路状态、最近记录全部保留。
## 4. 共享线投递
pulse(line,budget):line有效,budget为0..8,否则RANGE。每次合法pulse使该线dispatches加1,并清空全局deliveries,设置last_line=line、last_result=0。即使预算为0或无线处理者也合法。
一次pulse从该线调用前cursor开始,按设备ID环形递增,只选择 present=1、enabled=1且line相符的设备。最多调用budget个,每个设备在本次最多一次。跳过不合格槽不消耗预算。选择顺序不受pending、mask或处理结果影响;budget=0不调用。游标、设备启停、稀疏ID、跨0回绕均按此规则。
每次调用只承认该设备自己的 owned = pending & mask。owned=0 返回NONE(0),该设备none加1,pending不变;否则返回HANDLED(1),仅清除owned,保留被屏蔽pending,handled加1、ack_bits增加owned的popcount。mask/enabled/raises/cleared_bits均不变。NONE不能吞掉别的设备的中断或本设备被屏蔽的位。
按实际调用顺序向deliveries追加{device,result,acknowledged=owned},该线visits加1、ack_bits增加owned的popcount。每次调用后该线cursor设为(device+1)%8,包括返回NONE时;没有调用则cursor不变。last_result为所有调用result的按位OR。
一次合法pulse结束,该线根据last_result增加handled或none之一。线handled/none统计pulse次数,设备handled/none统计处理函数调用次数;不要混淆。所有其他线路状态不变。连续同线低预算pulse须持续轮转,无pending设备也占用一次调用机会。
last_line/last_result/deliveries只在合法pulse或reset改变;attach/detach/move之后旧记录仍保留,它是历史观察。设备detach不回滚线路历史计数。snapshot不计accepted、不修改任何状态;设备数组按ID、线路数组按线路号排列。
## 5. 构建、观察与交付
从当前目录构建:`g++ -std=c++17 -O2 -Wall -Wextra -I. irq_router.cpp tools/observe.cpp -o observe`。运行 `./observe < docs/repro.txt`;正常输入结束退出0,不向stderr输出。只要求下述well-formed输入协议;不要求候选为任意破损文本实现恢复。工具仅调用API并打印原始观察,无内置用例和期望。
每行一个大写命令,token以ASCII空白分隔。整数为十进制int64_t,允许负号,不带正号,不超过int64_t范围。参数个数必须准确,无行尾附加token。RESET无参数;ATTACH d l s m;DETACH d;MASK d m;RAISE d b;CLEAR d b;ENABLE d e;MOVE d l;TRANSFER s t b;PULSE l n;BATCH k d1 b1 ... dk bk;REBIND k d1 l1 ... dk lk。k在0..16,后面精确2k个整数。协议合法不表示API参数范围合法,API范围错误须返回规定错误码。
每条命令输出一行十进制整数:status accepted rejected last_line last_result;然后8个设备各输出present line shared enabled mask pending handled none ack_bits raises cleared_bits;然后4个线路各输出cursor dispatches handled none visits ack_bits;再按线路号输出4个Summary,各输出members enabled_members ready_members pending_union ready_union deferred_union pending_bits ready_bits deferred_bits(定义见§6);最后输出deliveries长度以及逐项device result acknowledged。布尔为0/1,无标签。RESET的status为0。每行长度由最近一次合法pulse的deliveries决定;其他命令保留最近记录。
只提交并评分 irq_router.hpp、irq_router.cpp;新增文件不收集。评分器使用同接口的独立观察器重新编译,不依赖工作区构建产物。实现须符合docs全部条款,不能仅匹配repro输出。除标准库外无依赖;禁止访问评分器、修改外部文件或执行外部程序。
## 6. 派生线路汇总
snapshot还包含按线路号排列的summaries数组,每项Summary有9个字段。members是该线已注册设备ID位图(1<<ID);enabled_members是其中已启用者;ready_members是其中已启用且pending&mask非零者。pending_union是该线所有设备pending的OR;每个设备ready取enabled ? pending&mask : 0,ready_union是其OR;每个设备deferred取pending&~ready,deferred_union是其OR。pending_bits、ready_bits、deferred_bits分别为各设备对应位集popcount之和,设备间同位单独计数。未注册设备不参与汇总;空线全部为0。汇总是当前状态的派生观察,不改变任何计数。
完整字段类型和API签名见api.md;输出顺序见§5。