Remove Debian from SECURITY.txt

[binutils-gdb.git] / gprofng / common / hwcentry.h

/* Copyright (C) 2021-2024 Free Software Foundation, Inc.
   Contributed by Oracle.

   This file is part of GNU Binutils.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, 51 Franklin Street - Fifth Floor, Boston,
   MA 02110-1301, USA.  */

#ifndef _HWCENTRY_H
#define _HWCENTRY_H

#ifndef LIBCOLLECTOR_SRC /* not running in libcollector */
#include <stdio.h>  /* FILE */
#endif  /* --- LIBCOLLECTOR_SRC --- */
#include <stdlib.h> /* size_t */
#include "hwc_cpus.h"
#include "gp-time.h"

#ifdef __cplusplus
extern "C"
{
#endif

  /* ABS backtrack types */
  typedef enum
  {
    /* !! Lowest 2 bits are used to indicate load and store, respectively !! */
    /* Example: On SPARC, backtrack.c did this: if (ABS_memop & inst_type) ... */
    ABST_NONE               = 0x0,
    ABST_LOAD               = 0x1,
    ABST_STORE              = 0x2,
    ABST_LDST               = 0x3,
    ABST_COUNT              = 0x4,
    ABST_US_DTLBM           = 0xF,
    ABST_NOPC               = 0x100,
    ABST_CLKDS              = 0x103,     // Obsolete
    ABST_EXACT              = 0x203,
    ABST_LDST_SPARC64       = 0x303,
    ABST_EXACT_PEBS_PLUS1   = 0x403
    /* full description below... */
  } ABST_type;

#define ABST_PLUS_BY_DEFAULT(n) ((n)==ABST_EXACT || (n)==ABST_EXACT_PEBS_PLUS1)
#define ABST_BACKTRACK_ENABLED(n) ((n)!=ABST_NONE && (n)!=ABST_NOPC)
#define ABST_MEMSPACE_ENABLED(n)  ((n)!=ABST_NONE && (n)!=ABST_NOPC && (n)!=ABST_COUNT)

  /* ABS determines the type of backtracking available for a particular metric.
   * Backtracking is enabled with the "+" in "-h +<countername>...".
   *
   * When Backtracking is not possible:
   *
   *  ABST_NONE=0:     Either the user did not specify "+", or backtracking
   *                   is not applicable to the metric, for example:
   *                     clk cycles,
   *                     instruct counts (dispatch + branch + prefetch),
   *                     i$,
   *                     FP ops
   *  ABST_NOPC=0x100  Used for non-program-related external events, for example:
   *                     system interface events,
   *                     memory controller counters
   *                   Of all ABST_type options, only ABST_NOPC prevents hwprofile.c
   *                     from recording PC/stack information.
   *
   * When backtracking is allowed:
   *
   *  ABST_LOAD=1:     data read events, used with metrics like:
   *                     D$, E$, P$ read misses and hits.
   *                     [DC+EC+PC]_rd*, Re_*_miss*,
   *                     EC_snoop_cb(?)
   *  ABST_STORE=2:    data write events, used with metrics like:
   *                     D$ writes and write related misses
   *                     DC_wr/wr-miss, EC_wb, WC=writecache, Rstall_storeQ
   *                     [EC+PC=pcache]_snoop_inv(?), WC_snoop_cb(?),
   *  ABST_LDST=3:     data reads/writes, used with metrics like:
   *                     E$ references, misses.
   *  ABST_COUNT=4:    dedicated assembly instruction: '%hi(0xfc000)'
   *                     See SW_count_n metric on sparc.
   *  ABST_US_DTLBM=0xF: for load-store on Sparc -- seems to be used only
   *                     for "unskidded DTLB_miss" with DTLB_miss metric.
   *                     Checks two adjacent instructions for Data access.
   *  ABST_CLKDS=0x103: data reads/writes, used with Clock-based Dataspace
   *                     profiling.  Ultrasparc T2 and earlier.
   *  ABST_EXACT=0x203: data reads/writes, precise trap with no skid
   *  ABST_LDST_SPARC64=0x303: Fujitsu SPARC64 load/store
   *  ABST_EXACT_PEBS_PLUS1=0x403: data reads/writes, precise sampling with 1 instr. skid
   */

  /* Hwcentry - structure for defining a counter.
   *   Some fields have different usage when returned from
   *   hwc_lookup(), hwc_post_lookup(), or hwc_scan_*().
   *   Each function will describe its return values in more detail.
   */
  typedef struct
  {
    char *name;         /* user HWC specification */
    char *int_name;     /* internal HWC specification */
    regno_t reg_num;    /* register in CPU, aka picnum, or REGNO_ANY */
    char *metric;       /* descriptive name, for well-known counters only */
    volatile int val;   /* default or actual overflow value */
    int timecvt;        /* multiplier to convert metric to time, 0 if N/A */
    ABST_type memop;    /* type of backtracking allowed */
    char *short_desc;   /* optional one-liner description, or NULL */
    /* the fields above this line are expected, in order, by the tables in hwctable.c */
    /* ================================================== */
    /* the fields below this line are more flexible */
    unsigned int use_perf_event_type : 16; /* Set 1 to use two fields below */
    unsigned int type : 16; /* Type of perf_event_attr */
    long long config;   /* perf_event_type -specific configuration */
    long long config1;  /* perf_event_type -specific configuration */
    int sort_order;     /* "tag" to associate experiment record with HWC def */
    hrtime_t min_time;  /* target minimum time between overflow events.  0 is off.  See HWCTIME_* macros */
    hrtime_t min_time_default; /* if min_time==HWCTIME_AUTO, use this value instead.  0 is off. */
    int ref_val;    /* if min_time==HWCTIME_AUTO, use this time.  0 is off. */
    int lval, hval; /* temporary to allow DBX to build until dbx glue.cc fixed */
  } Hwcentry;

  // Hwcentry.min_time canned values
#define HWCTIME_TBD ((hrtime_t)( -1LL)) /* self-adjusting enabled but nsecs not yet selected */
#define HWCTIME_HI  (   1 * 1000 * 1000LL ) /*   1 msec represented in nsecs */
#define HWCTIME_ON  (  10 * 1000 * 1000LL ) /*  10 msec represented in nsecs */
#define HWCTIME_LO  ( 100 * 1000 * 1000LL ) /* 100 msec represented in nsecs */

#define HWC_VAL_HI(refVal) (((refVal)/10) + 1)
#define HWC_VAL_ON(refVal) (refVal)
#define HWC_VAL_LO(refVal) (((refVal)*10)/100*100 + 1)  // zero's out lower digits, add 1
#define HWC_VAL_CUSTOM(refVal, targetNanoSec) ((double)(refVal)*(targetNanoSec)/HWCTIME_ON)

#define HWCENTRY_USES_SAMPLING(h)   ((h)->memop==ABST_EXACT_PEBS_PLUS1)

  extern int hwc_lookup (int forKernel, hrtime_t min_time_default,
                         const char *uname, Hwcentry *list[], unsigned listsz,
                         char **emsg, char **wmsg);
  /* Parses counter cmdline string.  Returns counter definitions.
   * Input:
   *   <forKernel> lookup using which table: 0-collect or 1-er_kernel
   *   <min_time_default> minimum nseconds between events if Hwcentry.min_time == HWCTIME_TBD.  0 to disable.
   *   <uname> command line HWC definition of format:
   *           <ctr_def>...[{','|(whitespace)}<ctr_n_def>] where
   *           <ctr_def> == [+]<ctr>[/<reg#>][,<interval>]
   *   <list> array of pointers to store counter definitions
   *   <listsz> number of elements in <list>
   * Returns:
   *   Success:
   *     Returns number of valid counters in <list> and <list>'s elements
   *     will be initialized as follows:
   *
   *     <list[]->name>:
   *       Copy of the <uname> with the following modification:
   *         if backtracking is not supported, the + will be removed.
   *     <list[]->int_name>:
   *       For well-known and convenience ctrs, the internal HWC specification,
   *         e.g. BSQ_cache_reference~emask=0x0100.
   *       For raw ctrs, this will be a copy of <name>.
   *     <list[]->reg_num>:
   *       Register number if specified by user or table, REGNO_ANY otherwise.
   *     <list[]->metric>:
   *       For well-known counters, descriptive name, e.g. "D$ Read Misses".
   *       NULL otherwise.
   *     <list[]->val>:
   *       Overflow value selected by user, default value otherwise.
   *     <list[]->timecvt>:
   *       Value from tables.
   *     <list[]->memop>:
   *       If + is selected and backtracking is allowed, value from table.
   *       ABST_NONE or ABST_NOPC otherwise.
   *
   *     It is the responsibility of the caller to free 'name' and 'int_name'.
   *     'metric' is a static string and shouldn't be freed.
   *     'emsg' will point to NULL
   *
   *   Failure:
   *     Frees all allocated elements.
   *     emsg will point to a string with an error message to print
   *     returns -1
   */

  extern char *hwc_validate_ctrs (int forKernel, Hwcentry *list[], unsigned listsz);
  /* Validates that the vector of specified HW counters can be loaded (more-or-less)
   *   Some invalid combinations, especially on Linux will not be detected
   */

  extern int hwc_get_cpc_cpuver ();
  /* Return the cpc_cpuver for this system.  Other possible values:
   *   CPUVER_GENERIC=0,           CPU could not be determined, but HWCs are ok.
   *   CPUVER_UNDEFINED=-1,        HWCs are not available.
   */

  extern char *hwc_get_docref (char *buf, size_t buflen);
  /* Return a CPU HWC document reference, or NULL. */

  extern char *hwc_get_default_cntrs2 (int forKernel, int style);
  /* like hwc_get_default_cntrs() for style==1 */
  /* but allows other styles of formatting as well */
  /* deprecate and eventually remove hwc_get_default_cntrs() */

  extern char *hwc_get_orig_default_cntrs (int forKernel);
  /* Get the default HW counter string as set in the table */
  /* NULL means none is defined in the table */

  extern void hwc_update_val (Hwcentry *ctr);
  /* Check time-based intervals and update Hwcentry.val as needed */

  extern char *hwc_get_cpuname (char *buf, size_t buflen);
  /* Return the cpc cpu name for this system, or NULL. */

  extern unsigned hwc_get_max_regs ();
  /* Return number of counters registers for this system. */

  extern unsigned hwc_get_max_concurrent (int forKernel);
  /* Return the max number of simultaneous counters for this system. */

  extern char **hwc_get_attrs (int forKernel);
  /* Return:
   *   Array of attributes (strings) supported by this system.
   *   Last element in array is null.
   *   Array and its elements should NOT be freed by the caller.
   */

  extern unsigned hwc_scan_attrs (void (*action)(const char *attr,
                                                 const char *desc));
  /* Scan the HW counter attributes, and call function for each attribute.
   * Input:
   *   <action>:
   *     If NULL, no action is performed, but count is still returned.
   *     Otherwise called for each type of attributes, or if none exist,
   *       called once with NULL parameter.
   * Return: count of times <action> would have been called w/ non-NULL data.
   */

  extern Hwcentry *hwc_post_lookup (Hwcentry * pret_ctr, char *uname,
                                    char * int_name, int cpc_cpuver);
  /* When post-processing a run, look up a Hwcentry for given type of system.
   * Input:
   *   <pret_ctr>: storage for counter definition
   *   <uname>: well-known name, convenience name, or complete HWC defintion.
   *   <int_name>: Hwcentry->int_name or NULL for don't care
   *   <cpc_cpuver>: version of cpu used for experiment.
   * Return:
   *   <pret_ctr>'s elements set as follows:
   *
   *     <pret_ctr->name>:
   *       Copy of <uname> with the following modifications:
   *         1) + and /<regnum> will be stripped off
   *         2) attributes will be sorted and values will shown in hex.
   *     <pret_ctr->int_name>:
   *       For well-known/convenience counters, the internal HWC specification
   *         from the table, e.g. BSQ_cache_reference~emask=0x0100.
   *       Otherwise, a copy of <uname>.
   *     <pret_ctr->reg_num>:
   *       Register number if specified by user or table,
   *       REGNO_ANY othewise.
   *     <pret_ctr->metric>:
   *       For well-known counters, descriptive name, e.g. "D$ Read Misses".
   *       NULL otherwise.
   *     <pret_ctr->timecvt>:
   *       For well-known/convenience/hidden counters, value from table.
   *       0 otherwise.
   *     <pret_ctr->memop>:
   *       For well-known/convenience/hidden counters, value from table.
   *       ABST_NONE otherwise.
   *     <pret_ctr->sort_order>:
   *       Set to 0.
   *
   *     It is the responsibility of the caller to free 'name' and 'int_name'.
   *     'metric' is a static string and shouldn't be freed.
   */

  extern Hwcentry **hwc_get_std_ctrs (int forKernel);
  /* Return:
   *   Array of well-known counters supported by this system.
   *   Last element in array will be NULL.
   *   Array and its elements should NOT be freed by the caller.
   */

  extern unsigned hwc_scan_std_ctrs (void (*action)(const Hwcentry *));
  /* Call <action> for each well-known counter.
   * Input:
   *   <action>:
   *     If NULL, no action is performed, but count is still returned.
   *     Otherwise called for each type of attributes, or if none exist,
   *       called once with NULL parameter.
   * Return:
   *   Count of times <action> would have been called w/ non-NULL data.
   *   If <action> is not NULL, Hwcentry fields will be set as follows:
   *     <ctr->name>:
   *       HWC alias name, e.g. dcrm.
   *     <ctr->int_name>:
   *       The internal HWC specification, e.g. BSQ_cache_reference~emask=0x0100.
   *     <ctr->reg_num>:
   *       Register number if specified by the table, REGNO_ANY otherwise.
   *     <ctr->metric>:
   *       Descriptive name, e.g. "D$ Read Misses".
   *     <ctr->lval>:
   *       Low-resolution overflow value.
   *     <ctr->val>:
   *       Default overflow value.
   *     <ctr->hval>:
   *       High-resolution overflow value.
   *     <ctr->timecvt>:
   *       multiplier to convert metric to time, 0 otherwise.
   *     <ctr->memop>:
   *       ABST_* type for this counter.
   *     <ctr->reg_list>:
   *       Array of legal <reg_num> values.  Terminated by REGNO_ANY.
   *
   *     Note: All fields point to static data, none should be freed.
   */

  extern Hwcentry **hwc_get_raw_ctrs (int forKernel);
  /* Return:
   *   Table of raw (not well-known) counters supported by this system.
   *   Last element in array will be NULL.
   *   Table and its elements should NOT be freed by the caller.
   */

  extern unsigned hwc_scan_raw_ctrs (void (*action)(const Hwcentry *));
  /* Call <action> for each raw counter.
   * Input:
   *   <action>:
   *     If NULL, no action is performed, but count is still returned.
   *     Otherwise called for each type of attributes, or if none exist,
   *       called once with NULL parameter.
   * Return:
   *   Count of times <action> would have been called w/ non-NULL data.
   *   If <action> is not NULL, Hwcentry fields will be set as follows:
   *     <ctr->name>:
   *       HWC raw name without attributes, e.g. BSQ_cache_reference.
   *     <ctr->int_name>:
   *       NULL.
   *     <ctr->metric>:
   *       NULL.
   *     The remainder of the fields are the same as for
   *       hwc_scan_std_ctrs().
   *
   *     Note: All fields point to static data, none should be freed.
   */

  extern void
  hwc_usage (int forKernel, const char *cmd, const char *dataspace_msg);
  /* Print an i18n'd description of "-h" usage, used by collect and er_kernel.
   */

  extern void hwc_usage_f (int forKernel, FILE *f, const char *cmd,
                           const char *dataspace_msg, int show_syntax,
                           int show_short_desc);
  /* Print an i18n'd description of "-h" usage to a FILE.  Used by GUI. */

  extern char *hwc_rate_string (const Hwcentry *pctr, int force_numeric_format);
  /* Returns {"on"|"hi"|"lo"|""|<value>}.  Return value must be freed by caller. */

  extern char *hwc_i18n_metric (const Hwcentry *ctr);
  /* Get a basic lable for a counter, properly i18n'd.
   *   Note: NOT MT SAFE.
   * Examples:
   *   CPU Cycles
   *   DC_rd Events
   * Pseudocode:
   *   if(ctr->metric != NULL) {
   *        sprintf(metricbuf, PTXT(ctr->metric) );
   *   } else if (ctr->name != NULL) {
   *        sprintf(metricbuf, GTXT("%s Events"), ctr->name );
   *   } else if (ctr->int_name != NULL) {
   *        sprintf(metricbuf, GTXT("%s Events"), ctr->int_name );
   *   }
   * Return: pointer to a buffer containing the above description.
   */

  extern char *hwc_hwcentry_string (char *buf, size_t buflen, const Hwcentry *ctr);
  /* Get a i18n'd description of a HW counter's options.
   *   Examples of well-known counters:
   *     cycles[/{0|1}],9999991 ('CPU Cycles', alias for Cycle_cnt; CPU-cycles)
   *     dcr[/0],1000003 ('D$ Read Refs', alias for DC_rd; load events)
   *   Examples of raw counters:
   *     Cycle_cnt[/{0|1}],1000003 (CPU-cycles)
   *     DC_rd[/0],1000003 (load events)
   * Return: <buf>, filled in.
   */

  extern char *hwc_hwcentry_specd_string (char *buf, size_t buflen, const Hwcentry *ctr);
  /* Get a i18n'd description of a HW counter's specific configuration.
   *   Examples of well-known counters:
   *     cycles,9999991 ('CPU Cycles')
   *     +dcr/0,1000003 ('D$ Read Refs')
   *   Examples of raw counters:
   *     Cycle_cnt,1000003
   *     +DC_rd/0,1000003
   * Return: <buf>, filled in.
   */

  extern const char *hwc_memop_string (ABST_type memop);
  /* Get a i18n'd description of a variable of type ABST_type.
   * Return: pointer to static string.
   */

#ifdef __cplusplus
}
#endif

#endif