libperfex, start counters, read counters, print counters

LIBPERFEX(3C)

NAME

libperfex, start_counters, read_counters, print_counters - a procedural interface to R10000 counters

C SYNOPSIS

int start_counters( int e0, int e1 );

int read_counters( int e0, long long *c0, int e1, long long *c1);

int print_counters( int e0, long long c0, int e1, long long c1);

FORTRAN SYNOPSIS

INTEGER*8 c0, c1

INTEGER*4 function start_counters( e0, e1 )

INTEGER*4 function read_counters( e0, c0, e1, c1 )

INTEGER*4 function print_counters( e0, c0, e1, c1 )

DESCRIPTION

These routines provide simple access to the R10000 event counters. The arguments e0 and e1 are int types specifying which events to count from the following table

          0 = Cycles
          1 = Issued instructions
          2 = Issued loads
          3 = Issued stores
          4 = Issued store conditionals
          5 = Failed store conditionals
          6 = Decoded branches
          7 = Quadwords written back from scache
          8 = Correctable scache data array ECC errors
          9 = Primary instruction cache misses
          10 = Secondary instruction cache misses
          11 = Instruction misprediction from scache way prediction table
          12 = External interventions
          13 = External invalidations
          14 = Virtual coherency conditions
          15 = Graduated instructions
          16 = Cycles
          17 = Graduated instructions
          18 = Graduated loads
          19 = Graduated stores
          20 = Graduated store conditionals
          21 = Graduated floating point instructions
          22 = Quadwords written back from primary data cache
          23 = TLB misses
          24 = Mispredicted branches
          25 = Primary data cache misses
          26 = Secondary data cache misses
          27 = Data misprediction from scache way prediction table
          28 = External intervention hits in scache
          29 = External invalidation hits in scache
          30 = Store/prefetch exclusive to clean block in scache
          31 = Store/prefetch exclusive to shared block in scache

The counts are returned in the long long arguments c0 and c1. The print_counters prints the counts to standard error. Similar to perfex two events which *must* be counted on the same hardware counter will cause a conflicting counters error.

The arguments e0 and e1 can be overridden by setting the environment variables T5_EVENT0 and T5_EVENT1. Calls to start_counters implicitly zero out the internal software counters before starting them, while read_counters implicitly stops the counters after reading them. Thus if you want to accumulate counts over multiple start/read calls, you must save out the counts and do the accumulation yourself. The print_counters procedure is just a formatting device and has no effect on the state of the counters.

DIAGNOSTICS

Normal completion returns 0. Negative return values signal an error.

FILES

/usr/lib64/libperfex.so

/usr/lib32/libperfex.so

DEPENDENCIES

These procedures are only available on R10000 systems, and currently only for the N32 and N64 ABIs (with mips4 or mips3 ISAs). Manipulating the counters with these routines and simultaneously through perfex or the OS counter interface ioctl procedures can produce an error if, for example, the counters are enabled twice without being released in the interim.