libkperf APIs

enum PmuTaskType {
    COUNTING = 0,   // Counting
    SAMPLING = 1,   // PMU sampling
    SPE_SAMPLING = 2,   // SPE sampling
};

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,         // By system
    PER_CORE,           // By core
    PER_NUMA,           // By NUMA
    PER_SOCKET,         // By socket
    PER_THREAD,         // By thread
};

enum SpeFilter {
    SPE_FILTER_NONE = 0,
    TS_ENABLE = 1UL << 0,       // Uses the value of the general timer to enable timestamps.
    PA_ENABLE = 1UL << 1,       // Collects the physical and virtual addresses of the load and store.
    PCT_ENABLE = 1UL << 2,      // Collects physical timestamps instead of virtual timestamps.
    JITTER = 1UL << 16,         // Uses jitter to avoid resonance during sampling.
    BRANCH_FILTER = 1UL << 32,  // Collects branches.
    LOAD_FILTER = 1UL << 33,    // Collects load instructions.
    STORE_FILTER = 1UL << 34,   // Collects store instructions.
    SPE_DATA_ALL = TS_ENABLE | PA_ENABLE | PCT_ENABLE | JITTER | BRANCH_FILTER | LOAD_FILTER | STORE_FILTER
};

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;                 // Event list.
    unsigned numEvt;                // Event list length.
    int* pidList;                   // PID list.
    unsigned numPid;                // PID list length.
    int* cpuList;                   // CPU ID list.
    unsigned numCpu;                // CPU ID list length.
    union {
        unsigned period;              // Sampling period.
        unsigned freq;                // Sampling frequency.
    };
    unsigned useFreq : 1;             // Indicates whether to use the sampling frequency. If the value is 1, the previous union indicates the frequency. If the value is 0, the previous union indicates the period.
    // SPE related fields.
    enum SpeFilter dataFilter;       // SPE data selector.
    enum SpeEventFilter evFilter;   // SPE event selector.
    unsigned long minLatency;       // Collects only samples with this delay or higher delay.
};

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

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;
};

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

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

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

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;                         // The ID meaning varies according to AggregateType:
                                    // For PER_SYSTEM, the ID is equal to -1.
                                    // For PER_CORE, the ID indicates the CPU ID.
                                    // For PER_NUMA, the ID indicates the NUMA node ID.
                                    // For PER_SOCKET, the ID indicates the socket ID.
                                    // For PER_THREAD, the ID indicates the PID.
    int metricType;                 // Aggregation type.
    union PmuMetricData data;       // Metric data.
};
struct PmuDataExt {
    unsigned long pa;               // Physical address.
    unsigned long va;               // Virtual address.
    unsigned long event;            // Event ID.
};
struct SampleRawData {
    char *data;                     // Raw data corresponding to the tracepointer event.
};
struct SampleRawField {
    char* fieldName;                 // Field name.
    char* fieldStr;                  // Field description.
    unsigned offset;                 // Offset.
    unsigned size;                   // Number of bytes.
    unsigned isSigned;               // Whether there is a sign.
};
struct PmuData {
    struct Stack* stack;            // Call stack.
    const char *evt;                // Event name.
    int64_t ts;                     // Timestamp.
    pid_t pid;                      // Process ID.
    int tid;                        // Thread ID.
    unsigned cpu;                   // CPU ID.
    struct CpuTopology *cpuTopo;    // CPU topology.
    const char *comm;               // Process command.
    uint64_t period;                // Collection duration.
    uint64_t count;                 // Count of the current data. This parameter is valid only for the COUNTING type.
    struct PmuDataExt *ext;         // Extended data. This parameter is valid only for the SPE type.
    struct SampleRawData *rawData;  // Raw data corresponding to the tracepointer event.
};

If the initialization is successful, a descriptor greater than or equal to 0 is returned. If the initialization fails, -1 is returned.

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

If the value of <milliseconds> is -1, the collection does not stop until the process ends or the collection is stopped by PmuStop.

The return value is an error code:

int PmuCollect(int pd, int milliseconds);

void PmuStop(int pd);

The return value is the length of <pmuData>.

If the data read fails, -1 is returned.

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

void PmuClose(int pd);

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

The metric data is stored in <metric>, which is an array structure.

The return value is the length of <metric>.

If the metric data fails to be calculated, -1 is returned.

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

void PmuMetricFree(struct PmuMetric* metricData);

void PmuDataFree(struct PmuData* pmuData);

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

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