gprofng/common/hwcdrv.h

   1 /* Copyright (C) 2021-2024 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 driver's header */
  22
  23 #ifndef __HWCDRV_H
  24 #define __HWCDRV_H
  25
  26 #include "hwcfuncs.h"
  27
  28 #ifdef linux
  29 #define HWCFUNCS_SIGNAL         SIGIO
  30 #define HWCFUNCS_SIGNAL_STRING  "SIGIO"
  31 #else
  32 #define HWCFUNCS_SIGNAL         SIGEMT
  33 #define HWCFUNCS_SIGNAL_STRING  "SIGEMT"
  34 #endif
  35
  36 #ifndef LIBCOLLECTOR_SRC /* not running in libcollector */
  37 #include <string.h>
  38
  39 #else /* running in libcollector */
  40 #include "collector_module.h"
  41 #include "libcol_util.h"
  42
  43 #define get_hwcdrv                  __collector_get_hwcdrv
  44
  45 #define GTXT(x) x
  46
  47 /* Implemented by libcollector */
  48 #define calloc          __collector_calloc
  49 #define close           CALL_UTIL(close)
  50 #define fcntl           CALL_UTIL(fcntl)
  51 #define fprintf         CALL_UTIL(fprintf)
  52 //#define free            __collector_free
  53 #define free(...)
  54 #define gethrtime       __collector_gethrtime
  55 #define ioctl           CALL_UTIL(ioctl)
  56 #define malloc          __collector_malloc
  57 #define memcpy          __collector_memcpy
  58 #define memset          CALL_UTIL(memset)
  59 #define mmap            CALL_UTIL(mmap)
  60 #define snprintf        CALL_UTIL(snprintf)
  61 #define strchr          CALL_UTIL(strchr)
  62 #define strcmp          CALL_UTIL(strcmp)
  63 #define strncmp         CALL_UTIL(strncmp)
  64 #define strcpy          CALL_UTIL(strcpy)
  65 #define strdup          __collector_strdup
  66 #define strncpy         CALL_UTIL(strncpy)
  67 #define strerror        CALL_UTIL(strerror)
  68 #define strlen          CALL_UTIL(strlen)
  69 #define strstr          CALL_UTIL(strstr)
  70 #define strtol          CALL_UTIL(strtol)
  71 #define strtoll         CALL_UTIL(strtoll)
  72 #define strtoul         CALL_UTIL(strtoul)
  73 #define strtoull        CALL_UTIL(strtoull)
  74 #define syscall         CALL_UTIL(syscall)
  75 #define sysconf         CALL_UTIL(sysconf)
  76 #define vsnprintf       CALL_UTIL(vsnprintf)
  77
  78 #endif  /* --- LIBCOLLECTOR_SRC --- */
  79
  80 /* TprintfT(<level>,...) definitions.  Adjust per module as needed */
  81 #define DBG_LT0 0 // for high-level configuration, unexpected errors/warnings
  82 #define DBG_LT1 1 // for configuration details, warnings
  83 #define DBG_LT2 2
  84 #define DBG_LT3 3
  85 #define DBG_LT4 4
  86
  87 #ifdef __cplusplus
  88 extern "C"
  89 {
  90 #endif
  91
  92   /* hwcdrv api */
  93   typedef struct
  94   {
  95     int (*hwcdrv_init)(hwcfuncs_abort_fn_t abort_ftn, int * tsd_sz);
  96     /* Initialize hwc counter library (do not call again after fork)
  97          Must be called before other functions.
  98        Input:
  99          <abort_ftn>: NULL or callback function to be used for fatal errors
 100          <tsd_sz>: If not NULL, returns size in bytes required for thread-specific storage
 101        Return: 0 if successful
 102      */
 103
 104     void (*hwcdrv_get_info)(int *cpuver, const char **cciname, uint_t *npics,
 105                             const char **docref, uint64_t *support);
 106     /* get info about session
 107        Input:
 108          <cpuver>: if not NULL, returns value of CPC cpu version
 109          <cciname>: if not NULL, returns name of CPU
 110          <npics>: if not NULL, returns maximum # of HWCs
 111          <docref>: if not NULL, returns documentation reference
 112          <support>: if not NULL, returns bitmask (see hwcfuncs.h) of hwc support
 113        Return: 0 if successful, nonzero otherwise
 114      */
 115
 116     int (*hwcdrv_enable_mt)(hwcfuncs_tsd_get_fn_t tsd_ftn);
 117     /* Enables multi-threaded mode (do not need to call again after fork)
 118        Input:
 119          <tsd_ftn>: If <tsd_sz>==0, this parameter is ignored.
 120                     Otherwise:
 121                      tsd_ftn() must be able to return a pointer to thread-specific
 122                      memory of <tsd_sz> bytes.
 123                      For a given thread, tsd_ftn() must
 124                      always return the same pointer.
 125        Return: none
 126      */
 127
 128     int (*hwcdrv_get_descriptions)(hwcf_hwc_cb_t *hwc_find_action,
 129                                    hwcf_attr_cb_t *attr_find_action,
 130                                    Hwcentry *raw_hwc_tbl);
 131     /* Initiate callbacks with all available HWC names and HWC attributes.
 132        Input:
 133          <hwc_find_action>: if not NULL, will be called once for each HWC
 134          <attr_find_action>: if not NULL, will be called once for each attribute
 135          <raw_hwc_tbl>: counter definitions.
 136        Return: 0 if successful
 137           or a cpc return code upon error
 138      */
 139
 140     int (*hwcdrv_assign_regnos)(Hwcentry* entries[], unsigned numctrs);
 141     /* Assign entries[]->reg_num values as needed by platform
 142        Input:
 143          <entries>: array of counters
 144          <numctrs>: number of items in <entries>
 145        Return: 0 if successful
 146           HWCFUNCS_ERROR_HWCINIT if resources unavailable
 147           HWCFUNCS_ERROR_HWCARGS if counters were not specified correctly
 148      */
 149
 150     int (*hwcdrv_create_counters)(unsigned hwcdef_cnt, Hwcentry *hwcdef);
 151     /* Create the counters, but don't start them.
 152          call this once in main thread to create counters.
 153        Input:
 154          <defcnt>: number of counter definitions.
 155          <hwcdef>: counter definitions.
 156        Return: 0 if successful
 157           or a cpc return code upon error
 158      */
 159
 160     int (*hwcdrv_start)(void);
 161     /* Start the counters.
 162          call this once in main thread to start counters.
 163        Return: 0 if successful
 164           or a cpc return code upon error
 165      */
 166
 167     int (*hwcdrv_overflow)(siginfo_t *si, hwc_event_t *sample,
 168                            hwc_event_t *lost_samples);
 169     /* Linux only.  Capture current counter values.
 170          This is intended to be called from SIGEMT handler;
 171        Input:
 172          <si>: signal handler context information
 173          <sample>: returns non-zero values for counters that overflowed
 174          <lost_samples>: returns non-zero values for counters that "lost" counts
 175        Return: 0 if successful
 176           or a cpc return code upon error.
 177      */
 178
 179     int (*hwcdrv_read_events)(hwc_event_t *overflow_data,
 180                               hwc_event_samples_t *sampled_data);
 181     /* Read current counter values and samples.  Read of samples is destructive.
 182        Note: hwcdrv_read_events is not supported on Linux.
 183        <overflow_data>: returns snapshot of counter values
 184        <sampled_data>: returns sampled data
 185        Return: 0 if successful
 186           HWCFUNCS_ERROR_UNAVAIL if resource unavailable(e.g. called before initted)
 187           (other values may be possible)
 188      */
 189
 190     int (*hwcdrv_sighlr_restart)(const hwc_event_t* startVals);
 191     /* Restarts the counters at the given value.
 192          This is intended to be called from SIGEMT handler;
 193        Input:
 194          <startVals>: Solaris: new start values.
 195                       Linux: pointer may be NULL; startVals is ignored.
 196        Return: 0 if successful
 197           or a cpc return code upon error.
 198      */
 199
 200     int (*hwcdrv_lwp_suspend)(void);
 201     /* Attempt to stop counters on this lwp only.
 202          hwcdrv_lwp_resume() should be used to restart counters.
 203        Return: 0 if successful
 204           or a cpc return code upon error.
 205      */
 206
 207     int (*hwcdrv_lwp_resume)(void);
 208     /* Attempt to restart counters on this lwp when counters were
 209          stopped with hwcdrv_lwp_suspend().
 210        Return: 0 if successful
 211           or a cpc return code upon error.
 212      */
 213
 214     int (*hwcdrv_free_counters)(void);
 215     /* Stops counters on this lwp only and frees resources.
 216          This will fail w/ unpredictable results if other lwps's are
 217          still running.  After this call returns,
 218          hwcdrv_create_counters() may be called with new values.
 219        Return: 0 if successful
 220           or a cpc return code upon error.
 221      */
 222
 223     int (*hwcdrv_lwp_init)(void);
 224     /* per-thread counter init.
 225          Solaris: nop.
 226          Linux: just after thread creation call this from inside thread
 227               to create context and start counters.
 228        Return: 0 if successful
 229           or a perfctr return code upon error
 230      */
 231
 232     void (*hwcdrv_lwp_fini)(void);
 233     /* per-thread counter cleanup.
 234          Solaris: nop.
 235          Linux: call in each thread upon thread destruction.
 236      */
 237
 238     int hwcdrv_init_status;
 239   } hwcdrv_api_t;
 240
 241   extern hwcdrv_api_t *get_hwcdrv ();
 242   extern hwcdrv_api_t *__collector_get_hwcdrv ();
 243   extern int __collector_hwcfuncs_bind_descriptor (const char *defstring);
 244   extern Hwcentry **__collector_hwcfuncs_get_ctrs (unsigned *defcnt);
 245
 246   /* prototypes for internal use by hwcdrv drivers */
 247   typedef struct
 248   { // see hwcdrv_get_info() for field definitions
 249     int cpcN_cpuver;
 250     uint_t cpcN_npics;
 251     const char *cpcN_docref;
 252     const char *cpcN_cciname;
 253   } hwcdrv_about_t;
 254
 255 #define logerr  hwcfuncs_int_logerr
 256
 257   /*---------------------------------------------------------------------------*/
 258   /* prototypes for internal use by linux hwcdrv drivers */
 259 #define PERFCTR_FIXED_MAGIC 0x40000000 /* tells perfctr to use intel fixed pmcs */
 260 #define PERFCTR_UMASK_SHIFT 8
 261 #define EXTENDED_EVNUM_2_EVSEL(evnum) \
 262   ( (((eventsel_t)(evnum) & 0x0f00ULL) << 24) | ((eventsel_t)(evnum) & ~0x0f00ULL) )
 263
 264   typedef uint64_t eventsel_t;
 265   typedef struct
 266   {
 267     const char * attrname;  // user-visible name of attribute
 268     int is_inverted;        // nonzero means boolean attribute is inverted
 269     eventsel_t mask;        // which attribute bits can be set?
 270     eventsel_t shift;       // how far to shift bits for use in x86 register
 271   } attr_info_t;
 272   extern const attr_info_t *perfctr_attrs_table;
 273
 274   /* hdrv_pcbe api: cpu-specific drivers for Linux */
 275   typedef struct
 276   {
 277     int (*hdrv_pcbe_init)(void);
 278     uint_t (*hdrv_pcbe_ncounters)(void);
 279     const char *(*hdrv_pcbe_impl_name)(void);
 280     const char *(*hdrv_pcbe_cpuref)(void);
 281     int (*hdrv_pcbe_get_events)(hwcf_hwc_cb_t *hwc_cb, Hwcentry *raw_hwc_tbl);
 282     int (*hdrv_pcbe_get_eventnum)(const char * eventname, uint_t pmc,
 283                                   eventsel_t *eventnum, eventsel_t *valid_umask,
 284                                   uint_t *pmc_sel);
 285   } hdrv_pcbe_api_t;
 286
 287 #ifdef __cplusplus
 288 }
 289 #endif
 290
 291 #endif