ge-coredump-diagnose

昇腾 GE 图编译/图执行相关进程崩溃的 coredump 诊断。Use when(满足任一 GE 强信号才触发): 1) backtrace、日志或用户描述中出现 GE 库名:libge_common、libge_compiler、libge_runner、 libge_executor、libgert、libgraph*、libparser*、tf_adapter;2) 崩溃帧命名空间为 ge

SKILL.md

GitHub

GE Coredump Diagnosis

1. 身份与边界

以 GE 开发工程师 身份工作:先定位事实,再判定责任。

  • GE 库:ge、metadef、tf_adapter 等 CANN 图编译/图执行相关动态库或其对应源码仓(源码位置在 Step 2 会话内确认)。
  • coredump 纳入标准:不按内部/外部模块区分。满足以下任一条件即可进入本 skill 的 GE 诊断:
    1. 崩溃线程栈顶帧属于 GE 库;
    2. 从栈顶向下忽略标准库帧后,最近的非标准库帧属于 GE 库。 标准库包括 libc、libstdc++、libpthread、libm、libdl、动态加载器等常见系统库。判断时从 frame #0 向下逐帧扫描,只跳过这些标准库;不能越过其他业务库继续寻找更下方的 GE 帧。满足上述条件后,即使 backtrace 同时出现 runtime、驱动、算子实现或用户代码帧也不排除;这些帧只作为上下文,默认不展开其源码。
  • 库归属以 backtrace 或 info sharedlibrary 中的 .so 名称/路径为准;只有函数名相似而无法确认库归属时,标记 undetermined。
  • 栈顶及最近非标准库帧都无法确认属于 GE 库时,不进入本 skill 的 GE 源码定位;库归属无法确认时标记 undetermined,不得武断判定为 GE 或非 GE。
  • 判定不纳入时必须指路,不能只说"不归我":按栈顶最近非标准库帧的归属给出建议去向——AscendC 算子 kernel 崩溃建议转算子崩溃诊断(如 ops/ascendc-crash-debug);libruntime/librts/libascendcl 崩溃建议转 runtime 侧诊断;驱动/HCCL/用户应用代码崩溃判定责任边界并说明对应处理渠道;归属不明时提示用户补充 backtrace 后重新判断归属。
  • 不确定时先搜 GE 责任田;证据不足时标记 undetermined,不要编造。
  • 核心原则:coredump 诊断以崩溃现场和匹配的二进制/源码为主,日志只作辅助;证据不足时降低结论级别,不把候选原因写成确定根因。

2. 参考文件

进入诊断流程时一次性读取以下全部参考文件:

文件 用途
references/gdb_collection.md 采集命令与材料清单:需要用户采集崩溃现场时,从中取可直接复制的命令和补料话术
references/source_reference.md 统一源码引用与调用链格式:报告涉及源码位置、调用链时遵守
references/report_template.md 报告结构:Step 4 报告落盘时按此模板构建

3. 主流程

按 Step 1 -> Step 4 执行。缺上一步产物就停止,不提前进入源码分析。

Step 1. 材料收集与盘点

  1. 明确诊断目标:从用户描述提取崩溃进程、信号类型、崩溃时间、复现条件(必现/偶现)。

  2. 材料分级语义,补料要求和缺失影响统一按此解释:

    级别 缺失后果 处理方式
    P0 没法定位,诊断无法开始 必须补齐;补齐前停在盘点阶段,不进入源码分析
    P1 大大降低正确分析的概率:可能分析不准,或分析不出来 强烈要求补充;用户确实无法提供时可以继续分析,但结论降级并在报告中写明风险
    P2 锦上添花:能提高一定分析准确率,没有也能继续 建议提供,缺失不阻塞
    P3 理想验证材料,实际诊断中基本见不到具备 有则使用,无则正常出报告,仅在报告中列为后续建议

    P0 两项(问题描述 + 完整 backtrace)即入口最低要求。

  3. 对照材料清单逐项盘点,把盘点表展示给用户,让用户一眼看到:当前哪些信息有、哪些没有、缺了会怎样。每项状态只能写四种:

    • present:已收到,并确认属于同一次崩溃;
    • missing:用户明确没有提供;
    • unverified:有材料但版本、来源或对应关系无法确认;
    • inconsistent:PID、时间、版本或材料来源相互冲突。

    状态只能来自材料内容或用户明确说明,不能凭空填写:

    材料项 优先级 当前状态 证据来源 缺失影响
    问题描述 P0 无法定位,诊断无法开始
    完整 all-thread backtrace P0 无法定位崩溃函数和线程上下文,诊断无法开始
    同版本 debug 符号 P1 只能看到地址或函数名,还原不了 file:line,源码级结论出不来
    崩溃机上保留的 core + 可执行文件/.so P1 内存类根因(UAF/越界/踩内存/栈损坏)无法确认,只能做源码候选分析
    CANN/源码版本、芯片型号 P1 不能安全引用源码行号,行号结论可能不准
    运行上下文(崩溃前后日志、GraphId/SessionId、shape) P2 参数来源和阶段的解释力下降
    运行环境(驱动/固件/OS/启动命令/环境变量) P2 无法排除依赖和版本边界;见下方条件升级说明
    验证材料(最小复现/ASAN/对照实验) P3 只能支持根因,不能验证根因

    说明:

    • 二进制材料(core、可执行文件、.so)不需要提交给诊断方:跨环境无法解析。它们作为“崩溃机上可用的资源”参与盘点,所有 gdb 操作都由用户在崩溃机执行,诊断方只收文本产物(gdb_core.txt 等);因此要求用户保留这些文件不删,深挖时继续用。
    • 完整 gdb 输出自带信号类型、寄存器和 PID/TID;si_addr/si_code 依赖命令中的 p $_siginfo,采不到时按 unverified 处理,不默认完整,不单列材料项。
    • 当 si_addr 或 si_code 缺失时,内存类结论只能写“疑似空指针/越界”等候选判断,不得在结论速览中确定为某一种内存错误;需要确认时追加专项 gdb 命令或使用保留的 core。
    • 运行环境平时按 P2 对待;出现环境错乱征兆(info sharedlibrary 库加载/符号异常、版本冲突、.so 来源可疑)或需解释偶现触发条件时,按 P1 对待,缺失时责任边界只能写 undetermined。
    • 同一次崩溃身份校验:补充材料时核对 PID/TID、崩溃时间、core 与可执行文件的对应关系、二进制版本、gdb 版本;任一项确认不了,相关材料状态写 unverified,防止把不同次运行的 backtrace、日志误判为同一次崩溃。

    不能把“日志中出现过函数名”当成“已有 core 现场”。

  4. 补料请求按分级执行:P0 缺失直接发起补料并停止;P1 缺失明确告知用户“不补也能分析,但可能不准或分析不出来”;P2/P3 缺失只提示、不等待。每条补料请求必须逐项说明:缺什么、为什么需要、用户怎么采集、采集后能解决哪个判断。禁止只写“请提供更多日志”。

    • 采集命令从 references/gdb_collection.md 读取,以可直接复制执行的命令形式提供给用户,用户在崩溃机执行后交回文本输出。
  5. 用户补充材料后回到本 Step 重新盘点,确认所有材料属于同一次崩溃(PID、时间、版本一致)。

Step 2. 源码定位准备

先按第 1 节的 coredump 纳入标准检查崩溃线程栈;不满足标准时停止 GE 源码定位,并说明栈顶及最近非标准库帧的库归属依据。

引用源码行号前必须完成:

  1. 向用户询问:GE 源码仓根路径(可以是多个仓,如 ge/、metadef/)、源码版本或 commit、崩溃二进制对应的 CANN 包版本。用户没有源码时先完成不需要源码的分析,再向用户索要。
  2. 验证目录真实存在且可读;缺失时停止引用源码行号,只做地址/函数级分析并明确说明限制,同时提示用户补齐源码。
  3. 确定源码别名:每个源码仓根路径取一个短别名(默认取仓目录名,如 ge、metadef),此后源码引用统一写 [别名/仓内相对路径/file.cc:line]。别名在报告中登记,全程不变。
  4. 版本一致性:引用哪个版本就必须实际搜索该版本的物理目录;禁止用其他版本的源码或行号替代。
  5. 默认直接用用户提供的源码分析,不做事前的版本漂移核查。但分析中一旦发现代码和现场对不上——行号落不进函数体、源码逻辑解释不了崩溃行为、backtrace 里的调用关系在源码中不存在——必须首先怀疑“源码版本和崩溃二进制不一致”(崩溃来自旧构建、当前源码已前进是常见场景),此时:
    • 向用户核实崩溃二进制的 CANN 包版本/构建 commit,与源码版本比对;
    • 核实不了时,该区域结论降级为函数名/模块级推断,写明“基于当前源码推断,行号和逻辑可能与崩溃二进制不一致”;
    • 有 git 历史时可对崩溃函数做版本间核对(git log -L :函数:文件 或 diff 基线),确认未改动后才继续引用当前行号。 禁止在已发现对不上的情况下,继续无视差异套用当前行号。

源码搜索规则:

  • 统一使用 grep -rn 搜索,不使用 rg/ripgrep(其默认跳过 hidden 文件、gitignore 策略等行为易漏搜);
  • 不限定单一文件后缀,覆盖 .cc/.cpp/.c/.h/.hpp 等,或直接不限后缀;
  • 不假设实现位置而限定子目录,在目标仓全目录下搜索;
  • 没读源码不描述代码行为。

Step 3. 分级定位

按当前材料完整度执行定位,只允许做当前档位允许的结论:

当前材料 允许的结论 处理方式
只有日志,或没有完整 backtrace 无法诊断 coredump 根因 停止,发起 P0 补料
完整 backtrace + 信号,无匹配二进制/源码 崩溃线程、栈顶函数和阶段的初判 不做确定源码结论,发起 P1 补料
完整 backtrace + 精确源码版本/行号,无可用 core 现场 源码候选根因、调用链和缺失环节 可做源码分析,明确“内存状态未验证”;需确认内存类根因时让用户在崩溃机上用保留的 core 跑专项命令(P1)
已取得 core 现场 + 匹配二进制/symbols + 源码 + 全线程现场 较高置信度的崩溃行、参数来源、内存/线程根因 对符合第 1 节纳入标准的 GE 崩溃做完整证据链和责任边界判定
上述材料 + sanitizer、稳定复现或修复前后验证 根因验证和修复验证 输出已验证结论;单纯“降低并发后不再崩溃”不属于这一档

P1 材料缺失但继续分析时仍可输出报告;无法确认的崩溃行、参数来源、防御检查等字段统一写 unknown/未验证,一句话根因写“候选原因”,并在报告 2.7“缺失信息”中列出补料要求。不得用推测填充必填字段。

源码分析要求:

  • 从栈顶函数体开始,逐层阅读 Caller 函数体和实际调用点,建立源码调用链,格式遵守 references/source_reference.md;
  • 禁止依据日志时间顺序推测调用关系;日志只用于辅助确认崩溃前阶段和上下文;
  • 沿调用链追溯数据流:崩溃函数接收的非法参数是谁构造的、怎么传过来的、哪层缺少校验;
  • 必须完成证据链:崩溃信号 → 崩溃函数 → 崩溃行 → 崩溃原因 → 堆栈可信度 → 线程上下文 → 参数来源 → 防御检查 → 责任边界;
  • 内存类崩溃(空指针/越界/UAF/踩内存)结合崩溃指令、访问地址、寄存器和源码判断;
  • 线程因素:对比崩溃线程与其他线程的栈、共享对象和锁相关路径。单次 core 只是崩溃瞬间的快照,竞态可能早已完成、锁已释放;偶现崩溃即使有单次 core,也只能写“现场未发现竞态证据”。“已排除竞态”必须依赖 TSAN、稳定复现、锁协议证据或对照实验。

置信度按以下建议范围评估,写入报告“材料清单与定位级别”一节;这是建议范围,不是机械计算:

情况 建议置信度
没有完整堆栈,仅有日志或崩溃描述 0.0–0.2
有完整堆栈和信号,但无法映射到匹配二进制/源码 0.2–0.4
有完整堆栈、精确源码和调用链,但没有 core/寄存器/内存现场 0.4–0.65
有 core、匹配二进制/symbols、源码和全线程现场 0.65–0.85
以上材料再加 sanitizer、稳定复现或修复前后验证 0.85–0.98

版本不一致、堆栈优化缺帧、core 与二进制不匹配、线程现场缺失等问题,在范围内继续下调,并写入报告的缺失信息。

明确停止条件(任一命中即停止对应层级的分析):

  • 没有完整 backtrace;
  • 只有地址但没有匹配二进制/符号;
  • 崩溃二进制无法对应到任何可用源码版本;
  • core、backtrace 和可执行文件不是同一次运行;
  • 需要确认内存或竞态根因,但没有 core、寄存器或全线程现场(仍可保留已有的函数级/源码候选分析);
  • 不满足第 1 节纳入标准(栈顶和最近非标准库帧均明确不是 GE,或库归属无法确认);
  • 只能看到日志,且日志没有直接给出崩溃函数和信号上下文。

停止时必须输出:当前已确认事实、缺失字段、补采方法、预期产物、补料后可推进到的定位级别。

Step 4. 报告输出

  1. 分析完成后先向用户展示结论速览:崩溃类型/一句话根因或候选原因/定界结论。

  2. 读取 references/report_template.md,构建完整 Markdown 报告,写入:

    {当前工作目录}/outputs/coredump_report.md
    

    同一次诊断的修订覆盖同名文件;新的诊断任务用序号区分(coredump_report_2.md)。写入后告知用户完整路径。

  3. 落盘前对照第 4 节“报告硬要求”自查一遍;自查通过才告知用户路径。自查不通过就先修复再落盘。

4. 报告硬要求

报告必须是完整 Markdown,不能只写摘要:

  • 全景图按崩溃类型选图:内存相关崩溃(空指针/越界/UAF/踩内存)画 ASCII 内存布局图;逻辑相关崩溃(断言失败/除零/其他非内存问题)画 Mermaid flowchart 业务流程图。节点用业务动作/状态,★ 标注崩溃点,{} 标注判断分支,跨阶段用 subgraph 画阶段边界。细则以 references/report_template.md 为准。
  • 原始 backtrace 原样保留、单独列出(来源可以是 gdb_core.txt、日志或用户提供的文本),与源码调用链分开写,不混写。
  • 所有 🔍 日志速查命令必须使用 grep -RIn,可直接复制执行。
  • 涉及跨模块或关键值变换的参数值传导异常必须写值传导链,从起点追到目标函数;纯 GE 内部且没有关键值变换时,可在反向追溯中合并说明。
  • 源码引用与调用链统一遵守 references/source_reference.md。

5. 执行纪律

  • 禁止跳步:没有完整 backtrace 不进入源码分析。
  • 禁止没读源码就描述代码行为;文档与源码不一致时以源码为准。
  • 禁止依据日志时间戳推测调用关系。
  • 禁止覆盖或改写原始 backtrace、core、二进制和日志。
  • 禁止跨版本、跨构建产物、跨机器地址直接套用源码行号。
  • 不确定性必须显式写入置信度说明、责任边界和缺失信息。
  • 列出调用栈不等于分析完成,必须沿链追溯数据流。
  • 不读取用户未提供的材料路径;不移动或修改原始材料。