PAPI_encode_events(3)

1PAPI_encode_events(3)                PAPI                PAPI_encode_events(3)
2
3
4

NAME

6       PAPI_encode_events  - read event definitions from a file and modify the
7       existing PAPI preset table.
8
9

SYNOPSIS

11       C Interface
12       #include <papi.h>
13       int PAPI_encode_events(char * event_file, int replace);
14
15

DESCRIPTION

17       NOTE: This API has been deprecated in PAPI 3.5 pending a data structure
18       redesign.
19
20       This  function  reads  event  descriptions  from  a file where they are
21       stored in comma separated value format and modifies or adds  events  to
22       the  PAPI preset event table. The file format is described below.  This
23       function presently works only to define or modify PAPI preset events.
24
25

FILE FORMAT

27       The comma separated value file format is one that can be easily  edited
28       in  a  standard text editor or a csv-aware spreadsheet application, and
29       can be easily parsed. Text strings can contain commas, but only if  the
30       strings  are  enclosed  in quotes. Each entry in the file is a separate
31       line, and each field, including empty fields, is separated by  a  comma
32       from  its neighbor. The specific format used in this case consists of a
33       title line for readability, a blank line, and a series  of  lines  con‐
34       taining  event definitions. A portion of such a file (for Pentium 4) is
35       shown below:
36
37       name,derived,postfix,short_descr,long_descr,note,[native,...]
38
39       PAPI_L1_ICM,NOT_DERIVED,,"L1I cache misses","Level 1 instruction cache misses",,BPU_fetch_request_TCMISS
40       PAPI_L2_TCM,NOT_DERIVED,,"L2 cache misses","Level 2 cache misses",,BSQ_cache_reference_RD_2ndL_MISS_WR_2ndL_MISS
41       PAPI_TLB_DM,NOT_DERIVED,,"Data TLB misses","Data translation lookaside buffer misses",,page_walk_type_DTMISS
42       MY_PAPI_TLB_DM,NOT_DERIVED,,"Data TLB misses","Data translation lookaside buffer misses","This is a note for my event",page_walk_type_DTMISS
43
44
45

ARGUMENTS

47       event_file --  string containing the name of the csv event file  to  be
48       read
49
50       replace  --   1  to replace existing events, or 0 to prevent accidental
51       replacement
52
53

RETURN VALUES

55       On success, the function returns PAPI_OK.  On error, a  non-zero  error
56       code is returned by the function.
57
58

ERRORS

60       PAPI_EPERM
61              You  are  trying  to modify an existing event without specifying
62              replace.
63
64       PAPI_EISRUN
65              You are trying to modify an event that  has  been  added  to  an
66              EventSet.
67
68       PAPI_EINVAL
69              One  or more of the arguments or fields of the info structure is
70              invalid.
71
72       PAPI_ENOTPRESET
73              The PAPI preset table is full and there is no  room  for  a  new
74              event.
75
76       PAPI_ENOEVNT
77              The  event  specified  is not a PAPI preset. Usually because the
78              PAPI_PRESET_MASK bit is not set.
79
80

EXAMPLE

82       /* Use the command line utility to create a csv copy of the currently defined events */
83       > /papi/utils/decode -a -> current.csv
84       /* View and modify the events in an editor */
85       > vi current.csv
86       /* Load the modified events into the preset table */
87       if (PAPI_encode_events("./current.csv", 1) != PAPI_OK)
88         handle_error(1);
89
90

BUGS

92       This function has no known bugs.
93
94