Ubuntu Manpage: likwid-perfctr - configure and read out hardware performance counters on x86 cpus

NAME

       likwid-perfctr - configure and read out hardware performance counters on x86 cpus

SYNOPSIS

       likwid-perfctr    [-vhHVmaeiMoO]    [-c/-C   <core_list>]   [-g   <performance_group>   or
       <performance_event_string>]  [-t   <frequency>]   [-S   <time>]   [-s   <skip_mask>]   [-o
       <output_file>]

DESCRIPTION

       likwid-perfctr  is  a  lightweight  command  line  application  to  configure and read out
       hardware performance monitoring data on supported x86 processors. It can measure either as
       wrapper  without changing the measured application or with marker API functions inside the
       code, which will turn on and off the counters. There are preconfigured groups with  useful
       event  sets  and derived metrics. Additonally arbitrary events can be measured with custom
       event sets. The marker API can measure mulitple named regions. Results are accumulated  on
       multiple calls.  The following x86 processors are supported:

       •      Intel Core 2: all variants. Counters: PMC[0-1], FIXC[0-2]

       •      Intel Nehalem: Counters: PMC[0-3], FIXC[0-2], UPMC[0-7]

       •      Intel  Nehalem EX: Counters: PMC[0-3], FIXC[0-2], MBOX[0-1]C[0-5], BBOX[0-1]C[0-3],
              RBOX[0-1]C[0-7], WBOX[0-5], UBOX0, SBOX[0-1]C[0-3], CBOX[0-9]C[0-4]

       •      Intel Westmere:
               Counters: PMC[0-3], FIXC[0-2], UPMC[0-7]

       •      Intel Westmere EX: Counters: PMC[0-3], FIXC[0-2], MBOX[0-1]C[0-5], BBOX[0-1]C[0-3],
              RBOX[0-1]C[0-7], WBOX[0-5], UBOX0, SBOX[0-1]C[0-3], CBOX[0-9]C[0-4]

       •      Intel Sandy Bridge: full RAPL support. Counters: PMC[0-3], FIXC[0-2], PWR[0-3]

       •      Intel  Sandy  Bridge  EP:  partial support for uncore, full RAPL support. Counters:
              PMC[0-3], FIXC[0-2], PWR[0-3]. MBOX[0-3]C[0-3]

       •      Intel Ivy Bridge: full RAPL support. Counters: PMC[0-3], FIXC[0-2], PWR[0-3]

       •      Intel Ivy Bridge EP: partial support  for  uncore,  full  RAPL  support.  Counters:
              PMC[0-3], FIXC[0-2], PWR[0-3], CBOX[0-9]C[0-3], MBOX[0-3]C[0-3], MBOX[0-3]FIX

       •      Intel Haswell: full RAPL support. Counters: PMC[0-3], FIXC[0-2], PWR[0-3]

       •      Intel  Haswell  EP:  no  uncore  support,  full  RAPL  support. Counters: PMC[0-3],
              FIXC[0-2], PWR[0-3]

       •      Intel Atom Silvermont: full RAPL support. Counters: PMC[0-1], FIXC[0-2], PWR[0-1]

       •      Intel Pentium M: Banias and Dothan variants. Counters: PMC[0-1]

       •      Intel P6: Tested on P3.

       •      AMD K8: all variants. Counters: PMC[0-3]

       •      AMD K10: Barcelona, Shanghai,  Istanbul,  MagnyCours  based  processors.  Counters:
              PMC[0-3]

OPTIONS

-v prints version information to standard output, then exits.

-h prints a help message to standard output, then exits.

-H prints group help message (use together with -g switch).

-V verbose output during execution for debugging.

-m run in marker API mode

-a print available performance groups for current processor.

-e print available counters and performance events of current processor.

-o <filename>
store all ouput to a file instead of stdout. For the filename the following
placeholders are supported: %j for PBS_JOBID, %r for MPI RANK (only Intel MPI at
the moment), %h hostname and %p for process pid. The placeholders must be
separated by underscore as, e.g., -o test_%h_%p. You must specify a suffix to the
filename. For txt the output is printed as is to the file. Other suffixes trigger a
filter on the output. Available filters are csv (comma separated values) and xml
at the moment.

-O Do not print tables for results, use easily parseable CSV instead.

-i print cpuid information about processor and on Intel Performance Monitoring
features, then exit.

-c <processor_list>
specify a numerical list of processors. The list may contain multiple items,
separated by comma, and ranges. For example 0,3,9-11.

-C <processor_list>
specify a numerical list of processors. The list may contain multiple items,
separated by comma, and ranges. For example 0,3,9-11. This variant will also pin
the threads to the cores. Also logical numberings can be used.

-g <performance group> or <performance event set string>
specify which performance group to measure. This can be one of the tags output with
the -a flag. Also a custom event set can be specified by a comma separated list of
events. Each event has the format eventId:register with the the register being one
of a architecture supported performance counter registers.

-t <frequency of measurements>
timeline mode for time resolved measurements, possible suffixes 's' and 'ms' like
100ms. The output has the format:

<Event> <Timestamp> <Result thread0> <Result thread1> ...

-S <time_in_seconds>
stethoscope mode with duration in senconds. Can be used to measure an application
from the outside.

EXAMPLE

Because likwid-perfctr measures on processors and not single applications it is necessary
to ensure that processes and threads are pinned to dedicated resources. You can either pin
the application yourself or use the builtin pin functionality.

1. As wrapper with performance group:

likwid-perfctr -C 0-2 -g TLB ./cacheBench -n 2 -l 1048576 -i 100 -t Stream

The parent process is pinned to processor 0, Thread 0 to processor 1 and Thread 1 to
processor 2.

2. As wrapper with custom event set on AMD:

likwid-perfctr -C 0-4 -g INSTRUCTIONS_RETIRED_SSE:PMC0,CPU_CLOCKS_UNHALTED:PMC3 ./myApp

It is specified that the event INSTRUCTIONS_RETIRED_SSE is measured on counter PMC0 and
the event CPU_CLOCKS_UNHALTED on counter PMC3. It is possible calculate the runtime of
all threads based on the CPU_CLOCKS_UNHALTED event. If you want this you have to include
this event in your custom event string as shown above.

3. As wrapper with custom event set on Intel:

likwid-perfctr -C 0 -g INSTR_RETIRED_ANY:FIXC0,CPU_CLK_UNHALTED_CORE:FIXC1 ./myApp

On Intel processors fixed events are measured on dedicated counters. These are
INSTR_RETIRED_ANY , CPU_CLK_UNHALTED_CORE. and CPU_CLK_UNHALTED_REF If you configure
these fixed counters, likwid-perfctr will calculate the runtime and CPI metrics for your
run.

4. Using the marker API to measure only parts of your code (this can be used both with
groups or custom event sets):

likwid-perfctr -m -C 0-4 -g INSTRUCTIONS_RETIRED_SSE:PMC0,CPU_CLOCKS_UNHALTED:PMC3
./cacheBench

You have to link you code against liblikwid.a/.so and use the marker API calls. The
following code snippet shows the necessary calls:

#include <likwid.h>

/* only one thread calls init */
if (threadId == 0)
{
likwid_markerInit();
}
/* if you want to measure an threaded application
* you have to call likwid_markerThreadInit() for
* preparation, example with OpenMP */
#pragma omp parallel
{
likwid_markerThreadInit();
}
BARRIER;
likwid_markerStartRegion("Benchmark");
/* your code to be measured is here.*/

likwid_markerStopRegion("Benchmark");
BARRIER;
/* again only one thread can close the markers */
if (threadId == 0)
{
likwid_markerClose();
}

5. Using likwid in timeline mode:

likwid-perfctr -c 0-3 -g FLOPS_DP -t 300ms ./myApp > out.txt

This will read out the counters every 300ms on physical cores 0-3 and write the results to
out.txt. For timeline mode there is a frontend application likwid-scope, which enables
live plotting of selected events. For more code examples have a look at the likwid WIKI
pages. The processes are not pinned to the CPUs 0-3.

6. Using likwid in stethoscope mode:

likwid-perfctr -c 0-3 -g FLOPS_DP -S 2s

This will start the counters and read them out after 2s on physical cores 0-3 and write
the results to stdout. The processes are not pinned to the CPUs 0-3.

AUTHOR

       Written by Jan Treibig <jan.treibig@gmail.com>.

BUGS

       Report Bugs on <http://code.google.com/p/likwid/issues/list>.