aclrtSetExceptionInfoCallback

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product / Atlas A3 inference product	√
Atlas A2 training product / Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	√
Atlas inference product	√
Atlas training product	√

Description

Sets the exception callback function. If the exception callback function is set repeatedly, the most recent setting applies.

Prototype

      
           aclError aclrtSetExceptionInfoCallback(aclrtExceptionInfoCallback callback)

Parameters

Parameter	Input/Output	Description
callback	Input	Callback function to be registered. Prototype: typedef void (aclrtExceptionInfoCallback)(aclrtExceptionInfo exceptionInfo);

Parameter

Input/Output

Description

callback

Input

Callback function to be registered.

Prototype:

typedef void (*aclrtExceptionInfoCallback)(aclrtExceptionInfo *exceptionInfo);

Returns

0 on success; otherwise, failure. For details, see aclError.

Restrictions

Callback functions involve shared resources (such as locks). Exercise caution when using callback functions. Do not call APIs for resource application & release, stream synchronization, device synchronization, task delivery, and task termination in callback functions. Otherwise, errors or deadlocks may occur.
Set an exception callback function before asynchronous task execution on the device. When a task fails, the system passes a pointer to the aclrtExceptionInfo struct that contains the task ID, stream ID, thread ID, device ID, and error code to the exception callback function and executes the callback function. You can call aclrtGetTaskIdFromExceptionInfo, aclrtGetStreamIdFromExceptionInfo, aclrtGetThreadIdFromExceptionInfo, aclrtGetDeviceIdFromExceptionInfo, and aclrtGetErrorCodeFromExceptionInfo to obtain the error task ID, stream ID, thread ID, device ID, and error code, respectively, to facilitate fault locating.
Example use case: Before the aclopExecuteV2 call, call aclrtSetExceptionInfoCallback to set an exception callback function. When operator execution on the device fails, the system passes a pointer to the aclrtExceptionInfo structure that contains the task ID, stream ID, thread ID, device ID, and error code to the exception callback function and executes the callback function.
To clear the callback function, pass a null pointer to the aclrtSetExceptionInfoCallback call.

API Call Process

Application scenario: For example, if an AI Core error is reported during network inference (dynamic shape scenarios unsupported), you can refer to this section to obtain the description of the error operator and then perform further troubleshooting.

The recommended API call sequence is as follows:

Define and implement the exception callback function fn (of the aclrtExceptionInfoCallback type).
The key logics for implementing the callback function are as follows:
1. Call aclrtGetDeviceIdFromExceptionInfo, aclrtGetStreamIdFromExceptionInfo, and aclrtGetTaskIdFromExceptionInfo in the exception callback function to obtain the device ID, stream ID, and task ID, respectively.
2. Call aclmdlCreateAndGetOpDesc in fn to obtain the operator description.
3. Call aclGetTensorDescByIndex in fn to obtain the input/output tensor description of the operator.
4. In the exception callback function fn, call the following APIs to obtain the tensor description for further analysis.
  For example, call aclGetTensorDescAddress to obtain the tensor data memory address, call aclGetTensorDescType to obtain the data type in the tensor description, call aclGetTensorDescFormat to obtain the tensor format, call aclGetTensorDescNumDims to obtain the number of dimensions in the shape of a tensor, and call aclGetTensorDescDimV2 to obtain the size of a specified dimension in the shape.
Call aclrtSetExceptionInfoCallback to set the exception callback function.
Execute model inference.
If an AI Core error is reported, the callback function fn is triggered to obtain the operator information for further troubleshooting.

Sample Code

The following is a code snippet of key steps for obtaining AI Core exception information. It is for reference only and cannot be directly copied for compilation or running. After APIs are called, you need to add exception handling branches and record error logs and info logs.

       
        
          
          
            ......

// 1. Load the model. After the model is successfully loaded, modelId that identifies the model is returned.

// 2. Create data of type aclmdlDataset to describe the inputs and outputs of the model.

// 3. Implement the exception callback function.
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; 
    // You can write the obtained operator information to a file, or start another thread. When an error occurs, the thread handling function is triggered, and the operator information is printed to the screen.
    aclmdlCreateAndGetOpDesc(deviceId, streamId, taskId, opName, 256,  &inputDesc, &inputCnt, &outputDesc, &outputCnt);
    // You can call related tensor APIs to obtain the operator information as required.
    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. Set the exception callback.
aclrtSetExceptionInfoCallback(callback);

// 5. Execute the model.
aclmdlExecute(modelId, input, output);

// 6. Process the model inference result.
......

// 7. Destroy the model input and output descriptions, free memory, and unload the model.
......

           

         

       
      

Parent topic: Exception Handling