ascendc_assert

Product Support

Product	Supported
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	√
Atlas inference product's AI Core	√
Atlas inference product's Vector Core	x
Atlas training products	x

Function

Provides an API for implementing the assert function in both the CPU domain and NPU domain. When the assert condition is not met, the system outputs the assert information and prints it in a formatted manner on the screen.

Use ascendc_assert to check the code where assertions need to be added to the operator kernel implementation code, and format the output of debugging information. The following is an example:

int assertFlag = 10;

ascendc_assert(assertFlag != 10);
ascendc_assert(assertFlag != 10, "The assertFlag value is 10.\n");
ascendc_assert(assertFlag != 10, "The assertFlag value is %d.\n", assertFlag);

The printing function of ascendc_assert affects the actual runtime performance of the operator. (For each ascendc_assert statement, the system adds an additional logic judgment. The specific performance impact depends on the number of ascendc_assert statements used in the code.) This function is usually used in the debugging phase. You can disable the printing function by setting ASCENDC_DUMP to 0.

The following is an example of the ascendc_assert print information in the NPU domain (the DumpHead information is printed only when a custom operator project is used):

DumpHead: AIV-0, CoreType=AIV, block dim=8, total_block_num=8, block_remain_len=696, block_initial_space=1024, rsv=0, magic=5aa5bccd
[ASSERT] /home/.../add_custom.cpp:44: Assertion `assertFlag != 10' The assertFlag value is 10.

The following is an example of the ascendc_assert print information in the CPU domain:

DumpHead: AIV-0, CoreType=AIV, block dim=8, total_block_num=8, block_remain_len=696, block_initial_space=1024, rsv=0, magic=5aa5bccd
[ASSERT]/home/.../add_custom.cpp:44: Assertion `assertFlag != 10'

Prototype

ascendc_assert(expr)
ascendc_assert(expr, __gm__ const char *fmt, Args&&... args)

Parameters

Parameter	Input/Output	Description
expr	Input	Condition for asserting whether to terminate a program. If the value is true, the program continues to be executed. If the value is false, the program is terminated.
fmt	Input	Format control string, which contains two types of objects: common characters and conversion descriptions. Common characters are printed as they are. Conversion descriptions are not directly output. Instead, they are used to control the conversion and printing of parameters in printf. Each conversion description starts with a percent (%) character and ends with the specific conversion description, indicating the type of the output data. The following conversion types are supported: %d / %i: outputs decimal numbers. The supported data types for printing are bool, int8_t, int16_t, int32_t, and int64_t. %f: outputs real numbers. The supported data types for printing are float and half. %x: outputs hexadecimal integers. The supported data types for printing are int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, and uint64_t. %s: outputs strings. %u: outputs unsigned data. The supported data types for printing are bool, uint8_t, uint16_t, uint32_t, and uint64_t. %p: outputs pointer addresses. Note: The preceding data types are those supported for debugging in the NPU domain. When debugging in the CPU domain, the supported data types comply with the C/C++ specifications. When the conversion type is %x, that is, a hexadecimal integer is output, the output in the NPU domain is 64-bit, while the output in the CPU domain is 32-bit.
args	Input	Additional parameters (a parameter list with variable quantities and types). Depending on the fmt string, the function may require a series of additional parameters. Each parameter contains a value to be inserted and replaces each % tag specified in the fmt parameter. The number of parameters must be the same as the number of % tags.

Parameter

Input/Output

Description

expr

Input

Condition for asserting whether to terminate a program. If the value is true, the program continues to be executed. If the value is false, the program is terminated.

fmt

Input

Format control string, which contains two types of objects: common characters and conversion descriptions.

Common characters are printed as they are.
Conversion descriptions are not directly output. Instead, they are used to control the conversion and printing of parameters in printf. Each conversion description starts with a percent (%) character and ends with the specific conversion description, indicating the type of the output data.
The following conversion types are supported:
- %d / %i: outputs decimal numbers. The supported data types for printing are bool, int8_t, int16_t, int32_t, and int64_t.
- %f: outputs real numbers. The supported data types for printing are float and half.
- %x: outputs hexadecimal integers. The supported data types for printing are int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, and uint64_t.
- %s: outputs strings.
- %u: outputs unsigned data. The supported data types for printing are bool, uint8_t, uint16_t, uint32_t, and uint64_t.
- %p: outputs pointer addresses.

Note:

The preceding data types are those supported for debugging in the NPU domain. When debugging in the CPU domain, the supported data types comply with the C/C++ specifications.
When the conversion type is %x, that is, a hexadecimal integer is output, the output in the NPU domain is 64-bit, while the output in the CPU domain is 32-bit.

args

Input

Additional parameters (a parameter list with variable quantities and types). Depending on the fmt string, the function may require a series of additional parameters. Each parameter contains a value to be inserted and replaces each % tag specified in the fmt parameter. The number of parameters must be the same as the number of % tags.

Returns

None

Restrictions

This API does not support the scenario of operator integration into a graph.
This API does not support the simulator mode.
This API does not need to use the AscendC namespace.

This API does not allow the printing of escape characters, except for newline characters.
The total amount of data printed by a single call to this API cannot exceed 1 MB (including a small amount of header and footer information required by the framework, which can usually be ignored). If this limit is exceeded, the data will not be printed.
When a custom operator project is used, note the following restrictions:
- This API uses the dump function. The total amount of data dumped by all APIs that use the dump function for an operator on each core cannot exceed 1 MB. You need to control the amount of data to be printed. If the limit is exceeded, no content will be printed.
- The space used by this API on each core cannot exceed 1 KB. You need to control the amount of data to be printed. If the limit is exceeded, no content will be printed.

Example

API calling example

int assertFlag = 10;

// Assert condition.
ascendc_assert(assertFlag == 10);

// Print messages.
ascendc_assert(assertFlag == 10, "The assertFlag value is 10.\n");

// Format the print.
ascendc_assert(assertFlag == 10, "The assertFlag value is %d.\n", assertFlag);
ascendc_assert(assertFlag != 10, "The assertFlag value is %d.\n", assertFlag);

Assert is triggered when the program is running. The print effect is as follows:

[ASSERT] /home/.../add_custom.cpp:44: Assertion `assertFlag != 10' The assertFlag value is 10.

Appendix: Examples of disabling ASCENDC_DUMP in custom operator projects and kernel launch projects
- Custom operator project
  Modify the CMakeLists.txt file in the op_kernel directory of the operator project. Add the compilation option -DASCENDC_DUMP=0 to the first line to disable ASCENDC_DUMP. The following is an example:
  1 2
  // Disable the printing function of all operators. add_ops_compile_options(ALL OPTIONS -DASCENDC_DUMP=0)
- Kernel launch project
  - Modify the npu_lib.cmake file in the cmake directory. Add the macro definition ASCENDC_DUMP=0 to the ascendc_compile_definitions command to disable ASCENDC_DUMP on the NPU. The following is an example:
    1 2 3 4
    // Disable the printing function of all operators. ascendc_compile_definitions(ascendc_kernels_${RUN_MODE} PRIVATE ASCENDC_DUMP=0 )
  - Modify the cpu_lib.cmake file in the cmake directory. Add the macro definition ASCENDC_DUMP=0 to the target_compile_definitions command to disable ASCENDC_DUMP on the CPU. The following is an example:
    1 2 3
    target_compile_definitions(ascendc_kernels_${RUN_MODE} PRIVATE ASCENDC_DUMP=0 )

Parent topic: Exception Detection