/*!\page lua_Info Information about LIKWID's Lua API

# How to include Lua API into own Lua applications

`package.path = package.path .. ';/usr/local/share/lua/?.lua'
local likwid = require("likwid")
`

Now all function and variables can be called with
`likwid.functionname()`
or
`likwid.variable`

# Global variables defined by LIKWID's Lua API

Variablename | Description
--- | ---
\a groupfolder | Path to the folder containing the definitions of the performance groups
\a version | Version of LIKWID
\a release | Release number of LIKWID
\a pinlibpath | Path to the pinning library. Is added automatically to $LD_PRELOAD by \ref likwid-pin and \ref likwid-perfctr
\a hline | Horizontal line with 80 '-' characters
\a sline | Horizontal line with 80 '*' characters
\a dline | Horizontal line with 80 '=' characters

\page lua_Config Config file module

# Data type definition for Lua config file module in the Lua API

\anchor lua_config

## Config file read

This structure is returned by \ref getConfiguration function
The config file can be created with \ref likwid-genTopoCfg executable. It searches the files /etc/likwid.cfg and /usr/local/etc/likwid.cfg. Other configuration file paths can be set in config.mk before building LIKWID.

Membername | Comment
--- | ---
\a configFile | Path to the config file
\a topologyFile | Path to the config file containing topology information
\a daemonPath | Path to the access daemon
\a daemonMode | Access mode for LIKWID (0 = direct access, 1 = access daemon)
\a maxNumThreads | Maximal amount of hardware threads in the system
\a maxNumNodes | Maximal amount of NUMA nodes in the system
\a maxHashTableSize | Maximal size for the internally used hash table

# Function definitions for Lua config file module in the Lua API

\anchor getConfiguration

## getConfiguration()

Read the configuration file and return a list of config options

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of configuration options, see \ref lua_config

\anchor setVerbosity

## setVerbosity(verbosity)

Define and/or change the verbosity level of LIKWID

Direction | Data type(s)
--- | ---
Input Parameter |
\a verbosity | 0 = only errors 1 = infos 2 = detail 3 = developer Other flags are rejected.
Returns | None

\anchor setGroupPath

## setGroupPath(path)

Change the path to the performance group files.

Direction | Data type(s)
--- | ---
Input Parameter |
\a path | Path to group files
Returns | None

\anchor putConfiguration

## putConfiguration()

Frees the C-structures that were created by \ref getConfiguration function.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | None

\page lua_LibInfo Library information module

# Data type definition for the library information module in the Lua API

\anchor lua_libinfo

## LibInfo

This structure is returned by \ref getLibInfo function

Membername | Comment
--- | ---
\a majorVersion | Major version number of LIKWID library
\a minorVersion | Minor version number of LIKWID library
\a bugfixVersion | Bugfix version number of LIKWID library
\a nvidiaSupport | Boolean whether library was built with Nvidia CUDA/CUPTI support
\a rocmSupport | Boolean whether library was built with AMD ROCm support
\a sysfeaturesSupport | Boolean whether library was built with sysFeatures enabled
\a maxNumThreads | Maximal number of hardware threads the library can handle
\a maxNumSockets | Maximal number of CPU sockets the library can handle
\a turbo | Flag if the system supports the Turbo mode

# Function definitions for the library information module in the Lua API

\anchor getLibInfo

## getLibInfo()

Returns library information like build configuration and supported modules.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List with various library information, see \ref lua_libinfo

\page lua_Access Access client module

# Data type definition for Lua access client module in the Lua API

# Function definitions for Lua access client module in the Lua API

\anchor setAccessMode

## setAccessMode(accessFlag)

Define and/or change the access mode to the MSR and PCI registers

Direction | Data type(s)
--- | ---
Input Parameter |
\a accessFlag | 0 = direct access 1 = access daemon Other flags are rejected.
Returns | Always 0

\page lua_CPUTopology CPU information module

# Data type definition for CPU information module in the Lua API

\anchor lua_cpuinfo

## Cpu Info

This structure is returned by \ref getCpuInfo function
It is similar to the C struct CpuInfo

Membername | Comment
--- | ---
\a family | Family ID of CPU
\a model | Model ID of CPU
\a stepping | Revision of CPU
\a clock | Base clock frequency
\a turbo | Flag if the system supports the Turbo mode
\a name | Name of the microarchitecture
\a osname | Name of the CPU as given by manufacturer
\a short_name | Short name of microarchitecture
\a features | String with all interesting CPU feature flags as a space separated list
\a featureFlags | Bitmask with all interesting CPU feature flags Bit positions can be retrieved from the FeatureBit enum
\a isIntel | Flag to check if the system is using Intel CPUs
\a perf_version | Version of architectural performance monitoring capabilities
\a perf_num_ctr | Amount of HWthread-local general-purpose counters
\a perf_num_fixed_ctr | Amount of HWthread-local fixed-purpose counters
\a perf_width_ctr | Register width of HWthread-local counters

\anchor lua_cputopo

## Cpu Topology

This structure is returned by \ref getCpuTopology function
The nested list structure is similar to the C struct CpuTopology.

Membername | Comment
--- | ---
\a numHWThreads | Total amount of hardware threads in the system
\a activeHWThreads | Amount of active hardware threads in the system
\a numSockets | Number of CPU sockets in the system
\a numCoresPerSocket | Number of physical cores of each socket in the system
\a numThreadsPerCore | Number of hardware threads of each CPU core in the system
\a numCacheLevels | Amount of cache levels in the system
\a threadPool (List with \a numHWThreads entries) |
Membername | Comment
--- | ---
\a threadId | Thread ID
\a coreId | ID of physical CPU core
\a apicId | ID of the interrupt line for the hardware thread as defined by ACPI
\a packageId | ID of CPU socket for the current thread
\a inCpuSet | Defines whether the thread is available in current cpuset
\a cacheLevels (List with \a numCacheLevels entries) |
Membername | Comment
--- | ---
\a level | Level of cache
\a associativity | Associativity in cache level
\a sets | Sets in cache level
\a lineSize | Size of a cache line in cache level
\a size | Size in bytes of cache level
\a threads | Amount of threads sharing the cache
\a inclusive | Inclusiveness of cache
\a type |
Typename | comment
--- | ---
DATACACHE | Cache manages only data
INSTRUCTIONCACHE | Cache manages only instructions
UNIFIEDCACHE | Cache manages data and instructions
ITLB | Translation Lookaside Buffer for instruction page addresses
DTLB | Translation Lookaside Buffer for data page addresses
NOCACHE | Type cannot be determined
\a topologyTree |
Membername | Comment
--- | ---
\a ID | ID of socket
\a Children |
Membername | Comment
--- | ---
\a ID | ID of hardware thread
\a Children | List of thread IDs for the current hardware thread

# Function definitions for Lua CPU information module in the Lua API

\anchor getCpuInfo

## getCpuInfo()

Get basic information about the CPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Cpu Info \ref lua_cpuinfo

\anchor getCpuTopology

## getCpuTopology()

Get the topology information about the CPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | Cpu Topology \ref lua_cputopo

## putTopology()

Frees C struct CpuInfo and CpuTopology. You can still use the lua_cpuinfo and lua_cputopo data structures
If you call \ref getCpuInfo or \ref getCpuTopology functions again after calling this function, the topology information will be read again.

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | None

\anchor cpustr_to_cpulist

## cpustr_to_cpulist(cpuexpression)

Resolve the given CPU expression string to a list of CPUs as available in the system

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuexpression | CPU expression string. Look at \ref likwid-pin for possible formats
Return |
\a nrCPUs | Number of CPUs in the \a cpulist
\a cpulist | List containing the CPU IDs after resolution of the cpu expression

## printSupportedCPUs()

Print all Intel and AMD CPU types that are supported by Likwid

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | None

\page lua_NumaInfo NUMA memory topology module

# Data type definition for Lua NUMA topology module in the Lua API

\anchor lua_numainfo

## NUMA Info

This structure is returned by \ref getNumaInfo function
It is similar to the C struct NumaTopology

Membername | Comment
--- | ---
\a numberOfNodes | Amount of NUMA nodes in the system
\a nodes |
Membername | Comment
--- | ---
id | ID of NUMA node
totalMemory | Total amount of memory in the NUMA domain
freeMemory | Free amount of memory in the NUMA domain
numberOfProcessors | Amount of CPUs in the NUMA domain
numberOfDistances | Amount of distances to local and remote NUMA nodes
processors | List of CPU IDs in the NUMA domain
distances | Two dimensional list of distances to NUMA nodes in the system

# Function definitions for Lua NUMA topology module in the Lua API

\anchor getNumaInfo

## getNumaInfo()

Get information about the NUMA domains in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | NUMA Info \ref lua_numainfo

## putNumaInfo()

Frees C struct NumaTopology. You can still use the lua_numainfo data structure
If you call \ref getNumaInfo function again after calling this function, the NUMA topology information will be read again.

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | None

## setMemInterleaved(nrThreads, threads2Cpus)

Set the 'Interleaved' memory policy to allocate data only on given CPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a nrThreads | Amount of threads in the \a threads2Cpus list
\a threads2Cpus | List of thread to CPU relations
Return | None

## nodestr_to_nodelist(nodeexpression)

Resolve the given node expression in NUMA affinity domain

Direction | Data type(s)
--- | ---
Input Parameter |
\a nodeexpression | List of CPUs in NUMA node
Return |
\a nrThreads | Amount of threads in the \a threads2Cpus list
\a threads2Cpus | List of thread to CPU relations

## sockstr_to_socklist(socketexpression)

Resolve the given socket expression in socket affinity domain

Direction | Data type(s)
--- | ---
Input Parameter |
\a socketexpression | List of CPUs in socket affinity domain
Return |
\a nrThreads | Amount of threads in the \a threads2Cpus list
\a threads2Cpus | List of thread to CPU relations

\page lua_AffinityInfo Thread affinity module

# Data type definition for Lua thread affinity module in the Lua API

\anchor lua_affinityinfo

## Affinity Info

This structure is returned by \ref getAffinityInfo function
It is similar to the C struct AffinityDomains

Membername | Comment
--- | ---
\a numberOfAffinityDomains | Total amount of affinity domains in the system
\a numberOfSocketDomains | Amount of affinity domains for CPU sockets in the system
\a numberOfNumaDomains | Amount of affinity domains for NUMA domains in the system
\a numberOfCacheDomains | Amount of affinity domains for LLC domains in the system
\a numberOfProcessorsPerSocket | Amount of hardware threads for each CPU socket in the system
\a numberOfCoresPerCache | Amount of physical CPU cores for each LLC in the system
\a numberOfProcessorsPerCache | Amount of hardware threads for each LLC in the system
\a domains |
Membername | Comment
--- | ---
tag | Tag identifiying the affinity domain
numberOfCores | Amount of physical CPU cores in the affinity domain
numberOfProcessors | Amount of hardware threads in the affinity domain
processorList | List with hardware thread IDs that are in the affinity domain

# Function definitions for Lua thread affinity module in the Lua API

\anchor getAffinityInfo

## getAffinityInfo()

Get information about the affinity domains in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Affinity Info \ref lua_affinityinfo

## putAffinityInfo()

Frees C struct AffinityDomains. You can still use the lua_affinityinfo data structure
If you call \ref getAffinityInfo function again after calling this function, the thread affinity information will be read again.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | None

\anchor pinProcess

## pinProcess(cpuID, silent)

Pins the current pocess to the given CPU ID

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to pin the process on
\a silent | Verbosity of pinning method
Returns | None

\page lua_Perfmon Performance monitoring module

# Data type definition for Lua performance monitoring module in the Lua API

\anchor lua_counterinfo

## Event and Counter Info

This structure is returned by \ref getEventsAndCounters function

Membername | Comment
--- | ---
\a Counters |
Membername | Comment
--- | ---
Name | Counter name as used by LIKWID
Index | Index of counter definition in internal list of counters
Type | ID number of counter type, use TypeName to get a human-readable name
TypeName | Name of counter type
Options | String with the options available for the counter
\a Events |
Membername | Comment
--- | ---
Name | Event name as used by LIKWID
ID | Event ID as defined by CPU vendor
Umask | Umask further restricting the event defined by ID
Limit | String containing the name(s) of registers the event can be programmed on
Options | String with the options available for the event

\anchor lua_groupdata

## Info about a performance group

This structure is returned by \ref get_groupdata function

Membername | Comment
--- | ---
EventString | Event set used for the performance group. Well formatted for \ref addEventSet function
GroupString | Name of the performance group
LongDescription | Description of the group. The 'LONG' section in the performance group file
\a Events |
Membername | Comment
--- | ---
Event ID |
\a Event | Name of event
\a Counter | LIKWID's name of the counter register
\a Metrics |
Membername | Comment
--- | ---
Metric ID |
\a description | Descriptive information of the metric
\a formula | Formula for calculating the metrics value

\anchor lua_pcidevinfo

## Info about online PCI devices used for performance monitoring

This structure is returned by \ref getOnlineDevices function

Membername | Comment
--- | ---
\a Name (used by LIKWID) |
Membername | Comment
--- | ---
Name | Name of PCI device
Path | Path to PCI device
Type | Human-readable name of the PCI device type
TypeDescription | Description about the PCI device

\anchor lua_groupinfo

## Info about performance groups

This structure is returned by \ref getGroups function

Membername | Comment
--- | ---
\a Index |
Membername | Comment
--- | ---
Name | Name of performance group
Info | Short description of the performance group
Long | Long description of the performance group

# Function definitions for Lua performance monitoring module in the Lua API

\anchor init

## init(nrThreads, thread2Cpus)

Initializes the Perfmon module of LIKWID, like opening the MSR files and check the PCI devices
If in access daemon mode, a single daemon instance is started to forward measurements on all given CPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a nrThreads | Number of CPUs that should be measured
\a thread2Cpus | List with length \a nrThreads containing the relation between thread number and measured CPU
Returns | Error code, 0 for success

\anchor addEventSet

## addEventSet(eventSet)

Creates the internal management structures for the given event set. Checks the registers and if needed PCI device access
The \ref init function as to be called previously

Direction | Data type(s)
--- | ---
Input Parameter |
\a eventSet | String composed of all events in the event set. Format is Event1:Counter1(:Option11:Options12:...),Event2:Counter2...
Returns | The group ID of the added event set

\anchor setupCounters

## setupCounters(groupID)

Setup the config registers to measure the events defined by group

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | ID of group returned by \ref addEventSet function.
Returns | Error code, 0 for success

\anchor startCounters

## startCounters()

Starts the perfmon group previously set up with \ref setupCounters function.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Error code, 0 for success

\anchor stopCounters

## stopCounters()

Stops the perfmon group and reads the counters into the internal result section. Use the \ref getResult or \ref getResults functions to get the results.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Error code, 0 for success

\anchor readCounters

## readCounters()

Reads the perfmon group into the internal result section. Use the \ref getResult or \ref getResults functions to get the results.
The counters will be stopped shortly and started after reading to exclude the LIKWID code from measurements.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Error code, 0 for success

\anchor switchGroup

## switchGroup(newgroup)

Switches the currently active group in the perfmon module. If the given group ID does not exist, it fallbacks to group ID 1.

Direction | Data type(s)
--- | ---
Input Parameter |
\a newgroup | Switch active group to \a newgroup
Returns | Error code, 0 for success

\anchor finalize

## finalize()

Destroy internal structures and clean all used registers

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Always 0

\anchor finalize

## finalize()

Destroy internal structures and clean all used registers

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Always 0

\anchor getResult

## getResult(groupID, eventID, threadID)

Get result for a group, event, thread combination. All options must be given

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return result from group defined by \a groupID
\a eventID | Return result for event with \a eventID. Position in string given to \ref addEventSet function
\a threadID | Return result for thread with \a threadID as defined by the \a thread2Cpus input parameter for \ref init function
Returns | Result

\anchor getLastResult

## getLastResult(groupID, eventID, threadID)

Get result for a group, event, thread combination of the last measurement cycle. All options must be given

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return result from group defined by \a groupID
\a eventID | Return result for event with \a eventID. Position in string given to \ref addEventSet function
\a threadID | Return result for thread with \a threadID as defined by the \a thread2Cpus input parameter for \ref init function
Returns | Result

\anchor getMetric

## getMetric(groupID, metricID, threadID)

Get the derived metric result for a group, metric, thread combination. All options must be given

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return result from group defined by \a groupID
\a metricID | Return result for metric with \a metricID.
\a threadID | Return result for thread with \a threadID as defined by the \a thread2Cpus input parameter for \ref init function
Returns | Result

\anchor getLastMetric

## getLastMetric(groupID, metricID, threadID)

Get the derived metric result for a group, metric, thread combination of the last measurement cycle. All options must be given

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return result from group defined by \a groupID
\a eventID | Return result for event with \a metricID.
\a threadID | Return result for thread with \a threadID as defined by the \a thread2Cpus input parameter for \ref init function
Returns | Result

\anchor getEventsAndCounters

## getEventsAndCounters()

Get a list containing all event and counter definitions

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Event and counter info like \ref lua_counterinfo

\anchor getOnlineDevices

## getOnlineDevices()

Get a list containing all online PCI devices

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | PCI device info like \ref lua_pcidevinfo

\anchor getNumberOfGroups

## getNumberOfGroups()

Returns the number of event sets (groups) added to the perfmon module

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Amount of configured groups

\anchor getIdOfActiveGroup

## getIdOfActiveGroup()

Returns the ID of the currently active group

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | ID of active group

\anchor getRuntimeOfGroup

## getRuntimeOfGroup(groupID)

Returns the measurement time of the given groupID

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return the measurement time for group defined by \a groupID
Returns | Measurement time of group

\anchor getNumberOfEvents

## getNumberOfEvents(groupID)

Returns the amount of events for the given groupID

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return the number of events in group defined by \a groupID
Returns | Amount of events in group

\anchor getNumberOfMetrics

## getNumberOfMetrics(groupID)

Returns the amount of metrics for the given groupID

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return the number of derived metrics for group defined by \a groupID
Returns | Amount of metrics in group

\anchor getNumberOfThreads

## getNumberOfThreads()

Returns the number of threads as given to \ref init function

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Amount of measurement threads

\anchor getNameOfEvent

## getNameOfEvent(groupID, eventID)

Returns the name of an event in a configured event set

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return event name from group defined by \a groupID
\a eventID | Return event name for event with \a eventID.
Returns | Name of event

\anchor getNameOfCounter

## getNameOfCounter(groupID, eventID)

Returns the name of counter in a configured event set

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return counter name from group defined by \a groupID
\a eventID | Return counter name for event with \a eventID.
Returns | Name of counter

\anchor getNameOfMetric

## getNameOfMetric(groupID, metricID)

Returns the name of a derived metric in a configured performance group

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return metric name from group defined by \a groupID
\a metricID | Return metric name for event with \a metricID.
Returns | Name of derived metric

\anchor getNameOfGroup

## getNameOfGroup(groupID)

Returns the name of a configured performance group or 'Custom' for own event sets

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return name of group defined by \a groupID
Returns | Name of group

\anchor getShortInfoOfGroup

## getShortInfoOfGroup(groupID)

Returns the short info string of a configured performance group or 'Custom' for own event sets

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return short description of a group defined by \a groupID
Returns | Short description of a group

\anchor getLongInfoOfGroup

## getLongInfoOfGroup(groupID)

Returns the long info string of a configured performance group or 'Custom' for own event sets

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | Return long description of a group defined by \a groupID
Returns | Long description of a group

\anchor getGroups

## getGroups()

Returns a list of all performance groups in \a groupfolder

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of performance groups, see \ref lua_groupinfo for structure

\anchor get_groupdata

## get_groupdata(group)

Read in the performance group \a group

Direction | Data type(s)
--- | ---
Input Parameter |
\a group | Get group data for \a group
Returns |
\a groupdata | Structure with all group information found for the performance group \a group, see \ref lua_groupdata

\anchor readMarkerFile

## readMarkerFile(filename)

Get the results for an output file written by \ref MarkerAPI

Direction | Data type(s)
--- | ---
Input Parameter |
\a filename | Filename written by \ref MarkerAPI
Returns | No return value

\anchor destroyMarkerFile

## destroyMarkerFile()

Destroy all results previously read in from the \ref MarkerAPI

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | No return value

\anchor markerNumRegions

## markerNumRegions()

Get the number of regions defined in the file previously read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Amount of regions

\anchor markerRegionGroup

## markerRegionGroup(regionID)

Get the group ID of a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get group ID from
Returns | Group ID for the region

\anchor markerRegionTag

## markerRegionTag(regionID)

Get the region name of a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the name from
Returns | Region name

\anchor markerRegionEvents

## markerRegionEvents(regionID)

Get the number of events of a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the event count from
Returns | Number of events

\anchor markerRegionThreads

## markerRegionThreads(regionID)

Get the number of thread participating in a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the thread count from
Returns | Number of threads

\anchor markerRegionCpulist

## markerRegionCpulist(regionID)

Get a list of CPUs participating in a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the thread count from
Returns | List with CPU IDs

\anchor markerRegionTime

## markerRegionTime(regionID, threadID)

Get the accumulated measurement time for a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the time from
\a threadID | Thread ID to get the time from
Returns | Measurement time

\anchor markerRegionCount

## markerRegionCount(regionID, threadID)

Get the call count for a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the call count from
\a threadID | Thread ID to get the call count from
Returns | Call count

\anchor markerRegionResult

## markerRegionResult(regionID, eventID, threadID)

Get the result for a region and thread read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the result
\a eventID | Event ID to get the result
\a threadID | Thread ID to get the result
Returns | Result

\anchor markerRegionMetric

## markerRegionMetric(regionID, metricID, threadID)

Get the derived metric result for a region read in with \ref readMarkerFile

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | Region ID to get the derived metric result
\a metricID | Metric ID to get the derived metric result
\a threadID | Thread ID to get the derived metric result
Returns | Metric result

\page lua_PowerInfo Power and Energy monitoring module

# Data type definition for Lua power and energy monitoring module in the Lua API

\anchor lua_powerinfo

## Power Information

This structure is returned by \ref getPowerInfo function
The nested list structure is almost similar to the C struct CpuTopology.

Membername | Comment
--- | ---
\a hasRAPL | If set, the system supports power readings through the RAPL interface
\a baseFrequency | Nominal clock frequency of the system
\a minFrequency | Minimal supported clock frequency of the system
\a powerUnit | Multiplier for power readings
\a timeUnit | Multiplier for time readings from RAPL
\a turbo |
Membername | Comment
--- | ---
\a numSteps | Amount of turbo mode steps
\a steps | List containing the turbo mode steps
\a domains |
Membername | Comment
--- | ---
\a RAPL domain |
Typename | comment
--- | ---
ID | Type of domain (PKG, PP0, PP1, DRAM)
energyUnit | Multiplier for energy readings for RAPL domain
supportStatus | RAPL domain has a status register to read energy values
supportPerf | RAPL domain has a perf register
supportPolicy | RAPL domain has a policy register to define a global energy policy
supportLimit | RAPL domain has a policy register to define a limit for the energy consumption
supportInfo | RAPL domain has a policy register to define a limit for the energy consumption
tdp | Thermal Design Power Only if supportInfo is set Only if supportInfo is set
minPower | Minimal power consumption for the RAPL domain Only if supportInfo is set
maxPower | Maximal power consumption for the RAPL domain Only if supportInfo is set
maxTimeWindow | Maximal duration between updates of the RAPL status registers Only if supportInfo is set

# Function definitions for Lua power and energy monitoring module in the Lua API

\anchor getPowerInfo

## getPowerInfo()

Get information about the RAPL interface in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Power Info \ref lua_powerinfo

\anchor putPowerInfo

## putPowerInfo()

Frees C struct PowerInfo. You can still use the lua_powerinfo data structure
If you call \ref getPowerInfo function again after calling this function, the power information struct will be filled again.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | None

\anchor startPower

## startPower(cpuID, domainID)

Start measuring given RAPL domain on given CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Start the power measurement on CPU \a cpuID
\a domainID | Start the power measurement for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
Returns | Power value at start

\anchor stopPower

## stopPower(cpuID, domainID)

Stop measuring given RAPL domain on given CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Stop the power measurement on CPU \a cpuID
\a domainID | Stop the power measurement for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
Returns | Power value at stop

\anchor printEnergy

## printEnergy(before, after, domainID)

Direction | Data type(s)
--- | ---
Input Parameter |
\a before | Result from \ref startPower function
\a after | Result from \ref stopPower function
\a domainID | Print the power result for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
Returns | Power value at stop

\anchor limitGet

## limitGet(cpuID, domainID) (EXPERIMENTAL)

Get the current limit in the limit register of domain. The limit is defined as maximal power consumption in a time window

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Get limit for CPU \a cpuID
\a domainID | Get limit for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
Returns |
\a power | Power limit value
\a time | Duration of time window

\anchor limitSet

## limitSet(cpuID, domainID, power, time, clamp) (EXPERIMENTAL)

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Set limit for CPU \a cpuID
\a domainID | Set limit for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
\a power | Set power value to \a power
\a time | Set time window value to \a time
\a clamp | Should the limit be clamped or can it sometimes exceed the power limit if in total the limit is satisfied
Returns | Error code, 0 for success

\anchor limitState

## limitState(cpuID, domainID) (EXPERIMENTAL)

Get the state of the limit

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Get the state on CPU \a cpuID
\a domainID | Get the state for domain domainID Possible values: 0=PKG, 1=PP0, 2=PP1, 3=DRAM
Returns | State, 0 for off, 1 for on

\page lua_ThermalInfo Thermal monitoring module

# Data type definition for Lua thermal monitoring module in the Lua API

# Function definitions for Lua thermal monitoring module in the Lua API

\anchor initTemp

## initTemp(cpuID)

Initialize the thermal measurements on given CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Initialize thermal readings on CPU \a cpuID
Returns | None

\anchor readTemp

## readTemp(cpuID)

Measure the temperature on given CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | Read the temperature on CPU \a cpuID
Returns | Temperature

\page lua_Timer Time measurement module

# Data type definition for Lua time measurement module in the Lua API

# Function definitions for Lua time measurement module in the Lua API

\anchor getCpuClock

## getCpuClock()

Returns the nominal clock speed

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Clock speed in Hz

\anchor getCycleClock

## getCycleClock()

Returns the clock speed of the time stamp counter

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Cycle clock speed in Hz

\anchor startClock

## startClock()

Start the TSC clock

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Current timestamp

\anchor stopClock

## stopClock()

Stop the TSC clock

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Current timestamp

\anchor getClockCycles

## getClockCycles(start, stop)

Return the amount of cycles between start and stop timestamps

Direction | Data type(s)
--- | ---
Input Parameter |
\a start | Start timestamp
\a stop | Stop timestamp
Returns | Amount of cycles between start and stop

\anchor getClock

## getClock(start, stop)

Return the time in seconds between start and stop timestamps

Direction | Data type(s)
--- | ---
Input Parameter |
\a start | Start timestamp
\a stop | Stop timestamp
Returns | Time in seconds between start and stop

\anchor sleep

## sleep(usecs)

Sleep for specified amount of microseconds

Direction | Data type(s)
--- | ---
Input Parameter |
\a usecs | Sleep for seconds
Returns | Remaining time to sleep. >0 if sleep is interrupted

\page lua_MemSweep Memory sweeping module

# Data type definition for Lua memory sweeping module in the Lua API

# Function definitions for Lua memory sweeping module in the Lua API

\anchor memSweep

## memSweep(nrThreads, Cpus)

Sweep the memory and LLC for given threads

Direction | Data type(s)
--- | ---
Input Parameter |
\a nrThreads | Amount of threads in the \a threads2Cpus list
\a Cpus | List with thread to CPU relations
Returns | None

\anchor memSweepDomain

## memSweepDomain(domainID)

Sweep the memory and LLC for a given NUMA domain

Direction | Data type(s)
--- | ---
Input Parameter |
\a domainID | Sweep the memory and LLC at the NUMA domain specified by \a domainID
Returns | None

\page lua_Misc Miscellaneous functions module

# Data type definition for Lua miscellaneous functions module in the Lua API

# Function definitions for Lua miscellaneous functions module in the Lua API

\anchor startProgram

## startProgram(Exec)

Start an executable in a new thread

Direction | Data type(s)
--- | ---
Input Parameter |
\a Exec | String containing the executable and its arguments. Executable and arguments are separated by ' '
\a numThreads | Number of HW thread IDs in the cpulist (third parameter)
\a cpulist | List of HW thread IDs. The application's cpuset is limited to these hw threads
Returns | PID of newly created thread

\anchor checkProgram

## checkProgram()

Check if the executable is running

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | True/False

\anchor killProgram

## killProgram(PID)

Kill the executable with SIGTERM

Direction | Data type(s)
--- | ---
Input Parameter |
\a PID | PID to send the SIGTERM signal
Returns | None

\anchor waitpid

## waitpid(PID)

Wait until the state of the program referenced by PID has a changed state. Blocking.

Direction | Data type(s)
--- | ---
Input Parameter |
\a PID | PID to check status
Returns | None

\anchor catchSignal

## catchSignal()

Add signal handler for SIGINT

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | None

\anchor getSignalState

## getSignalState()

Check whether SIGINT signal was received

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Amount of received SIGINT signals

\anchor setenv

## setenv(Name, Value)

Set environment variable. Lua only provides getenv()

Direction | Data type(s)
--- | ---
Input Parameter |
\a Name | Name of environment variable
\a Value | Value for the environment variable
Returns | None

\anchor getpid

## getpid()

Get the PID of the current process

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | PID number

\anchor access

## access(Filepath, perm)

Check the file existance for a given filepath

Direction | Data type(s)
--- | ---
Input Parameter |
\a Filepath | Name of Filepath to check
\a perm | Check for specified attribute r: read, w: write, x: executable, e: existance
Returns | PID number

\anchor msr_available

## msr_available()

Check whether the msr files are available. Basically checks whether the msr kernel module is loaded properly

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | True/False

\anchor gethostname

## gethostname()

Returns the hostname of the system in short format

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns |
\a Hostname | Hostname in short format

\anchor getjid

## getjid()

Returns the job ID if running in a batch environment. Basically reads the `PBS_JOBID` environment variable

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns |
\a Job ID | Job ID or 'X' if not in batch environment

\anchor getMPIrank

## getMPIrank()

Returns the MPI rank of the current process. Basically read the `PMI_RANK` and `OMPI_COMM_WORLD_RANK` environment variables

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns |
\a MPI Rank | MPI rank or 'X' if not in MPI environment

\page lua_cpuFeatures Module to read and manipulate CPU features

# Data type definition for Lua output functions module in the Lua API

# Function definitions for Lua output functions module in the Lua API

\anchor cpuFeaturesInit

## cpuFeaturesInit()

Initialize the internal structures to enable CPU features module

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | None

\anchor cpuFeaturesGet

## cpuFeaturesGet(cpuID, featID)

Get feature state

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to read feature state
\a featID | ID of a feature
Returns | None

\anchor cpuFeaturesEnable

## cpuFeaturesEnable(cpuID, featID)

Enable feature for CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to enable the feature
\a featID | ID of a feature
Returns | 0 for success, all others are erros, either by MSR access or invalid feature

\anchor cpuFeaturesDisable

## cpuFeaturesDisable(cpuID, featID)

Disable feature for CPU

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to disable the feature
\a featID | ID of a feature
Returns | 0 for success, all others are erros, either by MSR access or invalid feature

/*!\page lua_CpuFreq CPU frequency manipulation module

# Data type definition for Lua CPU frequency manipulation module in the Lua API

# Function definitions for Lua CPU frequency manipulation module in the Lua API

\anchor getCpuClockCurrent

## getCpuClockCurrent(cpuID)

Get the current CPU clock frequency

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get clock speed
Returns | Frequency for success, 0 in case of errors.

\anchor getCpuClockMin

## getCpuClockMin(cpuID)

Get the minimal CPU clock frequency

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get minimal clock speed
Returns | Frequency for success, 0 in case of errors.

\anchor setCpuClockMin

## setCpuClockMin(cpuID, freq)

Set the minimal CPU clock frequency

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to set minimal clock speed
\a freq | CPU frequency in kHz
Returns | Frequency for success, 0 in case of errors.

\anchor getCpuClockMax

## getCpuClockMax(cpuID)

Get the maximal CPU clock frequency

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get maximal clock speed
Returns | Frequency for success, 0 in case of errors.

\anchor setCpuClockMax

## setCpuClockMax(cpuID, freq)

Set the maximal CPU clock frequency

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to set maximal clock speed
\a freq | CPU frequency in kHz
Returns | Frequency for success, 0 in case of errors.

\anchor getGovernor

## getGovernor(cpuID)

Get the current CPU frequency governor

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get the current CPU frequency governor
Returns | Governor for success, nil in case of errors.

\anchor setGovernor

## setGovernor(cpuID, gov)

Set the current CPU frequency governor

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to set the current CPU frequency governor
\a gov | Governor name
Returns | 1 for success, 0 in case of errors.

\anchor getAvailFreq

## getAvailFreq(cpuID)

Get all available CPU frequency settings

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get the CPU frequency settings
Returns | frequency list + turbo value at success, {} and 0 in case of errors.

\anchor getAvailGovs

## getAvailGovs(cpuID)

Get all available CPU frequency governors

Direction | Data type(s)
--- | ---
Input Parameter |
\a cpuID | CPU to get the CPU frequency governors
Returns | governor list at success, {} in case of errors.

\page lua_InputOutput Input and output functions module

# Data type definition for Lua output functions module in the Lua API

# Function definitions for Lua output functions module in the Lua API

\anchor getopt

## getopt(commandline, optionlist)

Read commandline parameters and split them to the given options. The version LIKWID uses was originally taken from the web but extended to talk short '-o' and long options "--option". It returns an iterator for the commandline options.
Basic usage:

`for opt,arg in likwid.getopt(arg, {"n:","h"}) do
if (type(arg) == "string") then
local s,e = arg:find("-")
if s == 1 then
print(string.format("ERROR: Argument %s to option -%s starts with invalid character -.", arg, opt))
print("ERROR: Did you forget an argument to an option?")
os.exit(1)
end
end
--parse options
end
`
The option 'n' takes an argument, specified by the ':'. If found the option argument for option 'h' is true. The type check for the argument is recommended to get errors with an argument awaiting option where the argument is missing.

Direction | Data type(s)
--- | ---
Input Parameter |
\a commandline | Normally, Lua saves the commandline parameters in variable 'arg'
\a optionlist | List of options that should be recognized. Options with ':' as last character need an argument Example {"h","v","cpu:"}
Returns |
\a option | Option string found on the commandline without leading '-'
\a argument | Argument to the \a option. If \a option does not require an argument, true or false is returned in \a argument

\anchor parse_time

## parse_time(timestr)

Parses time interval describing strings like 2s, 100ms or 250us

Direction | Data type(s)
--- | ---
Input Parameter |
\a timestr | String describing a time interval
Returns |
\a duration | Time string \a timestr resolved to usecs

\anchor printtable

## printtable(table)

Prints the given two dimensional table as fancy ASCII table. For CSV output use \ref printcsv

Direction | Data type(s)
--- | ---
Input Parameter |
\a table | Two dimensional list with table entries. First dim. are columns and second dim. the lines
Returns | None

\anchor printcsv

## printcsv(table)

Prints the given two dimensional table in CSV format. For ASCII table output see \ref printtable

Direction | Data type(s)
--- | ---
Input Parameter |
\a table | Two dimensional list with table entries. First dim. are columns and second dim. the lines
Returns | None

\anchor stringsplit

## stringsplit(str, sSeparator,( nMax, bRegexp))

Splits the given string at separating character

Direction | Data type(s)
--- | ---
Input Parameter |
\a str | String to split
\a sSeparator | String with separating character
\a nMax | Split string maximally \a nMax times (optional)
\a bRegexp | Lua RegEx string for separation (optional)
Returns | List of \a str splitted at \a sSeparator or \a bRegexp

\anchor getResults

## getResults()

Get all results for all group, event, thread combinations

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Three-dimensional list with results. First dim. is groups, second dim. is events and third dim. are the threads

\anchor getLastResults

## getLastResults()

Get the results of the last measurement cycle for all group, event, thread combinations

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Three-dimensional list with results. First dim. is groups, second dim. is events and third dim. are the threads

\anchor getMetrics

## getMetrics()

Get all derived metric results for all group, metric, thread combinations

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Three-dimensional list with derived metric results. First dim. is groups, second dim. is metrics and third dim. are the threads

\anchor getLastMetrics

## getLastMetrics()

Get the derived metric results of the last measurement cycle for all group, metric, thread combinations

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Three-dimensional list with derived metric results. First dim. is groups, second dim. is metrics and third dim. are the threads

\anchor printOutput

## printOutput(results, metrics, cpulist, region, stats)

Prints results

Direction | Data type(s)
--- | ---
Input Parameter |
\a results | List of results with format list[ngroups][nevents][nthreads]
\a metrics | List of metric results with format list[ngroups][nmetrics][nthreads]
\a cpulist | List of thread ID to CPU ID relations
\a region | Name of region or 'nil' for no region
\a stats | Print statistics table for one CPU
Returns | None

\anchor addSimpleAsciiBox

## addSimpleAsciiBox(container, lineIdx, colIdx, label)

Add a simple ASCII box with given label to box container. This function is only used by \ref likwid-topology

Direction | Data type(s)
--- | ---
Input Parameter |
\a container | Box container containing all boxes
\a lineIdx | Add box at line index \a lineIdx
\a colIdx | Add box at column index \a colIdx
\a label | Content of the box
Returns | None

\anchor addJoinedAsciiBox

## addJoinedAsciiBox(container, lineIdx, startColIdx, endColIdx, label)

Add a joined ASCII box with given label to box container. Joined boxes can span the space of multiple simple boxes. This function is only used by \ref likwid-topology

Direction | Data type(s)
--- | ---
Input Parameter |
\a container | Box container containing all boxes
\a lineIdx | Add box at line index \a lineIdx
\a startColIdx | Start joined box at column index \a startColIdx
\a endColIdx | End joined box at column index \a endColIdx
\a label | Content of the box
Returns | None

\anchor printAsciiBox

## printAsciiBox(container)

Print the box container previously filled with \ref addSimpleAsciiBox and \ref addJoinedAsciiBox. This function is only used by \ref likwid-topology

Direction | Data type(s)
--- | ---
Input Parameter |
\a container | Box container containing all boxes
Returns | None

\page lua_NvidiaGPUTopology Nvidia GPU topology module

# Data type definition for Nvidia GPU topology module in the Lua API

\anchor lua_nvidiagputopology

## Nvidia GPU Topology

This structure is returned by \ref getCudaTopology function
It is similar to the C struct CudaTopology_t

Membername | Comment
--- | ---
\a numDevices | Number of Nvidia GPU devices
\a devices (List with \a numDevices entries) |
Membername | Comment
--- | ---
\a id | GPU ID
\a name | Name of the device
\a numaNode | Closest NUMA node
\a memory | Total memory of the device
\a ccapMajor | Major number of device's compute capability
\a ccapMinor | Minor number of device's compute capability
\a simdWidth | SIMD width of arithmetic units = warp size
\a l2Size | L2 cache in bytes. 0 if the device doesn't have L2 cache
\a maxThreadsPerBlock | Maximam number of thread per block
\a sharedMemPerBlock | Total amount of shared memory available per block
\a totalConstantMemory | Total amount of constant memory available on the device
\a memPitch | Maximum pitch allowed by the memory copy functions that involve memory regions allocated through cuMemAllocPitch()
\a regsPerBlock | Total number of registers available per block
\a clockRatekHz | Clock frequency in kilohertz
\a textureAlign | Alignment requirement
\a surfaceAlign | Alignment requirement for surfaces
\a memClockRatekHz | Peak memory clock frequency in kilohertz
\a pciBus | PCI bus identifier of the device
\a pciDev | PCI device (also known as slot) identifier of the device
\a pciDom | PCI domain identifier of the device
\a pciFunc | PCI function identifier of the device
\a maxBlockRegs | Maximum number of 32-bit registers available to a thread block
\a numMultiProcs | Number of multiprocessors on the device
\a maxThreadPerMultiProc | Maximum resident threads per multiprocessor
\a memBusWidth | Global memory bus width in bits
\a unifiedAddrSpace | 1 if the device shares a unified address space with the host, or 0 if not
\a ecc | 1 if error correction is enabled on the device, 0 if error correction is disabled or not supported by the device
\a asyncEngines | Number of asynchronous engines
\a mapHostMem | 1 if the device can map host memory into the CUDA address space
\a integrated | 1 if the device is an integrated (motherboard) GPU and 0 if it is a discrete (card) component
\a maxThreadsDim[3] | Maximum sizes of each dimension of a block
\a maxGridSize[3] | Maximum sizes of each dimension of a grid

# Function definitions for the Nvidia GPU topology module in the Lua API

\anchor getCudaTopology

## getCudaTopology()

Get the topology information about the Nvidia GPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | Nvidia Gpu Topology \ref lua_nvidiagputopology

\anchor putCudaTopology

## putCudaTopology()

Return the topology information about the Nvidia GPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | None

\anchor gpustr_to_gpulist_cuda

## gpustr_to_gpulist_cuda()

Read GPU selection string and resolve to available Nvidia GPUs numbers

Direction | Data type(s)
--- | ---
Input Parameter |
\a gpustr | GPU identifier string
Return | List with Nvidia GPU identifier

\anchor getCudaEventsAndCounters

## getCudaEventsAndCounters()

Return the events and counters provided by the available Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | Table with keys \a numDevices and \a devices. \a devices is a table where each entry has \a Name, \a Description and \a Limit.

\anchor getCudaGroups

## getCudaGroups()

Returns a list of all performance groups in \a groupfolder for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of performance groups, see \ref lua_groupinfo for structure

\page lua_NvidiaGPUAPI Nvidia GPU monitoring module

# Data type definition for the Nvidia GPU monitoring module in the Lua API

# Function definitions for the Nvidia GPU monitoring module in the Lua API

\anchor nvInit

## nvInit()

Initialize the monitoring module for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a numGPUs | The amount of Nvidia GPUs to monitor
\a gpuList | List of integer GPU IDs
Returns | 0 in case of success and -errno otherwise

\anchor nvAddEventSet

## nvAddEventSet()

Add a performance group or event set for Nvidia GPU monitoring module

Direction | Data type(s)
--- | ---
Input Parameter |
\a events_or_performance_group | Comma-separated list of event:counter pairs or the name of a performance group
Returns | Group identifier required to access the result data

\anchor nvFinalize

## nvFinalize()

Shut down the monitoring module for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | nothing

\anchor nvGetNameOfGroup

## nvGetNameOfGroup()

Returns the name of a performance group for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref nvAddEventSet
Returns | The group name as string

\anchor nvGetNameOfEvent

## nvGetNameOfEvent()

Returns the name of a event for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref nvAddEventSet
\a eventID | The eventID ID, the offset in the list of event:counter pairs inside the performance group.
Returns | The event name as string

\anchor nvGetNameOfCounter

## nvGetNameOfCounter()

Returns the name of a counter for Nvidia GPUs. For GPUs, this is commonly GPU0, GPU1, ...

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref nvAddEventSet
\a counterID | The counterID ID, the offset in the list of event:counter pairs inside the performance group.
Returns | The counter name as string

\anchor nvGetNameOfMetric

## nvGetNameOfMetric()

Returns the name of a performance group metric for Nvidia GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref nvAddEventSet
\a metricID | The metric ID, the offset in the list of metrics inside the performance group.
Returns | The metric name as string

\anchor readNvMarkerFile

## readNvMarkerFile()

Read a Nvmon MarkerAPI into the system for result retrieval.

Direction | Data type(s)
--- | ---
Input Parameter |
\a markerAPIfilename | Filename of the MarkerAPI file
Returns | 0 in case of success and -errno otherwise

\anchor destroyNvMarkerFile

## destroyNvMarkerFile()

Destroy internal data structures for handling results of the Nvmon MarkerAPI.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Nothing

\anchor nvMarkerNumRegions

## nvMarkerNumRegions()

Get the amount of regions defined in a Nvmon MarkerAPI file after reading it in.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | The amount of regions

\anchor nvMarkerRegionGroup

## nvMarkerRegionGroup()

Get the groupID for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The groupID for the region

\anchor nvMarkerRegionTag

## nvMarkerRegionTag()

Get the name for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The name for the region as defined in the application.

\anchor nvMarkerRegionEvents

## nvMarkerRegionEvents()

Get amount of events measured for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of events

\anchor nvMarkerRegionMetrics

## nvMarkerRegionMetrics()

Get amount of metrics derivable for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of metrics

\anchor nvMarkerRegionGpus

## nvMarkerRegionGpus()

Get amount of measured Nvidia GPUs for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of GPU devices

\anchor nvMarkerRegionGpulist

## nvMarkerRegionGpulist()

Get list of IDs of measured Nvidia GPUs for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | List of GPU devices (IDs)

\anchor nvMarkerRegionTime

## nvMarkerRegionTime()

Get the runtime of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
Returns | Runtime of GPU in region

\anchor nvMarkerRegionCount

## nvMarkerRegionCount()

Get the call count of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
Returns | Call count of the region on a GPU device

\anchor nvMarkerRegionResult

## nvMarkerRegionResult()

Get the measured result of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
\a eventOffset | The offset to the event in the eventset
Returns | Result as number

\anchor nvMarkerRegionMetric

## nvMarkerRegionMetric()

Get the derived metric of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
\a metricOffset | The offset to the metric in the eventset
Returns | Metric as number

\page lua_AMDGPUTopology AMD GPU topology module

# Data type definition for AMD GPU topology module in the Lua API

\anchor lua_amdgputopology

## AMD GPU Topology

This structure is returned by \ref getRocmTopology function
It is similar to the C struct RocmTopology_t

Membername | Comment
--- | ---
\a numDevices | Number of AMD GPU devices
\a devices (List with \a numDevices entries) |
Membername | Comment
--- | ---
\a id | GPU ID
\a name | Name of the device
\a short | Short name of the device used internally to select performance groups
\a numaNode | Closest NUMA node
\a memory | Total memory of the device
\a ccapMajor | Major number of device's compute capability
\a ccapMinor | Minor number of device's compute capability
\a l2Size | L2 cache in bytes. 0 if the device doesn't have L2 cache
\a maxThreadsPerBlock | Maximam number of thread per block
\a sharedMemPerBlock | Total amount of shared memory available per block
\a totalConstantMemory | Total amount of constant memory available on the device
\a memPitch | Maximum pitch allowed by the memory copy functions that involve memory regions allocated through cuMemAllocPitch()
\a regsPerBlock | Total number of registers available per block
\a clockRatekHz | Clock frequency in kilohertz
\a textureAlign | Alignment requirement
\a memClockRatekHz | Peak memory clock frequency in kilohertz
\a pciBus | PCI bus identifier of the device
\a pciDev | PCI device (also known as slot) identifier of the device
\a pciDom | PCI domain identifier of the device
\a pciFunc | PCI function identifier of the device
\a numMultiProcs | Number of multiprocessors on the device
\a maxThreadPerMultiProc | Maximum resident threads per multiprocessor
\a memBusWidth | Global memory bus width in bits
\a ecc | 1 if error correction is enabled on the device, 0 if error correction is disabled or not supported by the device
\a mapHostMem | 1 if the device can map host memory into the CUDA address space
\a integrated | 1 if the device is an integrated (motherboard) GPU and 0 if it is a discrete (card) component/TD>
\a maxThreadsDim[3] | Maximum sizes of each dimension of a block
\a maxGridSize[3] | Maximum sizes of each dimension of a grid

\anchor getRocmTopology

## getRocmTopology()

Get the topology information about the AMD GPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | AMD GPU Topology \ref lua_amdgputopology

\anchor putRocmTopology

## putRocmTopology()

Return the topology information about the AMD GPUs in the system

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | None

\anchor gpustr_to_gpulist_rocm

## gpustr_to_gpulist_rocm()

Read GPU selection string and resolve to available AMD GPUs numbers

Direction | Data type(s)
--- | ---
Input Parameter |
\a gpustr | GPU identifier string
Return | List with AMD GPU identifier

\anchor getRocmEventsAndCounters

## getRocmEventsAndCounters()

Return the events and counters provided by the available AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Return | Table with keys \a numDevices and \a devices. \a devices is a table where each entry has \a Name, \a Description and \a Limit.

\anchor getRocmGroups

## getRocmGroups()

Returns a list of all performance groups in \a groupfolder for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of performance groups, see \ref lua_groupinfo for structure

\page lua_AMDGPUAPI AMD GPU monitoring module

# Data type definition for the AMD GPU monitoring module in the Lua API

# Function definitions for the AMD GPU monitoring module in the Lua API

\anchor init_rocm

## init_rocm()

Initialize the monitoring module for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a numGPUs | The amount of AMD GPUs to monitor
\a gpuList | List of integer GPU IDs
Returns | 0 in case of success and -errno otherwise

\anchor addEventSet_rocm

## addEventSet_rocm()

Add a performance group or event set for AMD GPU monitoring module

Direction | Data type(s)
--- | ---
Input Parameter |
\a events_or_performance_group | Comma-separated list of event:counter pairs or the name of a performance group
Returns | Group identifier required to access the result data

\anchor finalize_rocm

## finalize_rocm()

Shut down the monitoring module for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | nothing

\anchor getNameOfGroupRocm

## getNameOfGroupRocm()

Returns the name of a performance group for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref addEventSet_rocm
Returns | The group name as string

\anchor getNameOfEventRocm

## getNameOfEventRocm()

Returns the name of a event for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref addEventSet_rocm
\a eventID | The eventID ID, the offset in the list of event:counter pairs inside the performance group.
Returns | The event name as string

\anchor getNameOfCounterRocm

## getNameOfCounterRocm()

Returns the name of a counter for AMD GPUs. For GPUs, this is commonly GPU0, GPU1, ...

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref addEventSet_rocm
\a counterID | The counterID ID, the offset in the list of event:counter pairs inside the performance group.
Returns | The counter name as string

\anchor getNameOfMetricRocm

## getNameOfMetricRocm()

Returns the name of a performance group metric for AMD GPUs

Direction | Data type(s)
--- | ---
Input Parameter |
\a groupID | The groupID returned by \ref addEventSet_rocm
\a metricID | The metric ID, the offset in the list of metrics inside the performance group.
Returns | The metric name as string

\anchor readMarkerFileRocm

## readMarkerFileRocm()

Read a Rocmon MarkerAPI into the system for result retrieval.

Direction | Data type(s)
--- | ---
Input Parameter |
\a markerAPIfilename | Filename of the MarkerAPI file
Returns | 0 in case of success and -errno otherwise

\anchor destroyMarkerFileRocm

## destroyMarkerFileRocm()

Destroy internal data structures for handling results of the Rocmon MarkerAPI.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Nothing

\anchor markerNumRegionsRocm

## markerNumRegionsRocm()

Get the amount of regions defined in a Rocmon MarkerAPI file after reading it in.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | The amount of regions

\anchor markerRegionGroupRocm

## markerRegionGroupRocm()

Get the groupID for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The groupID for the region

\anchor markerRegionTagRocm

## markerRegionTagRocm()

Get the name for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The name for the region as defined in the application.

\anchor markerRegionEventsRocm

## markerRegionEventsRocm()

Get amount of events measured for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of events

\anchor markerRegionMetricsRocm

## markerRegionMetricsRocm()

Get amount of metrics derivable for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of metrics

\anchor markerRegionGpusRocm

## markerRegionGpusRocm()

Get amount of measured AMD GPUs for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | The amount of GPU devices

\anchor markerRegionGpulistRocm

## markerRegionGpulistRocm()

Get list of IDs of measured AMD GPUs for a given regionID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
Returns | List of GPU devices (IDs)

\anchor markerRegionTimeRocm

## markerRegionTimeRocm()

Get the runtime of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
Returns | Runtime of GPU in region

\anchor markerRegionCountRocm

## markerRegionCountRocm()

Get the call count of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
Returns | Call count of the region on a GPU device

\anchor markerRegionResultRocm

## markerRegionResultRocm()

Get the measured result of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
\a eventOffset | The offset to the event in the eventset
Returns | Result as number

\anchor markerRegionMetricRocm

## markerRegionMetricRocm()

Get the derived metric of a region on a specific GPU device.

Direction | Data type(s)
--- | ---
Input Parameter |
\a regionID | The region identifier
\a gpuOffset | The offset to the GPU ID in the gpulist
\a metricOffset | The offset to the metric in the eventset
Returns | Metric as number

\page lua_likwid_device LIKWID device module

# Data type definition for the LIKWID device module in the Lua API

\anchor lua_likwiddevice

## LIKWID device

This structure is returned by \ref createDevice, \ref createDevicesFromString and \ref getAllDevices functions
It is the C struct LikwidDevice_t encapsulated in a Lua userdata type.

Membername | Comment
--- | ---
\a typeId | Type ID for the device
\a typeName | Type name for the device
\a id | ID for the device
\a internalId | Internally used ID for the device

# Function definitions for the LIKWID device module in the Lua API

\anchor createDevice

## createDevice()

Create a LIKWID device from the given type and ID.

Direction | Data type(s)
--- | ---
Input Parameter |
\a device_type | Device type
\a id | ID of the device
Returns | LIKWID device as defined in \ref lua_likwiddevice .

\anchor createDevicesFromString

## createDevicesFromString()

Create a LIKWID device from the given string like S:0 for socket 0, T:1 for HWthread with ID 1, etc.

Direction | Data type(s)
--- | ---
Input Parameter |
\a device_string | String combining type and ID
Returns | LIKWID device as defined in \ref lua_likwiddevice .

\anchor getAvailableDevices

## getAvailableDevices()

Get all available LIKWID devices in the system available for usage.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of available LIKWID devices (\ref lua_likwiddevice).

\anchor getAllDevices

## getAllDevices()

Get all LIKWID devices in the system without filtering them.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of LIKWID devices (\ref lua_likwiddevice).

\page lua_sysfeatures sysFeatures module

# Data type definition for the sysFeatures module in the Lua API

\anchor lua_sysfeature

## Sysfeature

A list of this structure is returned by the \ref sysFeatures_list function
It contains all information about a sysFeature.

Membername | Comment
--- | ---
\a Name | Name of the feature
\a Category | Category of the feature
\a Description | Description of the feature
\a ReadOnly | Boolean telling whether the Sysfeature can only be read.
\a WriteOnly | Boolean telling whether the Sysfeature can only be modified.
\a Type | LIKWID device type that supports this feature. See \ref lua_likwid_device for LIKWID device handling.
\a TypeID | LIKWID device type ID that supports this feature. See \ref lua_likwid_device for LIKWID device handling.

# Function definitions for the sysFeatures module in the Lua API

\anchor initSysFeatures

## initSysFeatures()

Initialize the sysFeatures module.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | 0 in case of success and -errno otherwise

\anchor sysFeatures_list

## sysFeatures_list()

List all available sysFeatures in the system.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | List of available sysFeatures, see \ref lua_sysfeature for structure.

\anchor sysFeatures_get

## sysFeatures_get()

Get the current state of a sysFeatures in the system (if not write-only).

Direction | Data type(s)
--- | ---
Input Parameter |
\a sysfeature | Category.Name or only Name (if unique) of sysFeature. See \ref lua_sysfeature
\a likwid_device | The device to get the state of. See \ref lua_likwid_device for LIKWID device handling.
Returns |
\a state | Current state of sysFeature
\a errorstring | Error string or nil

\anchor sysFeatures_set

## sysFeatures_set()

Modify the state of a sysFeatures in the system (if not read-only).

Direction | Data type(s)
--- | ---
Input Parameter |
\a sysfeature | Category.Name or only Name (if unique) of sysFeature. See \ref lua_sysfeature
\a likwid_device | The device to set the state for. See \ref lua_likwid_device for LIKWID device handling.
\a value | New value for the sysFeature as string
Returns |
\a modification_successful | Boolean signaling the success or failure of the operation
\a errorstring | Error string or nil

\anchor finalizeSysFeatures

## finalizeSysFeatures()

Shut down the sysFeatures module.

Direction | Data type(s)
--- | ---
Input Parameter | None
Returns | Nothing