Tenstorrent 端到端例子：让每一层对同一结果负责

先固定一个可以手算的任务

我们计算两个四乘四矩阵相加。A按行保存0到15，B全部为10，因此结果为10到25。选择位置可辨认的A，是为了让错误的tile顺序或分区立即显现。若A和B都填一，许多布局错误仍会返回一片二，让测试误以为程序正确。

本章的C++端到端模型把工作分成两行一组：reader复制该组，compute逐项相加，writer按原始偏移写回。它不是Metalium模拟器；它检查我们自己设计的数据分配、buffer顺序和回收位置。真实程序中这些阶段由相应设备API和kernel实现，并有独立同步合同。

Host准备的不只是数组

Host需要确定shape、dtype、layout、数据位置、使用哪些核以及每个kernel的参数。输入buffer和输出buffer的大小，要与设备代码的读取数量一致。处理两块tile的kernel若收到三块的数据，可能留下未写结果；反过来多读一块则可能越界或等待不存在的数据。

公开Metalium示例的host流程包含设备与命令队列、program、kernel配置、runtime参数、数据传入、执行、回读和清理。新旧版本的设备管理接口有差异，因此应成套使用同一版本示例，不应拼接历史API。如下仅展示目前公开示例中的mesh入口，不是完整运行程序。

三行建立了什么对象（补充，另估20分钟）

沿用已学的 auto、shared_ptr 和引用读法，把下面三行看成 host 对象的建立过程。假定匹配版本的环境中，编号 0 的设备可用；这个 0 是设备选择编号，与上一章的 tile 数量无关。

顺序	调用及返回值	到这里能确认什么
1	distributed::MeshDevice::create_unit_mesh(0)；公开例子用 shared_ptr<distributed::MeshDevice> 接收	创建以一个设备构成的 mesh，device 是它的共享拥有者
2	device->mesh_command_queue()；auto& 接收引用	queue 借用该 mesh 的命令队列，没有复制或取得一个独立拥有的队列
3	CreateProgram()；返回 Program 对象	program 是 host 侧程序描述，后面还要向它配置 kernel 等内容

寿命关系可以画成：device 持有 mesh；queue → 借用该 mesh 的队列；program 保存待配置的程序描述。 箭头表示借用，不转移拥有权。不要让 mesh 已被关闭或销毁后还使用 queue；有提交的异步工作时，还须满足该版本规定的完成和资源回收顺序。

**纸上走一次：**仍使用本章 A=0…15、B全为10。执行第一行得到设备拥有者，第二行得到队列引用，第三行得到程序对象。此时应能指出三个名字各自是什么，但不能声称结果已变成10…25：三行没有安排矩阵输入、配置相加 kernel 或提交执行。如果删去后续工作，只保留这三行，数学目标就尚未计算。

以上依据 Metalium 的逐项加法 host 示例（滚动 latest，核对日期 2026-09-08）。这里只读现有三行，未运行 SDK；真实环境应成套使用匹配的 headers、文档与示例。

// Metalium host语法示意，未在SDK/设备执行。
// 需要对应版本headers、namespace与兼容设备环境。
auto device = distributed::MeshDevice::create_unit_mesh(0);
auto& queue = device->mesh_command_queue();
Program program = CreateProgram();
// 后续仍需buffer、reader/compute/writer、参数、执行和回读。

三种正确性分别检查

数学正确性检查每个有效元素；布局正确性检查逻辑坐标与实际存储位置；协议正确性检查生产数、消费数、完成条件及buffer复用。只检查总和不能发现排列错误，只检查程序退出不能证明输出已写完。例一给每个输出位置记录写入次数，要求恰好一次，避免漏写和重复覆盖。

例二把十项工作分给三个核，采用商与余数分配，数量为四、三、三，起点为零、四、七。负载不整除时最容易在最后一个核漏项，或者让相邻核重复处理边界。覆盖计数是一个不依赖计算公式的小检查，适合先在CPU验证分区。

从单核到多核只改一件事

建议先用最小数据完成一个核上的完整生命周期，再增加tile数量，再增加核数。每一步保留相同数学oracle，记录变化的分布参数。分布变大以后出现错误，优先检查每核起点、数量、输出偏移和跨核依赖，不要同时改数值精度与通信策略。

低精度dtype可能带来合理舍入，比较标准应预先定义。输入中的NaN、Inf以及输出未初始化值也应单独处理，不能让容差公式把非有限结果算成通过。正确性通过后再测性能；本机CPU模型的运行时间不代表Tensix计算、NoC带宽或真实设备吞吐。

端到端报告怎样讲得清楚

先说问题、输入和期望结果，再说如何分配数据，以及最重要的同步与生命周期约束。最后说明测试覆盖和实际运行环境。如果没有设备，只展示已运行的CPU合同模型与未执行的API设计；如果以后有设备，再追加精确版本、命令、输出和测量范围。清楚说明限制会让技术讨论更具体，而不是削弱已完成工作的价值。

// Original CPU teaching model; not a device simulator or benchmark.
#include <iostream>
#include <vector>
#include <cstddef>
#include <stdexcept>

void require(bool ok) { if (!ok) throw std::runtime_error("model check failed"); }

int main() {
 std::vector<int> a(16),out(16,-1),writes(16,0);
 for(int i=0;i<16;++i) a[static_cast<std::size_t>(i)]=i;
 for(std::size_t base=0;base<16;base+=8) {
  std::vector<int> local(a.begin()+static_cast<std::ptrdiff_t>(base),a.begin()+static_cast<std::ptrdiff_t>(base+8));
  for(int& v:local) v+=10;
  for(std::size_t j=0;j<8;++j){out[base+j]=local[j];++writes[base+j];}
 }
 for(std::size_t i=0;i<16;++i) require(writes[i]==1 && out[i]==a[i]+10);
 std::cout<<"first="<<out.front()<<" last="<<out.back()<<" writes=16\n";
}

clang++ -std=c++20 -Wall -Wextra -Wpedantic -Werror -pthread 40-a.cpp -o example && ./example

first=10 last=25 writes=16

// Original CPU teaching model; not a device simulator or benchmark.
#include <iostream>
#include <vector>
#include <stdexcept>

void require(bool ok) { if (!ok) throw std::runtime_error("model check failed"); }

int main() {
 std::vector<int> visits(10,0),counts;
 int start=0;
 for(int core=0;core<3;++core) {
  const int count=10/3+(core<10%3);counts.push_back(count);
  for(int i=start;i<start+count;++i) ++visits[static_cast<std::size_t>(i)];
  start+=count;
 }
 for(int v:visits) require(v==1);
 require(start==10);
 std::cout<<"counts="<<counts[0]<<' '<<counts[1]<<' '<<counts[2]<<" coverage=ok\n";
}

clang++ -std=c++20 -Wall -Wextra -Wpedantic -Werror -pthread 40-b.cpp -o example && ./example

counts=4 3 3 coverage=ok