19-02 msproftx扩展接口
本章节描述 msproftx 扩展接口，用于自定义性能标记（Stamp）、范围标记及调用栈标记。
void *aclprofCreateStamp()：创建msproftx事件标记。aclError aclprofSetStampTraceMessage(void *stamp, const char *msg, uint32_t msgLen)：为msproftx事件标记携带字符串描述，在Profiling解析并导出结果中msprof_tx summary数据展示。aclError aclprofMark(void *stamp)：msproftx标记瞬时事件。aclError aclprofMarkEx(const char *msg, size_t msgLen, aclrtStream stream)：aclprofMarkEx打点接口。aclError aclprofPush(void *stamp)：msproftx用于记录事件发生的时间跨度的开始时间。aclError aclprofPop()：msproftx用于记录事件发生的时间跨度的结束时间。aclError aclprofRangeStart(void *stamp, uint32_t *rangeId)：msproftx用于记录事件发生的时间跨度的开始时间。aclError aclprofRangeStop(uint32_t rangeId)：msproftx用于记录事件发生的时间跨度的结束时间。aclError aclprofRangePushEx(aclprofEventAttributes *attr)：在Torch场景下，msproftx上报Tensor信息。aclError aclprofRangePop()：在Torch场景下，msproftx上报Tensor信息。void aclprofDestroyStamp(void *stamp)：释放msproftx事件标记。uint64_t aclprofStr2Id(const char *message)：msproftx用于将字符串转化为哈希ID。
扩展接口使用说明
- 调用接口要求：msproftx功能相关接口须在aclprofStart接口与aclprofStop接口之间调用。其中配对使用的接口有：aclprofCreateStamp/aclprofDestroyStamp、aclprofPush/aclprofPop、aclprofRangeStart/aclprofRangeStop。
- 接口调用顺序：aclprofStart接口(指定Device 0和Device 1)-->aclprofCreateStamp接口-->aclprofSetStampTraceMessage接口-->aclprofMark接口-->(aclprofPush接口-->aclprofPop接口)或(aclprofRangeStart接口-->aclprofRangeStop接口)-->aclprofDestroyStamp接口-->aclprofStop接口(与aclprofStart接口的aclprofConfig数据保持一致)。
aclprofCreateStamp
void *aclprofCreateStamp()
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
创建msproftx事件标记。后续调用aclprofMark、aclprofSetStampTraceMessage、aclprofPush和aclprofRangeStart接口时需要以描述该事件的指针作为输入，表示记录该事件发生的时间跨度。
返回值说明
- 返回void类型的指针，表示成功。
- 返回nullptr，表示失败。
约束说明
与aclprofDestroyStamp接口配对使用，需提前调用aclprofStart接口。
aclprofSetStampTraceMessage
aclError aclprofSetStampTraceMessage(void *stamp, const char *msg, uint32_t msgLen)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
为msproftx事件标记携带字符串描述，在Profiling解析并导出结果中msprof_tx summary数据展示。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stamp | 输入 | Stamp指针，指代msproftx事件标记。 指定aclprofCreateStamp接口的指针。 |
| msg | 输入 | Stamp信息字符串指针。 |
| msgLen | 输入 | 字符串长度。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
aclprofMark
aclError aclprofMark(void *stamp)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx标记瞬时事件。
调用此接口后，Profiling自动在Stamp指针中加上当前时间戳，将Event type设置为Mark，表示开始一次msproftx采集。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stamp | 输入 | Stamp指针，指代msproftx事件标记。 指定aclprofCreateStamp接口的指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
aclprofMarkEx
aclError aclprofMarkEx(const char *msg, size_t msgLen, aclrtStream stream)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
aclprofMarkEx打点接口。
调用此接口向配置的Stream流上下发打点任务，用于标识Host侧打点与Device侧打点任务的关系。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| msg | 输入 | 打点信息字符串指针。 |
| msgLen | 输入 | 字符串长度。最大支持127字符。 |
| stream | 输入 | 指定Stream。类型定义请参见aclrtStream。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
aclprofPush
aclError aclprofPush(void *stamp)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx用于记录事件发生的时间跨度的开始时间。
调用此接口后，Profiling自动在Stamp指针中记录开始的时间戳，将Event type设置为Push/Pop。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stamp | 输入 | Stamp指针，指代msproftx事件标记。 指定aclprofCreateStamp接口的指针。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 与aclprofPop接口成对使用，表示时间跨度的开始和结束。
- 在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
- 不能跨线程调用，若需要跨线程可使用aclprofRangeStart/aclprofRangeStop接口。
aclprofPop
aclError aclprofPop()
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx用于记录事件发生的时间跨度的结束时间。
调用此接口后，Profiling自动在Stamp指针中记录采集结束的时间戳。
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 与aclprofPush接口成对使用，表示时间跨度的开始和结束。
- 在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
- 不能跨线程调用。若需要跨线程可使用aclprofRangeStart/aclprofRangeStop接口。
aclprofRangeStart
aclError aclprofRangeStart(void *stamp, uint32_t *rangeId)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx用于记录事件发生的时间跨度的开始时间。
调用此接口后，Profiling自动在Stamp指针记录采集开始的时间戳，将Event type设置为Start/Stop，生成一个进程唯一的id，并将Stamp保存在以进程粒度维护的一个map中。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stamp | 输入 | Stamp指针，指代msproftx事件标记。 指定aclprofCreateStamp接口的指针。 |
| rangeId | 输出 | msproftx事件标记的唯一标识。用于在跨线程时区分。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 与aclprofRangeStop接口成对使用，表示时间跨度的开始和结束。
- 在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
- 可以跨线程调用。
aclprofRangeStop
aclError aclprofRangeStop(uint32_t rangeId)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx用于记录事件发生的时间跨度的结束时间。
调用此接口后，Profiling自动在Stamp指针中记录采集结束的时间戳。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| rangeId | 输入 | msproftx事件标记的唯一标识。用于在跨线程时区分。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
- 与aclprofRangeStart接口成对使用，表示时间跨度的开始和结束。
- 在aclprofCreateStamp接口和aclprofDestroyStamp接口之间调用。
- 可以跨线程调用。
aclprofRangePushEx
aclError aclprofRangePushEx(aclprofEventAttributes *attr)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
在Torch场景下，msproftx上报Tensor信息。
调用此接口后，Profiling判断messageType为MESSAGE_TYPE_TENSOR_INFO时，缓存Tensor信息。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| attr | 输入 | 需要上报的Tensor信息，结构体详见aclprofEventAttributes。 |
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
与aclprofRangePop接口配对使用，先调用aclprofRangePushEx接口再调用aclprofRangePop接口。
aclprofRangePop
aclError aclprofRangePop()
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
在Torch场景下，msproftx上报Tensor信息。
调用此接口后，Profiling上报缓存的Tensor信息。
返回值说明
返回0表示成功，返回其他值表示失败，请参见aclError。
约束说明
与aclprofRangePushEx接口配对使用，先调用aclprofRangePushEx接口再调用aclprofRangePop接口。
aclprofDestroyStamp
void aclprofDestroyStamp(void *stamp)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
释放msproftx事件标记。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| stamp | 输入 | Stamp指针，指代msproftx事件标记。 指定aclprofCreateStamp接口的指针。 |
返回值说明
无
约束说明
与aclprofCreateStamp接口配对使用，在aclprofStop接口前调用。
aclprofStr2Id
uint64_t aclprofStr2Id(const char *message)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品：支持
- Atlas 训练系列产品：支持
- IPV350：不支持
功能说明
msproftx用于将字符串转化为哈希ID。
参数说明
| 参数名 | 输入/输出 | 说明 |
|---|---|---|
| message | 输入 | 字符信息，例如算子名。 |
返回值说明
返回哈希ID，如果是uint64_t类型的最大值则表示失败，其他表示成功。
约束说明
与aclprofRangePushEx和aclprofRangePop接口配合使用，在aclprofRangePushEx接口调用之前调用。