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>
68 lines
8.8 KiB
Markdown
68 lines
8.8 KiB
Markdown
# 共享中断路由模型合同 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。
|