文档

assert

Function Usage

Implements the assert function in CPU/NPU domain for operators developed based on operator projects. During operator execution, if the internal assert condition is not true, the assert condition is output and the input information is formatted and printed on the screen.

Use assert to check the code where assertions need to be added to the implementation code on the kernel of the operator, and format the output of debugging information. The following is an example. 
1
2
3
4
5
 
int assertFlag = 10;

assert(assertFlag == 10);
assert(assertFlag == 10, "The assertFlag value is 10.\n");
assert(assertFlag == 10, "The assertFlag value is %d.\n", assertFlag);
The printing of assert APIs affects the runtime performance of the operator (each assert statement leads to an additional logic judgment by the system, and the number of assert statements used in the code determines the specific system performance). This function is usually used during debugging. You can disable the printing function in either of the following ways:
  • 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 printf 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 -DASCENDC_DUMP=0 macro definition to the ascendc_compile_definitions command to disable the ASCENDC_DUMP function. To disable the assertion printing function on the CPU, modify the cpu_lib.cmake file. The following is an example. 
    1
2
3
4
    		 
    // Disable the printf function of all operators.
ascendc_compile_definitions(ascendc_kernels_${RUN_MODE} PRIVATE
    -DASCENDC_DUMP=0
)
When the assert condition is triggered, the CANN_VERSION_STR and CANN_TIMESTAMP values are automatically printed at the beginning of the assertion information. CANN_VERSION_STR and CANN_TIMESTAMP are macro definitions. CANN_VERSION_STR indicates the version number of the CANN package in the form of a string. CANN_TIMESTAMP indicates the timestamp when the CANN package is released, the value is in the format of uint64_t. You can directly use the two macros in the code. The following is an example of the assert information: 
1
 
[ASSERT][CANN_VERSION : XXX.XX][TimeStamp : 20240807140556417] /home/.../add_custom.cpp:44: Assertion `assertFlag != 10' The assertFlag value is 10.

Prototype

1
2
 
assert(expr)
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.
      • %f: outputs real numbers.
      • %x: outputs hexadecimal integers.
      • %s: outputs character strings.
      • %u: outputs unsigned data.
      • %p: outputs pointer addresses.
    • Currently, the supported data types are uint8_t/int8_t/int16_t/uint16_t/int32_t/uint32_t/int64_t/uint64_t/float/half.

args

Input

Additional parameters (an output 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

Availability

Precautions

  • This function is supported only in the following scenarios:
    • Calling operators through single-operator APIs.
    • Calling a single-operator API (aclnnxxx) indirectly: single-operator calling in the PyTorch framework.
  • Do not include assert.h of the system during kernel development. Otherwise, macro definition conflicts may occur.
  • The assert API is called in the same way as the C language, and the AscendC namespace is not required.
  • This API does not allow the printing of escape characters, except for newline characters.
  • The sum size of the space used by the assert call, printf call, DumpTensor call, DumpAccChkPoint call, and framework dump function cannot exceed 1 MB on each core. Developers need to control the amount of data to be printed. If the limit is exceeded, no content will be printed.
  • Only the assert API is called in the program. The space used by the assert API on each core cannot exceed 1 KB. Developers need to control the amount of data to be printed. If the limit is exceeded, no content will be printed.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
int assertFlag = 10;

// Assert condition
assert(assertFlag == 10);

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

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

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

1
 
[ASSERT][CANN_VERSION : XXX.XX][TimeStamp : 20240807140556417] /home/.../add_custom.cpp:44: Assertion `assertFlag != 10' The assertFlag value is 10.
Parent topic: Operator Debugging APIs