| /* 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 */ |
| 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. */ |
| |
| // TBR |
| extern char *hwc_get_default_cntrs (); |
| /* Return a default HW counter string; may be NULL, or zero-length */ |
| /* NULL means none is defined in the table; or zero-length means string defined could not be loaded */ |
| |
| 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 (); |
| /* 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 |
