TENSTORRENT / LAB 04 OF 08
CB 发布协议：数据到齐才能 push
用有限状态模型解释 reserve、NoC完成、push、wait、pop。
本单元 4 小时。本公司八个单元共 32h，三家公司共额外 96h 核心实践；这笔时间在共同路线之外，未压入厂商入门的44h。
本页是实践讲义。打开、阅读或复制命令不代表完成。新单元的 SDK、simulator 与硬件命令均未在教材建设中执行；自己的结果应按实际后端保存。
先备与马上可用的例子
先完成：tenstorrent-03 →
- 39-a · 容量二的FIFO回绕：先看输入和实际源码，再开始自己的修改；教学实现与自己的产出分别记录。
- 39-b · 预留不代表可读：先看输入和实际源码，再开始自己的修改；教学实现与自己的产出分别记录。
直接打开机制图，边看边手推
- 43 · 逐步状态与文字图解 → Reader、compute、writer：缓冲区里的生产与消费；图解不执行厂商 SDK。
PREDICT FIRST
具体问题与独立预期
输入与约定
一个生产者、一个消费者，CB容量2页；依次发布tile id 0,1,2，每页值等于id+10。
先根据输入写下自己的结果与理由，再展开参考推演；随后运行或检查实现。
对照参考结果与原因
消费序列[(0,10),(1,11),(2,12)]；所有时刻0<=published-consumed<=2，结束计数都为3。
页容量限制在途可见数据。reserve等待空间，不会自行推进写指针；NoC完成和push负责不同条件。
机制怎样连接起来
把“有空间”和“有数据”分成两个判断。生产者先确认空间，再发起搬运，等待搬运完成后发布；消费者等已发布页，使用完后回收。为避免引入额外并发合同，本单元只做单生产者、单消费者和一次一页。
公开cb_reserve_back接口是等待足够空页，不推进CB指针。它不是给多个独立生产者的原子抢占服务。CPU模型可以另设inflight字段表示正在填充，但必须写明这是教学状态，不是声称硬件API内部字段。
一次只做一页让环绕和计数可手推。容量、一次reserve/push数量及wrap规则需要同一版本API约束；本单元不通过随机page批量操作去猜设备行为。
CHOOSE ONE EXECUTION PATH
按手头环境推进
CPU 路径可以先完成。额外的 SDK 或设备验证要有自己的运行记录；本单元的四小时不同时要求完成四个分支。安装等待超过本页预算时，留下阻塞条件，继续可做的数学、代码与协议工作。
CPU · 现有机器 · 本单元尚未验收
条件：现有 macOS 或 Linux；C++20 编译器或 Python 3 标准库。无需加速卡。
本分支做什么：有限状态模型安全拒绝非法协议，不忙等卡死。
保存什么证据：保存自己的源码、输入、实际 stdout/stderr 和退出码；只证明 CPU 逻辑。
教材初始执行状态：not-executed。这不是对你个人学习进度的判断。
SDK · 编译与环境 · 本单元尚未验收
条件：已有匹配发行版的 TT-Metalium/TTNN Linux 开发环境。
本分支做什么：核对本版CB/NoC接口，不把教学字段当真实实现内部。
保存什么证据：保存实际工具版本与编译命令；仅编译成功不能记成运行通过。
教材初始执行状态：not-executed。这不是对你个人学习进度的判断。
官方 simulator · 本单元尚未验收
条件：只有明确提供并且版本匹配的官方 simulator 才属于此分支。
本分支做什么：状态枚举不是Tensix simulator。
保存什么证据：记录 simulator 名称、版本、输入、日志、退出状态；网页或 CPU 模型不算 simulator。
教材初始执行状态：not-executed。这不是对你个人学习进度的判断。
真实设备 · 本单元尚未验收
条件：用户已有并可使用的兼容设备或实验室环境；本单元不要求购买、租用或提交集群作业。
本分支做什么：仅在已有正确单核pipeline上观察协议；错误注入留在CPU模型。
保存什么证据：真实设备输出、同步点、设备型号和复现日志单独保存；未执行保持未通过。
教材初始执行状态：not-executed。这不是对你个人学习进度的判断。
READ → BUILD → BREAK → EXPLAIN
四小时，留下一个完整产出
可拆成多个时段。每次停下时保存代码、输入、实际结果和下一步，不用重新读整篇。没有通过当前检查时继续修正，不靠翻页推进。
1. 手推容量2 · 30 分钟
- 画两个稳定槽位，按reserve0→fill0→complete0→push0→consume0→pop0记录。
- 让生产者先发布0和1，证明未pop时不能再开始占用第三页。
这一段的产出：槽位与计数表
2. 定义状态断言 · 40 分钟
- 实现published、consumed、inflight和payload_valid字段。
- 断言push前payload_valid，consume前published>consumed，pop后已消费页才可复用。
这一段的产出：协议检查函数
3. 实现事件模型 · 90 分钟
- 从39-a理解队列接口，但自己的模型显式拆分fill提交和完成。
- 执行三页流程并输出每次事件、槽号、页号、占用。
- 设备路径只在已正确的reader副本中对应reserve/read/barrier/push四行，保持单生产者约束。
这一段的产出：有界状态模型与三页日志
4. 制造未完成发布 · 50 分钟
- 仅CPU模型把push放到complete前，要求检查立即拒绝，不能靠最后一次总和偶然正确。
- 测试消费空CB、未消费就pop、第三页覆盖未回收页三个非法事件。
- 修复后验证最终published=consumed=3，inflight=0。
这一段的产出：四类非法事件回归
5. 解释等待与死锁 · 30 分钟
- 说明消费者在等什么、谁能让条件变真。
- 画一次忘记push的等待关系，不在共享硬件上故意制造hang。
这一段的产出：协议与活性说明
EXPLICIT ENVIRONMENT / EXPLICIT STATUS
命令与可保存的起点
以下代码按各自环境使用，运行前完成对应步骤并核对版本。编译失败后停止，不运行目录中的旧二进制；每次采集日志使用新的运行目录。设备程序仅运行在你已有且可使用的环境中。
这个单元复用前一单元的项目文件，并按上面的具体任务修改。对应章节例子的源码、编译命令和预期输出在本页先备链接里；不要把例子自己的固定成功判定遗留到已改输入的版本中。
一个必须能解释的错误
错误情境：reserve之后马上push，认为“NoC随后会填好”。
为什么会错：消费者会把已发布页当成可读数据；发布没有替代搬运完成。
怎样修复：保持reserve→read→read barrier→push，在writer路径同样等写完成后再释放所读页。
EVIDENCE BEFORE ADVANCING
验收与面试追问
- 消费顺序和payload都正确，而不只总计数。
- push-before-complete被拒绝。
- 明确reserve不推进指针，也不声称多生产者安全。
最后留下这几项
输入和预期、自己的源码或明确标为推演的状态表、实际命令/输出/退出码、一个失败与修复、后端与版本、尚未执行的部分。运行已有教学例子与独立完成修改分别记录。
1. reserve具体保证什么？
对照中文要点与英文回答
在约定生产者模式下等待空闲页满足要求；不自动复制数据、发布数据或推进指针。
Reserve waits for capacity. It neither moves data nor publishes a page or advances the CB pointer.
2. 为什么writer不能发起NoC写后立刻pop？
对照中文要点与英文回答
NoC还可能读取L1源页；提前回收允许生产者覆盖它。
The NoC write may still read the L1 source page. Popping it early permits reuse before the transfer completes.
3. 忘记push是数值bug还是活性bug？
对照中文要点与英文回答
消费者可能永远等待，因此首先是进展条件未满足；不能用容差修复。
A missing push is a progress failure: the consumer may wait forever. Numerical tolerance cannot repair it.
这些是依照本单元机制设计的追问，不是公司真题。个人验收仍依据实际代码、测试、测量与口述。
资料与版本核验
- cb_reserve_back API ↗
Blocking availability check; no pointer advancement
核验日期：2026-09-05。latest；按所用 tag 核对 page/tile 数量和 CB 容量规则。
- Matmul Single Core ↗
Tile indexing; reader/compute/writer; enqueue and verification
核验日期：2026-09-05。latest；记录 build_metal.sh 选项及源码 commit；页面代码片段不能替代完整匹配版本源码。
- Watcher ↗
Enabling; waypoints; NoC and CB diagnostics
核验日期：2026-09-05。latest；架构代际相关功能单独核对，不默认启用 DUMP_ALL。
正文、问题和实践设计依据公开资料独立撰写。官方页面的示例输出是资料中的结果，不是本机运行证据。latest 链接可能变化，请在自己的复现说明中保留实际版本。