gprofng/common/hwcentry.h

   1 /* Copyright (C) 2021-2023 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 #ifndef _HWCENTRY_H
  22 #define _HWCENTRY_H
  23
  24 #ifndef LIBCOLLECTOR_SRC /* not running in libcollector */
  25 #include <stdio.h>  /* FILE */
  26 #endif  /* --- LIBCOLLECTOR_SRC --- */
  27 #include <stdlib.h> /* size_t */
  28 #include "hwc_cpus.h"
  29 #include "gp-time.h"
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #endif
  35
  36   /* ABS backtrack types */
  37   typedef enum
  38   {
  39     /* !! Lowest 2 bits are used to indicate load and store, respectively !! */
  40     /* Example: On SPARC, backtrack.c did this: if (ABS_memop & inst_type) ... */
  41     ABST_NONE               = 0x0,
  42     ABST_LOAD               = 0x1,
  43     ABST_STORE              = 0x2,
  44     ABST_LDST               = 0x3,
  45     ABST_COUNT              = 0x4,
  46     ABST_US_DTLBM           = 0xF,
  47     ABST_NOPC               = 0x100,
  48     ABST_CLKDS              = 0x103,     // Obsolete
  49     ABST_EXACT              = 0x203,
  50     ABST_LDST_SPARC64       = 0x303,
  51     ABST_EXACT_PEBS_PLUS1   = 0x403
  52     /* full description below... */
  53   } ABST_type;
  54
  55 #define ABST_PLUS_BY_DEFAULT(n) ((n)==ABST_EXACT || (n)==ABST_EXACT_PEBS_PLUS1)
  56 #define ABST_BACKTRACK_ENABLED(n) ((n)!=ABST_NONE && (n)!=ABST_NOPC)
  57 #define ABST_MEMSPACE_ENABLED(n)  ((n)!=ABST_NONE && (n)!=ABST_NOPC && (n)!=ABST_COUNT)
  58
  59   /* ABS determines the type of backtracking available for a particular metric.
  60    * Backtracking is enabled with the "+" in "-h +<countername>...".
  61    *
  62    * When Backtracking is not possible:
  63    *
  64    *  ABST_NONE=0:     Either the user did not specify "+", or backtracking
  65    *                   is not applicable to the metric, for example:
  66    *                     clk cycles,
  67    *                     instruct counts (dispatch + branch + prefetch),
  68    *                     i$,
  69    *                     FP ops
  70    *  ABST_NOPC=0x100  Used for non-program-related external events, for example:
  71    *                     system interface events,
  72    *                     memory controller counters
  73    *                   Of all ABST_type options, only ABST_NOPC prevents hwprofile.c
  74    *                     from recording PC/stack information.
  75    *
  76    * When backtracking is allowed:
  77    *
  78    *  ABST_LOAD=1:     data read events, used with metrics like:
  79    *                     D$, E$, P$ read misses and hits.
  80    *                     [DC+EC+PC]_rd*, Re_*_miss*,
  81    *                     EC_snoop_cb(?)
  82    *  ABST_STORE=2:    data write events, used with metrics like:
  83    *                     D$ writes and write related misses
  84    *                     DC_wr/wr-miss, EC_wb, WC=writecache, Rstall_storeQ
  85    *                     [EC+PC=pcache]_snoop_inv(?), WC_snoop_cb(?),
  86    *  ABST_LDST=3:     data reads/writes, used with metrics like:
  87    *                     E$ references, misses.
  88    *  ABST_COUNT=4:    dedicated assembly instruction: '%hi(0xfc000)'
  89    *                     See SW_count_n metric on sparc.
  90    *  ABST_US_DTLBM=0xF: for load-store on Sparc -- seems to be used only
  91    *                     for "unskidded DTLB_miss" with DTLB_miss metric.
  92    *                     Checks two adjacent instructions for Data access.
  93    *  ABST_CLKDS=0x103: data reads/writes, used with Clock-based Dataspace
  94    *                     profiling.  Ultrasparc T2 and earlier.
  95    *  ABST_EXACT=0x203: data reads/writes, precise trap with no skid
  96    *  ABST_LDST_SPARC64=0x303: Fujitsu SPARC64 load/store
  97    *  ABST_EXACT_PEBS_PLUS1=0x403: data reads/writes, precise sampling with 1 instr. skid
  98    */
  99
 100   /* Hwcentry - structure for defining a counter.
 101    *   Some fields have different usage when returned from
 102    *   hwc_lookup(), hwc_post_lookup(), or hwc_scan_*().
 103    *   Each function will describe its return values in more detail.
 104    */
 105   typedef struct
 106   {
 107     char *name;         /* user HWC specification */
 108     char *int_name;     /* internal HWC specification */
 109     regno_t reg_num;    /* register in CPU, aka picnum, or REGNO_ANY */
 110     char *metric;       /* descriptive name, for well-known counters only */
 111     volatile int val;   /* default or actual overflow value */
 112     int timecvt;        /* multiplier to convert metric to time, 0 if N/A */
 113     ABST_type memop;    /* type of backtracking allowed */
 114     char *short_desc;   /* optional one-liner description, or NULL */
 115     int type;           /* Type of perf_event_attr */
 116     long long config;   /* perf_event_type -specific configuration */
 117     /* the fields above this line are expected, in order, by the tables in hwctable.c */
 118     /* ================================================== */
 119     /* the fields below this line are more flexible */
 120     int sort_order;     /* "tag" to associate experiment record with HWC def */
 121     regno_t *reg_list;  /* if not NULL, legal values for <reg_num> field above */
 122     /* Note: reg_list will be terminated by REGNO_ANY */
 123     /* Max size of array is MAX_PICS */
 124     hrtime_t min_time;  /* target minimum time between overflow events.  0 is off.  See HWCTIME_* macros */
 125     hrtime_t min_time_default; /* if min_time==HWCTIME_AUTO, use this value instead.  0 is off. */
 126     int ref_val;    /* if min_time==HWCTIME_AUTO, use this time.  0 is off. */
 127     int lval, hval; /* temporary to allow DBX to build until dbx glue.cc fixed */
 128   } Hwcentry;
 129
 130   // Hwcentry.min_time canned values
 131 #define HWCTIME_TBD ((hrtime_t)( -1LL)) /* self-adjusting enabled but nsecs not yet selected */
 132 #define HWCTIME_HI  (   1 * 1000 * 1000LL ) /*   1 msec represented in nsecs */
 133 #define HWCTIME_ON  (  10 * 1000 * 1000LL ) /*  10 msec represented in nsecs */
 134 #define HWCTIME_LO  ( 100 * 1000 * 1000LL ) /* 100 msec represented in nsecs */
 135
 136 #define HWC_VAL_HI(refVal) (((refVal)/10) + 1)
 137 #define HWC_VAL_ON(refVal) (refVal)
 138 #define HWC_VAL_LO(refVal) (((refVal)*10)/100*100 + 1)  // zero's out lower digits, add 1
 139 #define HWC_VAL_CUSTOM(refVal, targetNanoSec) ((double)(refVal)*(targetNanoSec)/HWCTIME_ON)
 140
 141 #define HWCENTRY_USES_SAMPLING(h)   ((h)->memop==ABST_EXACT_PEBS_PLUS1)
 142
 143   extern int hwc_lookup (int forKernel, hrtime_t min_time_default,
 144                          const char *uname, Hwcentry *list[], unsigned listsz,
 145                          char **emsg, char **wmsg);
 146   /* Parses counter cmdline string.  Returns counter definitions.
 147    * Input:
 148    *   <forKernel> lookup using which table: 0-collect or 1-er_kernel
 149    *   <min_time_default> minimum nseconds between events if Hwcentry.min_time == HWCTIME_TBD.  0 to disable.
 150    *   <uname> command line HWC definition of format:
 151    *           <ctr_def>...[{','|(whitespace)}<ctr_n_def>] where
 152    *           <ctr_def> == [+]<ctr>[/<reg#>][,<interval>]
 153    *   <list> array of pointers to store counter definitions
 154    *   <listsz> number of elements in <list>
 155    * Returns:
 156    *   Success:
 157    *     Returns number of valid counters in <list> and <list>'s elements
 158    *     will be initialized as follows:
 159    *
 160    *     <list[]->name>:
 161    *       Copy of the <uname> with the following modification:
 162    *         if backtracking is not supported, the + will be removed.
 163    *     <list[]->int_name>:
 164    *       For well-known and convenience ctrs, the internal HWC specification,
 165    *         e.g. BSQ_cache_reference~emask=0x0100.
 166    *       For raw ctrs, this will be a copy of <name>.
 167    *     <list[]->reg_num>:
 168    *       Register number if specified by user or table, REGNO_ANY otherwise.
 169    *     <list[]->metric>:
 170    *       For well-known counters, descriptive name, e.g. "D$ Read Misses".
 171    *       NULL otherwise.
 172    *     <list[]->val>:
 173    *       Overflow value selected by user, default value otherwise.
 174    *     <list[]->timecvt>:
 175    *       Value from tables.
 176    *     <list[]->memop>:
 177    *       If + is selected and backtracking is allowed, value from table.
 178    *       ABST_NONE or ABST_NOPC otherwise.
 179    *
 180    *     It is the responsibility of the caller to free 'name' and 'int_name'.
 181    *     'metric' is a static string and shouldn't be freed.
 182    *     'emsg' will point to NULL
 183    *
 184    *   Failure:
 185    *     Frees all allocated elements.
 186    *     emsg will point to a string with an error message to print
 187    *     returns -1
 188    */
 189
 190   extern char *hwc_validate_ctrs (int forKernel, Hwcentry *list[], unsigned listsz);
 191   /* Validates that the vector of specified HW counters can be loaded (more-or-less)
 192    *   Some invalid combinations, especially on Linux will not be detected
 193    */
 194
 195   extern int hwc_get_cpc_cpuver ();
 196   /* Return the cpc_cpuver for this system.  Other possible values:
 197    *   CPUVER_GENERIC=0,           CPU could not be determined, but HWCs are ok.
 198    *   CPUVER_UNDEFINED=-1,        HWCs are not available.
 199    */
 200
 201   extern char *hwc_get_docref (char *buf, size_t buflen);
 202   /* Return a CPU HWC document reference, or NULL. */
 203
 204   // TBR
 205   extern char *hwc_get_default_cntrs ();
 206   /* Return a default HW counter string; may be NULL, or zero-length */
 207   /* NULL means none is defined in the table; or zero-length means string defined could not be loaded */
 208
 209   extern char *hwc_get_default_cntrs2 (int forKernel, int style);
 210   /* like hwc_get_default_cntrs() for style==1 */
 211   /* but allows other styles of formatting as well */
 212   /* deprecate and eventually remove hwc_get_default_cntrs() */
 213
 214   extern char *hwc_get_orig_default_cntrs ();
 215   /* Get the default HW counter string as set in the table */
 216   /* NULL means none is defined in the table */
 217
 218   extern void hwc_update_val (Hwcentry *ctr);
 219   /* Check time-based intervals and update Hwcentry.val as needed */
 220
 221   extern char *hwc_get_cpuname (char *buf, size_t buflen);
 222   /* Return the cpc cpu name for this system, or NULL. */
 223
 224   extern unsigned hwc_get_max_regs ();
 225   /* Return number of counters registers for this system. */
 226
 227   extern unsigned hwc_get_max_concurrent (int forKernel);
 228   /* Return the max number of simultaneous counters for this system. */
 229
 230   extern char **hwc_get_attrs (int forKernel);
 231   /* Return:
 232    *   Array of attributes (strings) supported by this system.
 233    *   Last element in array is null.
 234    *   Array and its elements should NOT be freed by the caller.
 235    */
 236
 237   extern unsigned hwc_scan_attrs (void (*action)(const char *attr,
 238                                                  const char *desc));
 239   /* Scan the HW counter attributes, and call function for each attribute.
 240    * Input:
 241    *   <action>:
 242    *     If NULL, no action is performed, but count is still returned.
 243    *     Otherwise called for each type of attributes, or if none exist,
 244    *       called once with NULL parameter.
 245    * Return: count of times <action> would have been called w/ non-NULL data.
 246    */
 247
 248   extern Hwcentry *hwc_post_lookup (Hwcentry * pret_ctr, char *uname,
 249                                     char * int_name, int cpc_cpuver);
 250   /* When post-processing a run, look up a Hwcentry for given type of system.
 251    * Input:
 252    *   <pret_ctr>: storage for counter definition
 253    *   <uname>: well-known name, convenience name, or complete HWC defintion.
 254    *   <int_name>: Hwcentry->int_name or NULL for don't care
 255    *   <cpc_cpuver>: version of cpu used for experiment.
 256    * Return:
 257    *   <pret_ctr>'s elements set as follows:
 258    *
 259    *     <pret_ctr->name>:
 260    *       Copy of <uname> with the following modifications:
 261    *         1) + and /<regnum> will be stripped off
 262    *         2) attributes will be sorted and values will shown in hex.
 263    *     <pret_ctr->int_name>:
 264    *       For well-known/convenience counters, the internal HWC specification
 265    *         from the table, e.g. BSQ_cache_reference~emask=0x0100.
 266    *       Otherwise, a copy of <uname>.
 267    *     <pret_ctr->reg_num>:
 268    *       Register number if specified by user or table,
 269    *       REGNO_ANY othewise.
 270    *     <pret_ctr->metric>:
 271    *       For well-known counters, descriptive name, e.g. "D$ Read Misses".
 272    *       NULL otherwise.
 273    *     <pret_ctr->timecvt>:
 274    *       For well-known/convenience/hidden counters, value from table.
 275    *       0 otherwise.
 276    *     <pret_ctr->memop>:
 277    *       For well-known/convenience/hidden counters, value from table.
 278    *       ABST_NONE otherwise.
 279    *     <pret_ctr->sort_order>:
 280    *       Set to 0.
 281    *
 282    *     It is the responsibility of the caller to free 'name' and 'int_name'.
 283    *     'metric' is a static string and shouldn't be freed.
 284    */
 285
 286   extern Hwcentry **hwc_get_std_ctrs (int forKernel);
 287   /* Return:
 288    *   Array of well-known counters supported by this system.
 289    *   Last element in array will be NULL.
 290    *   Array and its elements should NOT be freed by the caller.
 291    */
 292
 293   extern unsigned hwc_scan_std_ctrs (void (*action)(const Hwcentry *));
 294   /* Call <action> for each well-known counter.
 295    * Input:
 296    *   <action>:
 297    *     If NULL, no action is performed, but count is still returned.
 298    *     Otherwise called for each type of attributes, or if none exist,
 299    *       called once with NULL parameter.
 300    * Return:
 301    *   Count of times <action> would have been called w/ non-NULL data.
 302    *   If <action> is not NULL, Hwcentry fields will be set as follows:
 303    *     <ctr->name>:
 304    *       HWC alias name, e.g. dcrm.
 305    *     <ctr->int_name>:
 306    *       The internal HWC specification, e.g. BSQ_cache_reference~emask=0x0100.
 307    *     <ctr->reg_num>:
 308    *       Register number if specified by the table, REGNO_ANY otherwise.
 309    *     <ctr->metric>:
 310    *       Descriptive name, e.g. "D$ Read Misses".
 311    *     <ctr->lval>:
 312    *       Low-resolution overflow value.
 313    *     <ctr->val>:
 314    *       Default overflow value.
 315    *     <ctr->hval>:
 316    *       High-resolution overflow value.
 317    *     <ctr->timecvt>:
 318    *       multiplier to convert metric to time, 0 otherwise.
 319    *     <ctr->memop>:
 320    *       ABST_* type for this counter.
 321    *     <ctr->reg_list>:
 322    *       Array of legal <reg_num> values.  Terminated by REGNO_ANY.
 323    *
 324    *     Note: All fields point to static data, none should be freed.
 325    */
 326
 327   extern Hwcentry **hwc_get_raw_ctrs (int forKernel);
 328   /* Return:
 329    *   Table of raw (not well-known) counters supported by this system.
 330    *   Last element in array will be NULL.
 331    *   Table and its elements should NOT be freed by the caller.
 332    */
 333
 334   extern unsigned hwc_scan_raw_ctrs (void (*action)(const Hwcentry *));
 335   /* Call <action> for each raw counter.
 336    * Input:
 337    *   <action>:
 338    *     If NULL, no action is performed, but count is still returned.
 339    *     Otherwise called for each type of attributes, or if none exist,
 340    *       called once with NULL parameter.
 341    * Return:
 342    *   Count of times <action> would have been called w/ non-NULL data.
 343    *   If <action> is not NULL, Hwcentry fields will be set as follows:
 344    *     <ctr->name>:
 345    *       HWC raw name without attributes, e.g. BSQ_cache_reference.
 346    *     <ctr->int_name>:
 347    *       NULL.
 348    *     <ctr->metric>:
 349    *       NULL.
 350    *     The remainder of the fields are the same as for
 351    *       hwc_scan_std_ctrs().
 352    *
 353    *     Note: All fields point to static data, none should be freed.
 354    */
 355
 356   extern void
 357   hwc_usage (int forKernel, const char *cmd, const char *dataspace_msg);
 358   /* Print an i18n'd description of "-h" usage, used by collect and er_kernel.
 359    */
 360
 361   extern void hwc_usage_f (int forKernel, FILE *f, const char *cmd,
 362                            const char *dataspace_msg, int show_syntax,
 363                            int show_short_desc);
 364   /* Print an i18n'd description of "-h" usage to a FILE.  Used by GUI. */
 365
 366   extern char *hwc_rate_string (const Hwcentry *pctr, int force_numeric_format);
 367   /* Returns {"on"|"hi"|"lo"|""|<value>}.  Return value must be freed by caller. */
 368
 369   extern char *hwc_i18n_metric (const Hwcentry *ctr);
 370   /* Get a basic lable for a counter, properly i18n'd.
 371    *   Note: NOT MT SAFE.
 372    * Examples:
 373    *   CPU Cycles
 374    *   DC_rd Events
 375    * Pseudocode:
 376    *   if(ctr->metric != NULL) {
 377    *        sprintf(metricbuf, PTXT(ctr->metric) );
 378    *   } else if (ctr->name != NULL) {
 379    *        sprintf(metricbuf, GTXT("%s Events"), ctr->name );
 380    *   } else if (ctr->int_name != NULL) {
 381    *        sprintf(metricbuf, GTXT("%s Events"), ctr->int_name );
 382    *   }
 383    * Return: pointer to a buffer containing the above description.
 384    */
 385
 386   extern char *hwc_hwcentry_string (char *buf, size_t buflen, const Hwcentry *ctr);
 387   /* Get a i18n'd description of a HW counter's options.
 388    *   Examples of well-known counters:
 389    *     cycles[/{0|1}],9999991 ('CPU Cycles', alias for Cycle_cnt; CPU-cycles)
 390    *     dcr[/0],1000003 ('D$ Read Refs', alias for DC_rd; load events)
 391    *   Examples of raw counters:
 392    *     Cycle_cnt[/{0|1}],1000003 (CPU-cycles)
 393    *     DC_rd[/0],1000003 (load events)
 394    * Return: <buf>, filled in.
 395    */
 396
 397   extern char *hwc_hwcentry_specd_string (char *buf, size_t buflen, const Hwcentry *ctr);
 398   /* Get a i18n'd description of a HW counter's specific configuration.
 399    *   Examples of well-known counters:
 400    *     cycles,9999991 ('CPU Cycles')
 401    *     +dcr/0,1000003 ('D$ Read Refs')
 402    *   Examples of raw counters:
 403    *     Cycle_cnt,1000003
 404    *     +DC_rd/0,1000003
 405    * Return: <buf>, filled in.
 406    */
 407
 408   extern const char *hwc_memop_string (ABST_type memop);
 409   /* Get a i18n'd description of a variable of type ABST_type.
 410    * Return: pointer to static string.
 411    */
 412
 413 #ifdef __cplusplus
 414 }
 415 #endif
 416
 417 #endif