Skip to content

LikwidAPI and MarkerAPI

Jump to bottom
Thomas Roehl edited this page Jul 27, 2021 · 3 revisions

Introduction

LIKWID consists of a shared library liblikwid.so with a C/C++ interface and some command line tools. Moreover, the library exposes a Lua interface which itself uses the C/C++ interface, called the LikwidAPI. The command line tools are mainly Lua scripts using the Lua interface of the library. For code instrumentation purposes, the library exposes an additional API for C/C++ and Fortran90, called the MarkerAPI. This API sits on top of the LikwidAPI and is basically it's first usage example. This page should further explain the use cases for the two APIs.

LikwidAPI

Like all shared libraries, the LIKWID library exposes a set of functions that can be used by other applications or libraries. The available functions are "announced" during compilation of the on-top application/library through the header file likwid-marker.h. The LikwidAPI provides low-level functionality like system topology data, affinity control, performance monitoring and system manipulation, anything that is provided by the command line tools. If you want to know the cache line size of a specific cache level, initialize the topology module (topology_init()), get the topology data (CpuTopology_t topo = get_cpuTopology()), read the line size (L1_cacheline_size = (topo->numCacheLevels > 0 ? topo->cacheLevels[0].lineSize : 0)) and close the topology again (topology_finalize()). The functions are grouped by their prefix, so NUMA information functions start with numa_, CPU hardware monitoring with perfmon_ and GPU hardware monitoring with nvmon_ and so on. The documentation of the LikwidAPI can be found here or created yourself with make docs (doxygen required).

Possible use cases:

  • Higher-level performance monitoring tools like Tau
  • Node monitoring agent for cluster monitoring systems like collectd
  • Daemon or runtime systems that manipulates CPU/Uncore frequencies like loop_adapt or GEOPM
  • Code instrumentation libraries like the MarkerAPI or timemory
  • Applications with a specific use-case for finer control of hardware measurements, CPU/Uncore frequencies, manipulate prefetchers, ...

Helpful links

MarkerAPI

The code instrumentation API MarkerAPI is one possible use case of the LikwidAPI. The MarkerAPI consists of simple functions/macros that set up LIKWID's performance monitoring module through the LikwidAPI and manage a hash table per thread for the measurement data. The MarkerAPI gets its basic configuration like cpu list, events and output file through environment variables to perform the initialization, set up the events and start the counters. When a marked code region is accessed, the functions read the counters and store the start value. When leaving a marked code region the counters are read again and the difference stored in the per-thread hash table. The hash table uses the region names as key and returns the region data struct for updating. When closing the MarkerAPI, the counters are stopped, the library finalized and the results are written to an output file.

Possible use cases:

  • Code instrumentation

Helpful links

Clone this wiki locally