16. 算力Group查询与设置
本章节描述 CANN Runtime 的算力 Group 接口，用于 AI Core 分组的设置、查询及信息获取。
aclError aclrtSetGroup(int32_t groupId)：指定当前运算使用哪个Group的算力，该接口必须在指定Context后调用。aclError aclrtGetGroupCount(uint32_t *count)：查询当前Context下可以使用的Group个数。aclError aclrtGetAllGroupInfo(aclrtGroupInfo *groupInfo)：查询当前Context下可以使用的所有Group的详细算力信息。aclError aclrtGetGroupInfoDetail(const aclrtGroupInfo *groupInfo, int32_t groupIndex, aclrtGroupAttr attr, void *attrValue, size_t valueLen, size_t *paramRetSize)：查询当前Context下指定Group的算力信息。aclrtGroupInfo *aclrtCreateGroupInfo()：根据实际支持的Group数量创建aclrtGroupInfo类型的连续内存块，并返回对应指针。aclError aclrtDestroyGroupInfo(aclrtGroupInfo *groupInfo)：销毁aclrtGroupInfo类型的数据，释放相关的内存。
aclrtSetGroup
aclError aclrtSetGroup(int32_t groupId)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
指定当前运算使用哪个Group的算力，该接口必须在指定Context后调用。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| groupId | 输入 | 表示Group的ID，用于指定当前计算要使用的Group。 您需要提前调用aclrtGetGroupInfoDetail接口获取Group的ID。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。
acl接口调用顺序：调用aclrtSetDevice接口指定计算设备-->调用aclrtGetAllGroupInfo接口获取所有Group信息-->调用aclrtGetGroupCount接口获取Group数量-->调用aclrtGetGroupInfoDetail接口获取指定Group信息-->调用aclrtSetGroup接口设置分组-->执行其它任务-->调用aclrtResetDevice接口释放计算设备。
在调用acl接口设置算力Group前，需先调用驱动提供的DCMI接口dcmi_create_capability_group创建分组。若刷新分组（例如调用dcmi_create_capability_group接口新增分组、调用dcmi_delete_capability_group接口删除分组等），需重启业务进程。
aclrtGetGroupCount
aclError aclrtGetGroupCount(uint32_t *count)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
查询当前Context下可以使用的Group个数。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| count | 输出 | 当前Context下可用Group个数的指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。
acl接口调用顺序：调用aclrtSetDevice接口指定计算设备-->调用aclrtGetAllGroupInfo接口获取所有Group信息-->调用aclrtGetGroupCount接口获取Group数量-->调用aclrtGetGroupInfoDetail接口获取指定Group信息-->调用aclrtSetGroup接口设置分组-->执行其它任务-->调用aclrtResetDevice接口释放计算设备。
在调用acl接口设置算力Group前，需先调用驱动提供的DCMI接口dcmi_create_capability_group创建分组。若刷新分组（例如调用dcmi_create_capability_group接口新增分组、调用dcmi_delete_capability_group接口删除分组等），需重启业务进程。
aclrtGetAllGroupInfo
aclError aclrtGetAllGroupInfo(aclrtGroupInfo *groupInfo)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
查询当前Context下可以使用的所有Group的详细算力信息。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| groupInfo | 输出 | 获取所有Group对应的详细算力信息的指针。 需提前调用aclrtCreateGroupInfo接口创建aclrtGroupInfo类型的数据。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。
acl接口调用顺序：调用aclrtSetDevice接口指定计算设备-->调用aclrtGetAllGroupInfo接口获取所有Group信息-->调用aclrtGetGroupCount接口获取Group数量-->调用aclrtGetGroupInfoDetail接口获取指定Group信息-->调用aclrtSetGroup接口设置分组-->执行其它任务-->调用aclrtResetDevice接口释放计算设备。
在调用acl接口设置算力Group前，需先调用驱动提供的DCMI接口dcmi_create_capability_group创建分组。若刷新分组（例如调用dcmi_create_capability_group接口新增分组、调用dcmi_delete_capability_group接口删除分组等），需重启业务进程。
aclrtGetGroupInfoDetail
aclError aclrtGetGroupInfoDetail(const aclrtGroupInfo *groupInfo, int32_t groupIndex, aclrtGroupAttr attr, void *attrValue, size_t valueLen, size_t *paramRetSize)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
查询当前Context下指定Group的算力信息。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| groupInfo | 输入 | 指定算力详细信息的首地址的指针。 需提前调用aclrtGetAllGroupInfo接口获取所有Group的算力信息。 |
| groupIndex | 输入 | 访问groupInfo连续内存块的Group索引。 Group索引的取值范围：[0, (Group数量-1)]，用户可调用aclrtGetGroupCount接口获取Group数量。 |
| attr | 输入 | 指定要获取其算力值的算力属性。类型定义请参见aclrtGroupAttr。 |
| attrValue | 输出 | 获取指定算力属性所对应的算力值的指针。 用户需根据每个属性的属性值数据类型申请对应大小的内存，用于存放属性值。 |
| valueLen | 输入 | 表示attrValue的最大长度，单位为Byte。 |
| paramRetSize | 输出 | 实际返回的attrValue大小的指针，单位为Byte。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。
acl接口调用顺序：调用aclrtSetDevice接口指定计算设备-->调用aclrtGetAllGroupInfo接口获取所有Group信息-->调用aclrtGetGroupCount接口获取Group数量-->调用aclrtGetGroupInfoDetail接口获取指定Group信息-->调用aclrtSetGroup接口设置分组-->执行其它任务-->调用aclrtResetDevice接口释放计算设备。
在调用acl接口设置算力Group前，需先调用驱动提供的DCMI接口dcmi_create_capability_group创建分组。若刷新分组（例如调用dcmi_create_capability_group接口新增分组、调用dcmi_delete_capability_group接口删除分组等），需重启业务进程。
aclrtCreateGroupInfo
aclrtGroupInfo *aclrtCreateGroupInfo()
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
根据实际支持的Group数量创建aclrtGroupInfo类型的连续内存块，并返回对应指针。
如需销毁aclrtGroupInfo类型的数据，请参见aclrtDestroyGroupInfo。
参数说明
无
返回值说明
返回aclrtGroupInfo类型的指针，如果无Group或不支持Group则返回nullptr。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。
aclrtDestroyGroupInfo
aclError aclrtDestroyGroupInfo(aclrtGroupInfo *groupInfo)
产品支持情况
- Ascend 950PR/Ascend 950DT：不支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：不支持
- IPV350：不支持
功能说明
销毁aclrtGroupInfo类型的数据，释放相关的内存。只能销毁通过aclrtCreateGroupInfo接口创建的aclrtGroupInfo类型。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| groupInfo | 输入 | 待销毁的aclrtGroupInfo类型数据的指针。 |
返回值说明
返回0表示成功，非零表示失败，请参见aclError。
约束说明
仅支持在Atlas 推理系列产品的Control CPU开放形态下调用本接口。不支持在Atlas 推理系列产品Ascend EP形态下调用本接口。