likwid.h

/*
 * =======================================================================================
 *
 *      Filename:  likwid.h
 *
 *      Description:  Header File of likwid API
 *
 *      Version:   <VERSION>
 *      Released:  <DATE>
 *
 *      Authors:  Thomas Roehl (tr), thomas.roehl@googlemail.com
 *
 *      Project:  likwid
 *
 *      Copyright (C) 2016 RRZE, University Erlangen-Nuremberg
 *
 *      This program is free software: you can redistribute it and/or modify it under
 *      the terms of the GNU General Public License as published by the Free Software
 *      Foundation, either version 3 of the License, or (at your option) any later
 *      version.
 *
 *      This program is distributed in the hope that it will be useful, but WITHOUT ANY
 *      WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 *      PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 *
 *      You should have received a copy of the GNU General Public License along with
 *      this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * =======================================================================================
 */
#ifndef LIKWID_H
#define LIKWID_H

#include <stdint.h>
#include <errno.h>
#include <string.h>

#include <bstrlib.h>

#define DEBUGLEV_ONLY_ERROR 0
#define DEBUGLEV_INFO 1
#define DEBUGLEV_DETAIL 2
#define DEBUGLEV_DEVELOP 3

#define LIKWID_VERSION "VERSION.RELEASE.MINORVERSION"
#define LIKWID_COMMIT GITCOMMIT

extern int perfmon_verbosity;

#ifdef LIKWID_PERFMON
#define LIKWID_MARKER_INIT likwid_markerInit()
#define LIKWID_MARKER_THREADINIT likwid_markerThreadInit()
#define LIKWID_MARKER_SWITCH likwid_markerNextGroup()
#define LIKWID_MARKER_REGISTER(regionTag) likwid_markerRegisterRegion(regionTag)
#define LIKWID_MARKER_START(regionTag) likwid_markerStartRegion(regionTag)
#define LIKWID_MARKER_STOP(regionTag) likwid_markerStopRegion(regionTag)
#define LIKWID_MARKER_CLOSE likwid_markerClose()
#define LIKWID_MARKER_GET(regionTag, nevents, events, time, count) likwid_markerGetRegion(regionTag, nevents, events, time, count)
#else
#define LIKWID_MARKER_INIT
#define LIKWID_MARKER_THREADINIT
#define LIKWID_MARKER_SWITCH
#define LIKWID_MARKER_REGISTER(regionTag)
#define LIKWID_MARKER_START(regionTag)
#define LIKWID_MARKER_STOP(regionTag)
#define LIKWID_MARKER_CLOSE
#define LIKWID_MARKER_GET(regionTag, nevents, events, time, count)
#endif

#ifdef __cplusplus
extern "C" {
#endif


/*
################################################################################
# Marker API related functions
################################################################################
*/
extern void likwid_markerInit(void) __attribute__ ((visibility ("default") ));
extern void likwid_markerThreadInit(void) __attribute__ ((visibility ("default") ));
extern void likwid_markerNextGroup(void) __attribute__ ((visibility ("default") ));
extern void likwid_markerClose(void) __attribute__ ((visibility ("default") ));
extern int likwid_markerRegisterRegion(const char* regionTag) __attribute__ ((visibility ("default") ));
extern int likwid_markerStartRegion(const char* regionTag) __attribute__ ((visibility ("default") ));
extern int likwid_markerStopRegion(const char* regionTag) __attribute__ ((visibility ("default") ));

extern void likwid_markerGetRegion(const char* regionTag, int* nr_events, double* events, double *time, int *count) __attribute__ ((visibility ("default") ));
/* utility routines */
extern int  likwid_getProcessorId() __attribute__ ((visibility ("default") ));
extern int  likwid_pinProcess(int processorId) __attribute__ ((visibility ("default") ));
extern int  likwid_pinThread(int processorId) __attribute__ ((visibility ("default") ));
/*
################################################################################
# Access client related functions
################################################################################
*/
typedef enum {
    ACCESSMODE_PERF = -1, 
    ACCESSMODE_DIRECT = 0, 
    ACCESSMODE_DAEMON = 1 
} AccessMode;

extern void HPMmode(int mode) __attribute__ ((visibility ("default") ));
extern int HPMinit() __attribute__ ((visibility ("default") ));
extern int HPMaddThread(int cpu_id) __attribute__ ((visibility ("default") ));
extern void HPMfinalize() __attribute__ ((visibility ("default") ));
/*
################################################################################
# Config file related functions
################################################################################
*/
typedef struct {
    char* configFileName; 
    char* topologyCfgFileName; 
    char* daemonPath; 
    char* groupPath; 
    AccessMode daemonMode; 
    int maxNumThreads; 
    int maxNumNodes; 
} Likwid_Configuration;

typedef Likwid_Configuration* Configuration_t;
extern int init_configuration(void) __attribute__ ((visibility ("default") ));
extern int destroy_configuration(void) __attribute__ ((visibility ("default") ));


extern Configuration_t get_configuration(void) __attribute__ ((visibility ("default") ));

extern int config_setGroupPath(const char* path) __attribute__ ((visibility ("default") ));

/*
################################################################################
# CPU topology related functions
################################################################################
*/
typedef struct {
    uint32_t family; 
    uint32_t model; 
    uint32_t stepping; 
    uint64_t clock; 
    int      turbo; 
    char*  osname; 
    char*  name; 
    char*  short_name; 
    char*  features; 
    int         isIntel; 
    int     supportUncore; 
    uint32_t featureFlags; 
    uint32_t perf_version; 
    uint32_t perf_num_ctr; 
    uint32_t perf_width_ctr; 
    uint32_t perf_num_fixed_ctr; 
} CpuInfo;

typedef struct {
    uint32_t threadId; 
    uint32_t coreId; 
    uint32_t packageId; 
    uint32_t apicId; 
    uint32_t inCpuSet; 
} HWThread;

typedef enum {
    NOCACHE=0, 
    DATACACHE, 
    INSTRUCTIONCACHE, 
    UNIFIEDCACHE, 
    ITLB, 
    DTLB 
} CacheType;

typedef struct {
    uint32_t level; 
    CacheType type; 
    uint32_t associativity; 
    uint32_t sets; 
    uint32_t lineSize; 
    uint32_t size; 
    uint32_t threads; 
    uint32_t inclusive; 
} CacheLevel;

typedef struct {
    uint32_t numHWThreads; 
    uint32_t activeHWThreads; 
    uint32_t numSockets; 
    uint32_t numCoresPerSocket; 
    uint32_t numThreadsPerCore; 
    uint32_t numCacheLevels; 
    HWThread* threadPool; 
    CacheLevel*  cacheLevels; 
    struct treeNode* topologyTree; 
} CpuTopology;

extern CpuInfo cpuid_info;
extern CpuTopology cpuid_topology;

typedef CpuInfo* CpuInfo_t;
typedef CpuTopology* CpuTopology_t;
extern int topology_init(void) __attribute__ ((visibility ("default") ));
extern CpuTopology_t get_cpuTopology(void) __attribute__ ((visibility ("default") ));
extern CpuInfo_t get_cpuInfo(void) __attribute__ ((visibility ("default") ));
extern void topology_finalize(void) __attribute__ ((visibility ("default") ));
extern void print_supportedCPUs(void) __attribute__ ((visibility ("default") ));
/*
################################################################################
# NUMA related functions
################################################################################
*/
typedef struct {
    uint32_t id; 
    uint64_t totalMemory; 
    uint64_t freeMemory; 
    uint32_t numberOfProcessors; 
    uint32_t*  processors; 
    uint32_t numberOfDistances; 
    uint32_t*  distances; 
} NumaNode;


typedef struct {
    uint32_t numberOfNodes; 
    NumaNode* nodes; 
} NumaTopology;

extern NumaTopology numa_info;

typedef NumaTopology* NumaTopology_t;

extern int numa_init(void) __attribute__ ((visibility ("default") ));
extern NumaTopology_t get_numaTopology(void) __attribute__ ((visibility ("default") ));
extern void numa_setInterleaved(const int* processorList, int numberOfProcessors) __attribute__ ((visibility ("default") ));
extern void numa_membind(void* ptr, size_t size, int domainId) __attribute__ ((visibility ("default") ));
extern void numa_finalize(void) __attribute__ ((visibility ("default") ));
extern int likwid_getNumberOfNodes(void) __attribute__ ((visibility ("default") ));
/*
################################################################################
# Affinity domains related functions
################################################################################
*/
typedef struct {
    bstring tag; 
    uint32_t numberOfProcessors; 
    uint32_t numberOfCores; 
    int*  processorList; 
} AffinityDomain;

typedef struct {
    uint32_t numberOfSocketDomains; 
    uint32_t numberOfNumaDomains; 
    uint32_t numberOfProcessorsPerSocket; 
    uint32_t numberOfCacheDomains; 
    uint32_t numberOfCoresPerCache; 
    uint32_t numberOfProcessorsPerCache; 
    uint32_t numberOfAffinityDomains; 
    AffinityDomain* domains; 
} AffinityDomains;

typedef AffinityDomains* AffinityDomains_t;

extern void affinity_init() __attribute__ ((visibility ("default") ));
extern AffinityDomains_t get_affinityDomains(void) __attribute__ ((visibility ("default") ));
extern void affinity_pinProcess(int processorId) __attribute__ ((visibility ("default") ));
extern void affinity_pinProcesses(int cpu_count, const int* processorIds) __attribute__ ((visibility ("default") ));
extern void affinity_pinThread(int processorId) __attribute__ ((visibility ("default") ));
extern int affinity_processGetProcessorId() __attribute__ ((visibility ("default") ));
extern int affinity_threadGetProcessorId() __attribute__ ((visibility ("default") ));
extern void affinity_finalize() __attribute__ ((visibility ("default") ));
/*
################################################################################
# CPU string parsing related functions
################################################################################
*/
extern int cpustr_to_cpulist(const char* cpustring, int* cpulist, int length)  __attribute__ ((visibility ("default") ));
extern int nodestr_to_nodelist(const char* nodestr, int* nodes, int length)  __attribute__ ((visibility ("default") ));
extern int sockstr_to_socklist(const char* sockstr, int* sockets, int length)  __attribute__ ((visibility ("default") ));

/*
################################################################################
# Performance monitoring related functions
################################################################################
*/
extern int perfmon_getGroups(char*** groups, char*** shortinfos, char*** longinfos) __attribute__ ((visibility ("default") ));

extern void perfmon_returnGroups(int nrgroups, char** groups, char** shortinfos, char** longinfos) __attribute__ ((visibility ("default") ));

extern int perfmon_init(int nrThreads, const int* threadsToCpu) __attribute__ ((visibility ("default") ));

extern void perfmon_init_maps(void) __attribute__ ((visibility ("default") ));
extern void perfmon_check_counter_map(int cpu_id) __attribute__ ((visibility ("default") ));
extern int perfmon_addEventSet(const char* eventCString) __attribute__ ((visibility ("default") ));
extern int perfmon_setupCounters(int groupId) __attribute__ ((visibility ("default") ));
extern int perfmon_startCounters(void) __attribute__ ((visibility ("default") ));
extern int perfmon_stopCounters(void) __attribute__ ((visibility ("default") ));
extern int perfmon_readCounters(void) __attribute__ ((visibility ("default") ));
extern int perfmon_readCountersCpu(int cpu_id) __attribute__ ((visibility ("default") ));
extern int perfmon_readGroupCounters(int groupId) __attribute__ ((visibility ("default") ));
extern int perfmon_readGroupThreadCounters(int groupId, int threadId) __attribute__ ((visibility ("default") ));
extern int perfmon_switchActiveGroup(int new_group) __attribute__ ((visibility ("default") ));
extern void perfmon_finalize(void) __attribute__ ((visibility ("default") ));
extern double perfmon_getResult(int groupId, int eventId, int threadId) __attribute__ ((visibility ("default") ));
extern double perfmon_getLastResult(int groupId, int eventId, int threadId) __attribute__ ((visibility ("default") ));
extern double perfmon_getMetric(int groupId, int metricId, int threadId) __attribute__ ((visibility ("default") ));
extern double perfmon_getLastMetric(int groupId, int metricId, int threadId) __attribute__ ((visibility ("default") ));

extern int perfmon_getNumberOfGroups(void) __attribute__ ((visibility ("default") ));
extern int perfmon_getNumberOfEvents(int groupId) __attribute__ ((visibility ("default") ));
extern double perfmon_getTimeOfGroup(int groupId) __attribute__ ((visibility ("default") ));
extern int perfmon_getIdOfActiveGroup(void) __attribute__ ((visibility ("default") ));
extern int perfmon_getNumberOfThreads(void) __attribute__ ((visibility ("default") ));


extern void perfmon_setVerbosity(int verbose) __attribute__ ((visibility ("default") ));

extern char* perfmon_getEventName(int groupId, int eventId) __attribute__ ((visibility ("default") ));
extern char* perfmon_getCounterName(int groupId, int eventId) __attribute__ ((visibility ("default") ));
extern char* perfmon_getGroupName(int groupId) __attribute__ ((visibility ("default") ));
extern char* perfmon_getMetricName(int groupId, int metricId) __attribute__ ((visibility ("default") ));
extern char* perfmon_getGroupInfoShort(int groupId) __attribute__ ((visibility ("default") ));
extern char* perfmon_getGroupInfoLong(int groupId) __attribute__ ((visibility ("default") ));

extern int perfmon_getNumberOfMetrics(int groupId) __attribute__ ((visibility ("default") ));

extern double perfmon_getLastTimeOfGroup(int groupId) __attribute__ ((visibility ("default") ));

extern int perfmon_readMarkerFile(const char* filename) __attribute__ ((visibility ("default") ));
extern void perfmon_destroyMarkerResults() __attribute__ ((visibility ("default") ));
extern int perfmon_getNumberOfRegions() __attribute__ ((visibility ("default") ));
extern int perfmon_getGroupOfRegion(int region) __attribute__ ((visibility ("default") ));
extern char* perfmon_getTagOfRegion(int region) __attribute__ ((visibility ("default") ));
extern int perfmon_getEventsOfRegion(int region) __attribute__ ((visibility ("default") ));
extern int perfmon_getMetricsOfRegion(int region) __attribute__ ((visibility ("default") ));
extern int perfmon_getThreadsOfRegion(int region) __attribute__ ((visibility ("default") ));
extern int perfmon_getCpulistOfRegion(int region, int count, int* cpulist)  __attribute__ ((visibility ("default") ));
extern double perfmon_getTimeOfRegion(int region, int thread) __attribute__ ((visibility ("default") ));
extern int perfmon_getCountOfRegion(int region, int thread) __attribute__ ((visibility ("default") ));
extern double perfmon_getResultOfRegionThread(int region, int event, int thread) __attribute__ ((visibility ("default") ));
extern double perfmon_getMetricOfRegionThread(int region, int metricId, int threadId) __attribute__ ((visibility ("default") ));

/*
################################################################################
# Time measurements related functions
################################################################################
*/

typedef union
{
    uint64_t int64; 
    struct {uint32_t lo, hi;} int32; 
} TscCounter;

typedef struct {
    TscCounter start; 
    TscCounter stop; 
} TimerData;

extern void timer_init( void ) __attribute__ ((visibility ("default") ));
extern double timer_print( const TimerData* time) __attribute__ ((visibility ("default") ));
extern uint64_t timer_printCycles( const TimerData* time) __attribute__ ((visibility ("default") ));
extern void timer_reset( TimerData* time ) __attribute__ ((visibility ("default") ));
extern uint64_t timer_getCpuClock( void ) __attribute__ ((visibility ("default") ));
extern uint64_t timer_getCpuClockCurrent( int cpu_id ) __attribute__ ((visibility ("default") ));
extern uint64_t timer_getCycleClock( void ) __attribute__ ((visibility ("default") ));
extern uint64_t timer_getBaseline( void ) __attribute__ ((visibility ("default") ));
extern void timer_start( TimerData* time ) __attribute__ ((visibility ("default") ));
extern void timer_stop ( TimerData* time) __attribute__ ((visibility ("default") ));
extern int timer_sleep(unsigned long usec) __attribute__ ((visibility ("default") ));

extern void timer_finalize(void) __attribute__ ((visibility ("default") ));

/*
################################################################################
# Power measurements related functions
################################################################################
*/
#define NUM_POWER_DOMAINS 5

extern const char* power_names[NUM_POWER_DOMAINS] __attribute__ ((visibility ("default") ));

#define POWER_DOMAIN_SUPPORT_STATUS (1ULL<<0)

#define POWER_DOMAIN_SUPPORT_LIMIT (1ULL<<1)

#define POWER_DOMAIN_SUPPORT_POLICY (1ULL<<2)

#define POWER_DOMAIN_SUPPORT_PERF (1ULL<<3)

#define POWER_DOMAIN_SUPPORT_INFO (1ULL<<4)


typedef struct {
    int numSteps; 
    double* steps; 
} TurboBoost;

typedef enum {
    PKG = 0, 
    PP0 = 1, 
    PP1 = 2, 
    DRAM = 3, 
    PLATFORM = 4 
} PowerType;

typedef struct {
    PowerType type; 
    uint32_t supportFlags; 
    double energyUnit; 
    double tdp; 
    double minPower; 
    double maxPower; 
    double maxTimeWindow; 
} PowerDomain;

typedef struct {
    double baseFrequency; 
    double minFrequency; 
    TurboBoost turbo; 
    int hasRAPL; 
    double powerUnit; 
    double timeUnit; 
    double uncoreMinFreq; 
    double uncoreMaxFreq; 
    uint8_t perfBias; 
    PowerDomain domains[NUM_POWER_DOMAINS]; 
} PowerInfo;

typedef struct {
    int domain; 
    uint32_t before; 
    uint32_t after; 
} PowerData;

extern PowerInfo power_info;

typedef PowerInfo* PowerInfo_t;
typedef PowerData* PowerData_t;

extern int power_init(int cpuId) __attribute__ ((visibility ("default") ));
extern PowerInfo_t get_powerInfo(void) __attribute__ ((visibility ("default") ));
extern int power_read(int cpuId, uint64_t reg, uint32_t *data) __attribute__ ((visibility ("default") ));
extern int power_tread(int socket_fd, int cpuId, uint64_t reg, uint32_t *data) __attribute__ ((visibility ("default") ));
extern int power_start(PowerData_t data, int cpuId, PowerType type) __attribute__ ((visibility ("default") ));
extern int power_stop(PowerData_t data, int cpuId, PowerType type) __attribute__ ((visibility ("default") ));
extern double power_printEnergy(const PowerData* data) __attribute__ ((visibility ("default") ));
extern double power_getEnergyUnit(int domain) __attribute__ ((visibility ("default") ));

int power_limitGet(int cpuId, PowerType domain, double* power, double* time) __attribute__ ((visibility ("default") ));

int power_limitSet(int cpuId, PowerType domain, double power, double time, int doClamping) __attribute__ ((visibility ("default") ));

int power_limitState(int cpuId, PowerType domain) __attribute__ ((visibility ("default") ));

extern void power_finalize(void) __attribute__ ((visibility ("default") ));
/*
################################################################################
# Thermal measurements related functions
################################################################################
*/
extern void thermal_init(int cpuId) __attribute__ ((visibility ("default") ));
extern int thermal_read(int cpuId, uint32_t *data) __attribute__ ((visibility ("default") ));
extern int thermal_tread(int socket_fd, int cpuId, uint32_t *data) __attribute__ ((visibility ("default") ));
/*
################################################################################
# Memory sweeping related functions
################################################################################
*/
extern void memsweep_domain(int domainId) __attribute__ ((visibility ("default") ));
extern void memsweep_threadGroup(const int* processorList, int numberOfProcessors) __attribute__ ((visibility ("default") ));
/*
################################################################################
# CPU feature related functions
################################################################################
*/
typedef enum {
    FEAT_HW_PREFETCHER=0, 
    FEAT_CL_PREFETCHER, 
    FEAT_DCU_PREFETCHER, 
    FEAT_IP_PREFETCHER, 
    FEAT_FAST_STRINGS, 
    FEAT_THERMAL_CONTROL, 
    FEAT_PERF_MON, 
    FEAT_FERR_MULTIPLEX, 
    FEAT_BRANCH_TRACE_STORAGE, 
    FEAT_XTPR_MESSAGE, 
    FEAT_PEBS, 
    FEAT_SPEEDSTEP, 
    FEAT_MONITOR, 
    FEAT_SPEEDSTEP_LOCK, 
    FEAT_CPUID_MAX_VAL, 
    FEAT_XD_BIT, 
    FEAT_DYN_ACCEL, 
    FEAT_TURBO_MODE, 
    FEAT_TM2, 
    CPUFEATURES_MAX
} CpuFeature;

extern void cpuFeatures_init() __attribute__ ((visibility ("default") ));
extern void cpuFeatures_print(int cpu) __attribute__ ((visibility ("default") ));
extern int cpuFeatures_get(int cpu, CpuFeature type)  __attribute__ ((visibility ("default") ));
extern char* cpuFeatures_name(CpuFeature type)  __attribute__ ((visibility ("default") ));
extern int cpuFeatures_enable(int cpu, CpuFeature type, int print) __attribute__ ((visibility ("default") ));
extern int cpuFeatures_disable(int cpu, CpuFeature type, int print) __attribute__ ((visibility ("default") ));
/*
################################################################################
# CPU frequency related functions
################################################################################
*/
extern uint64_t freq_getCpuClockCurrent(const int cpu_id ) __attribute__ ((visibility ("default") ));

extern uint64_t freq_getCpuClockMax(const int cpu_id ) __attribute__ ((visibility ("default") ));
extern uint64_t freq_setCpuClockMax(const int cpu_id, const uint64_t freq) __attribute__ ((visibility ("default") ));
extern uint64_t freq_getCpuClockMin(const int cpu_id ) __attribute__ ((visibility ("default") ));
extern uint64_t freq_setCpuClockMin(const int cpu_id, const uint64_t freq) __attribute__ ((visibility ("default") ));
extern int freq_setTurbo(const int cpu_id, int turbo) __attribute__ ((visibility ("default") ));
extern int freq_getTurbo(const int cpu_id) __attribute__ ((visibility ("default") ));
extern char * freq_getGovernor(const int cpu_id ) __attribute__ ((visibility ("default") ));
extern int freq_setGovernor(const int cpu_id, const char* gov) __attribute__ ((visibility ("default") ));
extern char * freq_getAvailFreq(const int cpu_id ) __attribute__ ((visibility ("default") ));
extern char * freq_getAvailGovs(const int cpu_id ) __attribute__ ((visibility ("default") ));

extern int freq_setUncoreFreqMin(const int socket_id, const uint64_t freq) __attribute__ ((visibility ("default") ));

extern uint64_t freq_getUncoreFreqMin(const int socket_id) __attribute__ ((visibility ("default") ));

extern int freq_setUncoreFreqMax(const int socket_id, const uint64_t freq) __attribute__ ((visibility ("default") ));

extern uint64_t freq_getUncoreFreqMax(const int socket_id) __attribute__ ((visibility ("default") ));
extern uint64_t freq_getUncoreFreqCur(const int socket_id) __attribute__ ((visibility ("default") ));
#ifdef __cplusplus
}
#endif

#endif /*LIKWID_H*/