Initialize

Applicability

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

Note: For Atlas A2 training product / Atlas A2 inference product , only the Atlas 800I A2 inference server and A200I A2 Box heterogeneous subrack are supported.

Function Description

Initializes an AdxlEngine instance. This API must be called before other APIs are called.

Prototype

      
           Status Initialize(const AscendString &local_engine, const std::map<AscendString, AscendString> &options)

Parameters

Parameter	Input/Output	Description
local_engine	Input	AdxlEngine identifier, which must be unique among all participants in the link establishment. The value is in the format of host_ip:host_port or host_ip. You are advised not to set this parameter to a loopback IP address, as it may lead to conflicts in scenarios involving multiple AdxlEngine instances. If host_port is set and its value is greater than 0, the current AdxlEngine instance functions as the server and needs to listen on the specified port. If host_port is not set or its value is less than or equal to 0, the current HIXL instance functions as the client and will not start listening.
options	Input	Initialization parameter values. For details, see Table 1.

Parameter

Input/Output

Description

local_engine

Input

AdxlEngine identifier, which must be unique among all participants in the link establishment. The value is in the format of host_ip:host_port or host_ip. You are advised not to set this parameter to a loopback IP address, as it may lead to conflicts in scenarios involving multiple AdxlEngine instances.

If host_port is set and its value is greater than 0, the current AdxlEngine instance functions as the server and needs to listen on the specified port. If host_port is not set or its value is less than or equal to 0, the current HIXL instance functions as the client and will not start listening.

options

Input

Initialization parameter values. For details, see Table 1.

**Table 1** Parameters in options
Parameter	Optional/Mandatory	Description
OPTION_BUFFER_POOL	Optional	String value "BufferPool". Intermediate buffer is required for transmission when: Direct H2H transmission via the HCCS protocol is not supported. The size of RDMA-registered host memory is limited. Multiple small memory blocks (for example, 128 KB) need to be transmitted through relay transmission for performance optimization. This parameter can be used to configure the size of the relay memory pool. The value format is "$BUFFER_NUM:$BUFFER_SIZE", with the system default being "4:8" (unit: MB). You can disable the relay memory pool by configuring it to "0:0". In concurrency scenarios, you are advised to increase the value of $BUFFER_NUM. Additionally, the same value must be configured wherever it is used. For restrictions on relay transmission mode, see TransferSync.
OPTION_RDMA_TRAFFIC_CLASS	Optional	String value "RdmaTrafficClass". This parameter specifies the traffic class of the RDMA NIC. If both this parameter and the environment variable HCCL_RDMA_TC are configured, this parameter takes precedence. If only one of them is configured, the configured one takes effect. Its value ranges from 0 to 255 and must be an integral multiple of 4. The default value is 132. For more information, see Environment Variables.
OPTION_RDMA_SERVICE_LEVEL	Optional	String value "RdmaServiceLevel". This parameter specifies the service level of the RDMA NIC. It has the same functionality as the environment variable HCCL_RDMA_SL. If both are configured, this parameter takes precedence. If only one of them is configured, the configured one takes effect. The value range is [0, 7]. The default value is 4. For more information, see Environment Variables.

Example

Click Gitee, download the sample package of the matching version based on the tag name, and obtain the sample from the cplusplus/level1_single_api/12_adxl directory.

Returns

SUCCESS: Success.
PARAM_INVALID: Incorrect parameter.
Other values: Failure.

Exception Handling

None

Restrictions

This API must be used in conjunction with Finalize. After successful initialization, Finalize must be called before any exit to ensure resource release. Otherwise, issues may arise due to unexpected resource release order.
Before initialization, aclrtSetDevice in Application Development (C&C++) must be called.

Parent topic: ADXL APIs