Running PAPI's High Level API in the MATLAB Environment

If you have the desire to do this, you most likely already
know why you want to make calls to PAPI inside of a 
MATLAB environment.

If you don't know much about what composes PAPI's high 
level API, you should probably take a look at this:

http://icl.cs.utk.edu/projects/papi/files/documentation/PAPI_USER_GUIDE_23.htm#WHAT_IS_HIGH_LEVEL_API

This section of the PAPI user guide covers C and FORTRAN
calls, but at the moment, you can only make C calls
from the MATLAB environment.

There is one overall function to call from Matlab; from there,
you specify which of the 6 specific functions you want to call, 
and then the arguments to each.  Here are some examples:

PAPI_num_counters - Returns the number of available
  hardware counters on the system.

Ex:  num_counters = PAPI('num')


PAPI_flips - Has 3 possibilities:
  Initialize FLIP counting with:
    PAPI('flips')
  Record the number of floating point instructions since
  initialization:
    ops = PAPI('flips')
  Record the number of floating point instructions and
  the incremental rate of floating point execution
  since initialization:
    [ops, mflips] = PAPI('flips')
  Use PAPI_stop_counters to stop counting flips and reset the counters.

PAPI_flops - Identical to PAPI_flips,
  but counts floating point *operations* rather than instructions.
  In most cases, these two are identical, but some instructions
  (e.g. FMA) might contain multiple operations or vice versa.

PAPI_ipc - Has 3 possibilities:
  Initialize instruction per cycle counting with:
    PAPI('ipc', 0)
  Record the number of instructions since
  initialization:
    ins = PAPI('ipc')
  Record the number of instructions and
  the incremental rate of instructions per cycle
  since initialization:
    [ins, ipc] = PAPI('ipc')
  

PAPI_start_counters - Specify the events to count
  (in text form or the actual numeric code; NOTE: make sure
  to not confuse normal decimal and hexadecimal.) You cannot
  specify more events than there are hardware counters.

  To begin counting cycles and instructions:
    PAPI('start', 'PAPI_TOT_CYC', 'PAPI_TOT_INS');


PAPI_read_counters - Simply specify the variables to read
  the values into.  You cannot specify more variables
  than there are hardware counters.  This will reset the
  counters.

  To read the above events you just started:
    [cycles, instructions] = PAPI('read');


PAPI_accum_counters - This function adds the value you
  pass to the readings in the hardware counter.  You
  cannot specify more variables than there are hardware
  counters.  This function will reset the counters.

  To add the values currently in the counters to the
  previously read values:
    [cycles, instructions] = PAPI('accum', cycles, instructions);


PAPI_stop_counters - This function reads the value of
  the running hardware counters into the variables
  you specify.  You cannot specify more variables than
  there are hardware counters.

  To stop the running counters you previously started
  and record their values:
    [cycles, instructions] = PAPI('stop');


PAPI_Matlab.c, when compiled, functions simply as a
wrapper.  In order to use the calls, you need to know a little
about mex.  mex is simply the compiler you use to make your
code run in the MATLAB environment.  If you don't know
how to use mex, you might want to acquaint yourself a bit.

"mex -setup "might be needed if you encounter problems, but
the simplest explanation might be to substitute "mex" for 
"gcc" and you are on your way.

All the other rules for compiling PAPI are the same.  mex
compilations can de done inside or outside of the Matlab
environment, but in this case, it is recommended that you
compile outside of Matlab.  For some reason, compiling 
inside does not work on some systems.

So far, the Linux environment and the Windows environment
have been tested, but _in theory_ this code should work anywhere 
PAPI and Matlab both work.

The following instructions are for a Linux/Unix environment:

Assuming papi.h is present in /usr/local/include and libpapi.so
is present in /usr/local/lib, the below should work.  If not,
you may need to alter the compile strings and/or the #include
statement in PAPI_Matlab.c.  Also, the compile string will be
different for different platforms.

For instance, if I want to compile and run on a linux
machine assuming PAPI_Matlab.c is in your current working
directory (you'll have a different compile string on a 
different architecture):

1. Compile the wrapper:
mex -I/usr/local/include PAPI_Matlab.c /usr/local/lib/libpapi.so -output PAPI

2.  Start Matlab:
matlab

3.  Run the code:
a.  Find the number of hardware counters on your system:
num_counters = PAPI('num')


b.  Play with flips - the first makes sure the counters are stopped and clear;
    the second initializes the counting;
    the third returns the number of floating point instructions
    since the first call, and the fourth line does the same as the
    second AND reports the incremental rate of floating point
    execution since the last call:
PAPI('stop')
PAPI('flips')
ins = PAPI('flips')
[ins, mflips] = PAPI('flips')

c.  Play with instructions per cycle - the first makes sure the 
    counters are stopped and clear; the second initializes counting;
    the third returns the number of instructions
    since the first call, and the fourth line does the same as the
    second AND reports the incremental rate of instructions per
    cycle since the last call:
PAPI('stop')
PAPI('ipc')
ins = PAPI('ipc')
[ins, ipc] = PAPI('ipc')

d. Try the example m files included with the distribution:
PAPIInnerProduct.m
PAPIMatrixVector.m
PAPIMatrixMatrix.m

e.  Start counting:
PAPI('start', 'PAPI_TOT_CYC', 'PAPI_TOT_INS')

f.  Read the counters and reset:
[cycles, instr] = PAPI('read')

g.  Add the current value of the counters to a previous read
    and reset:
[cycles, instr] = PAPI('accum', cycles, instr)

h.  Read the counters and stop them:
[cycles, instr] = PAPI('stop')

You can pass as many events as you like to be counted or
recorded, as long as that number does not exceed the number
of available hardware counters.

Contact ralph@eecs.utk.edu or/and ptools-perfapi@icl.utk.edu
with any questions regarding PAPI calls in Matlab - either errors or questions.
Also, this has just been implemented, so changes could
be coming..........