Simple MATLAB/Octave API for PAPI (Performance Application Programming Interface).

• Hardware counters are measured for the parent and child threads (e.g. when using parallelized functions like sum). Unfortunately, there is no way to differentiate which counters come from which thread.
• Each function in the MEX-file is locked (once loaded it can't be erased using clear function in MATLAB/Octave environment)

1. Install PAPI >=5.5.1
2. Build mPAPI functions: mPAPI_register, mPAPI_tic, mPAPI_toc, mPAPI_groupEvents, mPAPI_enumNativeEvents, mPAPI_enumPresetEvents with MEX-compatible compiler (the repository contains two bash script for building build.sh and build_all.sh):

Where directory /usr/local/include contains papi.h header and directory /usr/local/lib/ contains libpapi.so static library.

1. Register hardware performance monitoring counters (PMC) using preset or native events:

• For the current thread/process:
  ev = mPAPI_register({'FP_ARITH:SCALAR_SINGLE', 'L1D:REPLACEMENT', 'PAPI_L2_ICA'})
• In multiplex mode for the current thread:
  ev = mPAPI_register({'FP_ARITH:SCALAR_SINGLE', 'L1D:REPLACEMENT', 'PAPI_L2_ICA'}, true)
• For a specific thread/process by PID:
  ev = mPAPI_register({'PAPI_TOT_INS'}, 1234)

2. Start counters for the specific event-set(s):

3. Read counters measurements

• For the specific event-set:
  >> mPAPI_toc(ev) ans = [0, 1559, 4032]
• For many event-sets:
  >> mPAPI_toc([ev1, ev2]) ans = [0, 1559, 4032; 0, 1450, 3999]

4. Enumarate all available native or preset PAPI events:

5. Divide events into compatible groups (that can be measured simultaneously)

1. Register sampling event and frequency (using overflow threshold):

The first argument is a performance event used as time, here we sample the program performance after some number of cycles defined by the second argument — sampling interval in the domain of time. The third argument is a cell array of performance events to measure. The last argument is a location of the trace result.

2. Start the sub-trace, basically, a performance trace for a given test.

The second argument is a header. For conversion of the trace to CSV with trace2csv script you need to use header convention: env:threads:process:benchmark:version:N:in_process. The fields represents: env — execution environment e.g. R2015b; threads — number of threads, process — number of test execution on different environment instances, benchmark and version — the kernel and the version used (marked in the code with %! pragma version), N — input data size, in_process — test repeition in the same instance of the execution environment.

3. Perform the test.
4. Finish the sub-trace

In order to set an older version of GCC (newer might not be supported by MATLAB's MEX compiler), run mex as follows:

• The number of hardware counters available on the system defines the upper limit of counters you can register using mPAPI_register function.
• Not all hardware counters can be mixed and used simultaneously (except when in multiplex mode).