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 sampling frequency. If the value is 0, the previous union indicates the sampling 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.
};

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

int PmuCollect(int pd, int milliseconds);

void PmuStop(int pd);

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

void PmuClose(int pd);

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

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