aclInit

Applicability

Description

Performs initialization.

aclInit must be called before app development using acl APIs. Otherwise, errors may occur during the initialization of internal resources, causing service exceptions.

Prototype

1

aclError aclInit(const char *configPath)

Parameters

Returns

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

Restrictions

• aclInit can be called multiple times in a process, but the aclFinalize or aclFinalizeReference API must be called for deinitialization.
  • The configuration must be consistent each time aclInit is called. Otherwise, only the configuration of the first call is valid. Calling the aclInit API again may cause errors.
  • To be compatible with earlier versions, if the aclInit API is called repeatedly, the error code ACL_ERROR_REPEAT_INITIALIZE will be returned. You can ignore this error and continue to process services.
  • The aclInit and aclFinalize APIs can be called repeatedly for initialization and deinitialization, respectively. Only sequential calls are available for the two APIs.

    aclInit --> Service processing --> aclFinalize --> aclInit --> Service processing --> aclFinalize

    After you call aclInit multiple times, you only need to call aclFinalize once to perform deinitialization. The aclInit reference count will be reset to 0.

  • If the aclInit and aclFinalizeReference APIs are called for initialization and deinitialization, respectively, the two APIs need to be called in pairs.

    aclFinalizeReference involves the implementation of reference counting. Each time aclInit is called, the reference count increases by 1. Each time aclFinalizeReference is called, the reference count decreases by 1. Deinitialization is performed only when the reference count decreases to 0.

    Initialization and deinitialization can be performed repeatedly. Both sequential and concurrent calls are available for the two APIs.

    • Sequential API calls

      

    • Concurrent API calls

      

Model Dump Configuration and Single-Operator Dump Configuration

Model dump configuration (used to export the input and output data of operators at each layer in the model) and single-operator dump configuration (used to export the input and output data of a single operator). The exported data is used to compare with that of a specified model or operator to locate accuracy issues. For details about the comparison method, see Accuracy Analyzer. This dump configuration is disabled by default.

To enable the dump configuration through this API, you need to use the dump_path parameter to configure the path for storing dump data.

Model dump configuration example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{                                                                                            
	"dump":{
		"dump_list":[                                                                        
			{	"model_name":"ResNet-101"
			},
			{                                                                                
				"model_name":"ResNet-50",
				"layer":[
				      "conv1conv1_relu",
				      "res2a_branch2ares2a_branch2a_relu",
				      "res2a_branch1",
				      "pool1"
				] 
			}  
		],  
		"dump_path":"/home/output",
                "dump_mode":"output",
		"dump_op_switch":"off",
                "dump_data":"tensor"
	}                                                                                        
}

Example of single-operator dump configuration:

1
2
3
4
5
6
7
8

{
    "dump":{
        "dump_path":"/home/output",
        "dump_list":[{}], 
	"dump_op_switch":"on",
        "dump_data":"tensor"
    }
}

{
	"dump":{
		"dump_list":[     
			{                                                                                
				"model_name":"ResNet-50",
				"optype_blacklist":[
				    {
					  "name":"conv"
					  "pos":["input0", "input1"]
					} 
				] 
			}
		],  
		"dump_path":"/home/output",
                "dump_mode":"input",
	}  
}

{
	"dump":{
		"dump_list":[     
			{                                                                                
				"model_name":"ResNet-50",
				"opname_blacklist":[
				    {
					  "name":"conv"
					  "pos":["input0", "input1"]
					} 
				] 
			}
		],  
		"dump_path":"/home/output",
                "dump_mode":"input",
	}  
}

{
	"dump":{
		"dump_list":[
			{
				"model_name":"ResNet-50",
				"opname_range":[{"begin":"conv1", "end":"relu1" }, {"begin":"conv2", "end":"pool1"}]
			}
		],
		"dump_mode":"output",
        "dump_level": "op",
        "dump_path":"/home/output"
	}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
	"dump":{
		"dump_list":[     
			...... 
		],  
		"dump_path":"/home/output",
                "dump_mode":"output",
		"dump_op_switch":"off",
                "dump_step": "0|3-5|10"
	}  
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "dump":{
	"dump_list":[     
		...... 
	],  
        "dump_path":"/home/output",
        "dump_mode":"output",
        "dump_data":"stats",
        "dump_stats":["Max", "Min"]
    }
}

Dump Configuration for Abnormal Operators

This dump configuration is used to export the input and output data, workspace information, and tiling information of abnormal operators. The exported data is used to analyze AI Core errors. This dump configuration is disabled by default. For details about how to collect and locate AI Core errors, see Typical Faults > AI Core Error Locating in Troubleshooting.

You can enable dump for abnormal operators by setting dump_scene. The following is an example of the configuration file, indicating that lightweight exception dump is enabled:

{
    "dump":{
        "dump_path":"output",
        "dump_scene":"aic_err_brief_dump"
    }
}

The details are as follows:

• dump_scene can be set to:
  • aic_err_brief_dump: lightweight exception dump, which is used to export the input, output, and workspace data of abnormal operators of AI Core.
  • aic_err_norm_dump: common exception dump, which is used to export the shape, data type, format, and attribute information in addition to the lightweight exception dump.
  • aic_err_detail_dump: exports the internal storage, register, and call stack information of AI Core in addition to the lightweight exception dump.

    When configuring this parameter, note that:

    • This parameter is only available for the following models and requires the driver of 25.0.RC1 or later:

      Atlas A3 training product / Atlas A3 inference product

      Atlas A2 training product / Atlas A2 inference product

      You can click here to download the driver installation package of Ascend HDK 25.0.RC1 or later on the Firmware and Drivers page and install or upgrade the driver by referring to the document of the corresponding version.

    • During dump file export, the AI Core where an abnormal operator is located is suspended, which may affect the execution of other processes on the device. After dump files are exported, the AI Core automatically restores. Therefore, you are not advised to use aic_err_detail_dump when multiple host-side user service processes share the same device.
    • After dump files are exported, host-side user service processes are forcibly exited. Errors reported during the forcible exit are not used as the input for AI Core problem analysis.
    • If aic_err_detail_dump is configured and dump files are generated but not *.core files, aic_err_detail_dump is not configured successfully. In this case, aic_err_brief_dump will be used instead.
  • lite_exception: light exception dump, designed for compatibility with earlier versions and equivalent to aic_err_brief_dump.
• dump_path is an optional parameter, indicating the path for storing exported dump files.

  The priorities of the dump file storage paths are as follows: Environment variable NPU_COLLECT_PATH > Environment variable ASCEND_WORK_PATH > dump_path in the configuration file > Current execution directory of the application. For details about the environment variables, see Environment Variables.

• To view the content of an exported dump file, convert the dump file to a NumPy file and then view the NumPy file using Python. For details about the conversion procedure, see Viewing Dump Data Files in Accuracy Analyzer.

  If dump_scene is set to aic_err_detail_dump, you can use msDebug to view the content of an exported dump file. For details, see Operator Development Tools.

• The dump configuration for abnormal operators cannot be enabled if the model dump configuration or single-operator dump configuration is enabled.

Dump Configuration for Overflow/Underflow Operators

This dump configuration is used to export the input and output data of the overflow/underflow operators in the model. The exported data is used to analyze the cause of overflow/underflow and locate model accuracy issues. This dump configuration is disabled by default.

{
    "dump":{
        "dump_path":"output",
        "dump_debug":"on"
    }
}

Dump Watch Configuration for Operators

This configuration is used to enable the watch mode for the output data of a specified operator. After locating the accuracy issues of some operators and excluding the computation issues of the operators, you can enable the dump watch mode if you suspect that the accuracy issues are caused by memory overwriting by other operators. The dump watch mode is disabled by default.

Set dump_scene to watcher to enable dump watch for operators. Below is an example of the content in the configuration file. The configuration effect is as follows: (1) After operators A and B are executed, the output of operators C and D is dumped; (2) After operators C and D are executed, the output of operators C and D is also dumped. The dump files of operators C and D in (1) will be compared with those in (2) to check whether operator A or B overwrites the output memory of operator C or D.

{
    "dump":{
        "dump_list":[
            {
                "layer":["A", "B"],
                "watcher_nodes":["C", "D"]
            }
        ],
        "dump_path":"/home/",
        "dump_mode":"output",
        "dump_scene":"watcher"
    }
}

The details are as follows:

• If the operator dump watch mode is enabled, the overflow/underflow operator dump (by configuring the dump_debug parameter) or the single-operator model dump (by configuring the dump_op_switch parameter) cannot be enabled. Otherwise, an error will be reported. This mode does not take effect in the single-operator API dump scenario.
• In dump_list, the layer parameter is used to configure the names of the operators that may overwrite the memory of other operators, and the watcher_nodes parameter is used to configure the names of the operators with accuracy issues possibly due to output memory being overwritten by other operators.
  • If layer is specified, the output of the operators configured for watcher_nodes is dumped after all operators that support dump in the model are executed.
  • If any operator in layer and watcher_nodes is not in a static graph or static subgraph, the configuration does not take effect.
  • If an operator is in both layer and watcher_nodes or an operator in layer is a collective communication operator (the operator type starts with Hcom, for example, HcomAllReduce), only the dump files of operators in watcher_nodes will be exported.
  • For a fused operator, use its name after fusion when you add it to watcher_nodes. Otherwise, dump files cannot be exported.
  • Currently, model_name cannot be configured in dump_list.
• If the operator dump watch mode is enabled, dump_path, which is the path for storing the exported dump file, must be configured.

  The exported dump files cannot be viewed using a text tool. To view the content of a dump file, convert the dump file to a NumPy file and then view the NumPy file using Python. For details about the conversion procedure, see Viewing Dump Data Files in Accuracy Analyzer.

  dump_path can be either absolute or relative.

  • An absolute path starts with a slash (/), for example, /home.
  • A relative path starts with a directory name, for example, output.
• dump_mode is used to specify the data of the operators configured for watcher_nodes to be exported. Currently, only output can be configured.

Dump Configuration for Operator Kernel Debugging Information

This dump configuration is used to export the debugging information of the Ascend C operator kernel to locate operator problems. This dump configuration is disabled by default.

This configuration is only available for the following models:

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

Set the dump_kernel_data parameter to enable the dump of operator kernel debugging information. The following is an example in the configuration file:

{
    "dump":{
        "dump_kernel_data":"printf,assert",
        "dump_path":"/home/"
    }
}

The details are as follows:

• dump_kernel_data: indicates the type of data to be exported. Multiple types can be configured and are separated by commas (,). If this field is not configured but the model dump configuration and single-operator dump configuration are enabled, all debugging information is exported by default.
  Currently, the following types are supported:

  • all: exports the output data of all the following types:
  • printf: exports the output data debugged by AscendC::printf.
  • tensor: exports the output data debugged by AscendC::DumpTensor.
  • assert: exports the output data debugged by assert/ascendc_assert.
  • timestamp: exports the output data debugged by AscendC::PrintTimeStamp.

• dump_path: specifies the path for storing the dump file. This parameter is mandatory when the dump function for operator kernel debugging information is enabled. The path can be an absolute path or a relative path.

  The priorities of the dump file storage paths are as follows: Environment variable ASCEND_DUMP_PATH > Environment variable ASCEND_WORK_PATH > dump_path in the configuration file. For details about the environment variables, see Environment Variables.

  The content of the exported dump file cannot be directly viewed using a text tool. To view the content, use the show_kernel_debug_data tool to parse the debugging information into a readable format. For details about how to use the tool, see show_kernel_debug_data Tool in Ascend C Operator Development.

Profiling Configuration

For the configuration example, description, and restrictions of profiling configuration, see Using the acl.json Configuration File for Profiling in Performance Tuning Tool. The profiling configuration is disabled by default.

The dump configuration and profiling configuration are mutually exclusive. The dump operation could affect system performance, resulting in inaccurate profile data.

Operator Cache Aging Configuration

Operator cache aging configuration. To reduce the memory footprint and balance the call performance when you execute a single operator in a single-operator model (the aclopUpdateParams API excluded), you can use the max_opqueue_num parameter to configure the maximum length of the "operator type and single-operator model" mapping queue. If the length of the mapping queue reaches the maximum, the least used mapping information and single-operator models in the cache are deleted before the most recent mapping information and the corresponding single-operator model are loaded. The default maximum length of the mapping queue is 20000.

In single-operator model execution, operator execution is based on graph IR. First, the operator is compiled (for example, the ATC tool is used to compile the single-operator description file defined by Ascend IR into an operator .om model file). Then, an acl API (for example, aclopSetModelDir) is called to load the operator model. Finally, an acl API (for example, aclopExecuteV2) is called to execute the operator.

You can use max_opqueue_num to set the maximum length of the "operator type and single-operator model" mapping queue to age operator cache information. The following is an example in the configuration file:

{
        "max_opqueue_num": "10000"
}

The details are as follows:

• For statically loaded operators (a single operator is compiled to generate an *.om file and then loaded using an API such as aclopSetModelDir), the aging configuration is invalid and the operator information will not be aged.
• For operators that are compiled online (operators are compiled directly by calling an acl API such as aclopCompile or aclopCompileAndExecuteV2), the API loads a single-operator model based on input parameters. In this case, the aging configuration is valid.

  If an operator is compiled using aclopCompile and executed using aclopExecuteV2, promptly execute the operator in case the operator information is aged. If that happens, you will need to recompile the operator. You are advised to use aclopCompileAndExecuteV2 instead, which completes operator compilation and execution as one action.

• An API maintains two mapping queues, one for static-shape and the other for dynamic-shape operators. However, their maximum lengths are both determined by the max_opqueue_num parameter.
• The value of max_opqueue_num is the sum of the number of single-operator models with statically loaded operators and the number of single-operator models with operators compiled online. Therefore, the value of max_opqueue_num must be greater than the number of single-operator models with statically loaded operators that are available in the current process; otherwise, the information about operators compiled online cannot be aged.

Error Information Report Mode Configuration

Error information report mode configuration, which is used to control the aclGetRecentErrMsg API to obtain error information by process or thread level. By default, error information is obtained by thread level.

Value range of the err_msg_mode parameter: 0 is the default value, indicating that error information is obtained by thread. 1 indicates that error information is obtained by process.

The following gives a configuration example:

{
        "err_msg_mode": "1"
}

Example (Default Device Configuration)

This configuration is used to configure the default compute device. If the device is specified through aclrtSetDevice, aclrtSetDevice has a high priority. If you want to explicitly create a context after enabling the default device configuration, you need to call aclrtSetDevice. Otherwise, service exceptions may occur.

Set the device ID in default_device, which can be 0 or a decimal positive integer. You can call aclrtGetDeviceCount to obtain the number of available devices. The value range of the device ID is [0, (Number of available devices – 1)].

The following gives a configuration example:

{
    "defaultDevice":{
        "default_device":"0"
    }
}

Example of AI Core Stack Size Configuration

AI Core stack size configuration, which is used to control the size of the stack space allocated to each AI Core during kernel execution in a process. The default value is 32 KB. When compiling AI Core operators, the configured AI Core stack size is valid only when the O0 switch is enabled. This restriction does not apply to the Atlas 350 Accelerator Card.

This configuration is only available for the following models:

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

Use aicore_stack_size to set the stack size, in bytes. The value must meet the following requirements:

• The value of aicore_stack_size must be an integer multiple of 16 KB. Otherwise, the value will be rounded up to meet this requirement.
• The minimum value of aicore_stack_size is 32 KB. If the input value is smaller than that, the default value 32 KB will be used.
• The maximum value of aicore_stack_size for each product is as follows:

  For the Atlas 350 Accelerator Card, the maximum value of aicore_stack_size is 128 KB.

  For the Atlas A3 training product / Atlas A3 inference product , the maximum value of aicore_stack_size is 192 KB.

  For the Atlas A2 training product / Atlas A2 inference product , the maximum value of aicore_stack_size is 192 KB.

  For the Atlas 200I/500 A2 inference product , the maximum value of aicore_stack_size is 7680 KB.

The following gives a configuration example:

{
    "StackSize":{
        "aicore_stack_size":32768
    }
}

Example of SIMT Operator Stack Size Configuration

Single Instruction Multiple Thread (SIMT) stack size configuration is used to control the stack size of the SIMT operator in each thread and the divergence stack size of the SIMT operator, in bytes. Only the Atlas 350 Accelerator Card supports this configuration.

simt_stack_size: specifies the stack size of the SIMT operator in each thread, in bytes.

simt_divergence_stack_size: specifies the divergence stack size of the SIMT operator, in bytes.

The values of simt_stack_size and simt_divergence_stack_size must be an integer multiple of 128. If the input value is not a multiple of 128, the API automatically rounds up the value to ensure that it is a multiple of 128.

The following gives a configuration example:

{
  "StackSize": {      
    "simt_stack_size": 1024,            
    "simt_divergence_stack_size": 512   
  }
}

Example of SIMT printf FIFO Size Configuration

This configuration is used to control the FIFO size that can be printed by the SIMT operator using the printf function, in bytes. Only the Atlas 350 Accelerator Card supports this configuration.

The simt_printf_fifo_size parameter specifies the printf FIFO size of the SIMT operator, in bytes. The value must be an integer multiple of 8. If the input value is not an integer multiple of 8, the API automatically rounds up the value to ensure that it is an integer multiple of 8.

The default value of simt_printf_fifo_size is 2 MB, the minimum value is 1 MB, and the maximum value is 64 MB.

The following gives a configuration example:

{
  "simt_printf_fifo_size": 1048576
}

Example of SIMD printf FIFO Size Configuration

This configuration is used to control the FIFO size that can be printed by the SIMD operator on each core using the printf function. This configuration is only available for the following models:

Atlas 350 Accelerator Card

Atlas A3 training product / Atlas A3 inference product

Atlas A2 training product / Atlas A2 inference product

The simd_printf_fifo_size_per_core parameter specifies the printf FIFO size of the SIMD operator, in bytes. The value must be an integer multiple of 8. If the input value is not an integer multiple of 8, the API automatically rounds up the value to ensure that it is an integer multiple of 8.

The default value of simd_printf_fifo_size_per_core is 32 KB, the minimum value is 1 KB, and the maximum value is 64 MB.

The following gives a configuration example:

{
  "simd_printf_fifo_size_per_core": 1048576
}

Example of the Event Resource Scheduling Mode Configuration

This configuration is used to control the scheduling mode of event resources in the scenario where a model running instance is constructed in capture mode. This configuration is only available for the following models:

Atlas 350 Accelerator Card

Atlas A3 training product / Atlas A3 inference product

Atlas A2 training product / Atlas A2 inference product

Value range of event_mode: 0 is the default value, indicating the memory mode, where the number of event resources is limited by the memory. 1 indicates the hardware acceleration mode, where the number of event resources is limited by hardware specifications, but the performance is better.

The following gives a configuration example:

{
    "acl_graph":{
        "event_mode":"0"
    }
}

API Call Example

For the API call example, see Initialization.

More flexible APIs are provided for enabling dump or profiling. Unlike aclInit, these APIs can be called repeatedly in a process, allowing varied dump/profiling configurations with each call.

• Obtains dump data: aclmdlInitDump, aclmdlSetDump, and aclmdlFinalizeDump If dump data does not need to be written to a file, you can obtain the dump data by using a callback function. For details, see acldumpRegCallback.
• Obtains profile data: Profiling Data Collection