算力手记C++ & COMPUTING SYSTEMS
← Tenstorrent 专题与八个进阶单元

TENSTORRENT / LAB 05 OF 08

单核matmul：沿 K 轴累加，而不是覆盖

把小矩阵变为有两个K块的reader/compute/writer流程。

本单元 4 小时。本公司八个单元共 32h，三家公司共额外 96h 核心实践；这笔时间在共同路线之外，未压入厂商入门的44h。

本页是实践讲义。打开、阅读或复制命令不代表完成。新单元的 SDK、simulator 与硬件命令均未在教材建设中执行；自己的结果应按实际后端保存。

先备与马上可用的例子

36 · Tensor shape、stride 与 GEMM 分块41 · Tensix 与 tiles：先安排数据，再安排计算43 · Reader、compute、writer：缓冲区里的生产与消费44 · Tenstorrent 端到端例子：让每一层对同一结果负责

先完成：tenstorrent-04 →

直接打开机制图，边看边手推

PREDICT FIRST

具体问题与独立预期

输入与约定

教学 A=[[1,2,3],[4,5,6]]、B=[[1,0],[0,1],[1,1]]；教学K块宽2。设备物理矩阵改为 M=N=32,K=64，把第三个K元素放在索引32。

先根据输入写下自己的结果与理由，再展开参考推演；随后运行或检查实现。

对照参考结果与原因

第一K块贡献[[1,2],[4,5]]，第二K块贡献[[3,3],[6,6]]；和为[[4,5],[10,11]]。其余物理输出0。

把逻辑第三列/行映射到物理K=32，让设备确实经过两个32宽K tile，避免所有有效值都藏在第一块里。

机制怎样连接起来

为每个输出C tile固定(m,n)，然后遍历所有k tile累加。A与B是同一乘法的两个输入，不存在A先算完再传给B的依赖。一个输出的累加器要跨K迭代存活，完成全部K后才pack并发布输出。

教学图用2×2便于看坐标；设备路径明确使用32×32tile。这里的重新嵌入使A[0,32]=3、A[1,32]=6，B[32,0]=B[32,1]=1；第一tile保留逻辑k=0,1，其他位置填零。结果不变，但能够暴露漏第二K块的错误。

Metalium路径复用matching tag单核matmul，修改M/N/K及输入初始化和独立oracle，先保留该例的现成数据格式与计算配置。不要同时改核心配置、dtype、tile布局和多核分配。

CHOOSE ONE EXECUTION PATH

按手头环境推进

CPU 路径可以先完成。额外的 SDK 或设备验证要有自己的运行记录；本单元的四小时不同时要求完成四个分支。安装等待超过本页预算时，留下阻塞条件，继续可做的数学、代码与协议工作。

CPU · 现有机器 · 本单元尚未验收

条件：现有 macOS 或 Linux；C++20 编译器或 Python 3 标准库。无需加速卡。

本分支做什么：实现两K块的逻辑流水和完整矩阵oracle。

保存什么证据：保存自己的源码、输入、实际 stdout/stderr 和退出码；只证明 CPU 逻辑。

教材初始执行状态：not-executed。这不是对你个人学习进度的判断。

SDK · 编译与环境 · 本单元尚未验收

条件：已有匹配发行版的 TT-Metalium/TTNN Linux 开发环境。

本分支做什么：对照单核matmul完整源码修改自己的副本，保持release一致。

保存什么证据：保存实际工具版本与编译命令；仅编译成功不能记成运行通过。

教材初始执行状态：not-executed。这不是对你个人学习进度的判断。

官方 simulator · 本单元尚未验收

条件：只有明确提供并且版本匹配的官方 simulator 才属于此分支。

本分支做什么：CPU三函数不是RISC或NoC时序模拟。

保存什么证据：记录 simulator 名称、版本、输入、日志、退出状态；网页或 CPU 模型不算 simulator。

教材初始执行状态：not-executed。这不是对你个人学习进度的判断。

真实设备 · 本单元尚未验收

条件：用户已有并可使用的兼容设备或实验室环境；本单元不要求购买、租用或提交集群作业。

本分支做什么：在现有设备跑单核两Ktile例，记录format/MathFidelity和完整输出。

保存什么证据：真实设备输出、同步点、设备型号和复现日志单独保存；未执行保持未通过。

教材初始执行状态：not-executed。这不是对你个人学习进度的判断。

READ → BUILD → BREAK → EXPLAIN

四小时，留下一个完整产出

可拆成多个时段。每次停下时保存代码、输入、实际结果和下一步，不用重新读整篇。没有通过当前检查时继续修正，不靠翻页推进。

1. 手算两块 · 30 分钟

  1. 在37章机制图看K推进，独立写出两块贡献矩阵。
  2. 画逻辑k=2→物理k=32的映射，说明为何不是普通连续padding。

这一段的产出：两块贡献图

2. 列tile请求 · 40 分钟

  1. 计算Mt=1,Nt=1,Kt=2。reader请求(A0,B0),(A1,B1)，writer只产出C0。
  2. 在CB表上写每个输入tile一次push/pop与输出一次push/pop。

这一段的产出：tile请求与CB计数

3. 实现累加流程 · 90 分钟

  1. CPU路径写reader生成配对、compute累加、writer写回的三段函数；物理尺寸32×64和64×32，完整比较输出。
  2. 设备路径用下方官方构建入口，在自己的匹配源码副本中修改输入与尺寸；先保留单核结构。
  3. 记录首块完成后的partial，再记录最终矩阵；设备不能直接读partial时用CPU推导并明确标签。

这一段的产出：单核实现和K阶段结果

4. 捕捉覆盖错误 · 50 分钟

  1. CPU模型故意每轮K都清零累加器，错误结果只剩[[3,3],[6,6]]；测试必须失败。
  2. 再交换第二块B的两个非零值之一为2，独立计算新输出，确保读到了第二块。
  3. 恢复baseline，记录源码与实际编译/运行状态。

这一段的产出：覆盖错误回归

5. 解释资源存活 · 30 分钟

  1. 指出累加器何时获得、何时可释放，输入tile何时消费完。
  2. 区别CPU函数边界和真实kernel/CB完成条件。

这一段的产出：K累加解释

EXPLICIT ENVIRONMENT / EXPLICIT STATUS

命令与可保存的起点

以下代码按各自环境使用，运行前完成对应步骤并核对版本。编译失败后停止，不运行目录中的旧二进制；每次采集日志使用新的运行目录。设备程序仅运行在你已有且可使用的环境中。

1. 仅匹配 tt-metal checkout；会构建本地示例，不在本轮自动执行

环境：真实设备 · 状态：not-executed。核对官方 API / 工具说明 ↗

bash · 按说明保存到自己的练习目录
# Confirm the current directory is the selected tt-metal checkout.
export TT_METAL_HOME="$PWD"
./build_metal.sh --build-programming-examples && ./build/programming_examples/metal_example_matmul_single_core

一个必须能解释的错误

错误情境：把累加器清零放在每次K循环的开头。

为什么会错：较早K块的贡献被覆盖，最终只保留最后一个块。

怎样修复：在进入K循环前初始化，跨所有K块累加，最后一次pack输出。

EVIDENCE BEFORE ADVANCING

验收与面试追问

  • 明确存在两个物理Ktile，有效第三项位于k=32。
  • 两块partial与最终结果都能解释。
  • 漏块或每块清零可由测试识别。

最后留下这几项

输入和预期、自己的源码或明确标为推演的状态表、实际命令/输出/退出码、一个失败与修复、后端与版本、尚未执行的部分。运行已有教学例子与独立完成修改分别记录。

1. 为什么特意把第三项移到k=32？

对照中文要点与英文回答

如果所有有效值都在第一个物理tile，漏掉第二tile仍可能通过；这种输入强迫测试覆盖K推进。

Moving the third term to physical k=32 forces the test to exercise the second K tile.

2. A和B是否构成串行流水？

对照中文要点与英文回答

不是，它们是同一计算的并列输入；compute要等两者都可用。

A and B are peer inputs to the same multiplication. Compute waits for both.

3. 什么时间才能发布C？

对照中文要点与英文回答

对应输出tile的所有K贡献完成、结果可用并写入输出CB后。

C can be published only after all K contributions are complete and the output tile is ready.

这些是依照本单元机制设计的追问，不是公司真题。个人验收仍依据实际代码、测试、测量与口述。

资料与版本核验

  • Matmul Single Core ↗

    Tile indexing; reader/compute/writer; enqueue and verification

    核验日期：2026-09-05。latest；记录 build_metal.sh 选项及源码 commit；页面代码片段不能替代完整匹配版本源码。

  • ttnn.matmul API ↗

    Tiled inputs; dtype; program-dependent memory support

    核验日期：2026-09-05。latest；未把文档列出的不同 dtype/config 当成所有设备都支持。

  • cb_reserve_back API ↗

    Blocking availability check; no pointer advancement

    核验日期：2026-09-05。latest；按所用 tag 核对 page/tile 数量和 CB 容量规则。

正文、问题和实践设计依据公开资料独立撰写。官方页面的示例输出是资料中的结果，不是本机运行证据。latest 链接可能变化，请在自己的复现说明中保留实际版本。