Hygon Trace Toolchain 操作与扩展速查

hygon-trace-toolchain - 这篇文章属于一个选集。

§ 4: 本文

阅读信息
内容类型：参考
难度：高级
适合谁：需要查命令、模板资格、Run 字段、锁语义或扩展边界的操作员与开发者
前置知识：前述 Toolchain 心智模型、Linux 与 JSON
读完后：版本矩阵,命令参考,模板参考,Run 参考,状态与退出码,部署与扩展
依据版本：<TRACE_HOST> command surface and <TRACE_SOURCE_ROOT> worktree verified 2026-08-23
验证日期：2026-08-23

本文是一页面向 Hygon Trace Toolchain 生产环境的操作与扩展检索手册。在 <TRACE_HOST> 测试机上核对到的组件版本矩阵为：

/opt/hygon-trace/current → releases/4.1.4
├── Experiment Engine    : 4.1.3
├── Pattern Trace Parser : 4.1.3
└── Trace Status Utility : 4.1.4

切勿直接用 release 目录名（4.1.4）指代所有子组件。本文所有命令行入口、状态码与产物结构均基于 2026-08-23 在真实测试机上的实测行为；本地源码工作树仅用于补充底层机制，未部署能力均作显式标注。

Hygon Trace Toolchain 的组件版本、Session 状态、Experiment、模板资格、Run 与 Parser 判断及安全扩展速查 — 图：操作和扩展都应以当前组件身份、真实资格与可校验证据为准，不能用标签或表面状态代替证明。

1. 版本矩阵与安装布局
#

1.1 测试机运行态组件
#

组件 / 层级	运行版本	核验依据与读取命令
当前 Release 软链接	`releases/4.1.4`	`readlink -f /opt/hygon-trace/current`
Experiment Engine	`4.1.3`	`experiment --version`
Pattern Trace Parser	`4.1.3`	`/opt/hygon-trace/current/parser/pyproject.toml`
Trace Status Utility	`4.1.4`	`/opt/hygon-trace/current/status/pyproject.toml`
Status JSON 规范	`hygon.trace-status/v4`	`trace-status --json \| jq .schema`

服务端标准文件系统布局：

/opt/hygon-trace/
  ├── current -> releases/4.1.4
  └── releases/
        ├── 4.1.3/              # 上一稳定版本（回滚备用）
        └── 4.1.4/              # 当前活跃版本
              ├── experiment/   # Experiment Engine 核心库与预置模板
              ├── parser/       # Pattern Trace Parser 核心模块
              ├── status/       # trace-status 工具库
              └── contracts/    # 模板契约与硬件 profile 规范

面向操作员的公开入口封装在 /usr/local/bin 或 /usr/local/sbin 下。包装器在调用时动态解析 /opt/hygon-trace/current 路径，并自动处理环境隔离与所需系统提权。

1.2 本地开发工作树边界
#

本地开发源码目录 <TRACE_SOURCE_ROOT> 在 2026-08-23 审计时的状态：

Git HEAD 提交：d07719b；
HEAD 声明版本：VERSION=4.0.1；
未提交工作树版本：VERSION=4.1.3；
测试覆盖状态：make test 核心单元测试全部通过，但由于测试环境未安装 ruff，可选的 lint 检查门被安全跳过；
未部署能力：工作树内已包含 pattern-trace taiji-export 的完整代码，但生产测试机尚未发布该子命令。

在引用工具链行为时，证据优先级必须遵守：目标机实测 CLI 与真实 Run > 生产 release 实际文件 > 本地未提交工作树机制 > 历史 Git HEAD。

2. `trace-status` 命令参考
#

用于在无副作用前提下读取宿主机 Trace 全局状态、硬件控制寄存器及物理映射。

2.1 命令行语法
#

trace-status          # 终端交互式友好输出
trace-status --brief  # 单行摘要，适合登录提示或快速监控
trace-status --json   # 机器可读 JSON，供脚本严格解析

工具仅暴露上述三种调用方式，不接受其它子命令或参数。

2.2 Trace 全局状态字段
#

状态枚举	物理含义	操作建议
`IDLE`	当前全局 Trace Session 空闲，无活跃任务	允许申请新 Session 并启动实验
`BUSY`	已有操作员或任务占用了全局 Trace Session	严禁强行启动；等待释放或联系占用操作员
`UNKNOWN`	驱动未加载、锁文件异常或底层状态无法可靠判定	严禁启动实验；优先检查 `errors` 数组

IDLE 仅表示全局 Session 锁当前可用，不代表特定实验模板一定能成功执行。它不预检磁盘配额、模板语法、硬件寄存器兼容性或 workload 可执行文件的有效性。

2.3 PCT 硬件寄存器状态
#

trace-status 读取的 pct.bypass（ReqBypass）和 pct.prefetch（硬件预取）反映的是物理寄存器当前的真实配置：

on | off | mixed | unknown

mixed：不同 Core Complex 或 Memory Controller 上的寄存器位状态不一致；
unknown：MSR / SMN 寄存器读取超时或驱动无响应。

在 --json 模式下，details 对象会详细列出每个采集点的原始读回数量、唯一值集合、底层工具退出码与错误日志。

2.4 Memmap 物理映射
#

当前服务器回读的基准硬件映射：

token       0x11000000@0x2080000000
command     3
method      1
save        S1/D5
ring        16 MiB

对应 --brief 单行格式输出：

<TRACE_HOST> TRACE=IDLE map=0x11000000@0x2080000000 dst=S1D5/16M

3. `trace-run` 命令参考
#

为不属于 experiment run 体系的独立维护、标定或诊断命令提供排他的 Trace Session 占位保护。

3.1 命令行语法
#

trace-run -- <command> [arguments...]

必须通过 -- 将包装器与待执行的实际命令隔离。

禁止嵌套调用：experiment run 内部已集成 Session 锁生命周期管理，切勿在外层重复包裹 trace-run：

# 错误用法：产生重复加锁冲突
trace-run -- experiment run stream-copy-trace-qualified

3.2 生命周期与锁语义
#

运行阶段 / 事件	系统动作与行为保证
命令拉起	原子获取全局 Session 锁；Trace 状态置为 `BUSY`；记录当前 operator 与启动时间
正常执行结束	恢复 Trace 状态为 `IDLE`；`trace-run` 透明透传被包装子命令的原始退出码
收到 HUP / INT / TERM	将信号原样转发给子进程；等待子进程退出后强制释放 Session 锁，避免死锁残留
锁已被他人占用	子进程绝不启动；直接退出并返回专用状态码 `75`（`EX_TEMPFAIL`）

4. `experiment` 命令参考
#

Experiment Engine 是端到端测试编排的核心中枢，负责计划生成、工作负载管理、多阶段采集与 Parser 调度。

4.1 命令行语法
#

experiment run <TEMPLATE_OR_SPEC> [-o DIR] [--dry-run] [--json] [TEMPLATE_PARAMETERS]
experiment list [DIR]
experiment show <RUN_DIR>
experiment --version

experiment run --help 仅输出 Engine 通用参数。模板特有参数由各模板规范动态定义，需通过各模板声明查阅或通过 --dry-run 验证；
experiment list 检索指定目录（默认 ~/trace/runs）下的所有历史 Run；
experiment show 输出指定 Run 的完整状态、各阶段结果与完整性校验详情。

4.2 目标定位规则
#

输入形式	参数支持	处理行为
catalog 模板名称（如 `stream-copy-trace-qualified`）	支持模板动态参数（`--cpu-list` 等）	从系统 catalog 载入模板，应用参数并生成 Spec
JSON 文件路径（如 `./my-spec.json`）	不接受额外模板参数	直接将该 JSON 文件作为预先物化的完整 Spec 执行

4.3 默认产物路径
#

新实验默认存放在当前操作员的主目录下：

/home/<operator>/trace/runs/<full-type>/<UTC-timestamp>/

若同一秒内启动多次 Run，系统自动追加后缀序号（-2, -3）；
-o <DIR> 仅将当前单次 Run 重定向至指定路径，不修改系统全局默认规则。

4.4 核心模板参数速查
#

STREAM Standard 模板
#

experiment run stream-copy-trace-qualified \
  --label <string> \
  --cpu-list <list> \
  --threads <int> \
  --memory-node <int> \
  --completion <stop_after_pipeline|wait> \
  [--bypass <on|off>] \
  [--prefetch <on|off>]

--label：实验标识文本（不可包含空格）；
--cpu-list：绑定 workload 运行的逻辑 CPU（如 0-15）；
--threads：OpenMP 线程数（整数 ≥ 1）；
--memory-node：NUMA 内存分配节点（整数 ≥ 0）；
--completion：workload 结束策略。stop_after_pipeline 表示采集流水线完成即停止 workload；wait 表示等待 workload 自行计算完毕；
--bypass / --prefetch：请求覆盖宿主机硬件控制寄存器。

MLC Loaded Latency Standard 模板
#

experiment run mlc-loaded-latency-trace-standard \
  --probe-cpu <int> \
  --load-cpus <list> \
  --memory-node <int> \
  --duration <int> \
  --pattern <R|W_patterns> \
  --random <true|false> \
  [--bypass <on|off>] \
  [--prefetch <on|off>]

--probe-cpu：执行延迟采样的单独逻辑 CPU 编号；
--load-cpus：施加背景带宽负载的 CPU 集合（必须严格排除 probe-cpu）；
--memory-node：MLC 缓冲区所在的 NUMA 节点；
--pattern：访存流模式（只读 R 或预设写模式）；
--random：随机访存标志（布尔值）。

4.5 退出码与执行语义
#

退出码	阶段判定	物理意义与系统保证
`0`	采集成功，分析可用	端到端执行通过，Parser 判定为 `usable`
`3`	采集成功，分析不合格	硬件流水线执行完毕，但证据未通过资格门（`rejected`）
`2`	技术失败	采集阶段崩溃、Parser 运行出错或前置依赖缺失
`75`	锁冲突	Trace Session 被他人占用或硬件租约冲突

当硬件采集阶段成功（Capture succeeded）而 Parser 分析由于某种原因崩溃（退出码 2）时，Engine 不会将已有的采集成果标记为失败。Run 目录与原始 raw 数据被完整保留，操作员可在修复环境后针对该 Run 单独重新触发分析。

5. 模板资格体系
#

系统依据规范完整性与验证充分性，将模板划分为三个严格的资格层级：

5.1 Standard（标准生产级）
#

冻结了标准的 Pattern Capture Profile、硬件寄存器拓扑与前后基线校验契约，是跨时间、跨机型性能基准比对的唯一标准来源：

stream-copy-trace-qualified（v7）
stream-add-trace-qualified（v7）
mlc-throughput-trace-qualified（v5）
mlc-loaded-latency-trace-standard（v3）

标准 Pattern Profile 硬件参数锁定：

采集工具：instrumented PatternCaptureTool
控制命令：Command 3
环形缓冲区：16 MiB
导出位置：Socket 1 / Die 5
硬件通道源：Source 1, 2, 3, 4, 5, 7
协议接口：UMC SDP0
硬件标志：respect DebugBusValid，StoreOnChange 开启，StoreToCache 开启。

严禁手动提取这些底层硬件位常量去组装临时 Spec；必须使用标准模板以享受 Contract 自动漂移检测。

5.2 Qualified（已验收定制级）
#

具备真实可用的 adapter 运行路径与测试校验，但尚未固化为系列通用标准的实验模板：

stream-copy-observed / stream-add-observed
mlc-observed / mlc-throughput-observed
stream-copy-pmu
stream-copy-trace-c3 / stream-copy-trace-c4
process-example

在对 Qualified 模板的 Run 进行横向比对前，必须先比对两者的模板版本号（version）、输入源出处（provenance inputs）以及物化生成的 Spec 哈希摘要（spec digest）。

5.3 Contract-only（仅契约占位）
#

仅完成了参数 Schema 与执行计划静态验证，尚未打通底层真实执行链路的模板：

mysql-trace-contract
nvme-fio-contract
speccpu-trace-contract

此类模板严禁传入 experiment run 执行正式采集，仅允许用于 CI 契约校验与离线计划模拟。

6. Run 产物结构参考
#

标准 Experiment Run 输出目录树结构：

/home/<operator>/trace/runs/<full-type>/<UTC-timestamp>/
  ├── run.json             # 核心元数据：计划、操作员、状态、阶段结果与硬件观测
  ├── SHA256SUMS           # 目录内所有关键文件的 SHA-256 哈希校验清单
  ├── workload/            # workload 进程的标准输出、标准错误与就绪判定证据
  ├── host-controls/       # 硬件寄存器原始值、修改请求、生效确认与恢复记录
  ├── pmu-pre/             # 采样前的硬件 PMU 性能计数器基线
  ├── trace/               # 采集到的核心二进制 raw 文件及解压流
  ├── pmu-post/            # 采样后的硬件 PMU 性能计数器基线
  ├── analysis/            # 标准 Parser 分析产物（分析完成后生成）
  │     ├── report.md
  │     ├── summary.json
  │     ├── sources.csv
  │     └── commands.csv
  └── debug/               # 仅在采集失败、被中断或指定调试选项时生成

6.1 `run.json` 关键字段
#

字段路径	类型	含义与使用注意事项
`.schema`	string	Run 契约规范版本（如 `hygon.trace-run/v4`）
`.operator`	string	触发采集的原始个人登录用户名
`.request`	object	完整的 workload 拓扑、采集阶段配置与计划出处
`.stages[].status`	string	各阶段执行状态（`succeeded` / `failed`）
`.observations.host_controls`	object	记录 `original`、`requested`、`applied` 与 `restored` 四组寄存器值
`.observations.trace_producer`	object	记录驱动指纹与底层采集工具的二进制哈希
`.analysis.status`	string	最终分析判定（`usable` / `rejected` / `failed`）

在复核历史 Run 时，workload_identity_current=false 表示 workload 进程在测试结束后已正常终止，这是历史静态数据的标准表现，不可误判为采集异常。

7. `pattern-trace` 命令参考
#

7.1 服务端公开子命令矩阵
#

# 1. 验证整 Run 并发布标准分析产物
pattern-trace experiment-run --run-dir <RUN_DIR> [--output-dir <DIR>] [--integrity <MODE>]

# 2. 基于 JSON 配置重分析 Run
pattern-trace analyze-run <RUN_DIR> --config <FILE> --output-dir <DIR>

# 3. 解码单路 capture 文件
pattern-trace analyze --raw <FILE> --out <FILE> --profile <PROFILE> [--summary <FILE>]

# 4. 查看已知 Profile 与字段置信度
pattern-trace profiles

# 5. 查看 summary 元数据
pattern-trace summary-info --summary <FILE>

# 6. 多 Run 汇总分析
pattern-trace campaign <ROOT_DIR> --output-dir <DIR>

服务端当前 未部署 pattern-trace taiji-export。

7.2 完整性校验模式（`--integrity`）
#

模式	校验范围	适用场景
`analyzed`	仅校验本次分析所依赖的输入文件（默认）	常规重分析与敏感性参数比对
`all`	严格校验原 Run 中 `SHA256SUMS` 登记的全部文件	发布正式报告前的最终核验
`size`	仅检查文件字节大小是否匹配	调试解析器逻辑，严禁用于发布

7.3 Profile 置信度矩阵
#

Profile 标识	物理通道对应	置信度级别与限制
`umc-sdp0`	UMC SubChannel SDP0 请求负载	文档级：操作码、传输长度与地址位域具有明确官方文档定义；最终系统物理地址需配合 address-map 解析
`ccm-request`	CCM 事务请求负载	强交叉验证级：由多方物理反推验证，缺乏官方公开寄存器定义表；部分内部 Tag / Unit 属于推断属性

8. 部署与扩展契约
#

8.1 部署流程与自检验证
#

标准发版流程：

# 1. 在本地源码仓库执行测试并打包
make test
make release
# 输出：dist/trace-<VERSION>.tgz

# 2. 将包上传至测试机并由受控脚本部署
sudo deployment/deploy-trace-host.sh

deploy-trace-host.sh 脚本执行如下严格的只读与合成自检：

校验 release 压缩包与依赖组件哈希；
运行 PatternCaptureTool 离线 self-test；
使用预置合成数据集运行 Parser 解析自检；
验证 trace-status 命令可用性与 MOTD 显示；
执行 experiment run ... --dry-run 计划生成测试。

安全红线：部署脚本绝不运行真实 workload，不向物理寄存器写入配置，不修改系统 memmap 或 GRUB 启动项，不触发机器重启。系统仅保留当前版本与上一版本用于快速回退。

8.2 Workload Adapter 编写规范
#

新增测试负载必须以 Adapter 形式接入 Engine，严禁新增顶层公开命令。Adapter 必须严格满足以下 7 项契约：

参数严格类型化校验：在 dry-run 阶段拒绝所有非法或未定义参数；
生成规范 Handle：统一向 Engine 返回标准 Workload Handle 结构；
区分 Launch 与 Attach 属权：Launch 模式接管进程生命周期，Attach 模式仅作状态观测；
绑定不可伪造身份：采集并记录系统的 boot_id、进程 pid 以及 /proc/<pid>/stat 中的 starttime；
严禁越权清理：Launch 模式仅清理被测进程树自身，Attach 模式下严禁向被测程序发送任何进程终止信号；
记录可执行二进制哈希：将所有被调用的 workload 二进制文件的 SHA-256 写入审计清单；
执行最小环境隔离：使用 Engine 构造的受限安全环境，严禁无过滤复制宿主机的 os.environ。

8.3 Collector Adapter 与安全扩展
#

消费 Handle：Collector 必须且只能消费 Workload Handle，严禁去解析特定 workload 的私有日志；
声明硬件属性：凡触碰物理寄存器或总线的 Collector 必须显式声明 hardware=true，受统一 Hardware Lease 管辖；
Pipeline 拓扑：v1 版本的执行阶段采用严格的线性拓扑，遇到任意失败立即触发 fail-fast 中断；
破坏性操作防护（如 NVMe 测试）：严禁通过通用 Adapter 绕过安全保护。针对块设备测试必须强制实施设备白名单过滤、生成只读计划、校验 Spec digest 批准签名、拒绝已挂载/处于 swap/包含分区的目标盘，且必须显式传入破坏性操作确认标志。

9. 已知系统缺口速查
#

版本标识不单一：Release 软链接目录为 4.1.4，但内部核心组件分别为 Experiment 4.1.3、Parser 4.1.3、Status 4.1.4，记录时需分组件明确标注；
源码工作树状态：本地工作树基于 Git HEAD d07719b，存在未提交的 4.1.3 机制更新；
未部署功能：本地源码包含 pattern-trace taiji-export，但测试机 CLI 尚未部署，不可编写相关生产脚本；
Lint 门禁跳过：本地执行 make test 时，因当前环境未安装 ruff 工具，可选的 Python 代码风格门禁被自动跳过；
IDLE 状态边界：trace-status 显示 IDLE 仅反映 Session 锁空闲，不能作为硬件环境、参数配置或实验模板一定能跑通的充分条件。

本文采用 CC BY-NC-SA 4.0 许可。

hygon-trace-toolchain - 这篇文章属于一个选集。

§ 1: Hygon Trace Toolchain：从采集脚本到证据状态机

§ 2: 用 experiment 完成一次可核验的 Hygon Trace 采集

§ 3: 用 pattern-trace 验证、重分析与解释 Trace 结果

§ 4: 本文

1. 版本矩阵与安装布局#

1.1 测试机运行态组件#

1.2 本地开发工作树边界#

2. trace-status 命令参考#

2.1 命令行语法#

2.2 Trace 全局状态字段#

2.3 PCT 硬件寄存器状态#

2.4 Memmap 物理映射#

3. trace-run 命令参考#

3.1 命令行语法#

3.2 生命周期与锁语义#

4. experiment 命令参考#

4.1 命令行语法#

4.2 目标定位规则#

4.3 默认产物路径#

4.4 核心模板参数速查#

STREAM Standard 模板#

MLC Loaded Latency Standard 模板#

4.5 退出码与执行语义#

5. 模板资格体系#

5.1 Standard（标准生产级）#

5.2 Qualified（已验收定制级）#

5.3 Contract-only（仅契约占位）#

6. Run 产物结构参考#

6.1 run.json 关键字段#

7. pattern-trace 命令参考#

7.1 服务端公开子命令矩阵#

7.2 完整性校验模式（--integrity）#

7.3 Profile 置信度矩阵#

8. 部署与扩展契约#

8.1 部署流程与自检验证#

8.2 Workload Adapter 编写规范#

8.3 Collector Adapter 与安全扩展#

9. 已知系统缺口速查#

相关文章