TutorialLikwidLua

Embed LIKWID into a Lua application

During the transition from LIKWID version 3 to 4, we restructured LIKWID to a more library centric approach. The main motivation was that users can embed LIKWID into their applications. Similar to LIKWID 3, the core of LIKWID is written in C and of course can be directly used with C/C++ programs. On top of the C-core, we added an interface to the scripting language Lua. Lua was chosen because it can be easily embedded in other programming languages and Lua itself can embed other languages pretty easy. Nearly all LIKWID applications are now written in Lua and can be used as examples for more advanced LIKWID programming.

In order to load the LIKWID module, the search path of Lua must be extended by:

-- Add likwid.lua to search path for Lua modules
package.path = '<INSTALLPREFIX>/share/lua/?.lua;' .. package.path
-- Load LIKWID module (expands cpath to LIKWID C-library)
likwid = require("likwid")

Some Lua functions for LIKWID

The Lua interface has a lot of functions but for measuring performance data, only a few are required. The most functions address sub modules of LIKWID directly but only the main ones are needed in the first place.

• likwid.getCpuInfo() Returns a list of information of the current system like CPU name, microarchitecture, CPU features,...
• likwid.getCpuTopology() Returns a list of information about the topology of the current system like amount of CPU sockets, amount of total/online CPUs, sublist holding all threads with their IDs and location, ...
• likwid.putTopology() Finalize the topology module of the LIKWID. You can still use the lists you retrieved by likwid.getCpuInfo() or likwid.getCpuTopology() but if you call one of the functions again, the topology module is initialized again causing some overhead.
• err = likwid.init(amount_of_cpus, list_of_cpus) Initializes the LIKWID library to allow measuring on the given set of CPUs.
• gid = likwid.addEventSet(string_of_events) Add the given string to the LIKWID library. The string_of_events has the format: event1:counter1(:option1.1:option1.2:...),event2:counter2(:option2.1:option2.2:...),.... The function returns the ID of the eventset that is needed for setting up the counters. Notice: You cannot add a predefined performance group name here, the group must be resolved to the event string using gdata = likwid.get_groupdata(group) and then likwid.addEventSet(gdata.EventString).
• err = likwid.setupCounters(gid) Program the hardware performance counter to measure the event string identified by gid.
• err = likwid.startCounters() Start the previously programmed event string.
• err = likwid.stopCounters() Stop the previously programmed event string.
• result = likwid.getResult(gid, eid, tid) Get the result for the event string identified by gid for the event eid and the thread tid. The eid is the position of the desired event in the event string starting with 1. Similarily, tid is the index of the desired CPU in the list that was submitted to likwid.init()
• likwid.finalize() Finalize the performance monitoring module of LIKWID. Don't use any of the module functions afterwards.

Example code

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

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.