Querying the Topology Information

Background

To cope with complex network topologies, communication operators need to select the most matched algorithm based on the topology of the communicator. Therefore, the HCCL control plane provides the function of querying the topology information.

Topology Information

The following table describes the topology information that can be queried using the HCCL control plane APIs.

Topology Information	Query API
Obtains the rank ID of a device in a specified communicator.	HcclGetRankId
Queries the number of ranks in a specified communicator.	HcclGetRankSize
Queries the list of topology layers that contain the current rank and the number of topology layers.	HcclRankGraphGetLayers
Returns the list of all rank IDs and the number of ranks in the topology instance where the current rank is located at a specified topology layer in a specified communicator.	HcclRankGraphGetRanksByLayer
Returns the number of ranks in the topology instance where the current rank is located at a specified topology layer in a specified communicator.	HcclRankGraphGetRankSizeByLayer
Returns the topology type of the topology layer where the current rank is located in a specified communicator.	HcclRankGraphGetTopoTypeByLayer
Queries the number of topology instances at a specified topology layer and the number of ranks in each instance in a specified communicator.	HcclRankGraphGetInstSizeListByLayer
Queries information about the communication connection between the source rank and the destination rank at a specified topology layer in a specified communicator.	HcclRankGraphGetLinks

Sample Code

Query the ID of the current rank in a communicator.

u32 userRank = INVALID_VALUE_RANKID;
HcclResult ret = HcclGetRankId(comm, &userRank);
if (userRank == root && sendBuf == nullptr) {     // send_buff of the root rank cannot be empty.
    return HCCL_E_PTR;
}

Query the number of ranks in a communicator.

u32 rankSize = INVALID_VALUE_RANKSIZE;
HcclResult ret = HcclGetRankSize(comm, &rankSize);
if (userRank >= rankSize) {     // rank_id is out of range.
    return HCCL_E_PARA;
}

Query information about the link between the current device and device 0 on the server.

u32 dstRank = 0;
u32 srcRank = rank;
CommLink *linkList = nullptr;
u32 listSize = 0;
HcclResult ret = HcclRankGraphGetLinks(comm, 0, srcRank, dstRank, &linkList, &listSize);
for (u32 i = 0; i < listSize; ++i) {
    CommLink& currentLink = linkList[i]; // Enumerate all link objects.
    if (currentLink.linkAttr.linkProtocol == CommProtocol::COMM_PROTOCOL_HCCS) {
        // Determine the HCCS link.
    }
}

Query the number of SuperPoDs in the communicator where the device is located.

u32 *netlayers = nullptr;
u32 netLayersNum = 0;
HcclResult ret = HcclRankGraphGetLayers(comm, &netlayers, &netLayersNum); // Obtain the communication network layers in the communicator.
u32 superPodNum;
u32 level1RankListNum = 0;
u32 *level1SizeList = nullptr;
if (netLayersNum == 3) { // SuperPoD scenario
    ret = HcclRankGraphGetInstSizeListByLayer(comm, 1, &level1SizeList, &level1RankListNum);
    superPodNum = level1RankListNum;
}

Parent topic: AIV Operator Development