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

TENSTORRENT / LAB 01 OF 08

确认 TT 开发环境：版本栈与矩阵 oracle

在现有机器上建立 CPU 起点，并为已有 TT 设备选择匹配安装路线。

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

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

先备与马上可用的例子

17 · 多文件编译、链接与构建18 · 测试与调试：独立定位失败36 · Tensor shape、stride 与 GEMM 分块41 · Tensix 与 tiles：先安排数据，再安排计算42 · TTNN 与 Metalium：不同抽象保留同一份数学合同
直接打开机制图，边看边手推

PREDICT FIRST

具体问题与独立预期

输入与约定

A=[[1,2,3],[4,5,6]]，B=[[1,0],[0,1],[1,1]]。

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

对照参考结果与原因

C=A×B=[[4,5],[10,11]]。缺少 /dev/tenstorrent 或 ttnn 不是学习失败，是 CPU 路径条件。

四个结果分别是三项乘加。后续把这个小矩阵嵌入真实 tile，保留同一个独立 oracle。

机制怎样连接起来

TTNN 是高层张量接口，Metalium 让学习者直接组织 kernel、tile 和数据移动。本路线先得到 TTNN 的端到端结果，再向下追一层，避免一开始同时调所有缓冲、格式和计算配置。

在已有 Linux 设备上记录 OS、架构、glibc、KMD、firmware、TT-SMI 和 TTNN/Metalium 版本。官方安装文档建议按同一发行版的说明配置；某个组件比 tested stack 更新，不自动意味着整套组合已验证。Mac 无卡路径只运行自己的 CPU 实现。

安装工作有明确边界：先用只读命令确认，再选择官方手动安装或匹配源代码构建。此页不自动安装、刷 firmware、reset 板卡或启动云实例。依赖没齐时在75分钟后切回 CPU，不把整个四小时耗在不可控制的配置上。

CHOOSE ONE EXECUTION PATH

按手头环境推进

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

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

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

本分支做什么：写 row-major matmul 与三类用例。

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

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

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

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

本分支做什么：按照已选 release 安装说明准备 venv/source build，记录版本；不自动系统修改。

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

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

官方 simulator · 本单元尚未验收

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

本分支做什么：本路线没有假设一个可直接运行 TTNN 的通用公开 simulator；使用 CPU oracle。

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

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

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

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

本分支做什么：已有受支持 TT 设备才执行官方最小例子，缺卡不要求采购。

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

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

READ → BUILD → BREAK → EXPLAIN

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

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

1. 盘点现状 · 30 分钟

  1. 运行只读系统与 Python 包诊断；Linux 才检查 /dev/tenstorrent。
  2. 有现成 TT-SMI 时读取版本和设备列表，不使用 reset。

这一段的产出：env.md

2. 选定官方路径 · 45 分钟

  1. 用实际发行版安装文档核对 OS/glibc/KMD/firmware 条件，记录选定 tag。
  2. 已有 source checkout 就记录 commit；新建环境时先记录选择的 release/tag，再按安装页配置独立 venv。

这一段的产出：版本栈与缺失条件

3. 写矩阵 oracle · 75 分钟

  1. 自己实现三重循环 C[i,j]+=A[i,k]*B[k,j]，写出四个预期值。
  2. 加 B 为3×3单位阵的用例，结果应还原 A；再加一个内维不匹配用例并拒绝。
  3. 运行37-a对照 tile 逻辑；本单元自己的 oracle 保持普通 row-major。

这一段的产出：oracle 与三个用例

4. 区分入口状态 · 60 分钟

  1. 已有 TT 环境按官方安装页运行 smoke/example；保存真实状态，不把 import 成功当设备运行。
  2. 无设备则写两种布局映射函数的接口草图，列后续需要的32×32填零规则。
  3. 建立 backend 字段：cpu、ttnn-hardware、metalium-hardware，各自未执行不得填通过。

这一段的产出：入口状态表

5. 口述 · 30 分钟

  1. 说明为什么采用小矩阵和相同 oracle。
  2. 列一个下一单元已经具备的前置和一个仍欠缺的条件。

这一段的产出：环境与数学基线

EXPLICIT ENVIRONMENT / EXPLICIT STATUS

命令与可保存的起点

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

1. 只读诊断；Linux 才执行最后一行

环境：CPU · 现有机器 · 状态：not-executed。核对官方 API / 工具说明 ↗

bash · 按说明保存到自己的练习目录
uname -srm
python3 --version
python3 -m pip show ttnn
ls /dev/tenstorrent
2. 只在已有 TT-SMI 环境中执行

环境：SDK · 编译与环境 · 状态：not-executed。核对官方 API / 工具说明 ↗

bash · 按说明保存到自己的练习目录
tt-smi --version
tt-smi --list
tt-smi --snapshot
3. 在用户已选择的 tt-metal checkout 中；后两行创建/进入本地 venv

环境：SDK · 编译与环境 · 状态：not-executed。核对官方 API / 工具说明 ↗

bash · 按说明保存到自己的练习目录
git rev-parse HEAD
./create_venv.sh && source python_env/bin/activate

一个必须能解释的错误

错误情境：pip show ttnn 成功就认为驱动和设备可用。

为什么会错：包元数据只证明 Python 环境中有这个发行包，不验证设备、内核驱动或 firmware 组合。

怎样修复：分别记录包发现、设备发现、实际运行与结果回读。

EVIDENCE BEFORE ADVANCING

验收与面试追问

  • 四个矩阵元素都比较，内维不符被拒绝。
  • 记录 matching release/commit，而不只写 latest。
  • 环境诊断无 reset/刷写；CPU 路径有完整可交付实现。

最后留下这几项

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

1. 为什么同时记录 KMD 和 firmware？

对照中文要点与英文回答

它们与用户态库一起影响设备访问与执行；Python 包版本并不能描述整套栈。

The Python package does not identify the complete device stack. I record the kernel driver and firmware alongside the user-space release.

2. 为什么不用随机大矩阵做第一例？

对照中文要点与英文回答

小输入每个元素可独立手算，更容易分辨布局错误、索引错误和数值误差。

A tiny matrix gives an independent, inspectable oracle for each output element.

3. 没有 TT 设备能通过什么？

对照中文要点与英文回答

能证明 CPU 数学、布局和协议模型正确；TTNN/Metalium 真设备分支保持未通过。

I can validate the CPU math and layout model. Device execution remains unverified.

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

资料与版本核验

  • TT-Metalium installation ↗

    Prerequisites; source build; Python virtual environment; run an example

    核验日期：2026-09-05。latest 滚动文档；使用实际发行版 README，记录 git rev-parse HEAD、ttnn 包版本、KMD/firmware，不混用不同 tag。

  • TT-SMI official README ↗

    Usage; version; list; snapshot; tested versions

    核验日期：2026-09-05。main 页面核验；tt-smi --version 给实际版本，--list 与 --snapshot 获取设备信息；不执行 reset。

  • TTNN matrix multiplication ↗

    Open device; tensor configuration; matmul; close device

    核验日期：2026-09-05。latest；记录 ttnn 包版本、设备、memory_config 与 compute config。

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