---
title: libkperf API说明
description: "- 采集类型："
url: https://www.hikunpeng.com/document/detail/zh/kunpengdevkithistory/devkit_24/usermanual/KunpengDevKit_0099.html
sourcePath: /source/zh/kunpengdevkithistory/devkit_24/usermanual/KunpengDevKit_0099.html
indexId: 63622930e0547f4766221aa43d4b8c41d387682ddbfb8ed6828a1fede948232676
---
# libkperf API说明

- 采集类型：

```
enum PmuTaskType {
COUNTING = 0,   // 计数
SAMPLING = 1,   // Pmu采样
SPE_SAMPLING = 2,   // SPE采样
};
```


- 指标类型：

```
enum PmuMetricType {
TMA_LEVEL1,         // topdown level1
TMA_FRONTEND,       // topdown frontend
TMA_BADSPEC,        // topdown bad speculation
TMA_CORE_BOUND,     // topdown core bound
TMA_MEM_BOUND,      // topdown memory bound
TMA_RESOURCE_BOUND, // topdown resource bound
};
```


- 指标聚合类型：

```
enum AggregateType {
PER_SYSTEM,         // 以系统为维度
PER_CORE,           // 以core为维度
PER_NUMA,           // 以numa为维度
PER_SOCKET,         // 以socket为维度
PER_THREAD,         // 以线程为维度
};
```


- SPE数据选择器：

```
enum SpeFilter {
SPE_FILTER_NONE = 0,
TS_ENABLE = 1UL << 0,       // 使用通用计时器的值启用时间戳
PA_ENABLE = 1UL << 1,       // 收集load和store的物理地址（以及VA）
PCT_ENABLE = 1UL << 2,      // 收集物理时间戳而不是虚拟时间戳
JITTER = 1UL << 16,         // 使用抖动避免采样时的共振
BRANCH_FILTER = 1UL << 32,  // 收集分支
LOAD_FILTER = 1UL << 33,    // 收集load指令
STORE_FILTER = 1UL << 34,   // 收集store指令
SPE_DATA_ALL = TS_ENABLE | PA_ENABLE | PCT_ENABLE | JITTER | BRANCH_FILTER | LOAD_FILTER | STORE_FILTER
};
```


- SPE事件选择器：

```
enum SpeEventFilter {
SPE_EVENT_NONE = 0,
SPE_EVENT_RETIRED = 0x2,        // instruction retired
SPE_EVENT_L1DMISS = 0x8,        // L1D refill
SPE_EVENT_TLB_WALK = 0x20,      // TLB refill
SPE_EVENT_MISPREDICTED = 0x80,  // mispredict
};
```


- 任务属性：

```
struct PmuAttr {
char** evtList;                  // 事件列表
unsigned numEvt;                 // 事件列表的长度
int* pidList;                    // pid列表
unsigned numPid;                 // pid列表的长度
int* cpuList;                    // cpu id列表
unsigned numCpu;                 // cpu id列表的长度
union {
unsigned period;              // 采样周期
unsigned freq;                // 采样频率
};
unsigned useFreq : 1;             // 是否使用采样频率，如果为1，那么上一个union表示频率，如果为0，那么上一个union表示周期
// SPE related fields.
enum SpeFilter dataFilter;        // SPE数据选择器
enum SpeEventFilter evFilter;     // SPE事件选择器
unsigned long minLatency;         // 仅采集具有此延迟或更高延迟的样本
};
```


- topdown level1数据：

```
struct TmaLevel1 {
float ipc;
float retired;
float backendBd;
float frontendBd;
float badSpeculation;
};
```


- topdown frontend数据：

```
struct TmaFtEndBd {
struct TmaLevel1* level1;
float fetchLatencyBound;
float itlbMiss;
float l1Tlb;
float l2Tlb;
float icacheMiss;
float l1Miss;
float l2Miss;
float bpMispFlush;
float oooFlush;
float spFlush;
float fetchBandwidthBound;
};
```


- topdown core bound数据：

```
struct TmaCoreBd {
struct TmaLevel1* level1;
float coreBound;
float divider;
float fsuStall;
float exePortsUtil;
};
```


- topdown bad speculation数据：

```
struct TmaBadSpec {
struct TmaLevel1* level1;
float branchMispredict;
float indirectBranch;
float pushBranch;
float popBranch;
float otherBranch;
float machineClear;
float nukeFlush;
float otherFlush;
};
```


- topdown memory bound数据：

```
struct TmaMemBd {
struct TmaLevel1* level1;
float memoryBound;
float l1Bound;
float l2Bound;
float memBound;
float storeBound;
};
```


- topdown resource bound数据：

```
struct TmaResourceBd {
struct TmaLevel1* level1;
float resourceBound;
float syncStall;
float robStall;
float ptagStall;
float saveopqStall;
float pcBufferStall;
float ccphysicalStall;
float intphysicalStall;
float vfpphysicalStall;
};
```


- 指标数据：

```
union PmuMetricData {
struct TmaLevel1* level1;
struct TmaFtEndBd* tmaFtEndBd;
struct TmaCoreBd* tmaCorebd;
struct TmaBadSpec* tmaBadSpec;
struct TmaMemBd* tmaMemBd;
struct TmaResourceBd* tmaResourceBd;
};
```


- 指标数据：

```
struct PmuMetric {
int id;                         // 根据AggregateType，id有不同的含义：
// PER_SYSTEM，id等于-1；
// PER_CORE，id表示cpu id；
// PER_NUMA，id表示numa id；
// PER_SOCKET，id表示socket id；
// PER_THREAD，id表示pid。
int metricType;                 // 聚合类型
union PmuMetricData data;       // 指标数据
};
struct PmuDataExt {
unsigned long pa;               // 物理地址
unsigned long va;               // 虚拟地址
unsigned long event;            // 事件id
};
struct SampleRawData {
char *data;                     // tracepointer事件对应的raw data数据
};
struct SampleRawField {
char* fieldName;                 // 字段名称
char* fieldStr;                  // 字段描述
unsigned offset;                 // 偏移量
unsigned size;                   // 字节数
unsigned isSigned;               // 是否有符号
};
struct PmuData {
struct Stack* stack;            // 调用栈
const char *evt;                // 事件名称
int64_t ts;                     // 时间戳
pid_t pid;                      // 进程id
int tid;                        // 线程id
unsigned cpu;                   // cpu id
struct CpuTopology *cpuTopo;    // cpu拓扑
const char *comm;               // 进程的命令
uint64_t period;                // 采集时长
uint64_t count;                 // 当前数据的计数。只有在COUNTING类型下才有效
struct PmuDataExt *ext;         // 扩展数据，目前只在SPE类型下才有效
struct SampleRawData *rawData;  // tracepointer事件对应的raw data数据
};
```


- 初始化采集任务。
  初始化成功后返回大于等于0的描述符；初始化失败后返回-1。

```
int PmuOpen(enum PmuTaskType collectType, struct PmuAttr *attr);
```


- 执行采集过程。
  <milliseconds>的单位是毫秒。

  如果<milliseconds>是-1，则一直会采集到进程结束或者采集被PmuStop停止。

  返回值是错误码。

```
int PmuCollect(int pd, int milliseconds);
```


- 停止采集过程：

```
void PmuStop(int pd);
```


- 读取上一次的采集数据，数据存放在<pmuData>，<pmuData>是数组结构。
  返回值是<pmuData>的长度。

  如果读取数据失败，则返回-1。

```
int PmuRead(int pd, struct PmuData** pmuData);
```


- 关闭<pd>对应的采集任务

```
void PmuClose(int pd);
```


- 获取topdown的事件列表，用于调用PmuOpen。

```
const char** PmuTopDownEvents(enum PmuMetricType metric, unsigned *numEvt);
```


- 根据指标类型和聚合类型计算指标数据。
  指标数据存放在<metric>，是数组结构。

  返回值是<metric>的长度。

  如果计算指标数据失败，则返回-1。

```
int PmuComputeMetric(
int pd, enum PmuMetricType metricType, enum AggregateType aggregateType, struct PmuMetric** metric);
```


- 释放struct PmuMetric*。

```
void PmuMetricFree(struct PmuMetric* metricData);
```


- 释放struct PmuData*。

```
void PmuDataFree(struct PmuData* pmuData);
```


- 获取tracepointer指定字段。

```
int PmuGetField(struct SampleRawData *rawData, const char *fieldName, void *value, uint32_t vSize);
```


- 获取tracepointer指定字段的说明。

```
struct SampleRawField *PmuGetFieldExp(struct SampleRawData *rawData, const char *fieldName);
```