LIBSTATCOUNTERS(3)

NAME
libstatcounters - A library to gather basic performance counter numbers

LIBRARY
libstatcounters

SYNOPSIS
#include <statcounters.h>

DESCRIPTION
The libstatcounters library provides an API to access BERI/CHERI statcounters and RISC-V HPM CSRs. To link with libstatcounters , use "-lstatcounters" when compiling. When linking statically, add

"-Wl,--whole-archive -lstatcounters -Wl,--no-whole-archive"

to the linking flags to still enable the automatic sampling of statcounters before and after main() , and output of the difference (this feature is directly available when linking non static). The behaviour of the automatic sampling is controlled by the STATCOUNTERS_PROGNAME , STATCOUNTERS_ARCHNAME , STATCOUNTERS_OUTPUT and STATCOUNTERS_FORMAT environment variables.

ENVIRONMENT

STATCOUNTERS_PROGNAME
    Environment variable specifying the program name to output (useful when appending entries to a csv output file)

STATCOUNTERS_ARCHNAME
    Environment variable specifying the architecture name to output (useful when appending entries to a csv output file)

STATCOUNTERS_OUTPUT
    Environment variable specifying the file in which to output the statcounters' values

STATCOUNTERS_FORMAT
    Environment variable specifying the desired output format. "csv" is supported, any other value will output in a human readable format

API
int statcounters_zero(statcounters_bank_t * const b)

statcounters_zero() zeroes the statcounters_bank_t b. Returns 0 on success or -1 if b is NULL.

int statcounters_sample(statcounters_bank_t * const b)

statcounters_sample() samples the hardware statcounters into statcounters_bank_t b. Returns 0 on success or -1 if b is NULL.

int statcounters_diff(statcounters_bank_t * const bd, const statcounters_bank_t * const be, const statcounters_bank_t * const bs)

statcounters_diff() subtracts statcounters_bank_t bs from be and stores the result in statcounters_bank_t bd. Returns 0 on success or -1 if either of bd, be, or bs is NULL.

int statcounters_dump(const statcounters_bank_t * const b)

statcounters_dump() is a wrapper around statcounters_dump_with_args(). The b argument is passed unchanged, the fmt_flg argument is set to HUMAN_READABLE and all other arguments are set to NULL.

int statcounters_dump_with_phase(const statcounters_bank_t * const b, const char * phase)

statcounters_dump_with_phase() is a wrapper around statcounters_dump_with_args(). The b and phase arguments are passed unchanged, the fmt_flg argument is set to HUMAN_READABLE and all other arguments are set to NULL.

int statcounters_dump_with_args(const statcounters_bank_t * const b, const char * progname, const char * phase, const char * archname, const FILE * const fp, const statcounters_fmt_flag_t fmt_flg)

statcounters_dump_with_args() dumps the statcounters_bank_t b content in file described by the file descriptor fp according to the format flag fmt_flg along with progname (and phase as a suffix if it is not NULL ) and archname (useful for csv output). The currently supported value for the fmt_flg argument are CSV_NOHEADER for csv output, CSV_HEADER for csv output with a header row, and HUMAN_READABLE for human readable output. If progname is NULL , the value in environment variable STATCOUNTERS_PROGNAME is used if it exists, otherwise, getprogname() is used. If archname is NULL , the value in environment variable STATCOUNTERS_ARCHNAME is used if it exists, otherwise, "mips" or "cheri" is used. If fp is NULL , the value in environment variable STATCOUNTERS_OUTPUT is used as an argument to fopen() if it exists, otherwise, stdout is used. If the STATCOUNTERS_FORMAT environment variable exists, it overwrites the fmt_flg argument. The function returns 0 on success or -1 if either of b or fp are NULL.

AUTHORS
Alexandre Joannou <aj443@cl.cam.ac.uk> Alex Richardson <arichardson@FreeBSD.org>