PAPI 3 Event Description API

1. PAPI 3 Event Description API The following slides describe proposed changes to the API calls that describe events to the user. These changes are intended to provide a simplified common interface for describing both preset and native events.

2. Event Description API Old API int PAPI_describe_event(char *name, int *EventCode, char *description) int PAPI_query_event(int EventCode) int PAPI_query_event_verbose(int EventCode, PAPI_preset_info_t *info) const PAPI_preset_info_t *PAPI_query_all_events_verbose(void) int PAPI_label_event(int EventCode, char *label) int PAPI_event_code_to_name(int EventCode, char *out) int PAPI_event_name_to_code(char *in, int *out) New API int PAPI_query_event(int EventCode) int PAPI_get_event_info(PAPI_event_info_t *event_info) int PAPI_event_code_to_name(int EventCode, char *out) int PAPI_event_name_to_code(char *in, int * EventCode) int PAPI_enum_event(int EventCode, int modifier)

3. API Philosophy 101 • K.I.S.S. – keep it simple, stupid • Avoid ‘convenience’ APIs • Fewer APIs == • Less to document • Less code • Less to break • Symmetry • GETs imply SETs • If it works for case A, see if it can work for case B(e.g. presets and native) • Break any of these rules to make things simpler

4. New Event Description Goals • Operate symmetrically on preset and native event tables • Separate exposed user structure from internal data structures • Eliminate ‘query all’ functions to decouple from internal structures and allow calling code to manage memory • Add an ‘enum’ function to scan valid event table entries

5. PAPI 3 Event Description API /* Returns event existence status */int PAPI_query_event(int EventCode) /* Returns structure containing human-readable info for an EventCode */int PAPI_get_event_info(int EventCode, PAPI_event_info_t *event_info) /* Returns name of given event code */int PAPI_event_code_to_name(int EventCode, char *name) /* Returns event code for given name */int PAPI_event_name_to_code(char *name, int *EventCode) /* Updates EventCode to next valid value, or returns error; modifer can specify {all / available} for presets, or other values for native tables and may be platform specific (Major groups / all mask bits; P / M / E chip, etc) */int PAPI_enum_event(int *EventCode, int modifier)

6. PAPI 2 Event Description Structure(s) Hardware Independent Hardware Dependent (e.g. Linux) typedef struct pre_info { char *event_name; unsigned int event_code; char *event_descr; char *event_label; int avail; char *event_note; int flags; } PAPI_preset_info_t; typedef struct hwd_preset { unsigned char selector; unsigned char derived; unsigned char operand_index; struct perfctr_control counter_cmd; char note[PAPI_MAX_STR_LEN]; } hwd_preset_t; In PAPI 2, one structure defined the hardware independent parts of preset events, and another structure defined the hardwaredependent parts. There was no separate description of native events. This changes in PAPI 3.

7. PAPI 3 Event Description Structure(s) typedef struct preset_search { unsigned int preset; int derived; int natEvent[MAX_COUNTER_TERMS]; } preset_search_t; typedef struct hwi_preset { int derived; int metric_count; int natIndex[MAX_COUNTER_TERMS]; char operation[OPS]; char note[PAPI_MAX_STR_LEN]; } hwi_preset_t; typedef struct pre_info { char *event_name; unsigned int event_code; char *event_descr; char *event_label; int avail; char *event_note; int flags; } PAPI_preset_info_t; Currently, PAPI 3 has 3 hardware independent structures. The first is identical to PAPI 2. The second is a dense structure containing the preset events defined for a specific platform. The third is a sparse array the same size as the first into which the second array is copied at init time. The first and third structures can be merged.

8. PAPI 3 Event Description Structure(s) typedef struct preset_search { unsigned event_code; int derived; char operation[OPS]; int nativeEvent[MAX_COUNTER_TERMS]; char note[PAPI_MAX_STR_LEN]; } preset_search_t; typedef struct { char *symbol; char *short_descr; char *long_descr; unsigned event_code; int derived; char operation[OPS]; int nativeEvent[MAX_COUNTER_TERMS]; char event_note[PAPI_MAX_STR_LEN]; } PAPI_preset_event_info_t; Combining and rearranging produces the above structures. The first four fields are statically initialized in the hwi. The last four fields are dynamically initialized from static information in the hwd preset_search array. Event existence (avail) is signaled by a non-zero nativeEvent[0]. This captures the internal description of a PAPI preset event.

9. External Event Description Structure A pointer to a copy of this structure is passed to PAPI_get_event_info() after initializing the event_code field with the event of interest. Strings are constructed if necessary and copied into this structure. Memory management is handled by the caller. typedef struct { unsigned event_code; int avail; unsigned derived; char symbol[PAPI_MIN_STR_LEN]; char short_descr[PAPI_MIN_STR_LEN]; char long_descr [PAPI_MAX_STR_LEN]; char vendor_symbol[PAPI_MAX_STR_LEN]; char vendor_descr[PAPI_HUGE_STR_LEN]; char event_note[PAPI_MAX_STR_LEN]; } PAPI_event_info_t; Preset events may fill in all fields as appropriate, while native events will only fill in the ‘vendor’ and ‘avail’ fields.

10. PAPI 2 Native Event Support • Native events supported through a 32-bit binary code • Easy to implement • Flexible and powerful • Clumsy for end user • Newer architectures restricted by 32-bit limit

11. PAPI 3 Native Event Support • Substrates contain internal native event table. • Similar to old preset table info • Vendor names & descriptions • Counter mappings for register allocation • Preset handling becomes hardware independent by referencing the native table • Self-documenting • Accommodates arbitrary event structure info • May not contain all possible variations

12. PAPI 3 Event Editing • Provide a mechanism to edit preset and native event tables. • First implementation may be binary only • {get,set}_name, descr, hwd_register_t • Provides low level hooks to modify tables • Tools could be built to translate binary into an ASCII internal representation • Could be used as part of a ‘config file’ mechanism • Later tools could support XML

13. PAPI_{en,de}code_event() int PAPI_encode_event(char *, int *eventCode) int PAPI_decode_event(int eventCode, char *) • Symmetric across encode/decode • Symmetric across PRESET/Native • Lets users: • explore preset definitions • (re)define presets • define new/custom native events • export preset / native events for: • Documentation • Later import via config file or custom program • Experiment with new or alternative events

14. PAPI_{en,de}code_event() int PAPI_encode_event(char *, int *eventCode) int PAPI_decode_event(int eventCode, char *) • Specification string could be: • Custom format (varargs or delimited text) • Simple(r) & quicker implementation • XML tag format • Well understood standard • Rich & expressive • Potentially useful elsewhere in PAPI • Language neutral • Possibly big and slow • Longer implementation