amos 8b7616bfd8 Batch 22 (20261027-C-hwe-hard-22): add 63 calibrated HWE hard-design tasks
From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27,
11 canonical families), 38 skipped for scope or duplication. Each task
has at least one independent contract-edge defect, boundary types
rotate, and public docs state trap clauses as plain contract prose.
Claude reviewed 63/63 USABLE against current digests. Difficulty is
unmeasured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 16:14:57 +08:00

8.7 KiB
Raw Blame History

Blink 会话合同

范围与交付

[B01] 这是单进程、显式事件的用户态模型。没有线程、睡眠、GPIO设备或内核调用;所有计时单位为抽象 tick。API 与日志的行为均须符合本文全部条款。 [B02] 正式交付只收集 blink.hpp、blink_config.cpp、gpio_lease.cpp、pulse_timer.cpp、blink_session.cpp、blink_cleanup.cpp 六个文件。新增文件不会收集。C++17 标准库与普通 Linux C++ 工具链足够,禁止依赖外部资源。 [B03] Platform 是调用方提供的设备后端。Session 不拥有 Platform 的存储;调用方保证后端和 Session 活到显式 stop 完成。Session 不可复制,不要求析构器隐式停机。GpioLease、PulseTimer 是内部实现组件,公开头文件为完整构建接口,正式对外入口是下面的 Session 和配置函数。

参数和返回

[B04] Config 包含 pin(0..1023)、period(1..1000000)、active_low(0或1)、initial(0或1)。默认值依次为0、500、0、0。逻辑电平转换成物理电平为 logical XOR active_low;关闭后的安全逻辑电平恒为0。 [B05] validate 合法配置返回0,否则返回-22。open(config, commit_result) 仅接受 commit_result=0 或 -5;非空闲时优先返回-16,不访问后端、不改变任何状态。空闲时若配置或 commit_result 非法,返回-22且完全不改变状态。 [B06] 初始 Snapshot 为 [phase=0,pin=-1,gpio=-1,timer=-1,logical=0,period=0,pulses=0,generation=0,callbacks=0]。phase 的值为0空闲、1建立中、2运行、3回收中。对外调用结束后只能见0或2。handle 是后端返回的不透明非负数,不能替换为固定值。 [B07] generation 只在完整 open 成功时加1;callbacks 记录进入 Session 回调的累计次数,包括停机 drain 的回调;这两项跨 stop、失败和重开保留。pulses 只计当前会话实际翻转次数,stop或建立失败后清零。空闲 Snapshot 的 pin/gpio/timer/logical/period 回到初始值。

建立与回调

[B08] 空闲 open 先 request(pin),再 configure(handle, initial XOR active_low),再 create_timer(callback,context),最后 arm(timer,period)。成功后 logical=initial,除非期间已发生回调;phase=2、period 为配置值。GPIO和定时器必须在整个有效会话中保持持有。 [B09] create_timer 只创建,不回调。首次 arm 可在返回前同步进入回调;回调此时必须与普通回调完全相同:callbacks与pulses各加1,逻辑电平翻转,write输出新物理电平,再arm同一定时器、同一period。后端不会在重arm内递归回调,也不会在重arm返回错误。首次arm返回错误时也允许已经回调或保留待完成回调。 [B10] 正常显式 tick 由后端把一个pending触发交给回调;Session 的每个运行态回调恰好write一次、再arm一次。回调无时间补算、无合并;没有待触发事件则不调用Session。停机/回收期间进入的回调仍计 callbacks,但不write、不翻转、不加pulses、不重arm。 [B11] open中的后端负返回值原样返回,首个失败后不继续建立。request失败:无资源可回收。configure失败:只release该GPIO,不write、不建timer。create_timer失败:write安全物理电平,再release GPIO。 [B12] create_timer成功后,首次arm失败或commit_result=-5时,先进入回收状态,然后依次调用 cancel(timer)、drain(timer)、destroy_timer(timer)、write(GPIO,安全物理电平)、release(GPIO),最后返回首个错误。上述cancel和drain调用不取决于pending或正在完成的回调是否存在。commit_result=-5在首次arm成功后才生效。 [B13] 后端cancel只撤销pending,并不完成已经保留的回调。drain同步完成保留回调后才返回。资源句柄仅为数字模型,非法顺序记录日志用于诊断,不制造真实UAF。失败恢复为空闲,下一次open应能重用对象;不回滚后端已经分配的句柄序列。

会话操作

[B14] stop在空闲时返回0且没有后端调用;其他情况进入回收状态,并严格执行B12中的同一完整回收顺序。stop之后显式tick或完成事件不得重新arm或访问释放的GPIO。重复stop幂等。停止有保留回调的会话时必须排空,不能只cancel。 [B15] change_period在非运行态返回-2(优先于参数错误);运行时period不在1..1000000返回-22且不改变状态。成功更新period,并arm一次;不翻转、不改变pulses/generation/callbacks。即使存在保留回调,完成后应使用更新后的period重arm。 [B16] set_level在非运行态返回-2;运行时logical非0/1返回-22且无副作用。成功write一次指定逻辑电平,不改变pulses。toggle在非运行态返回-2;成功把逻辑电平翻转并write一次,不增加pulses。两者不arm、不改变generation/callbacks。 [B17] 每个Session独立:不同实例的资源、配置、电平、计数和回调互不串扰。错误操作没有文档要求的副作用时,全部Snapshot字段及后端日志均保持不变。

文本配置

[B18] parse_config(text, output)接受至多128字节的ASCII文本,以空格、tab、CR、LF分隔key=value项(每项内部不允许空白)。pin必须出现;period、low、initial可选,缺省取B04默认值,key分别对应Config的同名字段及active_low。项顺序任意;十进制仅含0..9,可有前导零。不接受正负号、未知key、重复key、缺值、超出unsigned范围或B04范围的数。空文本无效。输出只在完全成功时一次性替换;返回0或-22,不修改输入。 [B19] format_config不做校验,按 pin=N period=N low=N initial=N 输出普通十进制,无多余空白或换行;合法配置可经parse_config往返。validate/parse/format不访问设备、无全局状态。

公开观察工具

[B20] make构建blink-demo;make smoke运行smoke.txt。stdin每行一条命令,U 0/1选两个独立实例之一,I seed为该实例初始化句柄序列(只在首次设备操作前使用,seed为0..100000);M fault inline reserve设置后端(fault=0正常/1 request失败/2 configure失败/3 create失败/4首次arm失败,inline和reserve为0或1)。inline/reserve及fault=4仅作用每个新定时器的首次arm;后续重arm总成功。其他fault在其对应操作返回错误。I后GPIO成功句柄从seed+10递增,timer从seed+100递增;失败request/create不占用号。 [B21] D pin period low initial调用validate;O pin period low initial commit调用open;S stop;P period change_period;L logical set_level;V toggle;Q snapshot;T count显式触发至多count次pending(count为0..100);H保留一个pending回调;F完成保留回调。M/I/U/Q/H/F/T正常返回0。每条命令输出一个JSON对象,字段r为返回值,s为B06顺序的9元素快照,b为[GPIO持有数,timer持有数,pending,flight,物理电平,累计write数,累计arm数],log为本命令发生的后端原始事件列表。空闲物理电平保留最后输出,初值-1。U输出所选实例的观察。 [B22] 事件用数字数组表示:request=[1,pin,result],configure=[2,handle,physical,result],write=[3,handle,physical],release=[4,handle],create=[5,result],arm=[6,handle,period,result],cancel=[7,handle],drain=[8,handle,flight],destroy=[9,handle],进入回调=[10,handle],保留回调=[11,handle]。write在持有GPIO时更新物理电平,任何write都累计次数;arm累计次数且设置pending,cancel清pending,drain在其事件之后完成flight,destroy移除timer。H只在pending且非flight时清pending、设flight并记录11;F只在flight时清flight、记录10并调回调;T只在timer存在、pending且非flight时清pending、记录10并调回调。初次arm先记录6并设pending,再可同步回调(清pending、记录10),最后可按reserve保留pending(清pending、设flight、记录11),返回其结果。 [B23] C pin period low initial hex调用parse_config,先用前四个数初始化output;hex为文本字节的十六进制编码,-代表空。输出另含c=[pin,period,low,initial]、text(format_config结果)及input(调用后输入文本的十六进制编码,空串输出空字符串)。此命令仍输出所选实例不变的s/b和空log。观察工具只打印原始观测,不检查正确答案。正式验收会重编译六个交付文件并提供同等观察后端,不接受只针对smoke打印固定结果。 [B24] 本题仅需处理以上规定范围内的观察命令;命令格式或十六进制非法时工具退出2,正常输入处理完成退出0。stdout使用UTF-8 JSON。允许JSON对象字段顺序和无意义空白变化,数组数值及事件顺序必须符合合同;stderr不作为业务输出约束。后端每次错误均为-5,所有handle非负,计数在本次测试中不会溢出。