TutorialLikwidC

Embed LIKWID into a C/C++ application

With the older versions of LIKWID embedding it into C/C++ applications was an unusual way. Most users just used the set of LIKWID applications. For LIKWID 4, we took a more library centric approach to ease the embedding of LIKWID into other applications. All functions of the C/C++ LIKWID API are exported to Lua thus it is recommended to use Lua for writing wrapper applications. If you want to embed LIKWID into your code, you can of course use the C/C++ API.

Some C/C++ functions for LIKWID

The LIKWID C/C++ API is comprehensive because it allows to address sub modules like the topology or timer code directly. In order to use it for hardware performance counter measurements, only a few functions are required.

• int err = topology_init() Initialize the topology module and fill internal structures with the topology of the current system. If err unequal zero, there was a failure.
• CpuInfo_t info = get_cpuInfo() Get a pointer to the CPU information structure holding global information like CPU name, microarchitecture or CPU stepping.
• CpuTopology_t topo = get_cpuTopology() Get a pointer to the topology information structure holding data like number of total/online CPUs, number of CPU sockets and a sub list for all threads with their IDs and location.
• accessClient_setaccessmode(int mode) Change the hardware access mode for LIKWID. 0 for direct access to the registers (requires higher privileges) and 1 for the access daemon.
• int err = perfmon_init(int numCPUs, int* cpulist) Initialize the perfmon module that enables performance measurements. Depending on the access mode, it starts the access daemon or initializes direct access to the MSR and PCI devices. If err unequal zero, there was a failure.
• int gid = perfmon_addEventSet(char* eventSet) Add the event string eventSet to the perfmon module for measurments. gid is the ID of the event group used later to setup the counters and retrieve the measured results. If an error occurs, the gid is negative.
• int err = perfmon_setupCounters(int gid) Program the hardware counter registers to reflect the the event string idenified by gid.
• int err = perfmon_startCounters() Start the hardware counters on all configured CPUs.
• int err = perfmon_stopCounters() Stop the hardware counters on all configured CPUs.
• double result = perfmon_getResult(gid, eid, tid) Retrieve the results identified by the group ID gid, the event ID eid (index of the event in the event string) and thread ID tid (index of the CPU in the cpulist given at perfmon_init(...)).
• topology_finalize() Empty and delete the data structures of the topology module. The data structures returned by get_cpuInfo() and get_cpuTopology() are not usable afterwards.
• perfmon_finalize() Close the connection to the performance monitoring module. Except perfmon_init(...) no other call starting with perfmon_ should be called afterwards.

Example code

An example code can be found here: https://github.com/RRZE-HPC/likwid/blob/master/examples/C-likwidAPI.c

Complete interface

In order to see the complete interface, create the HTML documentation with make docs by now, I will add Wiki pages as soon as I have time.