gprofng/common/hwcfuncs.h

   1 /* Copyright (C) 2021 Free Software Foundation, Inc.
   2    Contributed by Oracle.
   3
   4    This file is part of GNU Binutils.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3, or (at your option)
   9    any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, 51 Franklin Street - Fifth Floor, Boston,
  19    MA 02110-1301, USA.  */
  20
  21 /* Hardware counter profiling */
  22
  23 #ifndef __HWCFUNCS_H
  24 #define __HWCFUNCS_H
  25
  26 #ifdef LIBCOLLECTOR_SRC /* running in libcollector */
  27 #define hwcfuncs_int_logerr         __collector_hwcfuncs_int_logerr
  28 #define hwcfuncs_parse_ctr          __collector_hwcfuncs_parse_ctr
  29 #define hwcfuncs_parse_attrs        __collector_hwcfuncs_parse_attrs
  30 #define hwcfuncs_bind_descriptor    __collector_hwcfuncs_bind_descriptor
  31 #define hwcfuncs_bind_hwcentry      __collector_hwcfuncs_bind_hwcentry
  32 #define hwcfuncs_assign_regnos      __collector_hwcfuncs_assign_regnos
  33 #define regno_is_valid              __collector_regno_is_valid
  34 #define hwcfuncs_get_ctrs           __collector_hwcfuncs_get_ctrs
  35 #define hwcfuncs_errmsg_get         __collector_hwcfuncs_errmsg_get
  36 #endif  /* --- LIBCOLLECTOR_SRC --- */
  37
  38 #include <signal.h>     /* siginfo_t */
  39 #include <limits.h>     /* UINT64_t */
  40 #include <sys/types.h>
  41 #include <stdint.h>
  42
  43 #include "hwcentry.h"   /* for Hwcentry type */
  44 #include "gp-time.h"
  45
  46 typedef unsigned int uint_t;
  47
  48 #ifdef  __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /*---------------------------------------------------------------------------*/
  53 /* compile options */
  54
  55 #define HWC_DEBUG   0 /* 0/1 to enable extra HWC debug */
  56
  57 /*---------------------------------------------------------------------------*/
  58 /* typedefs */
  59 /* generic hw event */
  60   typedef struct _hwc_event_t
  61   { /* generalized counter event */
  62     hrtime_t ce_hrt;            /* gethrtime() */
  63     uint64_t ce_pic[MAX_PICS];  /* counter samples or start values */
  64   } hwc_event_t;
  65
  66   /* supplementary data that accompanies some hw events */
  67   typedef struct
  68   { /* supplementary data fields */
  69     uint64_t smpl_pc;           /* pc related to event */
  70     uint64_t smpl_data_source;  /* chip-specific data source encoding */
  71     uint64_t smpl_latency;      /* latency related to event */
  72     uint64_t smpl_mem_addr;     /* memory address related to event */
  73   } hwc_sample_t;
  74 #define HWCFUNCS_INVALID_U64 0xFEEDBEEFDEADBEEFllu /* identifies fields as unused */
  75
  76 typedef struct {                                /* supplementary data fields */
  77     hwc_sample_t sample[MAX_PICS];  /* counter samples or start values */
  78 } hwc_event_samples_t;
  79
  80 #define HWCFUNCS_SAMPLE_RESET(sample) \
  81         do { \
  82             (sample)->smpl_pc          =HWCFUNCS_INVALID_U64; \
  83             (sample)->smpl_data_source =HWCFUNCS_INVALID_U64; \
  84             (sample)->smpl_latency     =HWCFUNCS_INVALID_U64; \
  85             (sample)->smpl_mem_addr    =HWCFUNCS_INVALID_U64; \
  86         } while(0)
  87
  88 #define HWCFUNCS_SAMPLE_IS_RESET(sample) \
  89         ( \
  90             (sample)->smpl_pc         ==HWCFUNCS_INVALID_U64 && \
  91             (sample)->smpl_data_source==HWCFUNCS_INVALID_U64 && \
  92             (sample)->smpl_latency    ==HWCFUNCS_INVALID_U64 && \
  93             (sample)->smpl_mem_addr   ==HWCFUNCS_INVALID_U64 \
  94         )
  95
  96 /*---------------------------------------------------------------------------*/
  97 /* macros */
  98
  99 #define HW_INTERVAL_MAX         UINT64_MAX
 100 #define HW_INTERVAL_PRESET(x)   (HW_INTERVAL_MAX - ((uint64_t)(x) - 1))
 101 #define HW_INTERVAL_TYPE(x)     ((uint64_t) (x)
 102
 103 /* parsing */
 104 #define HWCFUNCS_MAX_ATTRS              20
 105 #define HWCFUNCS_PARSE_ATTR             '~'
 106 #define HWCFUNCS_PARSE_EQUAL            '='
 107 #define HWCFUNCS_PARSE_BACKTRACK        '+'
 108 #define HWCFUNCS_PARSE_BACKTRACK_OFF    '-'
 109 #define HWCFUNCS_PARSE_REGNUM           '/'
 110 #define HWCFUNCS_PARSE_VALUE            ','
 111
 112 /* error codes */
 113 #define HWCFUNCS_ERROR_GENERIC          (-1)
 114 #define HWCFUNCS_ERROR_NOT_SUPPORTED    (-2)
 115 #define HWCFUNCS_ERROR_ALREADY_CALLED   (-3)
 116 #define HWCFUNCS_ERROR_HWCINIT          (-4)
 117 #define HWCFUNCS_ERROR_HWCARGS          (-5)
 118 #define HWCFUNCS_ERROR_MEMORY           (-6)
 119 #define HWCFUNCS_ERROR_UNAVAIL          (-7)
 120 #define HWCFUNCS_ERROR_ERRNO_ZERO       (-8)
 121 #define HWCFUNCS_ERROR_UNEXPECTED       (-99)
 122
 123 /*---------------------------------------------------------------------------*/
 124 /* prototypes */
 125
 126 typedef void (*hwcfuncs_abort_fn_t) (int errnum, const char *msg);
 127
 128 extern void hwcfuncs_int_logerr(const char *format,...);
 129 /* Log an error to the internal error buffer. See hwcfuncs_errmsg_get().
 130      Note: Not MT-safe; don't even enable logging in an MT environment.
 131        Recommend using this call only during init.
 132      Note: when a libcpc call fails, it may automatically call
 133        cpcN_capture_errmsg() to log the error message in the same internal buffer.
 134        Recommend using this call only for non-cpc failures.
 135  */
 136
 137 #define HWCFUNCS_SUPPORT_OVERFLOW_PROFILING 0x01llu
 138 #define HWCFUNCS_SUPPORT_PEBS_SAMPLING      0x02llu
 139 #define HWCFUNCS_SUPPORT_OVERFLOW_CTR_ID    0x04llu // OS identifies which counter overflowed
 140   /* get info about session
 141      Input:
 142        <cpuver>: if not NULL, returns value of CPC cpu version
 143        <cciname>: if not NULL, returns name of CPU
 144        <npics>: if not NULL, returns maximum # of HWCs
 145        <docref>: if not NULL, returns documentation reference
 146        <support>: if not NULL, returns bitmask (see above) of hwc support
 147      Return: none
 148    */
 149
 150   typedef void* (*hwcfuncs_tsd_get_fn_t) (void);
 151   typedef void (hwcf_hwc_cb_t) (uint_t cpcregno, const char *name);
 152   typedef void (hwcf_attr_cb_t) (const char *attr);
 153
 154   extern void
 155   hwcfuncs_parse_ctr (const char *counter_def, int *pplus, char **pnameOnly,
 156                       char **pattrs, char **pregstr, regno_t *pregno);
 157 /* Parse a counter definition string (value must already be stripped off).
 158      Input:
 159        <counter_def>: input whose format is
 160          [+|-]<countername>[~attrs...][/<regno>]
 161        pointers to return values:  Any can be NULL.
 162      Return:
 163        <plus>: 1 if [+] is found, -1 if [-] is found, 0 otherwise
 164        <pnameonly>: strdup(<countername>)
 165        <pattrs>: strdup([~attrs...]) if specified, NULL otherwise.
 166        <pregstr>: strdup(/<regno>) if specified, NULL otherwise.
 167        <pregno>: <regno> if readable, REGNO_ANY if not specd, or -2 otherwise.
 168    */
 169
 170   typedef struct
 171   {
 172     char *ca_name;
 173     uint64_t ca_val;
 174   } hwcfuncs_attr_t; /* matches cpc_attr_t */
 175
 176   void * hwcfuncs_parse_attrs (const char *countername,
 177                                hwcfuncs_attr_t attrs[], unsigned max_attrs,
 178                                uint_t *pnum_attrs, char **errstring);
 179   /* Extract the attribute fields from <countername>.
 180        Input:
 181          <countername>: string whose format is
 182             [+]<ctrname>[~attributes...][/<regno>][,...]
 183          <attrs>: array of attributes to be returned
 184          <max_attrs>: number of elements in <attrs>
 185          <pnum_attrs>: if not NULL, will return how many attrs were found.
 186          <errstring>: pointer to a buffer for storing error info, or NULL.
 187        Return: upon success, a pointer to an allocated copy of <countername>, or
 188            NULL if there's a failure.  (A copy is made in order to provide storage
 189            for the ca_name fields in the <attrs> array.)
 190
 191            The pointer should be freed when <attrs> is no longer in use.
 192            <attrs> will be filled in data from countername.
 193          <pnum_attrs> will have the number of elements in <attrs>.  May be
 194            non-zero even if return value indicates an error.
 195          <errstring> NULL if no error, otherwise, a malloc'd GTXT string.
 196    */
 197
 198   extern int hwcfuncs_bind_descriptor (const char *defstring);
 199   /* Bind counters to resources.
 200      Input:
 201        <defstring>: string whose format is
 202           :%s:%s:0x%x:%d:%d,0x%x[:%s...repeat for each ctr]
 203          where the fields are:
 204           :<userName>:<internalCtr>:<register>:<timeoutVal>:<tag>:<memop>
 205      Return: 0 if successful
 206         HWCFUNCS_ERROR_HWCINIT if resources unavailable
 207         HWCFUNCS_ERROR_HWCARGS if counters were not specified correctly
 208    */
 209
 210   extern int hwcfuncs_bind_hwcentry (const Hwcentry *entries[],
 211                                      unsigned numctrs);
 212   /* Bind counters to resources.
 213      Input:
 214        <entries>: array of counters
 215        <numctrs>: number of items in <entries>
 216      Return: 0 if successful
 217         HWCFUNCS_ERROR_HWCINIT if resources unavailable
 218         HWCFUNCS_ERROR_HWCARGS if counters were not specified correctly
 219    */
 220
 221   extern int hwcfuncs_assign_regnos (Hwcentry *entries[], unsigned numctrs);
 222   /* Assign entries[]->reg_num values as needed by platform
 223        Note: modifies <entries> by supplying a regno to each counter
 224      Input:
 225        <entries>: array of counters
 226        <numctrs>: number of items in <entries>
 227      Output:
 228        <entries>: array of counters is modified
 229      Return: 0 if successful
 230         HWCFUNCS_ERROR_HWCINIT if resources unavailable
 231         HWCFUNCS_ERROR_HWCARGS if counters were not specified correctly
 232    */
 233
 234   extern int regno_is_valid (const Hwcentry *pctr, regno_t regno);
 235   /* return 1 if <regno> is in Hwcentry's list
 236      Input:
 237        <pctr>: counter definition, reg_list[] should be initialized
 238        <regno>: register to check
 239      Return: 1 if <regno> is in Hwcentry's list, 0 otherwise
 240    */
 241
 242   extern Hwcentry **hwcfuncs_get_ctrs (unsigned *defcnt);
 243   /* Get descriptions of the currently bound counters.
 244      Input:
 245        <defcnt>: if not NULL, returns number of counter definitions.
 246      Return:
 247        table of counter definition pointers
 248    */
 249
 250   extern char *hwcfuncs_errmsg_get (char * buf, size_t bufsize,
 251                                     int enable_capture);
 252   /* Gets a recent HWC error message.
 253        To clear previous error messages and insure error message is enabled,
 254        call hwcfuncs_errmsg_get(NULL,0,1).
 255        Once enabled, one error is stored in an internal buffer.  A call to this
 256        function will clear the buffer and allow a new message to be captured.
 257        Note: Not MT-safe - don't enable this feature in an MT environment.
 258      Input:
 259        <buf>: pointer to buffer or NULL.
 260        <bufsize>: size of <buf>
 261        <enable_capture>: 0 - disable buffering, 1 - enable buffering.
 262      Return: error string or an empty string.
 263    */
 264
 265 #ifdef  __cplusplus
 266 }
 267 #endif
 268
 269 #endif /* ! __HWCFUNCS_H */