1. 概述

本文档介绍了曦云®系列GPU EID，旨在帮助开发人员、FAE和系统管理员理解信息具体的含义，以达到分析和解决GPU相关问题的目的。

1.1. 什么是EID消息

EID（Error Message ID）是沐曦GPU上运行 MXMACA® 异构程序的错误报告，打印在系统的内核日志或系统日志中，分为Driver EID和SDK EID。

EID代表发生了常规 GPU 错误，通常是由于MXMACA异构程序错误地对 GPU 进行编程或发送到 GPU 的命令损坏。这些消息可能表示硬件问题、MXMACA平台软件问题或用户在MXMACA平台上开发的应用软件问题。每条消息的含义在MXMACA软件栈版本之间是一致的。

1.2. 如何使用EID消息

EID主要为调试用途。由于许多问题可能有多个可能的根本原因，因此无法仅从 EID 本身提供的信息来了解所有问题。当用户发现问题时，可用mx-report工具来收集所有的日志信息，便于综合分析。

2. EID格式

2.1. EID通用格式

EID日志打印格式：

LOGLEVEL EID([device id]):[Error Code],[Descrition],[Recover Suggestion],[Error Data]
表 2.1 EID字段说明

编号

字段

说明

1

LOGLEVEL

表示日志等级，定义参见表 2.2

2

device id

发生EID错误的GPU设备PCIe DBDF号，如0000:0e:00.0

3

Error Code

错误码

4

Description

该EID错误的简要描述信息

5

Recover Suggestion

可选，可能的修复方案

6

Error Data

可选，错误相关的数据，可以帮助进一步的问题诊断
表 2.2 日志等级说明

编号

LOGLEVEL

说明

1

EMERG

紧急错误，系统不可用

2

ALERT

告警错误，需要立即处理

3

CRIT

严重错误

4

ERROR

一般错误

5

WARN

告警提示

6

INFO

普通信息

7

DEBUG

调试信息

2.2. Driver日志格式

在Linux系统中，GPU KMD内核驱动打印日志通常会放在 /var/log/messages路径下，通过以下命令可以查看GPU KMD打印的错误信息：

sudo grep -P "METAX.*ERROR|MXCD.*ERROR|MXGVM.*ERROR" /var/log/messages

备注

Linux内核日志存放路径会因Linux发行版本不同而有所区别，主流Linux发行版内核日志存放路径如下：

Ubuntu： /var/log/kern.log

CentOS： /var/log/messages

如果存在GPU KMD内核驱动错误记录，比如ATU Fault，会得到类似如下日志：

[…] METAX.B10200.ATU.ERROR EID (xxxx:xx:xx.x): 0x2101, atu 0x0 pde_base_addr 0x50016c0000

[…] METAX.B10200.ATU.ERROR EID (xxxx:xx:xx.x): 0x2101, xpid 1 vfid 0 vf 0 page va 224200000

[…] METAX.B10200.ATU.ERROR EID (xxxx:xx:xx.x): 0x2101, hwip DMAW0 fault code(7) perm code: 2

2.2.1. Driver日志正文打印格式

MODULE.DBDF.SUBMOD.LOGLEVEL EID([device id]):[Error Code],[Descrition],[Recover Suggestion],[Error Data]

其中 MODULE.DBDF.SUBMOD 为Driver特有字段。LOGLEVEL 之后字段说明参见 2.1 EID通用格式。

表 2.3 Driver日志特有字段说明

编号

字段

说明

1

MODULE

打印日志的主模块，目前包括 METAX、MXCD 和 MXGVM

2

DBDF

日志所属的GPU卡的PCIe DBDF（Domain Bus Device Function）

格式为 BXXXX，XXXX 为PCIe DBDF的16进制编码。其中，bits[31:16] 为Domain，bits[15:8] 为Bus，bits[7:3] 为Device，bits[2:0] 为Function

3

SUBMOD

打印日志的子模块，根据主模块的不同，子模块的具体定义也不一样

2.3. SDK日志格式

在Linux系统中，GPU SDK EID打印日志默认存放在 /var/log/syslog 路径下，通过以下几种方法可以查看GPU SDK EID打印的错误信息。

备注

Linux内核日志存放路径会因Linux发行版本不同而有所区别，主流Linux发行版内核日志存放路径如下：

Ubuntu： /var/log/syslog

CentOS： /var/log/messages

  1. 实时查看：使用以下命令可以实时查看日志文件的最新内容

    sudo tail -f /var/log/syslog

  2. 过滤特定日志：使用以下命令可以查找包含特定关键词的日志，例如“error”

    sudo grep "error" /var/log/syslog

  3. 分页查看：使用以下命令可以分页查看日志文件

    sudo less /var/log/syslog

如果存在SDK EID错误记录，比如执行用户进程 eidNumericTrap 出现核函数除零错误，会得到类似如下日志：

./eidNumericTrap

sudo tail -f /var/log/syslog

……

Jun 4 15:22:36 myhostname maca:[406708.798499]SDK.0203300X.UMD.WARN EID(0000:0a:00.0):0x3111,(eidNumericTrap)Divide 0,check app kernel, ZL16kernel_data_copyPfs

syslog 日志遵循标准格式，每条记录包含以下字段：

  • 时间戳：记录事件发生时间（如 Jun 4 15:22:36）。

  • 主机名：生成日志的主机名或IP地址（如 myhostname）。

  • 服务名：产生日志的服务或程序名称，MXMACA SDK的服务名固定为 maca。

  • 程序ID：产生日志的进程ID和线程ID（如 :[406708.798499]）。

  • 日志正文：消息内容，描述具体事件或错误信息。

2.3.1. SDK日志正文打印格式

PACKAGE.VERSION.SUBPACK.LOGLEVEL EID([device id]):[Error Code],[Descrition],[Recover Suggestion],[Error Data] MODULE.DBDF.SUBMOD.LOGLEVEL CONTENT

其中 PACKAGE.VERSION.SUBPACK 为SDK特有字段。LOGLEVEL 之后字段说明参见 2.1 EID通用格式。

表 2.4 SDK日志特有字段说明

编号

字段

说明

1

PACKAGE

打印日志的软件发布包名，目前只包括 SDK

2

VERSION

打印日志的软件发布包版本， 内容为 mx-smi 命令显示的 MACA Version 信息。从左到右的数字含义依次为 X.Y.Z.build_id

左起1-2位为软件架构版本X（如 02 表示MXMACA2.0）

左起3-5位为该软件架构版本发布开始的第Y个版本，从0开始计数（如 02033 表示MXMACA2.33）

左起第6位为第Y个版本的分支Z（如 020330 表示 MXMACA2.33.0）

左起7-8位为基于X.Y.Z的构建数量，从0开始计数（如 02033017 表示 MXMACA2.33.0.17）

3

SUBPACK

打印日志的软件发布包子模块，目前只包括 UMD

3. EID日志收集方法

3.1. 通用收集方法

表 3.1 EID通用收集方法

编号

方法

说明

1

mx-report工具

可执行 sudo mx-report 收集GPU所有模块日志。

mx-report工具的使用方法参见《曦云®系列通用计算GPU用户指南》。

2

mx-exporter工具

mx-exporter通过指标 mx_driver_eid_errors 收集Driver EID相关日志，指标 mx_sdk_eid_errors 收集Driver EID相关日志。

mx-exporter 工具的使用方法参见《曦云®系列通用计算GPU mx-exporter使用手册》。

3.2. Dirver日志收集方法

Driver日志收集方法参见表 3.2：

表 3.2 Driver日志收集方法

编号

方法

说明

1

dmesg命令

Linux系统通用命令，只能查看当前运行时内核日志信息。同时由于Linux内核日志缓存区大小限制，可能无法显示当前运行时内核的完整日志。

命令如下：

sudo dmesg | grep -P "METAX.*ERROR|MXCD.*ERROR|MXGVM.*ERROR"

2

journalctl命令

基于systemd启动的Linux系统上的强大日志工具，没有dmesg命令的内核日志缓存区限制问题，还可以查看系统的历史运行日志。

命令如下：

sudo journalctl -k -b 0 | grep -P "METAX.*ERROR|MXCD.*ERROR|MXGVM.*ERROR"

3

/var/log/message 或 /var/log/kern.log 文件

Linux系统内核日志在磁盘存放位置，用户需要注意收集的内核日志是否属于当前系统运行时日志，还是系统以前运行的历史日志。

CentOS系统命令如下：

sudo grep -P "METAX.*ERROR|MXCD.*ERROR|MXGVM.*ERROR" /var/log/messages

Ubuntu系统命令如下：

sudo grep -P "METAX.*ERROR|MXCD.*ERROR|MXGVM.*ERROR" /var/log/kern.log

3.3. SDK日志收集方法

MXMACA SDK日志收集方法参见表 3.3。

本节以Ubuntu系统为例，下列为收集时的注意事项：

  1. 日志文件可能很大，考虑压缩后再传输（gzip /var/log/syslog）。

  2. 确保有足够的权限访问日志文件（通常需要 root 权限）。

  3. 定期清理旧日志，避免磁盘空间不足。

  4. 敏感信息可能存在于日志中，传输时考虑加密。

  5. 对于持续收集，建议设置日志轮转策略。

表 3.3 SDK日志收集方法

编号

方法

说明

1

直接复制文件 /var/log/syslog

最简单的方法是直接复制文件：

cp /var/log/syslog/path/to/destination/

或者使用 scp 传输到远程服务器：

scp /var/log/syslog user@remotehost:/path/to/destination/

2

journalctl命令

基于systemd启动的Linux系统上的强大日志工具，可以查看系统的历史运行日志。命令如下：

sudo journalctl -k -b 0 | grep -P "maca" > maca.log

sudo journalctl --since "2025-06-01" --until "2025-07-01" > logs_jun1.log

3

rsync 同步

使用 rsync 同步：

rsync -avz /var/log/syslog user@remotehost:/path/to/destination/

4

logrotate 管理

配置 /etc/logrotate.conf 或 /etc/logrotate.d/ 下的配置文件，可以自动管理日志文件大小和备份：

sudo logrotate -f /etc/logrotate.conf

5

使用系统日志服务 (rsyslog/syslog-ng)

  • rsyslog 配置

    编辑 /etc/rsyslog.conf 或 /etc/rsyslog.d/ 下的配置文件：

    & /path/to/collect/syslog.log
& @remotehost:514

    重启服务：

    systemctl restart rsyslog

  • syslog-ng 配置

    编辑 /etc/syslog-ng/syslog-ng.conf：

    destination d_remote {
  udp("remotehost" port(514));
};
log {
  source(s_src);
  destination(d_remote);
};

    重启服务：

    systemctl restart syslog-ng

4. EID错误列表

下表展示了EID 错误类型、可能原因、影响及修复建议，供用户参考。

表 4.1 EID错误列表

EID

可能原因

影响

修复建议

0x1101

EEPROM数据校验出错

固件中存储的参数可能出错

联系售后维修

0x1102

寄存器访问违反安全策略限制

软件的寄存器操作未成功

检查软件中是否有对寄存器的越权访问

0x1103

主flash损坏，从备用flash启动

无直接影响，固件会自动修复

不需要修复

0x1104

board自检异常，或初始化失败

业务无法运行

检查使用的VBIOS是否正确

0x1105

芯片硬件配置信息校验出错

业务无法运行

检查使用的VBIOS是否正确

0x1106

VR芯片固件版本校验出错

芯片性能可能受影响

尝试更新VR固件

0x1107

PHY固件SRAM数据校验出错

PCIe链路可能会出现异常

联系售后维修

0x1108

光模块被拔出，或光链路异常

光口通信可能出现异常

检查光口物理连接

0x1109

slave die flash损坏，尝试修复

无直接影响，固件会自动修复

不需要修复

0x2101

  1. 页表所在HBM不稳定

  2. KMD页表管理逻辑出错

  3. 非法VA或者越界访问

业务发生异常

使用非法VA或者越界访问，用户定位代码是否非法使用地址，其他原因报bug给硬件厂商处理

0x2102

error_type xxx：表示触发了哪种类型的XCORE shader error

  • 0x1：fwe_err

  • 0x2：illegal_inst

  • 0x4：mem_viol (non align access)

  • 0x8：xnack_error

  • 0x10：out_of_range

  • 0x20：fuc_error

  • 0x40：timeout_error

发生异常进程结束

  • 若error type = 1，即fwe error，一般是卡内部SRAM没有初始化导致，报bug给硬件厂商

  • 若error type = 2，即非法指令，确保用户编写的kernel函数正确并且编译器正确使用，如果无法解决，报bug给硬件厂商

  • 若error type = 4，即memory violation，一般是非对齐访问导致的，检查用户编写的kernel函数

  • 若error type = 8，即xnack error，会有对应的ATU fault触发，根据提示信息进一步调试，参见EID(0x2101)的描述

0x2103

GPU内部资源释放失败

应用程序结束过慢或者卡住

尝试warmreset或重启服务器进行恢复，仍无法解决报bug给硬件厂商

0x2104

HBM显存出现坏页

坏页隔离失败会发生异常结束进程

  • 遇到HBM显存坏页错误，可以尝试将业务进程全部退出，重新执行业务。若重新执行业务还会遇到同样的坏页错误，可以尝试warm reset或重启服务器进行恢复

  • GPU HBM内存颗粒有问题，可以尝试换卡

0x2105

在GPU内核驱动加载或者卸载过程中，用户正在尝试通过SMI接口访问GPU相关资源

SMI信息获取失败

在GPU内核驱动加载或卸载完成后，再执行GPU业务操作

0x2106

导致这个问题的原因比较复杂，需要结合软硬件环境综合判断

KMD与SMP通讯失败导致驱动加载失败或者SMI获取信息失败

联系硬件厂商解决

0x2107

PCIe bar空间不够

设备枚举异常，驱动无法加载

  • 修改服务器BIOS，启用large BAR功能，有些服务器选项为启用超过4GB PCI地址空间，具体可联系硬件厂商确认

  • 若启用large BAR无法解决问题，则需确认VBIOS是否启用了VF BAR导致服务器PCI空间不够，联系硬件厂商解决

0x2108

UMD申请内存使用的VA有重叠，KMD会检测每个进程各GPU VA到PA的entry映射是否与其他entry有重复（包括部分重复），一旦检测到GPU VA到PA存在多重映射，KMD 日志就会记录冲突地址，标记当前映射失败，并返回错误码

业务执行失败

联系硬件厂商解决

0x2109

GPU应用程序使用了过多的HBM显存或者GPU SDK存在内存管理相关问题

业务执行失败

  • 应用程序使用过多的显存，需要减少对HBM显存过多申请或者及时释放没用的HBM显存

  • GPU SDK存在内存管理相关问题，可以联系硬件厂商解决

0x210A

GPU应用程序使用了过多的系统内存或者GPU SDK存在内存管理相关问题

业务执行失败

  • 应用程序使用过多的系统内存，需要减少对系统内存过多申请或者及时释放没用的系统内存

  • GPU SDK存在内存管理相关问题，可以联系硬件厂商解决

0x210B

GPU触发INT中断和CPU处理中断的过程是异步的，当GPU触发INT中断消息的速度超过CPU处理中断的速度，会出现GPU驱动的中断FIFO队列溢出问题

出现丢中断，影响业务执行

确认CPU是不是运行在最高频率，通过 cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor，确认是否为performance模式；如果不是，则执行 echo performance > /sys/devices/system/cpu/cpu<x>/cpufreq/scaling_governor 命令切换为performance模式，其中 <x> 为所有CPU的index。

如果还有问题，请联系硬件厂商。

0x210C

GPU卡PCIe通讯链路不稳定或者服务器PCIe相关配置不对

业务异常或者不可靠

链路不稳定可以尝试重新插拔GPU卡或者更换PCIe板卡。

需要联系硬件厂商和服务器厂家分析PCIe AER产生的原因。如果是偶尔发生这种情况，可以尝试warm reset或重启服务器进行恢复。

0x210D

前面执行业务异常导致GPU通讯断开或者硬件问题导致

GPU设备无法访问

硬件问题可以尝试更换PCIe slot或者GPU卡进行测试。

需要联系硬件厂商和服务器厂家分析PCIe通讯断开产生的原因。如果是偶尔发生这种情况，可以尝试warm reset或重启服务器进行恢复。

0x210E

IP发生Fatal error或者uncorrectable error

发生异常业务退出

可能是IP发生了Fatal Error或者Uncorrectable Error，可以先尝试warmreset或重启服务器进行恢复。如果还是会重现这个错误，则需要换卡进行测试。

需要联系硬件厂商分析造成syncflood的IP发生错误的原因。

0x210F

硬件发生RAS异常

发生异常业务退出

可能是硬件问题，可以先尝试warm reset或者重启服务器进行恢复。如果还是会重现这个错误，可以尝试更换GPU卡进行测试。

需要联系硬件厂商分析RAS ERROR产生的原因。

0x2201

GPU内部资源释放失败

应用程序结束过慢或者卡住

GPU内部任务调度失败，报bug给硬件厂商，然后尝试warm reset或重启服务器进行恢复

0x2202

一般是软件传参非法或者条件不满足导致

业务发生异常

该问题需要结合实际环境配置和报错信息综合判断原因

0x2301

服务器MMIO空间不够

驱动加载失败

确认服务器BIOS是否有MMIO空间相关配置选项，如果有，建议将MMIO空间配置到最大

0x2302

GPU驱动与SMP通讯失败

驱动加载失败或者SMI获取信息失败

  1. 初步排查，使用 lspci -s DBDF -x 命令测试GPU卡的PCIe configure space能否继续访问（DBDF为故障卡的PCIe DBDF）

    • 如果命令返回全f数据，则表示GPU卡PCIe基本通路有问题，建议按照步骤2排查硬件问题

    • 如果命令返回有效值，则表示GPU卡PCIe基本通路正常，建议按照步骤3排查GPU VBIOS软件问题

  2. 排查硬件相关问题，比如GPU卡与服务器的接插件的连接是否良好，断电后重新插拔GPU卡、更换PCIe slot或更换GPU卡

  3. 排查GPU VBIOS软件问题，通过mx-report工具抓取GPU卡状态信息，然后报告给硬件厂商

0x2303

GPU卡的VBIOS固件版本与当前GPU驱动不兼容

业务无法使用GPU设备

可以尝试升级与GPU驱动兼容的VBIOS版本

0x2304

GPU卡不支持SRIOV虚拟化

驱动加载失败

GPU卡不支持SRIOV功能，使用 lspci -s DBDF -vvv 命令查看GPU卡是否有SRIOV能力（DBDF为故障卡的PCIe DBDF），如果不支持SRIOV能力，则需要升级为支持SRIOV的VBIOS版本

0x2305

服务器BIOS是否开启SRIOV相关配置且MMIO空间不够或者GPU VBIOS版本与服务器不匹配

驱动加载失败

  • 服务器BIOS是否开启SRIOV相关配置，MMIO空间是否开启到最大

  • 确认GPU VBIOS版本是否与服务器匹配，可以尝试升级为SRIOV MMIO空间需求更小的VBIOS版本

0x2306

服务器BIOS未开启SRIOV相关配置

驱动加载失败

  • 服务器BIOS是否开启SRIOV相关配置，如果有SRIOV配置选项，则将SRIOV配置打开

  • 用mx-report工具收集VBIOS运行日志，并报告给硬件厂商

0x2307

GPU硬件或者VBIOS固件问题

FLR复位失败

用mx-report工具收集VBIOS运行日志，并报告给硬件厂商

0x2308

可能之前业务执行异常导致GPU通讯断开或者硬件问题

GPU设备无法访问

  • 可能是前面执行业务异常，导致GPU通讯断开，可从之前最开始出现错误的地方排查

  • 可能是硬件问题，可以尝试更换PCIe slot或GPU卡进行测试

0x2309

  1. 页表所在HBM不稳定

  2. KMD页表管理逻辑出错

  3. 非法VA或者越界访问

业务发生异常

使用非法VA或者越界访问，用户定位代码是否非法使用地址，其他原因报bug给硬件厂商处理

0x3101

核函数在寄存器初始化前读取寄存器

用户进程因GPU致命异常退出

  • 若更新MXMACA SDK版本后发生，可先回退MXMACA SDK版本，报bug给硬件厂商处理

  • 若首次出现，可尝试MXMACA SDK的不同版本，报bug给硬件厂商处理

0x3102

核函数指令的编码或操作数有误，GPU硬件检测到非法指令

  • 若更新MXMACA SDK版本后发生，可先回退MXMACA SDK版本，报bug给硬件厂商处理

  • 若首次出现，可尝试设置环境变量保护GPU rodata段（export MACA_DEVICE_IMAGE_MALLOC_MODE=1）后，再次运行用户进程。如果问题不能解决，报bug给硬件厂商处理

0x3103

核函数访问内存的偏移量小于0，越界或数据未按要求对齐

EID打印的核函数所属软件模块定位分析：review核函数代码，可借助MXMACA SDK的trap工具和打印详情辅助分析，也可以到沐曦开发者社区寻求更多帮助

0x3104

核函数使用的VA地址有误

0x3105

寄存器访问越界，例如在只分配16个STREG时访问第17个STREG触发

0x3106

硬件极小概率的电磁干扰引起的，瞬间就会恢复

检修设备周围的电磁环境

0x3107

核函数执行时间超过了 MACA_KERNEL_TIMEOUT 设定的时间，GPU shader根据超时设置停止执行

EID打印的核函数所属软件模块定位分析：review核函数代码，可借助MXMACA SDK的trap工具和打印详情辅助分析，也可以到沐曦开发者社区寻求更多帮助

0x3111

核函数存在除零操作（divide 0）

GPU因Numeric异常短暂停止服务，相关信息收集完毕后，用户程序继续执行。

说明：这部分EID仅在开启Nemeric异常（ export MACA_TRAP_HANDLER=2），才会在执行相关问题的核函数时触发SDK EID打印。

EID打印的核函数所属软件模块定位分析：review核函数代码，可借助MXMACA SDK的trap工具和打印详情辅助分析，也可以到沐曦开发者社区寻求更多帮助

必要时使用精度和Loss异常分析与排查手段，包括但不限于：

  • 硬件层诊断：

    1）使用mx-smi检查GPU温度、功耗是否超限

    2）运行硬件诊断工具（如 mx-diagease）检测显存错误或PCIe/MetaxLink/IB/RoCE通信故障

  • 软件层数据检查：

    1）验证输入数据是否存在异常值（如文本中的 \0、图像中的全黑帧）

    2）检查数据预处理逻辑（如归一化分母为0、数据增强越界）

  • 软件层模型检查：

    1）使用 torch.autograd.detect_anomaly() 定位反向传播中的NaN来源

    2）检查自定义算子（如MXMACA Kernel）的数值稳定性（边界条件、除零风险）

  • 软件层优化器配置：

    1）降低学习率或启用梯度裁剪（torch.nn.utils.clip_grad_norm_）

    2）混合精度训练（AMP）中调整 loss_scale 防止溢出

  • 软件层设计检查与优化策略调整：

    1）数值稳定性设计，例如在损失函数中添加微小epsilon（如 x += 1e-8）避免除零，使用 torch.isnan(tensor).any() 在关键计算后主动检查张量等

    2）混合精度训练防护，例如启用AMP的 autocast 与 GradScaler，动态调整缩放因子

    3）数据预处理兜底，例如数据加载时强制 np.nan_to_num()，过滤异常样本

0x3112

核函数存在数据上溢

（data overflow）

0x3113

核函数存在数据下溢

（data underflow）

0x3114

核函数存在无效操作（invalid operation，如NaN/Not a Number，未定义或不可表示的值）

0x3115

核函数输入了非规约数

（input denormal）

0x3116

核函数数据出现了精度损失（Inexact）

0x3211

  1. 核函数死循环

  2. 并行流上的两个任务有依赖关系，被MXMACA SDK默认配置算法分配到同一个ring-buffer串行执行

  3. 核函数超时门限设置太低（误报）

用户进程可能Hang，可能需运维干预

根据EID打印的Hang详情日志文件定位分析

0x3212

  1. 硬件PCIe超时

  2. 数据拷贝超时门限设置太低（误报）