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

18 lines
4.2 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.

# 数组输出事务的公开库合同
1. C11 ABI 见 `include/array.h`。设备有24根pin,编号0..23;数组成员上限8,允许空数组。一个成员为 `(pin, active_low, initial)`,后两项必须是0或1;数组中pin不得重复。排列是调用者给定的顺序,不得按pin编号重排。
2. 所有 `int` 参数的公开测试域为-32768..32767;长度即元素个数。有效非空指针指向足量可读对象,不得修改输入。`session`、`bus`及其4个回调和context始终有效,调用期间没有外部并发修改。所有返回值都是整数,不以stderr决定结果。
3. `lb_plan_validate(lines,count)`:整体合法返回0,否则-1。count须为0..8;count=0时允许NULL,非零count遇NULL非法。必须检查每个成员的全部字段及重复pin。该函数无回调、无状态副作用。
4. `lb_physical(active_low,logical)`:二者均为0或1时返回异或结果,否则-1,无副作用。逻辑值1表示点亮;active_low=1时物理电平0点亮。
5. `lb_plan_mask(lines,count)`:完整有效计划返回各pin对应的24位集合,bit pin为1;空计划和任意非法计划返回0。NULL处理同validate,无副作用。这是独立可调用的公开辅助接口。
6. `lb_session_init(session)`:写入完全清零的会话。只能用于尚未拥有pin的会话;观察器的N先重置模拟设备,再初始化会话。初始化后active/count/generation和三个8元素数组均为0。
7. `lb_open(session,bus,lines,count)`:首先完整验证整个计划,非法返回-1,不能发生任何后端回调,会话不变;非法计划与active同时出现时仍返回-1。随后若会话已active返回-2,无回调。每次成功open(包括空数组)generation加1、active=1、count保存长度。
8. open的副作用顺序:按输入顺序request全部pin,全部成功后再按相同顺序direction(pin, initial异或active_low)。任一request失败立刻停止,逆序release此前成功request的pin;任一direction失败立刻停止,逆序release本次全部request的pin。失败返回-3,会话逐字段不变。请求失败的pin不release。不能触碰未属于本次申请的pin。
9. open完全成功才发布pins/active_low/logical,logical取initial;未使用的数组尾部保持0。空open无回调。失败不增加generation,不发布部分成员,失败后可用同一会话重新open。
10. `lb_apply(session,bus,values,count)`:先检查count为0..8、非零count指针非NULL及每个值为0或1。非法返回-1且不能有任何回调;再检查active,未active返回-2;最后count不等于会话长度返回-1。上述错误不改会话与设备。空数组允许NULL,active空会话apply空数组成功,无回调。
11. apply按会话保存的成员顺序逐个write(pin, value异或active_low),即使逻辑值未改变也执行。全部成功才同时发布logical数组;成功返回0,不改generation和计划。必须在任何write之前验证全部值,后段非法时无副作用。
12. write失败时停止前进,按逆序对本次先前成功write的成员write其调用前的物理电平(调用前logical异或active_low);不对失败成员或尚未尝试成员write。恢复回调保证成功。返回-3,会话逐字段不变,所有pin恢复调用前状态。不是恢复成默认值,也不是恢复成open时的值。失败后可继续apply。
13. `lb_close(session,bus)`:active时按成员逆序release,随后清零active/count及三个数组,保留generation,返回0;非active重复close返回0且无回调。空active会话close同样清零,不产生回调。再次open复用干净尾部和保留的generation。
14. 后端request/direction/write返回0成功、非零失败,release无返回。request仅取得资源,不配置输出;direction设置初始物理值;write只改变物理值;release清除本次资源。release和回滚write保证成功,其他失败由观察器注入或资源冲突造成。库不得绕过回调直接操作模拟状态。
15. 所有错误必须按上文规定精确返回。完整状态和回调次序均是可观察行为;不能通过只修改返回值或输出文本掩盖副作用。单次运行不依赖真实时间或负载。