PYPTO 框架 DFX#

本文档明确框架错误码及日志配置规范，并提供问题定位指南。

DFX 目标与要求#

  1. 问题归属可区分：打屏报错必须携带错误码，支持快速区分“外部写法问题”与“框架内部问题”。

  2. 外部问题可修复：外部写法问题须通过 ErrorMsg 明确“哪里错、为什么错、如何改”。

  3. 内部问题可定界：框架内部问题须通过 ErrorCode 直接定界到对应组件。

  4. 根因定位可落地：框架内部问题支持结合 plog 日志与 docs/zh/trouble_shooting/*.md 组件文档定位并修复。

ErrorCode#

范围映射与组件文档#

所有中断流程中的 PyptoError/CHECK/ASSERT/ERROR 均需由错误码承载。范围映射如下：

范围

归属与用途

文档

F0XXXX

外部写法问题

-

F1XXXX

框架内部公共问题

-

F2-F3XXXX

FUNCTION 组件内部问题

function.md

F4-F5XXXX

PASS 组件内部问题

pass.md

F6XXXX

CODEGEN 组件内部问题

codegen.md

F7-F8XXXX

MACHINE 组件内部问题

machine.md

F9XXXX

SIMULATION 组件内部问题

simulation.md

FAXXXX

DISTRIBUTED 组件内部问题

distributed.md

FBXXXX

VERIFY 组件内部问题

verify.md

FCXXXX

OPERATION 组件内部问题

operation.md

FC0-FC2XXX

VECTOR 子类内部问题

vector.md

FC3-FC5XXX

MATMUL 子类内部问题

matmul.md

FC6-FC8XXX

CONV 子类内部问题

conv.md

FC9XXX

视图类 OP 子类内部问题

view_op.md

规范原则#

  • 统一定义：错误码统一定义在 framework/include/tilefwk/error_code.h，组件侧头文件仅做兼容包含。

  • 归属一致：PyptoError/CHECK 表示外部写法问题（F0XXXX）；ASSERT/ERROR 表示框架内部问题（F1XXXX 及之后组件范围）。

  • 文档可追溯：若单靠 ErrorMsg 无法说明原因或难以定位，需在 docs/zh/trouble_shooting/*.md 补充原因、排查步骤与解决方案。

  • 单码单义：一个错误码仅对应一个场景，避免一码多义。

  • Skill 可联动：可在组件文档中标注关联 Skill（如 pypto-environment-setup），辅助自动化排查。

日志环境变量#

以下变量用于控制 CANN 日志输出行为（级别、打屏、落盘路径、文件数量等）。详情参考昇腾社区官方文档取值约束，本节仅给出常用作用与示例。

环境变量

作用（简要）

示例

ASCEND_GLOBAL_LOG_LEVEL

设置全局日志级别（控制整体日志详细程度）。

export ASCEND_GLOBAL_LOG_LEVEL=0

ASCEND_SLOG_PRINT_TO_STDOUT

是否打屏输出日志；1 表示打屏，0 表示按默认方式落盘。

export ASCEND_SLOG_PRINT_TO_STDOUT=1

ASCEND_MODULE_LOG_LEVEL

按模块设置日志级别（用于定向放大某些模块日志）。

export ASCEND_MODULE_LOG_LEVEL="PASS=0:PYPTO=1"

ASCEND_GLOBAL_EVENT_ENABLE

控制全局事件日志开关（用于事件类问题排查）。

export ASCEND_GLOBAL_EVENT_ENABLE=1

ASCEND_HOST_LOG_FILE_NUM

控制单进程日志文件保留数量（超出后滚动删除最早日志）。

export ASCEND_HOST_LOG_FILE_NUM=1000

ASCEND_PROCESS_LOG_PATH

指定进程日志落盘目录（不存在时会自动创建）。

export ASCEND_PROCESS_LOG_PATH=/tmp/ascend_plog

ASCEND_WORK_PATH

指定 CANN 运行工作目录（用于相关运行产物/中间文件）。

export ASCEND_WORK_PATH=/tmp/ascend_work

组合示例（调试时常用）：

export ASCEND_MODULE_LOG_LEVEL=PASS=0:PYPTO=1 即设置PyPTO对应PASS组件日志级别为debug，其余日志级别为info
export ASCEND_HOST_LOG_FILE_NUM=1000
export ASCEND_PROCESS_LOG_PATH=/tmp/ascend_plog