13. 异常处理
本章节描述 CANN Runtime 的异常处理接口，包括错误信息获取、异常回调注册、内存 UCE 修复及任务中止。
const char *aclGetRecentErrMsg()：获取并清空与本接口在同一个进程或线程中的其它acl接口调用失败时的错误描述信息。aclError aclrtSetExceptionInfoCallback(aclrtExceptionInfoCallback callback)：设置异常回调函数。若多次设置异常回调函数，以最后一次设置为准。aclError aclrtExceptionInfoCallbackRegister(aclrtExceptionInfoCallback callback)：注册进程级异常回调函数，支持注册多个不同的回调函数。aclError aclrtExceptionInfoCallbackUnregister(aclrtExceptionInfoCallback callback)：注销通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数。uint32_t aclrtGetTaskIdFromExceptionInfo(const aclrtExceptionInfo *info)：获取异常信息中的任务ID。uint32_t aclrtGetStreamIdFromExceptionInfo(const aclrtExceptionInfo *info)：获取异常信息中的Stream ID。uint32_t aclrtGetThreadIdFromExceptionInfo(const aclrtExceptionInfo *info)：获取异常信息中的线程ID。uint32_t aclrtGetDeviceIdFromExceptionInfo(const aclrtExceptionInfo *info)：获取异常信息中的Device ID。uint32_t aclrtGetErrorCodeFromExceptionInfo(const aclrtExceptionInfo *info)：获取异常信息中的错误码。aclError aclrtPeekAtLastError(aclrtLastErrLevel level)：获取当前线程的Runtime（运行时管理模块）错误码，仅获取但不清空错误码。aclError aclrtGetLastError(aclrtLastErrLevel level)：获取当前线程的Runtime（运行时管理模块）错误码，获取后清空当前线程的错误码，这时在线程中无新增错误码之前，调用本接口获取到的是ACL_SUCCESS。aclError aclrtGetMemUceInfo(int32_t deviceId, aclrtMemUceInfo *memUceInfoArray, size_t arraySize, size_t *retSize)：获取内存UCE（uncorrectable error，指系统硬件不能直接处理恢复内存错误）的错误虚拟地址。aclError aclrtMemUceRepair(int32_t deviceId, aclrtMemUceInfo *memUceInfoArray, size_t arraySize)：修复内存UCE的错误虚拟地址。aclError aclrtDeviceTaskAbort(int32_t deviceId, uint32_t timeout)：停止指定Device上的正在执行的任务，同时丢弃指定Device上已下发的任务。aclError aclrtGetErrorVerbose(int32_t deviceId, aclrtErrorInfo *errorInfo);：用于在发生设备故障后获取详细错误信息。此接口必须在获取故障事件之后，提交任务中止之前调用。aclError aclrtRepairError(int32_t deviceId, const aclrtErrorInfo *errorInfo)：基于aclrtGetErrorVerbose接口获取的详细信息进行故障恢复，此接口应该在提交任务中止之后调用。aclError aclrtSetDeviceTaskAbortCallback(const char *regName, aclrtDeviceTaskAbortCallback callback, void *args)：调用本接口注册回调函数，用于在调用aclrtDeviceTaskAbort接口前后触发该回调函数。
aclGetRecentErrMsg
const char *aclGetRecentErrMsg()
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取并清空与本接口在同一个进程或线程中的其它acl接口调用失败时的错误描述信息。
获取进程级别、还是线程级别的错误描述信息由aclInit接口中的err_msg_mode配置控制，默认线程级别。
建议在每次调用acl接口失败时都调用aclGetRecentErrMsg接口，以便获取调用acl接口异常时的错误描述信息，用于定位问题，否则可能导致错误信息堆积、丢失。同一个进程或线程中多次调用aclGetRecentErrMsg接口后，只有最后一次调用aclGetRecentErrMsg接口返回的错误描述字符串的指针有效，之前aclGetRecentErrMsg接口返回的错误描述字符串指针不能使用，否则可能导致内存非法访问。
参数说明
无
返回值说明
返回错误描述字符串的指针。如果通过本接口获取到多条错误描述信息，最上面的错误描述信息为最新的。
获取错误描述信息失败时，返回nullptr。
aclrtSetExceptionInfoCallback
aclError aclrtSetExceptionInfoCallback(aclrtExceptionInfoCallback callback)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
设置异常回调函数。若多次设置异常回调函数，以最后一次设置为准。该覆盖语义仅作用于通过本接口设置的回调函数，不影响通过aclrtExceptionInfoCallbackRegister接口注册的回调函数。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| callback | 输入 | 指定要注册的回调函数。 回调函数的函数原型为： typedef void (aclrtExceptionInfoCallback)(aclrtExceptionInfoexceptionInfo); |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
-
回调函数涉及共享资源（例如锁），因此在使用回调函数需慎重，在回调函数内调用资源申请&释放、Stream同步、Device同步、任务下发、任务终止等接口，可能会导致错误或死锁。
-
您需要在执行异步任务之前，设置异常回调函数，当Device上的任务执行异常时，系统会向用户设置的异常回调函数中传入一个包含任务ID、Stream ID、线程ID、Device ID以及错误码的aclrtExceptionInfo结构体指针，并执行回调函数，用户可以再分别调用aclrtGetTaskIdFromExceptionInfo、aclrtGetStreamIdFromExceptionInfo、aclrtGetThreadIdFromExceptionInfo、aclrtGetDeviceIdFromExceptionInfo、aclrtGetErrorCodeFromExceptionInfo接口获取产生异常的任务ID、Stream ID、线程ID、Device ID以及错误码，便于定位问题。
使用场景举例：例如，在调用aclopExecuteV2接口前，调用aclrtSetExceptionInfoCallback接口设置异常回调函数，当算子在Device执行异常时，系统会向用户设置的异常回调函数中传入一个包含任务ID、Stream ID、线程ID、Device ID以及错误码的aclrtExceptionInfo结构体指针，并执行回调函数。
接口调用流程
使用场景举例：执行整网模型推理时（不支持动态Shape场景），如果产生AI Core报错，可以按照本章的内容获取报错算子的描述信息，再做进一步错误排查。
推荐的接口调用顺序如下：
-
定义并实现异常回调函数fn(aclrtExceptionInfoCallback类型)。
实现回调函数的关键逻辑如下：
-
在异常回调函数fn内调用aclrtGetDeviceIdFromExceptionInfo、aclrtGetStreamIdFromExceptionInfo、aclrtGetTaskIdFromExceptionInfo接口分别获取Device ID、Stream ID、Task ID。
-
在异常回调函数fn内调用aclmdlCreateAndGetOpDesc接口获取算子的描述信息。
-
在异常回调函数fn内调用aclGetTensorDescByIndex接口获取指定算子输入/输出的tensor描述。
-
在异常回调函数fn内调用如下接口获取tensor描述中的数据，进行进一步分析。
例如，调用aclGetTensorDescAddress接口获取tensor数据的内存地址（用户可从该内存地址中获取tensor数据）、调用aclGetTensorDescType接口获取tensor描述中的数据类型、调用aclGetTensorDescFormat接口获取tensor描述中的Format、调用aclGetTensorDescNumDims接口获取tensor描述中的Shape维度个数、调用aclGetTensorDescDimV2接口获取Shape中指定维度的大小。
-
-
调用aclrtSetExceptionInfoCallback接口设置异常回调函数。
-
执行模型推理。
如果存在AI Core报错，则触发回调函数fn，获取算子的信息，进行进一步分析。
示例代码
以下是AI Core异常信息获取功能的关键步骤代码示例，不能直接拷贝编译运行，仅供参考。调用接口后，需增加异常处理的分支，并记录报错日志、提示日志，此处不一一列举。
......
// 1.模型加载，加载成功后，返回标识模型的modelId
// 2.创建aclmdlDataset类型的数据，用于描述模型的输入数据input、输出数据output
// 3.实现异常回调函数
void callback(aclrtExceptionInfo *exceptionInfo)
{
deviceId = aclrtGetDeviceIdFromExceptionInfo(exceptionInfo);
streamId = aclrtGetStreamIdFromExceptionInfo(exceptionInfo);
taskId = aclrtGetTaskIdFromExceptionInfo(exceptionInfo);
char opName[256];
aclTensorDesc *inputDesc = nullptr;
aclTensorDesc *outputDesc = nullptr;
size_t inputCnt = 0;
size_t outputCnt = 0;
// 用户可以将获取的算子信息写入到文件，或者另起线程，当发生异常回调时触发线程处理函数，在线程处理函数中将算子信息在屏幕上显示
aclmdlCreateAndGetOpDesc(deviceId, streamId, taskId, opName, 256, &inputDesc, &inputCnt, &outputDesc, &outputCnt);
// 可以调用tensor的相关接口，获取算子的相关信息，用户可以根据自己需要调用
for (size_t i = 0; i < inputCnt; ++i) {
const aclTensorDesc *desc = aclGetTensorDescByIndex(inputDesc, i);
aclGetTensorDescAddress(desc);
aclGetTensorDescFormat(desc);
}
for (size_t i = 0; i < outputCnt; ++i) {
const aclTensorDesc *desc = aclGetTensorDescByIndex(outputDesc, i);
aclGetTensorDescAddress(desc);
aclGetTensorDescFormat(desc);
}
aclDestroyTensorDesc(inputDesc);
aclDestroyTensorDesc(outputDesc);
}
// 4.设置异常回调
aclrtSetExceptionInfoCallback(callback);
// 5.执行模型
aclmdlExecute(modelId, input, output);
// 6.处理模型推理结果
......
// 7.释放描述模型输入/输出信息、内存等资源，卸载模型
......
aclrtExceptionInfoCallbackRegister
aclError aclrtExceptionInfoCallbackRegister(aclrtExceptionInfoCallback callback)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
注册进程级异常回调函数。通过本接口可以注册多个函数指针值不同的回调函数。对于通过本接口注册的回调函数，Runtime以callback参数中的函数指针值（即回调函数的入口地址）标识注册项。重复调用本接口注册同一个回调函数时返回成功，但不会新增注册项，也不会增加该回调函数在同一次异常通知中的调用次数或该注册项的引用计数；一次成功注销即可删除该注册项。
通过本接口注册的回调函数可与通过aclrtSetExceptionInfoCallback接口设置的回调函数共存。当Device任务执行异常并进入Runtime异常通知流程时，系统会将异常信息通知给已注册的回调函数。对于已经进入该流程的异常，Runtime不会根据回调函数的注册模块、任务类型或异常类型筛选回调函数；各回调函数需根据任务ID、Stream ID、线程ID、Device ID以及错误码自行判断是否处理。
同一个回调函数既通过aclrtSetExceptionInfoCallback接口设置，又通过本接口注册时，Runtime会将其保存为两个相互独立的注册项。若两个注册项在某次异常通知开始分发时均有效，且本次通知未被回调函数抛出的C++异常中断，则该回调函数在本次通知中会被调用两次，两次调用的先后顺序不做保证。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| callback | 输入 | 指定要注册的回调函数，不能为NULL。 回调函数的函数原型为： typedef void (*aclrtExceptionInfoCallback)(aclrtExceptionInfo *exceptionInfo); |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。入参为NULL时，返回参数错误。
约束说明
- 为确保收到目标异步任务的异常通知，请在下发该任务之前完成注册。不同回调函数的执行顺序不做保证。
- Runtime不记录调用本接口的模块身份。进程内任意调用方只要持有相同的回调函数指针，均可调用aclrtExceptionInfoCallbackUnregister接口注销该回调函数。
exceptionInfo由Runtime管理，仅在本次回调执行期间有效。回调函数不得保存、释放或修改该指针及其内容。- 回调函数中应谨慎访问共享资源（例如锁）。在回调函数内调用资源申请与释放、Stream同步、Device同步、任务下发、任务终止等接口，可能会导致错误或死锁。
- Runtime不保证同一个回调函数只在一个线程中执行。不同异常通知可能在不同线程中并发调用同一个回调函数，回调函数需自行保证其访问的数据线程安全。
- Runtime不对各回调函数进行异常隔离。任一回调函数抛出C++异常可能中断本次通知，使尚未执行的其他回调函数不再被调用，并可能中断Runtime后续异常处理。因此，回调函数不得抛出C++异常跨越C接口边界。
示例代码
以下示例仅展示多个回调函数的注册和注销顺序，省略初始化、任务下发及异常处理逻辑。
void callbackA(aclrtExceptionInfo *exceptionInfo)
{
// 读取并处理callbackA关注的异常信息。
}
void callbackB(aclrtExceptionInfo *exceptionInfo)
{
// 读取并处理callbackB关注的异常信息。
}
aclrtExceptionInfoCallbackRegister(callbackA);
aclrtExceptionInfoCallbackRegister(callbackB);
// 下发异步任务并处理任务执行结果，然后停止下发新的异步任务。
aclrtExceptionInfoCallbackUnregister(callbackA);
aclrtExceptionInfoCallbackUnregister(callbackB);
// 注销接口不等待在途回调结束。释放回调函数访问的资源前，
// 需通过业务同步确认所有在途回调均已结束。
aclrtExceptionInfoCallbackUnregister
aclError aclrtExceptionInfoCallbackUnregister(aclrtExceptionInfoCallback callback)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
注销通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数。本接口根据callback参数中的函数指针值查找并删除对应的本接口注册项，不影响其他异常回调函数，也不影响通过aclrtSetExceptionInfoCallback接口设置的回调函数。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| callback | 输入 | 待注销的回调函数，不能为NULL。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。callback为NULL时，返回参数错误。callback未注册时，不执行操作并返回成功。
约束说明
- Runtime不记录调用本接口的模块身份。进程内任意调用方只要持有已注册的相同函数指针，均可注销该注册项。
- 本接口不会等待已经进入异常通知流程或正在执行的回调函数结束。在未再次注册同一个回调函数的情况下，接口返回成功后，后续开始分发的异常通知不再包含该注册项，但已经进入通知流程的回调仍可能执行。调用方必须通过自身的同步机制确认所有在途回调均已结束，之后才能卸载回调函数所在的动态库或释放回调函数访问的资源。
aclrtGetTaskIdFromExceptionInfo
uint32_t aclrtGetTaskIdFromExceptionInfo(const aclrtExceptionInfo *info)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取异常信息中的任务ID。Runtime向异常回调函数传入aclrtExceptionInfo指针；本章中通过aclrtSetExceptionInfoCallback接口设置或通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数均可调用本接口读取该字段。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| info | 输入 | 异常信息的指针。 在执行任务之前调用aclrtSetExceptionInfoCallback接口或者aclrtExceptionInfoCallbackRegister接口，系统会将产生异常的任务ID、Stream ID、线程ID、Device ID存放在aclrtExceptionInfo结构体中。 |
返回值说明
返回异常信息中的任务ID，返回值为0xFFFFFFFF（以十六进制为例）时表示Device异常。
aclrtGetStreamIdFromExceptionInfo
uint32_t aclrtGetStreamIdFromExceptionInfo(const aclrtExceptionInfo *info)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取异常信息中的Stream ID。Runtime向异常回调函数传入aclrtExceptionInfo指针；本章中通过aclrtSetExceptionInfoCallback接口设置或通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数均可调用本接口读取该字段。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| info | 输入 | 异常信息的指针。 在执行任务之前调用aclrtSetExceptionInfoCallback接口或者aclrtExceptionInfoCallbackRegister接口，系统会将产生异常的任务ID、Stream ID、线程ID、Device ID存放在aclrtExceptionInfo结构体中。该指针由Runtime管理，仅在本次回调执行期间有效。 |
返回值说明
返回异常信息中的Stream ID，返回值为0xFFFFFFFF（以十六进制为例）时表示Device异常。
aclrtGetThreadIdFromExceptionInfo
uint32_t aclrtGetThreadIdFromExceptionInfo(const aclrtExceptionInfo *info)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取异常信息中的线程ID。Runtime向异常回调函数传入aclrtExceptionInfo指针；本章中通过aclrtSetExceptionInfoCallback接口设置或通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数均可调用本接口读取该字段。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| info | 输入 | 异常信息的指针。 在执行任务之前调用aclrtSetExceptionInfoCallback接口或者aclrtExceptionInfoCallbackRegister接口，系统会将产生异常的任务ID、Stream ID、线程ID、Device ID存放在aclrtExceptionInfo结构体中。 |
返回值说明
返回异常信息中的线程ID，返回值为0xFFFFFFFF（以十六进制为例）时表示Device异常。
aclrtGetDeviceIdFromExceptionInfo
uint32_t aclrtGetDeviceIdFromExceptionInfo(const aclrtExceptionInfo *info)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取异常信息中的Device ID。Runtime向异常回调函数传入aclrtExceptionInfo指针；本章中通过aclrtSetExceptionInfoCallback接口设置或通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数均可调用本接口读取该字段。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| info | 输入 | 异常信息的指针。 在执行任务之前调用aclrtSetExceptionInfoCallback接口或者aclrtExceptionInfoCallbackRegister接口，系统会将产生异常的任务ID、Stream ID、线程ID、Device ID存放在aclrtExceptionInfo结构体中。该指针由Runtime管理，仅在本次回调执行期间有效。 |
返回值说明
返回异常信息中的Device ID，返回值为0xFFFFFFFF（以十六进制为例）时表示Device异常。
aclrtGetErrorCodeFromExceptionInfo
uint32_t aclrtGetErrorCodeFromExceptionInfo(const aclrtExceptionInfo *info)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
获取异常信息中的错误码。Runtime向异常回调函数传入aclrtExceptionInfo指针；本章中通过aclrtSetExceptionInfoCallback接口设置或通过aclrtExceptionInfoCallbackRegister接口注册的进程级异常回调函数均可调用本接口读取该字段。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| info | 输入 | 异常信息的指针。 在执行任务之前调用aclrtSetExceptionInfoCallback接口或者aclrtExceptionInfoCallbackRegister接口，系统会将产生异常的任务ID、Stream ID、线程ID、Device ID、错误码存放在aclrtExceptionInfo结构体中。 |
返回值说明
返回异常信息中的错误码，返回值为0xFFFFFFFF（以十六进制为例）时表示Device异常。
aclrtPeekAtLastError
aclError aclrtPeekAtLastError(aclrtLastErrLevel level)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
获取当前线程的Runtime（运行时管理模块）错误码，仅获取但不清空错误码。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| level | 输入 | 指定获取错误码的级别，当前仅支持线程级别。类型定义请参见aclrtLastErrLevel。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtGetLastError
aclError aclrtGetLastError(aclrtLastErrLevel level)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：支持
功能说明
获取当前线程的Runtime（运行时管理模块）错误码，获取后清空当前线程的错误码，这时在线程中无新增错误码之前，调用本接口获取到的是ACL_SUCCESS。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| level | 输入 | 指定获取错误码的级别，当前仅支持线程级别。类型定义请参见aclrtLastErrLevel。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtGetMemUceInfo
aclError aclrtGetMemUceInfo(int32_t deviceId, aclrtMemUceInfo *memUceInfoArray, size_t arraySize, size_t *retSize)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
获取内存UCE（uncorrectable error，指系统硬件不能直接处理并恢复内存错误）的错误虚拟地址。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| deviceId | 输入 | Device ID。 与aclrtSetDevice接口中Device ID保持一致。 |
| memUceInfoArray | 输入&输出 | aclrtMemUceInfo数组的指针。类型定义请参见aclrtMemUceInfo。 |
| arraySize | 输入 | 传入aclrtMemUceInfo数组的长度。 |
| retSize | 输出 | 实际返回的aclrtMemUceInfo数组的有效长度。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtMemUceRepair
aclError aclrtMemUceRepair(int32_t deviceId, aclrtMemUceInfo *memUceInfoArray, size_t arraySize)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
修复内存UCE的错误虚拟地址。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| deviceId | 输入 | Device ID。 与aclrtSetDevice接口中Device ID保持一致。 |
| memUceInfoArray | 输入 | aclrtMemUceInfo数组的指针。 |
| arraySize | 输入 | 传入aclrtMemUceInfo数组的长度。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtDeviceTaskAbort
aclError aclrtDeviceTaskAbort(int32_t deviceId, uint32_t timeout)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
停止指定Device上的正在执行的任务，同时丢弃指定Device上已下发的任务。该接口支持用户设置永久等待、或配置具体的超时时间，若配置具体的超时时间，则调用本接口超出超时时间，则接口返回报错。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| deviceId | 输入 | Device ID。 与aclrtSetDevice接口中Device ID保持一致。 |
| timeout | 输入 | 超时时间。 取值说明如下： - 0：表示永久等待； - >0：配置具体的超时时间，单位是毫秒。最大超时时间36分钟。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtGetErrorVerbose
aclError aclrtGetErrorVerbose(int32_t deviceId, aclrtErrorInfo *errorInfo);
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
用于在发生设备故障后获取详细错误信息。此接口必须在获取故障事件之后，提交任务中止之前调用。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| deviceId | 输入 | Device ID。 与aclrtSetDevice接口中Device ID保持一致。 |
| errorInfo | 输出 | 错误信息。 typedef enum { ACL_RT_NO_ERROR = 0, // 无错误 ACL_RT_ERROR_MEMORY = 1, // 内存错误 ACL_RT_ERROR_L2 = 2, // L2 Buffer错误 ACL_RT_ERROR_AICORE = 3, // AI Core错误 ACL_RT_ERROR_LINK = 4, // 网络错误 ACL_RT_ERROR_L3_PORT = 5, // L3端口错误 ACL_RT_ERROR_OTHERS = 0xFFFF, // 其它错误 } aclrtErrorType; typedef enum aclrtAicoreErrorType { ACL_RT_AICORE_ERROR_UNKNOWN, // 未知错误 ACL_RT_AICORE_ERROR_SW, // 建议排查软件错误 ACL_RT_AICORE_ERROR_HW_LOCAL, // 建议排查当前Device的硬件错误 } aclrtAicoreErrorType; #define ACL_RT_MEM_UCE_INFO_MAX_NUM 20 typedef struct { size_t arraySize; // memUceInfoArray数组大小 aclrtMemUceInfo memUceInfoArray[ACL_RT_MEM_UCE_INFO_MAX_NUM]; // 内存UCE的错误虚拟地址数组 } aclrtMemUceInfoArray; typedef union aclrtErrorInfoDetail { aclrtMemUceInfoArray uceInfo; // 内存UCE（uncorrect error） aclrtAicoreErrorType aicoreErrType; // AI Core错误 } aclrtErrorInfoDetail; typedef struct aclrtErrorInfo { uint8_t tryRepair; // 是否需要修复 ，0表示无需修复，1表示需修复 uint8_t hasDetail; // 是否有详细报错信息，0表示没有，1表示有 uint8_t reserved[2]; // 预留参数 aclrtErrorType errorType; // 错误类型 aclrtErrorInfoDetail detail; // 错误详细信息 } aclrtErrorInfo; |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
如果通过aclrtGetOpTimeOutInterval接口查询到的超时最短时间间隔小于100ms时，本接口返回的故障的详细信息可能不准确。 对于Atlas A3 训练系列产品/Atlas A3 推理系列产品、Atlas A2 训练系列产品/Atlas A2 推理系列产品，仅支持获取ACL_RT_NO_ERROR（无错误） 、ACL_RT_ERROR_MEMORY（内存错误） 、ACL_RT_ERROR_OTHERS（其它错误）。
aclrtRepairError
aclError aclrtRepairError(int32_t deviceId, const aclrtErrorInfo *errorInfo)
须知：本接口为试验特性，后续版本可能会存在变更，不支持应用于生产环境中。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
基于aclrtGetErrorVerbose接口获取的详细信息进行故障恢复，此接口应该在提交任务中止之后调用。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| deviceId | 输入 | Device ID。 与aclrtSetDevice接口中Device ID保持一致。 |
| errorInfo | 输入 | 错误信息。 aclrtErrorInfo结构体的描述请参见aclrtGetErrorVerbose。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclrtSetDeviceTaskAbortCallback
aclError aclrtSetDeviceTaskAbortCallback(const char *regName, aclrtDeviceTaskAbortCallback callback, void *args)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：不支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
调用本接口注册回调函数，用于在调用aclrtDeviceTaskAbort接口前后触发该回调函数。不支持重复注册。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| regName | 输入 | 注册名称，保持唯一，不能为空，输入保证字符串以\0结尾。 |
| callback | 输入 | 回调函数。若callback不为NULL，则表示注册回调函数；若为NULL，则表示取消注册回调函数。 回调函数的函数原型为： typedef enum { ACL_RT_DEVICE_TASK_ABORT_PRE = 0, ACL_RT_DEVICE_TASK_ABORT_POST, } aclrtDeviceTaskAbortStage; typedef int32_t (aclrtDeviceTaskAbortCallback)(int32_t deviceId, aclrtDeviceTaskAbortStage stage, uint32_t timeout, voidargs); 此处的timeout表示期望回调函数执行的最长时间。 |
| args | 输入 | 待传递给回调函数的用户数据的指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。