Initialize

Applicable Products

Product	Supported (√/x)
Ascend 950PR / Ascend 950DT	√
Atlas A3 training products / Atlas A3 inference products	√
Atlas A2 training products / Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	x
Atlas inference products	x
Atlas training products	x

Note: For Atlas A2 training products / Atlas A2 inference products , 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** 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.
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.

Returns

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

Exception Handling

None

Constraints

This API must be used together 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 must be called.

Parent topic: ADXL APIs