1PAPI_encode_events(3) PAPI PAPI_encode_events(3)
2
3
4
6 PAPI_encode_events - read event definitions from a file and modify the
7 existing PAPI preset table.
8
9
11 C Interface
12 #include <papi.h>
13 int PAPI_encode_events(char * event_file, int replace);
14
15
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
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
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
55 On success, the function returns PAPI_OK. On error, a non-zero error
56 code is returned by the function.
57
58
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
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
92 This function has no known bugs.
93
94
96 papi_decode(1), PAPI(3), PAPIF(3), PAPI_get_event_info(3),
97 PAPI_set_event_info(3)
98
99
100
101PAPI Programmer's Reference October, 2006 PAPI_encode_events(3)