希姆计算HPE Python接口说明
版本历史
| 版本 | 作者 | 日期 | 注释 |
|---|---|---|---|
| V1.0 | 希姆计算 | 2022-01-30 | 初始版本。 |
| V1.2.0 | 希姆计算 | 2022-04-11 | 配套HPE V1.2.0发布文档。 |
概述
北京希姆计算科技有限公司提供了主机端运行时（hpert）及性能数据采集（stcpti）的python接口，通过python接口可以控制设备端内存访问、核函数执行、性能数据采集等操作。
主机端运行时库的详细信息参考希姆计算异构编程手册。
性能数据采集的详细信息参考希姆计算stc-prof使用说明。
部署工作
参考希姆计算STCP920快速安装指南，在主机部署希姆计算异构编程环境
安装python，版本不小于3.6
安装python库：
$ pip3 install numpy
运行示例
#!/usr/bin/env python
# coding=utf-8
import numpy as np
import hpe.hpert.api as hpe
import hpe.profiler.api as prof
def main():
'''
copy 100 integers from host to device and then back to host
'''
DATA_NUM = 100
try:
print("version", hpe.version())
hpe.detect()
print('get device:', hpe.get_device())
prof.init()
prof.enable()
# prepare host memory
host_in = np.arange(DATA_NUM, dtype=np.int32)
host_out = np.zeros(DATA_NUM, dtype=np.int32)
# prepare device memory
device_in = hpe.device_mem(host_in.nbytes)
device_out = hpe.device_mem(host_out.nbytes)
# move 100 integers from host to device
device_in.copy_from_host(host_in)
# 'hello' kernel function in hello.o moves 100 integers from device_in to device_out
mod = hpe.module('hello.o')
mod.launch_kernel('hello', [device_in, device_out, DATA_NUM])
hpe.synchronize()
# move 100 integers from device to host
device_out.copy_to_host(host_out)
print("host_out:")
print(host_out)
prof.disable()
perf_datas = prof.get_perf_datas()
print("*************profiler data*************")
print(perf_datas)
prof.release()
except hpe.CruntimeException as e:
print(e)
if __name__ == "__main__":
main()
hello.o对应的程序：
#include <npurt.h>
extern "C" {
void hello(int *in, int *out, int num) {
if (CoreID == 0){
for(int i=0; i<num; i++)
out[i] = in[i];
}
}
}
主机端运行时（hpert）接口说明
使用方法：
import hpe.hpert.api
接口功能上分为四类：设备管理，内存管理，执行控制，流管理。
注意：接口函数的执行错误码通过异常（RuntimeAPIError）方式上报用户。
设备管理
hpe.hpert.api.detect()
函数描述：显示主机上的NPU设备信息。输出每个NPC Cluster的标识符、名称、以及PCI信息。
函数类型：同步函数
返回值：发现NPU设备返回True，否则返回False
hpe.hpert.api.set_device(device_id)
函数描述：设置用于主机线程执行设备端程序的默认NPC Cluster。线程的默认NPC Cluster为0。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| device_id | 输入参数 | NPC Cluster标识符 |
| + 返回值：None |
hpe.hpert.api.get_device()
函数描述：获取当前用于主机线程执行设备端程序的默认NPC Cluster。
函数类型：同步函数
返回值：NPC Cluster标识符
hpe.hpert.api.synchronize(device_id=None)
函数描述：等待当前进程的所有设备端操作执行结束。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| device_id | 输入参数 | NPC Cluster标识符。默认值为None，使用默认NPC Cluster |
| + 返回值：None |
内存管理
hpe.hpert.api.device_mem(size, device_id=None)
函数描述：从设备端0GB～3GB全局内存区动态分配内存。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| size | 输入参数 | 分配请求的字节大小 |
| device_id | 输入参数 | NPC Cluster标识符。默认值为None，使用默认NPC Cluster |
| + 返回值：hpe.hpert.api.DeviceMem对象 |
hpe.hpert.api.host_mem(shape, dtype=numpy.float16)
函数描述：从主机端分配内存并设置为不会被换出的页锁定内存。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| shape | 输入参数 | 数据的形状 |
| dtype | 输入参数 | 数据元素的类型，默认值为numpy.float16 |
| + 返回值：numpy.ndarray对象 |
hpe.hpert.api.host_pinned(host_array)
函数描述：将主机内存设置为不会被换出的页锁定内存。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| host_array | 输入参数 | 锁定numpy.ndarray对象的数据页内存 |
| + 返回值：None |
hpe.hpert.api.DeviceMem.offset_address(offset)
函数描述：获取设备端偏移地址。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| offset | 输入参数 | 设备端地址基址的偏移字节 |
| + 返回值：设备端偏移地址 |
hpe.hpert.api.DeviceMem.copy_from_host(host_array, device_offset=0, host_offset=0, size=None, stream=0)
函数描述：将主机端numpy.ndarray对象的数据内存拷贝到设备端内存。
函数类型：同步函数（stream=0），异步函数（stream!=0）
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| host_array | 输入参数 | 主机端numpy.ndarray对象 |
| device_offset | 输入参数 | 设备端内存地址偏移字节大小，默认值为0 |
| host_offset | 输入参数 | 主机端内存地址偏移字节大小，默认值为0 |
| size | 输入参数 | 拷贝字节大小。默认值为None，代表整个host_array的内存字节大小 |
| stream | 输入参数 | 流标识符，默认值为0 |
| + 返回值：None |
hpe.hpert.api.DeviceMem.copy_to_host(host_array, device_offset=0, host_offset=0, size=None, stream=0)
函数描述：将设备端内存拷贝到主机端numpy.ndarray对象的数据内存。
函数类型：同步函数（stream=0），异步函数（stream!=0）
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| host_array | 输入参数 | 主机端numpy.ndarray对象 |
| device_offset | 输入参数 | 设备端内存地址偏移字节大小，默认值为0 |
| host_offset | 输入参数 | 主机端内存地址偏移字节大小，默认值为0 |
| size | 输入参数 | 拷贝字节大小。默认值为None，代表整个host_array的内存字节大小 |
| stream | 输入参数 | 流标识符，默认值为0 |
| + 返回值：None |
执行控制
hpe.hpert.api.module(image, device_id=None)
函数描述：加载设备端目标程序。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| image | 输入参数 | 要加载的目标程序文件名或内存字节串 |
| device_id | 输入参数 | NPC Cluster标识符。默认值为None，使用默认NPC Cluster |
| + 返回值：hpe.hpert.api.Module对象 |
hpe.hpert.api.Module.launch_kernel(kernel_name, *kernel_params, stream=0, core_num=8, flags=KernelFlag.stcKernelFlagNone)
函数描述：核函数运行配置。
函数类型：异步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| kname | 输入参数 | 核函数名称 |
| kernelParams | 输入参数 | 核函数参数数组 |
| stream | 输入参数 | 流标识符，默认值为0 |
| core_num | 输入参数 | 一个NPC Cluster上并行执行核函数的NPC个数，默认值为8 |
| flags | 输入参数 | 核函数执行标志，默认值为KernelFlag.stcKernelFlagNone |
| + 返回值：None |
流管理
hpe.hpert.api.stream(device_id=None)
函数描述：创建一个流。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| device_id | 输入参数 | NPC Cluster标识符。默认值为None，使用默认NPC Cluster |
| + 返回值：hpe.hpert.api.Stream对象 |
hpe.hpert.api.Stream.synchronize()
函数描述：等待指定流上的所有操作执行结束。如果核函数执行异常退出，输出触发异常时核函数的调用栈。
函数类型：同步函数
返回值：None
hpe.hpert.api.Stream.wait (event)
函数描述：该流接下来的操作请求要等待指定事件完成再处理。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| event | 输入参数 | 事件标识符 |
| + 返回值：None |
hpe.hpert.api.event(device_id=None)
函数描述：创建一个事件。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| device_id | 输入参数 | NPC Cluster标识符。默认值为None，使用默认NPC Cluster |
| + 返回值：hpe.hpert.api.Event对象 |
hpe.hpert.api.Event.synchronize()
函数描述：等待指定事件执行完成。
函数类型：同步函数
返回值：None
hpe.hpert.api.Event.record (stream=0)
函数描述：在指定流的当前运行点添加事件。如果指定流为0，在所有流的当前运行点添加事件。
函数类型：同步函数
参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| stream | 输入参数 | 流标识符，默认值为0 |
| + 返回值：None |
通用数据类型
class hpe.hpert.api.Module
描述：管理加载到设备端的程序
class hpe.hpert.api.DeviceMem
描述：管理设备端分配的一段内存
class hpe.hpert.api.Stream
描述：管理流信息
class hpe.hpert.api.Event
描述：管理事件信息
class hpe.hpert.api.RuntimeAPIError
描述：管理接口函数执行的错误对应的异常信息
性能数据采集（stcpti）接口说明
使用方法：
import hpe.profiler.api
注意：接口函数的执行错误码通过异常（RuntimeAPIError）方式上报用户。
接口说明
hpe.profiler.api.init()
函数描述：初始化性能数据采集上下文。
函数类型：同步函数
返回值：成功则返回hpe.profiler.capi_ret.STC_PROFILER_SUCCESS，否则返回hpe.profiler.capi_ret.STC_PROFILER_ERROR
hpe.profiler.api.release()
函数描述：释放性能数据采集上下文。
函数类型：同步函数
返回值：成功则返回hpe.profiler.capi_ret.STC_PROFILER_SUCCESS，否则返回hpe.profiler.capi_ret.STC_PROFILER_ERROR
hpe.profiler.api.enable()
函数描述：使能性能数据采集。
函数类型：同步函数
返回值：成功则返回hpe.profiler.capi_ret.STC_PROFILER_SUCCESS，否则返回hpe.profiler.capi_ret.STC_PROFILER_ERROR
hpe.profiler.api.disable()
函数描述：禁止性能数据采集。
函数类型：同步函数
返回值：成功则返回hpe.profiler.capi_ret.STC_PROFILER_SUCCESS，否则返回hpe.profiler.capi_ret.STC_PROFILER_ERROR
hpe.profiler.api.get_perf_datas()
函数描述：设置用于主机线程执行设备端程序的默认NPC Cluster。线程的默认NPC Cluster为0。
函数类型：同步函数
返回值：
| 名称 | 类型 | 说明 |
|---|---|---|
| python_perf_datas | hpe.profiler.api.ProfilingResult | 性能数据采集结果 |
通用数据类型
class hpe.profiler.api.ProfilingResult
描述：性能数据采集结果
class hpe.profiler.api.KernelFunction
描述：核函数性能数据
hpe.profiler.capi_ret.STC_PROFILER_SUCCESS
描述：性能数据采集接口函数执行成功
hpe.profiler.capi_ret.STC_PROFILER_ERROR
描述：性能数据采集接口函数执行失败