---
title: HcclGetRootInfo
description: "| 产品 | 是否支持 |"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/hcclug/hcclcpp_07_0005.html
sourcePath: /source/zh/canncommercial/900/API/hcclug/hcclcpp_07_0005.html
indexId: ae202c514c93d61acd4dd9315404cdb58a59dba859cc784b8b1175da09a8b08d61
---
# HcclGetRootInfo

#### 产品支持情况

| 产品 | 是否支持 |
| --- | --- |
| Atlas 350 加速卡 | √ |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | ☓ |
| Atlas 推理系列产品 | √ |
| Atlas 训练系列产品 | √ |


针对 Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ，仅支持Atlas 800T A2 训练服务器、Atlas 900 A2 PoD 集群基础单元、Atlas 200T A2 Box16 异构子框。

针对 Atlas 推理系列产品 ，仅支持Atlas 300I Duo 推理卡。


#### 功能说明

此接口需要在HCCL初始化接口HcclCommInitRootInfo或HcclCommInitRootInfoConfig前调用，仅需在root节点调用，用于生成root节点的rank标识信息（HcclRootInfo）。

- 该接口需要和初始化接口  HcclCommInitRootInfo
或  HcclCommInitRootInfoConfig
接口配对使用，不能单独使用。

- 该接口支持单线程循环调用，即开发者可在一个for循环中通过“指定不同的Device + 调用此接口”，从而实现在一个线程中获取不同设备的rootInfo信息。
  假设一个AI Server中有8张卡，8张卡分成4个通信域，每个通信域中的两张卡之间通信，如下图所示。

  图1 通信域划分示例

  获取rootInfo信息并进行集合通信初始化的流程如图2所示。首先在一个线程中通过切换Device创建4个rootInfo信息，并存入一个长度为4的数组中。rootInfo信息获取完成后，起4个线程，分别调用HcclCommInitRootInfo或者HcclCommInitRootInfoConfig接口（图2中以HcclCommInitRootInfo接口示意）根据不同的rootInfo信息进行通信域初始化。

  图2 单线程循环调用示例

- 多机集合通信场景，调用HcclGetRootInfo前，可以进行如下操作（非必选）：

  - 配置环境变量    HCCL_IF_IP
或    HCCL_SOCKET_IFNAME
，指定HCCL的初始化root网卡IP（环境变量HCCL_IF_IP的优先级高于HCCL_SOCKET_IFNAME，若二者都不配置，默认使用网卡名称的字典序升序选择root网卡）。
  - 配置环境变量    HCCL_WHITELIST_DISABLE
开启白名单校验，并通过    HCCL_WHITELIST_FILE
指定通信白名单配置文件（若不配置，默认关闭通信白名单校验）。


#### 函数原型

```
HcclResult HcclGetRootInfo(HcclRootInfo *rootInfo)
```


#### 参数说明

| 参数名 | 输入/输出 | 描述 |
| --- | --- | --- |
| rootInfo | 输出 | 本rank的标识信息，主要包含device ip、device id等信息。此信息需广播至集群内所有rank用来进行HCCL初始化。 HcclRootInfo类型的定义可参见HcclRootInfo。 |


#### 返回值

HcclResult：接口成功返回HCCL_SUCCESS，其他失败。


#### 约束说明

无


#### 调用示例

```
uint32_t rankSize = 8;
uint32_t deviceId = 0;
// 生成 root 节点的 rank 标识信息
HcclRootInfo rootInfo;
HcclGetRootInfo(&rootInfo);
// 初始化通信域
HcclComm hcclComm;
HcclCommInitRootInfo(rankSize, &rootInfo, deviceId, &hcclComm);
// 销毁通信域
HcclCommDestroy(hcclComm);
```