API 参考

目录

API 参考#

TPU 指令包的汇编器与反汇编器。

tpuasm.assemble_listing(text, *, filename='<assembly>')#

将完整的 TPU 汇编源码转换为所声明目标的程序映像字节。

汇编包括整个指令包的资源求解、编码结果重解码核对及原生字节往返校验。本函数不读写文件。

参数:

  • text (str) -- 完整的 .tpuasm 源码，必须声明 .target；bundle 总数是该目标每块 bundle 数的正整数倍：v4 TC 为 10，v4 BCS 为 16，v6e TC 为 8，v6e TEC 为 1。

  • filename (str) -- 错误诊断中的文件名，默认 '<assembly>'；不会打开对应路径。

返回:

完整程序映像的字节，不是 serialized executable。

抛出:

  • ValueError -- 源码语法、操作数类型、范围或编码约束冲突，或编码结果与求解结果不一致。

  • RuntimeError -- 原生后端不可用或原生校验失败。

返回类型:

bytes

示例

在仓库根目录汇编现成样例:

from pathlib import Path
from tpuasm import assemble_listing

source = Path('tests/data/tpu_v4_tc/slots.tpuasm')
image = assemble_listing(source.read_text(encoding='utf-8'), filename=str(source))
Path('/tmp/slots.bin').write_bytes(image)
tpuasm.encode_tpu_v4_bcs_program(program)#

将完整 BCS semantic protobuf 编码为机器程序映像，不读写文件或访问设备。

program 是 BarnaCoreSequencerProgram（repeated field-1 bundles），不是外层的 TpuCoreProgramProto。bundle 数必须为 16 的正整数倍；不会自动补齐 fragment 或隐式覆盖双槽的共享字段。使用与当前环境匹配的 libtpu 后端，并核对原生编码和实际硬件字段。latency/resource_usage/bit_width 是辅助元数据，不属于机器映像。返回机器字节。非法结构、字段范围、共享字段冲突或不可逆编码抛出 ValueError/RuntimeError。调用方继续负责内存分配、装载、生命周期及运行时对程序长度的限制。

参数:

program (bytes)

返回类型:

bytes

tpuasm.decode_tpu_v4_bcs_program(image)#

将完整 BCS 机器映像解码为当前后端的 semantic protobuf。

不读写文件或访问设备。输入须为非空 512 字节对齐的完整映像，且通过原生 decode→encode 逐字节检查。返回值可交回 encode_tpu_v4_bcs_program()；保证机器映像固定点，不保证恢复此前 protobuf 的字段顺序、presence 或辅助元数据。非法输入抛出 ValueError/RuntimeError。

参数:

image (bytes)

返回类型:

bytes

tpuasm.extract_tpu_v4_bcs_program(core_program)#

从一个 TpuCoreProgramProto 提取 BCS semantic protobuf，不选择 codec。

当前已核对的 libtpu 容器路径为 barna_core(6) → sequencer(1) → pufferfish(10)。输入是单个 protobuf，区别于长度分隔的 serialized executable。不提取 Channel Controller，不解码为机器字节，不修改容器。缺失或重复路径抛出 ValueError；后续用 encode_tpu_v4_bcs_program 验证完整程序。

参数:

core_program (bytes)

返回类型:

bytes

tpuasm.dump_compiled(compiled, output_dir, *, encoding='exact', sources=True, source_map_json=False, target=None)#

将已编译的 JAX 对象中指定目标的程序映像导出为 .tpuasm 文件。

调用 bytes(compiled.runtime_executable().serialize())，然后交给 dump_executable()；本函数不替调用者编译 kernel。

参数:

  • compiled (Compiled) -- 已编译的 JAX 对象，例如 jax.jit(kernel).lower(*example_inputs).compile() 的结果。

  • output_dir (Path) -- 输出目录，使用 pathlib.Path；自动创建目录及父目录并覆盖同名文件。

  • encoding (str) -- 'exact' （默认）保留原机器字节；'canonical' 重新分配共享资源，不保证字节相同。具体保证见 format_assembly()。

  • target (str | None) -- 可省略并从容器推断；缺少或存在多个目标时必须指定。可选 'tpu-v4-tc'、'tpu-v4-bcs'、'tpu-v6e-tc'、'tpu-v6e-tec'；TEC 必须显式指定。BCS 与 TEC 无编译来源注释。

  • sources (bool) -- 默认 True，将已保存的 TC 来源显示为注释；False 关闭注释。

  • source_map_json (bool) -- 默认 False；True 另外写入 TC .sources.json，不受 sources 开关影响；BCS 与 TEC 明确拒绝 True。

返回:

与 dump_executable() 相同的 pathlib.Path 列表，按容器顺序仅包含 .tpuasm 路径；文件名对两目标均包含完整 target。

抛出:

  • ValueError -- 容器或来源元数据无效，或程序映像无法按所选 encoding 导出。

  • RuntimeError -- 原生后端不可用或原生校验失败。

  • OSError -- 输出目录无法创建或文件写入失败；可能已写入部分文件。

返回类型:

list[Path]

tpuasm.dump_executable(serialized, output_dir, *, encoding='exact', sources=True, source_map_json=False, target=None)#

将 serialized executable 中指定目标的程序映像导出为 .tpuasm 文件。

所有程序映像完成格式化后才开始创建目录和写入文件。自动创建输出目录及父目录，覆盖同名文件，保留其他文件；文件系统写入失败仍可能留下部分文件。

参数:

  • serialized (bytes) -- bytes(compiled.runtime_executable().serialize()) 得到的字节。

  • output_dir (Path) -- 输出目录，使用 pathlib.Path。

  • encoding (str) -- 'exact' （默认）通过命名编码约束及重汇编校验保留原字节；'canonical' 按确定规则重新分配共享资源，不保证字节相同。具体保证见 format_assembly()。

  • target (str | None) -- 可省略并从容器推断；缺少或存在多个目标时必须指定。可选 'tpu-v4-tc'、'tpu-v4-bcs'、'tpu-v6e-tc'、'tpu-v6e-tec'；TEC 必须显式指定。BCS 与 TEC 无编译来源注释。

  • sources (bool) -- 默认 True，将已保存的 TC 来源显示为注释；False 关闭注释。

  • source_map_json (bool) -- 默认 False；True 另外写入每份程序映像对应的``program-<target>-<record>-<index>.sources.json``，不受 sources 开关影响。BCS 与 TEC 不支持该选项，指定 True 会报错。

返回:

与 executable_programs() 顺序相同的 pathlib.Path 列表，文件名为``program-<target>-<record>-<index>.tpuasm``；target 包含 TPU 代际与执行单元。返回值只含 .tpuasm 路径，不含 JSON 路径。

抛出:

  • ValueError -- 容器或来源元数据无效，或程序映像无法按所选 encoding 导出。

  • RuntimeError -- 原生后端不可用或原生校验失败。

  • OSError -- 输出目录无法创建或文件写入失败。

返回类型:

list[Path]

示例

从已保存的 executable 导出所有程序映像:

from pathlib import Path
from tpuasm import dump_executable

serialized = Path('/tmp/my-executable.bin').read_bytes()
paths = dump_executable(serialized, Path('/tmp/tpuasm-output'))
tpuasm.executable_programs(serialized, *, target=None)#

按容器顺序提取 serialized executable 中指定目标的程序映像。

TC 路径只解析容器，不选择原生后端；BCS 路径提取 semantic body 后调用匹配的原生 codec 生成并验证机器映像；TEC 路径在 TC 记录携带的 SparseCore 代码中用原生 codec 定位 TEC 程序映像。不读写文件，数据段不会被当作 TC 程序映像。当前容器字段布局的来源和扩展边界见仓库的 docs/design/architecture.md。

参数:

  • serialized (bytes) -- bytes(compiled.runtime_executable().serialize()) 得到的字节。

  • target (str | None) -- 'tpu-v4-tc'、'tpu-v4-bcs'、'tpu-v6e-tc' 或 'tpu-v6e-tec'。省略时从容器的 program oneof / ABI 推断；目标不唯一或缺少证据时要求显式指定。SparseCore 代码由 TC 记录携带，省略时推断为 TC，提取 TEC 必须显式指定。executable 不一定包含 BCS 或 TEC 程序。

返回:

按容器顺序排列的 (record, index, image) 列表。record 是从零开始的记录号，index 是该记录内从零开始的程序映像索引，image 是程序映像字节。

抛出:

  • ValueError -- 目标/容器格式无效、没有对应程序、代码范围超出 initialized data，或遇到不支持的压缩代码。

  • RuntimeError -- BCS 或 TEC 原生后端不可用，或 codec 校验失败。

返回类型:

list[tuple[int, int, bytes]]

示例

从已保存的 executable 提取程序映像:

from pathlib import Path
from tpuasm import executable_programs

serialized = Path('/tmp/my-executable.bin').read_bytes()
for record, index, image in executable_programs(serialized):
    print(record, index, len(image))
tpuasm.replace_executable_programs(serialized, images, *, target=None)#

用新的程序映像替换 serialized executable 中的 TC 或 TEC 程序映像，返回新的 executable 字节。

本函数处理等长替换：新映像必须与原映像的字节数相同。需要增加 bundle 时，使用 insert_executable_bundles()，显式给出插入点以迁移分支、装载参数和元数据。

内容有变化的记录会得到新的程序身份：segment set 的 hash 和 core program 的 fingerprint（及其在 sequencer 与 CompilerMetadata 中的副本）改为由原值和新内容导出的 SHA-256。runtime 以这两项识别已装载的程序；不改变它们时，同一进程中已装载过原程序的 runtime 会继续执行原程序。与原映像相同的替换不改变任何字节。

参数:

  • serialized (bytes) -- bytes(compiled.runtime_executable().serialize()) 得到的字节。

  • images (Mapping[tuple[int, int], bytes]) -- 以 executable_programs() 给出的 (record, index) 为键的新程序映像，例如 assemble_listing() 的结果。

  • target (str | None) -- 'tpu-v4-tc'、'tpu-v6e-tc' 或 'tpu-v6e-tec'；省略时从容器推断，规则同 executable_programs()，TEC 必须显式指定。BCS 程序在容器中保存为 semantic protobuf，不支持替换。

返回:

新的 serialized executable 字节，长度与输入相同。可用 load_executable() 装载执行。

抛出:

  • ValueError -- 目标是 BCS、键不存在、映像长度不同，或容器缺少程序身份字段。

  • RuntimeError -- 原生后端不可用，或新映像未通过原生校验。

返回类型:

bytes

示例

修改一条指令后写回:

from tpuasm import assemble_listing, executable_programs, format_assembly, replace_executable_programs

serialized = bytes(compiled.runtime_executable().serialize())
(record, index, image), = executable_programs(serialized)
source = format_assembly(image, target='tpu-v4-tc').replace('v0, 1.0', 'v0, 0.5')
patched = replace_executable_programs(serialized, {(record, index): assemble_listing(source)})
class tpuasm.BundleInsertion(image_pc, source, branch_target='inserted')#

在原映像的 image_pc 之前插入汇编片段。

source 含 .target 声明和一个或多个 bundle，无需块对齐。片段中的直接分支只能引用片段内标签或片段局部编号（允许指向末尾以继续执行原程序）。branch_target='inserted' 使原程序中指向 image_pc 的直接分支先执行片段；'original' 则跳过片段。fallthrough 总会执行片段。多个插入点的编号均相对于输入映像。

参数:

  • image_pc (int)

  • source (str)

  • branch_target (Literal['inserted', 'original'])

branch_target: Literal['inserted', 'original'] = 'inserted'#
image_pc: int#
source: str#
tpuasm.insert_executable_bundles(serialized, insertions, *, target=None)#

在 TensorCore executable 中插入独立 bundle，返回已迁移的 executable。

插入位置是输入映像的 bundle 编号。自动处理直接分支、装载块数、块对齐、代码 segment、protobuf 长度、overlay、符号范围、注释和程序身份。新增 bundle 不继承原源码归属。原 bundle 除需要迁移的分支与装载指令外保持原编码。

当前支持一个前缀 overlay 和一个主程序 overlay，在主程序内部插入；拒绝多个代码映像与尾部 continuation 内部插入，也拒绝在原 sbr/scall（包括间接形式）的延迟窗口内插入：v4 为分支后的 1 个 bundle，v6e 为 4 个。片段中每条 sbr/scall 的延迟窗口必须完整落在片段内。调用者负责寄存器与内存资源、片段自身的流水线及延迟槽内容，以及通过寄存器或内存保存的间接跳转地址；本函数不分配资源或重新调度。

参数:
返回:

可交给 load_executable() 的 executable 字节；空编辑保持原字节。

抛出:

  • ValueError -- 插入点、汇编片段、元数据或 overlay 布局不支持。

  • RuntimeError -- 原生编解码或校验失败。

返回类型:

bytes

tpuasm.load_executable(serialized, template, *, devices=None)#

按 template 的输入输出结构与分片装载 serialized executable，返回可调用的 Compiled。

template 提供 executable 以外的全部内容：参数 pytree、aval、分片和输出结构。装载过程与 jax.experimental.serialize_executable.deserialize_and_load 相同，只是把其中的 executable 换成 serialized。serialized 必须与 template 的调用约定一致，例如由 template 自身的 executable 经 replace_executable_programs() 得到。

参数:

  • serialized (bytes) -- 要装载的 serialized executable 字节。

  • template (Compiled) -- 已编译的 JAX 对象。可以是离线编译的结果，此时需要用 devices 指定执行设备。

  • devices (Sequence[Device] | None) -- 执行设备，顺序与 template 的设备分配一致；省略时使用 template.runtime_executable().local_devices()。

返回:

执行 serialized 中程序的 Compiled 对象。

抛出:
返回类型:

Compiled

示例

装载替换了程序映像的 executable 并执行:

from tpuasm import load_executable

patched_compiled = load_executable(patched, compiled)
result = patched_compiled(x)
tpuasm.format_assembly(image, *, target, encoding='exact', source_map=None)#

将完整程序映像导出为可独立汇编的源码，不读写文件。

参数:

  • image (bytes) -- 非空、按目标块大小对齐的完整程序映像。TPU v4 TC、v6e TC 和 BCS 每块 512 字节，分别含 10、8、16 个 bundle；v6e TEC 每块 64 字节，含 1 个 bundle。

  • target (str) -- 必填，'tpu-v4-tc'、'tpu-v4-bcs'、'tpu-v6e-tc' 或 'tpu-v6e-tec'。raw image 没有目标标记，不根据字节长度或尝试不同 codec 猜测。

  • encoding (str) -- 'exact' （默认）保存原机器编码，必要时附加指令包级命名 .encoding 约束，实际重汇编并逐字节比较成功后才返回源码。'canonical' 按确定规则重新分配共享资源，生成便于编辑的源码，不承诺与输入程序映像的字节相同。

  • source_map (ProgramSourceMap | None) -- 可选的 TC 编译来源，用于在清单中添加注释；BCS 与 v6e TEC 不支持。

返回:

含目标声明和完整 bundle 清单的 .tpuasm 源码。可汇编性不代表流水线调度或设备执行已经验证。

抛出:

  • ValueError -- target / encoding 无效、目标不支持 source_map、指令形式不支持、编码无法恢复，或重汇编校验失败。

  • RuntimeError -- 原生后端不可用、程序映像格式无效或原生校验失败。

返回类型:

str

示例

从已保存的程序映像生成精确源码和便于编辑的源码:

from pathlib import Path
from tpuasm import assemble_listing, format_assembly

image = Path('/tmp/slots.bin').read_bytes()
exact_source = format_assembly(image, target='tpu-v4-tc')
editable_source = format_assembly(image, target='tpu-v4-tc', encoding='canonical')
assert assemble_listing(exact_source) == image
tpuasm.parse_assembly(text, *, filename='<assembly>', fragment=False)#

将 .tpuasm 源码解析为按 bundle 编号排列的语法树，用于在清单中定位指令；不做编码，也不读写文件。

只检查语法、物理槽名称和 bundle 数，不检查助记符、操作数类型和范围；这些由 assemble_listing() 负责。

参数:

  • text (str) -- .tpuasm 源码，首行必须声明 .target，例如 format_assembly() 的输出。

  • filename (str) -- 错误诊断中的文件名，默认 '<assembly>'；不会打开对应路径。

  • fragment (bool) -- 默认 False，要求 bundle 总数为目标块容量的正整数倍；True 用于解析插入片段，不要求凑齐整块。

返回:

AssemblyProgram，bundles[pc] 是编号为 pc 的 bundle。

抛出:

ValueError -- 语法错误、未知物理槽或 bundle 数不合要求；消息包含文件名、行列和 bundle 编号。

返回类型:

AssemblyProgram

示例

找到带唯一立即数的标记指令所在的 bundle:

program = parse_assembly(format_assembly(image, target='tpu-v4-tc'))
pc, = [pc for pc, bundle in enumerate(program.bundles) if any('0x13579bdf' in instruction.operands for instruction in bundle.instructions)]
class tpuasm.AssemblyProgram(bundles, labels, hardware)#

parse_assembly() 的结果。

变量:
参数:
target(operand, pc, relative, location)#

解析位于 bundle pc 的分支目标操作数：标签换算为 bundle 编号，relative 为 True 时返回相对 pc 的位移；其他操作数按整数解析。

参数:
返回类型:

int

bundles: tuple[AssemblyBundle, ...]#
labels: dict[str, int]#
hardware: HardwareTarget#
class tpuasm.AssemblyBundle(instructions, constraints, location)#

一个 bundle；空 bundle 的 instructions 为空。

变量:
参数:
instructions: tuple[AssemblyInstruction, ...]#
constraints: tuple[EncodingConstraint, ...]#
location: AssemblyLocation#
class tpuasm.AssemblyInstruction(slot, mnemonic, operands, predicate, location)#

一个物理槽中的指令。

变量:

  • slot (str) -- 物理槽名称，例如 's0'、'va0'。

  • mnemonic (str) -- 助记符，例如 'vxor.8x128.u32'。

  • operands (tuple[str, ...]) -- 操作数，保留源码文本，例如 ('v1', '0x13579bdf', 'v0')。

  • predicate (int) -- 谓词：15 表示无条件，0–14 表示 @pN，16–30 表示 @!pN。

  • location (tpuasm.assembly_syntax.AssemblyLocation) -- 指令在源码中的位置。

参数:
slot: str#
mnemonic: str#
operands: tuple[str, ...]#
predicate: int#
location: AssemblyLocation#
class tpuasm.EncodingConstraint(name, value, location)#

.encoding { name = value } 中的一条命名编码约束，exact 导出用它固定原机器编码。

变量:
参数:
name: str#
value: str#
location: AssemblyLocation#
class tpuasm.AssemblyLocation(filename, line, column)#

汇编源码中的位置，用于诊断。

变量:

  • filename (str) -- 解析时给出的文件名。

  • line (int) -- 行号，从 1 开始。

  • column (int) -- 列号，从 1 开始。

参数:
error(message, pc=None, slot=None)#

构造带文件名、行列及可选 bundle 编号和物理槽的 ValueError，由调用者抛出。

参数:

  • message (str)

  • pc (int | None)

  • slot (str | None)

返回类型:

ValueError

filename: str#
line: int#
column: int#
class tpuasm.HardwareTarget(identifier, image_block_size, bundles_per_block, slots, branch_delay_bundles=None)#

一种 TPU 代际与执行单元的程序格式。

变量:

  • identifier (str) -- 目标名称，例如 'tpu-v4-tc'。

  • image_block_size (int) -- 程序映像块的字节数。

  • bundles_per_block (int) -- 每块的 bundle 数。

  • slots (tuple[str, ...]) -- 物理槽名称，按清单中的书写顺序排列。

  • branch_delay_bundles (int | None) -- 分支的延迟 bundle 数；None 表示该目标尚未确定。

参数:

  • identifier (str)

  • image_block_size (int)

  • bundles_per_block (int)

  • slots (tuple[str, ...])

  • branch_delay_bundles (int | None)

branch_delay_bundles: int | None = None#
identifier: str#
image_block_size: int#
bundles_per_block: int#
slots: tuple[str, ...]#
tpuasm.compiler_source_mapping()#

在 lowering/compile 期间保留静态来源，支持嵌套与异常恢复。

这是进程级补丁。锁只协调本接口调用者；上下文期间不得有绕过本接口的并发编译。缓存产物不会重新生成来源；可用 jax.clear_caches() 并禁用持久编译缓存重新编译。

返回类型:

Iterator[CompilerSourceMapping]

class tpuasm.CompilerSourceMapping#

一次上下文的原生计数；计数代表发射捕获，不保证所有来源均可恢复。

counters()#
返回类型:

dict[str, int]

tpuasm.executable_source_maps(serialized)#

读取 executable 保存的来源元数据，并核对实际解码的物理槽。

无需 TPU、编译补丁或 final dump，但需要匹配的 libtpu decoder；不写文件。本函数只恢复已有来源，不会补齐编译时未保存的信息。

参数:

serialized (bytes) -- bytes(compiled.runtime_executable().serialize()) 得到的字节。

返回:

每份程序映像对应一个 ProgramSourceMap，与 executable_programs() 的顺序相同。每份映射包含程序身份、overlay、函数范围、逐槽来源和诊断。status='captured' 不保证来源完整，'absent' 仍可含原生注释或函数归属；客户端应直接读取 SlotSource.source_frames，详细原始证据见 SlotSource 和 InstructionOrigin。可用 ProgramSourceMap.to_dict() / .to_json() 导出版本 3 的记录，或用 source_maps_json() 合并为一个 JSON 文档。

抛出:

  • ValueError -- 容器或来源元数据无效，或程序映像包含不支持的指令形式。

  • RuntimeError -- 匹配的原生后端不可用或原生解码失败。

返回类型:

list[ProgramSourceMap]

tpuasm.source_maps_json(maps)#

将多份程序映像的来源映射序列化为一个 JSON 文档，不写文件。

参数:

maps (list[ProgramSourceMap]) -- 待导出的 ProgramSourceMap 列表，例如 executable_source_maps() 的返回值。

返回:

含 schema_version=3 和 programs 数组的 JSON 文本。数组按输入顺序保存每份映射的 ProgramSourceMap.to_dict() 结果。保留非 ASCII 字符，以两个空格缩进并以换行结尾。

返回类型:

str

class tpuasm.BundleAnnotation(image_pc: 'int', annotation_key: 'int', annotation_pc: 'int', coordinate_space: 'str', overlay: 'int', text: 'str')#
参数:

  • image_pc (int)

  • annotation_key (int)

  • annotation_pc (int)

  • coordinate_space (str)

  • overlay (int)

  • text (str)

image_pc: int#
annotation_key: int#
annotation_pc: int#
coordinate_space: str#
overlay: int#
text: str#
class tpuasm.FunctionSource(symbol_id, hlo_name, deduplicated_name, display_name, parent_symbols, ranges)#

程序映像内的函数身份及其半开区间列表。

函数由本程序映像内的 symbol_id 标识，display_name 可以重复。ranges 保存多个半开区间，保留函数范围中的空洞。

参数:
symbol_id: int#
hlo_name: str#
deduplicated_name: str#
display_name: str#
parent_symbols: tuple[int, ...]#
ranges: tuple[SourceRange, ...]#
class tpuasm.InstructionOrigin(hlo_name, hlo_module_name, hlo_module_id, llo_ordinal, locations)#

一条指令的独立来源，保存 HLO/module 身份、最终 LLO ordinal 和所有原始位置。

变量:
参数:
hlo_name: str#
hlo_module_name: str#
hlo_module_id: int#
llo_ordinal: int#
locations: tuple[SourceLocation, ...]#
class tpuasm.Overlay(index, emitted_start, emitted_limit, encoded_word_offset, image_start, prefix_size, suffix_size, hlo_function_overlay)#

一个 overlay 在发射坐标与程序映像坐标之间的换算；image_start 由 encoded_word_offset 按目标的编码字大小换算。

参数:

  • index (int)

  • emitted_start (int)

  • emitted_limit (int)

  • encoded_word_offset (int)

  • image_start (int)

  • prefix_size (int)

  • suffix_size (int)

  • hlo_function_overlay (bool)

property body_limit: int#
property body_start: int#
translate(emitted)#
参数:

emitted (int)

返回类型:

int

index: int#
emitted_start: int#
emitted_limit: int#
encoded_word_offset: int#
image_start: int#
prefix_size: int#
suffix_size: int#
hlo_function_overlay: bool#
class tpuasm.ProgramSourceMap(target, record, image_index, segment_set_index, segment_index, image_offset, image_hash, program_fingerprint, compilation_id, metadata_record, metadata_program_id, module_name, bundle_count, status, overlays, functions, slots, annotations, diagnostics)#

一份程序映像的来源映射，身份由记录、程序映像与 segment 共同限定。

hash、fingerprint 和元数据 ID 分开保存。overlays 保存坐标映射，functions 保存函数身份及半开区间列表，slots 保存逐槽来源，annotations 保存 bundle 注释，diagnostics 保存来源恢复时的诊断。

status 为 'captured' 表示保存了 tpuasm 记录，不表示每条指令都有完整来源；'absent' 表示没有 tpuasm 来源记录，仍可包含编译器原生注释或函数归属。空来源表示未知，不能据此判定指令一定由编译器生成。

to_dict() 和 to_json() 导出版本 3 的结构化记录； source_maps_json() 将多份映射导出到同一个 JSON 文档。版本 3 相对版本 2 增加统一来源 source_frames 与 source_kind，并列出函数范围中未保存注释的已占用槽。

参数:
to_dict()#

返回含 schema_version=3 和全部映射字段的字典，不写文件。

嵌套数据类递归转换为字典，tuple 集合仍为 tuple；字段和状态含义见 ProgramSourceMap。

返回类型:

dict[str, Any]

to_json()#

返回 to_dict() 的 JSON 文本，不写文件。

保留非 ASCII 字符，以两个空格缩进并以换行结尾；tuple 集合序列化为 JSON 数组。

返回类型:

str

target: str#
record: int#
image_index: int#
segment_set_index: int#
segment_index: int#
image_offset: int#
image_hash: str#
program_fingerprint: str#
compilation_id: int | None#
metadata_record: int | None#
metadata_program_id: int | None#
module_name: str#
bundle_count: int#
status: str#
overlays: tuple[Overlay, ...]#
functions: tuple[FunctionSource, ...]#
slots: tuple[SlotSource, ...]#
annotations: tuple[BundleAnnotation, ...]#
diagnostics: tuple[str, ...]#
class tpuasm.SlotSource(image_pc, slot, native_slot, annotation_key, annotation_pc, coordinate_space, overlay, compiler_annotation, annotation_locations, origins, function_symbols, source_frames, source_kind)#

一个已解码物理槽的来源集合、编译器注释及函数归属。

origins 保存独立的 InstructionOrigin 集合。空来源表示未知，不能据此推断该指令一定由编译器生成。function_symbols 引用本程序映像内的函数 symbol ID。

source_frames 是供调用者直接消费的统一源码位置：它合并捕获的 SourceMap frame 与原编译器 loc(...) 并按坐标去重。source_kind 区分 captured、compiler_location 和 unknown。compiler_annotation、annotation_locations 和 origins 保留原始编译器证据；不从机器码数据依赖推断源码。

参数:
image_pc: int#
slot: str#
native_slot: str#
annotation_key: int#
annotation_pc: int#
coordinate_space: str#
overlay: int#
compiler_annotation: str#
annotation_locations: tuple[SourceFrame, ...]#
origins: tuple[InstructionOrigin, ...]#
function_symbols: tuple[int, ...]#
source_frames: tuple[SourceFrame, ...]#
source_kind: str#
class tpuasm.SourceFrame(path: 'str', line_start: 'int', line_end: 'int', col_start: 'int', col_end: 'int', function_name: 'str' = '')#
参数:

  • path (str)

  • line_start (int)

  • line_end (int)

  • col_start (int)

  • col_end (int)

  • function_name (str)

function_name: str = ''#
path: str#
line_start: int#
line_end: int#
col_start: int#
col_end: int#
class tpuasm.SourceLocation(frames, primitive, scope_stack, ordinals)#

Pallas 原始位置；汇编源码中的诊断位置是 AssemblyLocation。

变量:

  • frames (tuple[tpuasm.tc_source_mapping.SourceFrame, ...]) -- 原始来源的位置栈。

  • primitive (str) -- 保存的 Pallas primitive 名称。

  • scope_stack (tuple[str, ...]) -- 保存的 scope 栈。

  • ordinals (tuple[int, ...]) -- 与该位置相关的 ordinals；捕获的记录中只含所属指令的 ordinal。

参数:
frames: tuple[SourceFrame, ...]#
primitive: str#
scope_stack: tuple[str, ...]#
ordinals: tuple[int, ...]#
class tpuasm.SourceRange(image_start: 'int', image_limit: 'int', emitted_start: 'int', emitted_limit: 'int', overlay: 'int')#
参数:

  • image_start (int)

  • image_limit (int)

  • emitted_start (int)

  • emitted_limit (int)

  • overlay (int)

image_start: int#
image_limit: int#
emitted_start: int#
emitted_limit: int#
overlay: int#
目录