pfmlib.h

Go to the documentation of this file.

/*
 * Copyright (c) 2001-2007 Hewlett-Packard Development Company, L.P.
 * Contributed by Stephane Eranian <eranian@hpl.hp.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
#ifndef __PFMLIB_H__
#define __PFMLIB_H__

#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h>
#include <inttypes.h>

#include <perfmon/pfmlib_os.h>
#include <perfmon/pfmlib_comp.h>

#define PFMLIB_VERSION          (3 << 16 | 9)
#define PFMLIB_MAJ_VERSION(v)   ((v)>>16)
#define PFMLIB_MIN_VERSION(v)   ((v) & 0xffff)

/*
 * Maximum number of PMCs/PMDs supported by the library (especially bitmasks)
 */
#define PFMLIB_MAX_PMCS         512 /* maximum number of PMCS supported by the library */
#define PFMLIB_MAX_PMDS         512 /* maximum number of PMDS supported by the library */

/*
 * privilege level mask (mask can be combined)
 * The interpretation of the level is specific to each
 * architecture. Checkout the architecture specific header
 * file for more details.
 */
#define PFM_PLM0        0x1     /* priv level 0 */
#define PFM_PLM1        0x2     /* priv level 1 */
#define PFM_PLM2        0x4     /* priv level 2 */
#define PFM_PLM3        0x8     /* priv level 3 */

/*
 * type used to describe a set of bits in the mask (container type)
 */
typedef unsigned long pfmlib_regmask_bits_t;

/*
 * how many elements do we need to represent all the PMCs and PMDs (rounded up)
 */
#if PFMLIB_MAX_PMCS > PFMLIB_MAX_PMDS
#define PFMLIB_REG_MAX  PFMLIB_MAX_PMCS
#else
#define PFMLIB_REG_MAX  PFMLIB_MAX_PMDS
#endif

#ifndef SWIG
#define __PFMLIB_REG_BV_BITS (sizeof(pfmlib_regmask_bits_t)<<3)
#define PFMLIB_BVSIZE(x) (((x)+(__PFMLIB_REG_BV_BITS)-1) / __PFMLIB_REG_BV_BITS)
#define PFMLIB_REG_BV PFMLIB_BVSIZE(PFMLIB_REG_MAX)
#endif

typedef struct {
        pfmlib_regmask_bits_t bits[PFMLIB_REG_BV];
} pfmlib_regmask_t;


#define PFMLIB_MAX_MASKS_PER_EVENT 48 /* maximum number of unit masks per event */

/*
 * event definition for pfmlib_input_param_t
 */
typedef struct {
        unsigned int    event;          /* event descriptor */
        unsigned int    plm;            /* event privilege level mask */
        unsigned long   flags;          /* per-event flag */
        unsigned int    unit_masks[PFMLIB_MAX_MASKS_PER_EVENT]; /* unit-mask identifiers */
        unsigned int    num_masks;      /* number of masks specified in 'unit_masks' */
        unsigned long   reserved[2];    /* for future use */
} pfmlib_event_t;

/*
 * generic register definition
 */
typedef struct {
        unsigned long long      reg_value;      /* register value */
        unsigned long long      reg_addr;       /* hardware register addr or index */
        unsigned int            reg_num;        /* logical register index (perfmon2) */
        unsigned int            reg_reserved1;  /* for future use */
        unsigned long           reg_alt_addr;   /* alternate hw register addr of index */
} pfmlib_reg_t;

/*
 * library generic input parameters for pfm_dispatch_event()
 */
typedef struct {
        unsigned int     pfp_event_count;               /* how many events specified (input) */
        unsigned int     pfp_dfl_plm;                   /* default priv level : used when event.plm==0 */
        unsigned int     pfp_flags;                     /* set of flags for all events used when event.flags==0*/
        unsigned int     reserved1;                     /* for future use */
        pfmlib_event_t   pfp_events[PFMLIB_MAX_PMCS];   /* event descriptions */
        pfmlib_regmask_t pfp_unavail_pmcs;              /* bitmask of unavailable PMC registers */
        unsigned long    reserved[6];                   /* for future use */
} pfmlib_input_param_t;

/*
 * pfp_flags possible values (apply to all events)
 */
#define PFMLIB_PFP_SYSTEMWIDE   0x1 /* indicate monitors will be used in a system-wide session */

/*
 * library generic output parameters for pfm_dispatch_event()
 */
typedef struct {
        unsigned int     pfp_pmc_count;                 /* number of entries in pfp_pmcs */
        unsigned int     pfp_pmd_count;                 /* number of entries in pfp_pmds */
        pfmlib_reg_t     pfp_pmcs[PFMLIB_MAX_PMCS];     /* PMC registers number and values */
        pfmlib_reg_t     pfp_pmds[PFMLIB_MAX_PMDS];     /* PMD registers numbers */
        unsigned long    reserved[7];                   /* for future use */
} pfmlib_output_param_t;

/*
 * library configuration options
 */
typedef struct {
        unsigned int    pfm_debug:1;    /* set in debug  mode */
        unsigned int    pfm_verbose:1;  /* set in verbose mode */
        unsigned int    pfm_reserved:30;/* for future use */
} pfmlib_options_t;

/*
 * special data type for libpfm error value used to help
 * with Python support and in particular for SWIG. By using
 * a specific type we can detect library calls and trap errors
 * in one SWIG statement as opposed to having to keep track of
 * each call individually. Programs can use 'int' safely for
 * the return value.
 */
typedef int pfm_err_t;                  /* error if !PFMLIB_SUCCESS */

extern pfm_err_t pfm_set_options(pfmlib_options_t *opt);
extern pfm_err_t pfm_initialize(void);

extern pfm_err_t pfm_list_supported_pmus(int (*pf)(const char *fmt,...));
extern pfm_err_t pfm_get_pmu_name(char *name, int maxlen);
extern pfm_err_t pfm_get_pmu_type(int *type);
extern pfm_err_t pfm_get_pmu_name_bytype(int type, char *name, size_t maxlen);
extern pfm_err_t pfm_is_pmu_supported(int type);
extern pfm_err_t pfm_force_pmu(int type);

/*
 * pfm_find_event_byname() is obsolete, use pfm_find_event
 */
extern pfm_err_t pfm_find_event(const char *str, unsigned int *idx);
extern pfm_err_t pfm_find_event_byname(const char *name, unsigned int *idx);
extern pfm_err_t pfm_find_event_bycode(int code, unsigned int *idx);
extern pfm_err_t pfm_find_event_bycode_next(int code, unsigned int start,
                                            unsigned int *next);
extern pfm_err_t pfm_find_event_mask(unsigned int event_idx, const char *str,
                                     unsigned int *mask_idx);
extern pfm_err_t pfm_find_full_event(const char *str, pfmlib_event_t *e);

extern pfm_err_t pfm_get_max_event_name_len(size_t *len);

extern pfm_err_t pfm_get_num_events(unsigned int *count);
extern pfm_err_t pfm_get_num_event_masks(unsigned int event_idx,
                                         unsigned int *count);
extern pfm_err_t pfm_get_event_name(unsigned int idx, char *name,
                                    size_t maxlen);
extern pfm_err_t pfm_get_full_event_name(pfmlib_event_t *e, char *name,
                                         size_t maxlen);
extern pfm_err_t pfm_get_event_code(unsigned int idx, int *code);
extern pfm_err_t pfm_get_event_mask_code(unsigned int idx,
                                         unsigned int mask_idx,
                                         unsigned int *code);
extern pfm_err_t pfm_get_event_counters(unsigned int idx,
                                        pfmlib_regmask_t *counters);
extern pfm_err_t pfm_get_event_description(unsigned int idx, char **str);
extern pfm_err_t pfm_get_event_code_counter(unsigned int idx, unsigned int cnt,
                                            int *code);
extern pfm_err_t pfm_get_event_mask_name(unsigned int event_idx,
                                         unsigned int mask_idx,
                                         char *name, size_t maxlen);
extern pfm_err_t pfm_get_event_mask_description(unsigned int event_idx,
                                                unsigned int mask_idx,
                                                char **desc);

extern pfm_err_t pfm_dispatch_events(pfmlib_input_param_t *p,
                                     void *model_in,
                                     pfmlib_output_param_t *q,
                                     void *model_out);

extern pfm_err_t pfm_get_impl_pmcs(pfmlib_regmask_t *impl_pmcs);
extern pfm_err_t pfm_get_impl_pmds(pfmlib_regmask_t *impl_pmds);
extern pfm_err_t pfm_get_impl_counters(pfmlib_regmask_t *impl_counters);
extern pfm_err_t pfm_get_num_pmds(unsigned int *num);
extern pfm_err_t pfm_get_num_pmcs(unsigned int *num);
extern pfm_err_t pfm_get_num_counters(unsigned int *num);

extern pfm_err_t pfm_get_hw_counter_width(unsigned int *width);
extern pfm_err_t pfm_get_version(unsigned int *version);
extern char *pfm_strerror(int code);
extern pfm_err_t pfm_get_cycle_event(pfmlib_event_t *e);
extern pfm_err_t pfm_get_inst_retired_event(pfmlib_event_t *e);

/*
 * Supported PMU family
 */
#define PFMLIB_NO_PMU                   -1      /* PMU unused (forced) */
#define PFMLIB_UNKNOWN_PMU              0       /* type not yet known (dynamic) */
#define PFMLIB_GEN_IA64_PMU             1       /* Intel IA-64 architected PMU */
#define PFMLIB_ITANIUM_PMU              2       /* Intel Itanium   */
#define PFMLIB_ITANIUM2_PMU             3       /* Intel Itanium 2 */
#define PFMLIB_MONTECITO_PMU            4       /* Intel Dual-Core Itanium 2 9000 */
#define PFMLIB_AMD64_PMU                16      /* AMD AMD64 (K7, K8, Fam 10h) */
#define PFMLIB_GEN_IA32_PMU             63      /* Intel architectural PMU for X86 */
#define PFMLIB_I386_P6_PMU              32      /* Intel PIII (P6 core) */
#define PFMLIB_PENTIUM4_PMU             33      /* Intel Pentium4/Xeon/EM64T */
#define PFMLIB_COREDUO_PMU              34      /* Intel Core Duo/Core Solo */
#define PFMLIB_I386_PM_PMU              35      /* Intel Pentium M */
#define PFMLIB_CORE_PMU                 36      /* obsolete, use PFMLIB_INTEL_CORE_PMU */
#define PFMLIB_INTEL_CORE_PMU           36      /* Intel Core */
#define PFMLIB_INTEL_PPRO_PMU           37      /* Intel Pentium Pro */
#define PFMLIB_INTEL_PII_PMU            38      /* Intel Pentium II */
#define PFMLIB_INTEL_ATOM_PMU           39      /* Intel Atom */
#define PFMLIB_INTEL_NHM_PMU            40      /* Intel Nehalem */
#define PFMLIB_INTEL_WSM_PMU            41      /* Intel Westmere */

#define PFMLIB_MIPS_20KC_PMU            64      /* MIPS 20KC */
#define PFMLIB_MIPS_24K_PMU             65      /* MIPS 24K */
#define PFMLIB_MIPS_25KF_PMU            66      /* MIPS 25KF */
#define PFMLIB_MIPS_34K_PMU             67      /* MIPS 34K */
#define PFMLIB_MIPS_5KC_PMU             68      /* MIPS 5KC */
#define PFMLIB_MIPS_74K_PMU             69      /* MIPS 74K */
#define PFMLIB_MIPS_R10000_PMU          70      /* MIPS R10000 */
#define PFMLIB_MIPS_R12000_PMU          71      /* MIPS R12000 */
#define PFMLIB_MIPS_RM7000_PMU          72      /* MIPS RM7000 */
#define PFMLIB_MIPS_RM9000_PMU          73      /* MIPS RM9000 */
#define PFMLIB_MIPS_SB1_PMU             74      /* MIPS SB1/SB1A */
#define PFMLIB_MIPS_VR5432_PMU          75      /* MIPS VR5432 */
#define PFMLIB_MIPS_VR5500_PMU          76      /* MIPS VR5500 */
#define PFMLIB_MIPS_ICE9A_PMU           77      /* SiCortex ICE9A */
#define PFMLIB_MIPS_ICE9B_PMU           78      /* SiCortex ICE9B */

#define PFMLIB_POWERPC_PMU              90      /* POWERPC */

#define PFMLIB_CRAYX2_PMU               96      /* Cray X2 */

#define PFMLIB_CELL_PMU                 100     /* CELL */

#define PFMLIB_PPC970_PMU               110     /* IBM PowerPC 970(FX,GX) */
#define PFMLIB_PPC970MP_PMU             111     /* IBM PowerPC 970MP */     
#define PFMLIB_POWER3_PMU               112     /* IBM POWER3 */
#define PFMLIB_POWER4_PMU               113     /* IBM POWER4 */
#define PFMLIB_POWER5_PMU               114     /* IBM POWER5 */
#define PFMLIB_POWER5p_PMU              115     /* IBM POWER5+ */
#define PFMLIB_POWER6_PMU               116     /* IBM POWER6 */
#define PFMLIB_POWER7_PMU               117     /* IBM POWER7 */

#define PFMLIB_SPARC_ULTRA12_PMU        130     /* UltraSPARC I, II, IIi, and IIe */
#define PFMLIB_SPARC_ULTRA3_PMU         131     /* UltraSPARC III */
#define PFMLIB_SPARC_ULTRA3I_PMU        132     /* UltraSPARC IIIi and IIIi+ */
#define PFMLIB_SPARC_ULTRA3PLUS_PMU     133     /* UltraSPARC III+ and IV */
#define PFMLIB_SPARC_ULTRA4PLUS_PMU     134     /* UltraSPARC IV+ */
#define PFMLIB_SPARC_NIAGARA1_PMU       135     /* Niagara-1 */
#define PFMLIB_SPARC_NIAGARA2_PMU       136     /* Niagara-2 */

/*
 * pfmlib error codes
 */
#define PFMLIB_SUCCESS            0     /* success */
#define PFMLIB_ERR_NOTSUPP       -1     /* function not supported */
#define PFMLIB_ERR_INVAL         -2     /* invalid parameters */
#define PFMLIB_ERR_NOINIT        -3     /* library was not initialized */
#define PFMLIB_ERR_NOTFOUND      -4     /* event not found */
#define PFMLIB_ERR_NOASSIGN      -5     /* cannot assign events to counters */
#define PFMLIB_ERR_FULL          -6     /* buffer is full or too small */
#define PFMLIB_ERR_EVTMANY       -7     /* event used more than once */
#define PFMLIB_ERR_MAGIC         -8     /* invalid library magic number */
#define PFMLIB_ERR_FEATCOMB      -9     /* invalid combination of features */
#define PFMLIB_ERR_EVTSET       -10     /* incompatible event sets */
#define PFMLIB_ERR_EVTINCOMP    -11     /* incompatible event combination */
#define PFMLIB_ERR_TOOMANY      -12     /* too many events or unit masks */

#define PFMLIB_ERR_IRRTOOBIG    -13     /* code range too big */
#define PFMLIB_ERR_IRREMPTY     -14     /* empty code range */
#define PFMLIB_ERR_IRRINVAL     -15     /* invalid code range */
#define PFMLIB_ERR_IRRTOOMANY   -16     /* too many code ranges */
#define PFMLIB_ERR_DRRINVAL     -17     /* invalid data range */
#define PFMLIB_ERR_DRRTOOMANY   -18     /* too many data ranges */
#define PFMLIB_ERR_BADHOST      -19     /* not supported by host CPU */
#define PFMLIB_ERR_IRRALIGN     -20     /* bad alignment for code range */
#define PFMLIB_ERR_IRRFLAGS     -21     /* code range missing flags */
#define PFMLIB_ERR_UMASK        -22     /* invalid or missing unit mask */
#define PFMLIB_ERR_NOMEM        -23     /* out of memory */

#define __PFMLIB_REGMASK_EL(g)          ((g)/__PFMLIB_REG_BV_BITS)
#define __PFMLIB_REGMASK_MASK(g)        (((pfmlib_regmask_bits_t)1) << ((g) % __PFMLIB_REG_BV_BITS))

static inline int
pfm_regmask_isset(pfmlib_regmask_t *h, unsigned int b)
{
        if (b >= PFMLIB_REG_MAX)
                return 0;
        return (h->bits[__PFMLIB_REGMASK_EL(b)] & __PFMLIB_REGMASK_MASK(b)) != 0;
}

static inline int
pfm_regmask_set(pfmlib_regmask_t *h, unsigned int b)
{
        if (b >= PFMLIB_REG_MAX)
                return PFMLIB_ERR_INVAL;

        h->bits[__PFMLIB_REGMASK_EL(b)] |=  __PFMLIB_REGMASK_MASK(b);

        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_clr(pfmlib_regmask_t *h, unsigned int b)
{
        if (h == NULL || b >= PFMLIB_REG_MAX)
                return PFMLIB_ERR_INVAL;

        h->bits[__PFMLIB_REGMASK_EL(b)] &= ~ __PFMLIB_REGMASK_MASK(b);

        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_weight(pfmlib_regmask_t *h, unsigned int *w)
{
        unsigned int pos;
        unsigned int weight = 0;

        if (h == NULL || w == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                weight += (unsigned int)pfmlib_popcnt(h->bits[pos]);
        }
        *w = weight;
        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_eq(pfmlib_regmask_t *h1, pfmlib_regmask_t *h2)
{
        unsigned int pos;

        if (h1 == NULL || h2 == NULL)
                return 0;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                if (h1->bits[pos] != h2->bits[pos]) return 0;
        }
        return 1;
}

static inline int
pfm_regmask_and(pfmlib_regmask_t *dst, pfmlib_regmask_t *h1, pfmlib_regmask_t *h2)
{
        unsigned int pos;
        if (dst == NULL || h1 == NULL || h2 == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                dst->bits[pos] = h1->bits[pos] & h2->bits[pos];
        }
        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_andnot(pfmlib_regmask_t *dst, pfmlib_regmask_t *h1, pfmlib_regmask_t *h2)
{
        unsigned int pos;
        if (dst == NULL || h1 == NULL || h2 == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                dst->bits[pos] = h1->bits[pos] & ~h2->bits[pos];
        }
        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_or(pfmlib_regmask_t *dst, pfmlib_regmask_t *h1, pfmlib_regmask_t *h2)
{
        unsigned int pos;
        if (dst == NULL || h1 == NULL || h2 == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                dst->bits[pos] = h1->bits[pos] | h2->bits[pos];
        }
        return PFMLIB_SUCCESS;
}

static inline int
pfm_regmask_copy(pfmlib_regmask_t *dst, pfmlib_regmask_t *src)
{
        unsigned int pos;
        if (dst == NULL || src == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                dst->bits[pos] = src->bits[pos];
        }
        return PFMLIB_SUCCESS;
}
static inline int
pfm_regmask_not(pfmlib_regmask_t *dst)
{
        unsigned int pos;
        if (dst == NULL)
                return PFMLIB_ERR_INVAL;

        for (pos = 0; pos < PFMLIB_REG_BV; pos++) {
                dst->bits[pos] = ~dst->bits[pos];
        }
        return PFMLIB_SUCCESS;
}

#ifdef __cplusplus /* extern C */
}
#endif

#endif /* __PFMLIB_H__ */