1PMGENMAP(1) General Commands Manual PMGENMAP(1)
2
6 pmgenmap - generate C code to simplify handling of performance metrics
7
9 pmgenmap [infile]
10
12 Given one or more lists of metric names in infile or on standard input,
13 pmgenmap generates C declarations and cpp(1) macros suitable for use
14 across the Performance Metrics Programming Interface (PMAPI) on stan‐
15 dard output.
16 The declarations produced by pmgenmap simplify the coding for client
18 applications using the PMAPI.
19 The input should consist of one or more lists of metric names of the
21 form
22 listname {
24 metricname1 symbolname1
25 metricname2 symbolname2
26 ...
27 }
28 which will generate C and cpp(1) declarations of the form
30 char *listname[] = {
32 #define symbolname1 0
33 "metricname1",
34 #define symbolname2 1
35 "metricname2",
36 ...
37 };
38 The array declarations produced are suitable as parameters to pmLookup‐
40 Name(3) and the #defined constants may be used to index the vsets in
41 the pmResult structure returned by a pmFetch(3) call.
42 Obviously, listname must conform to the C identifier naming rules, each
44 symbolname must conform to the cpp(1) macro naming rules, and each met‐
45 ricname is expected to be a valid performance metrics name (see PMNS(5)
46 for more details).
47 The input may include sh-style comment lines, i.e. with a `#' as the
49 first non-blank character of a line, and these are translated on output
50 to either single line or multi-line C comments in the K&R style. For
51 example, the input:
52 # leading block of multi-line comments
55 # initialization group
56 foo {
57 a.b.c ONE
58 d.e.f.g TWO
59 # embedded block of multi-lines
60 # comments and boring pad text
61 xx.yy.zz THREE
62 }
63 # trailing single line comment
65 Produces the output:
67 /*
69 * leading block of multi-line comments
70 * initialization group
71 */
72 char *foo[] = {
73 #define ONE 0
74 "a.b.c",
75 #define TWO 1
76 "d.e.f.g",
77 /*
78 * embedded block of multi-lines
79 * comments and boring pad text
80 */
81 #define THREE 2
82 "xx.yy.zz",
83 };
85 /* trailing single line comment */
88
90 For brevity we have removed the error handling code, and assumed the
91 chosen metrics do not have multiple values.
92 The input file
94 mystats {
96 kernel.percpu.cpu.idle IDLE
97 kernel.percpu.cpu.sys SYS
98 kernel.percpu.cpu.user USER
99 hinv.ncpu NCPU
100 }
101 produces the following C code, suitable for #include-ing
103 /*
105 * Performance Metrics Name Space Map
106 * Built by pmgenmap from the file
107 * mystats.metrics
108 * on Wed Dec 28 19:44:17 EST 1994
109 *
110 * Do not edit this file!
111 */
112 char *mystats[] = {
114 #define IDLE 0
115 "kernel.percpu.cpu.idle",
116 #define SYS 1
117 "kernel.percpu.cpu.sys",
118 #define USER 2
119 "kernel.percpu.cpu.user",
120 #define NCPU 3
121 "hinv.ncpu",
122 };
124 Using the code generated by pmgenmap, we are now able to easily obtain
126 metrics from the Performance Metrics Collection Subsystem (PMCS) as
127 follows:
128 #define MAX_PMID 4
131 int trip = 0;
133 int numpmid = sizeof(mystats)/sizeof(mystats[0]);
134 double duration;
135 pmResult *resp;
136 pmResult *prev;
137 pmID pmidlist[MAX_PMID];
138 pmNewContext(PM_CONTEXT_HOST, "localhost");
140 pmLookupName(numpmid, mystats, pmidlist);
141 pmFetch(numpmid, pmidlist, &resp);
142 printf("%d CPUs: %d usr %d sys %d idle0,
144 resp->vset[NCPU]->vlist[0].value.lval,
145 resp->vset[USER]->vlist[0].value.lval,
146 resp->vset[SYS]->vlist[0].value.lval,
147 resp->vset[IDLE]->vlist[0].value.lval);
148 Some calls to ensure portability have been removed from the code above
150 for the sake of clarity - the example above should not be used as a
151 template for programming. In particular, the raw values of the metrics
152 were used when pmLookupDesc(3) should have been called to determine the
153 semantics of each metric.
154 More complete examples that demonstrate the use of pmgenmap which may
156 be used as a basis for program development are included in the PCP
157 demos, e.g. $PCP_DEMOS_DIR/pmclient.
158
160 $PCP_VAR_DIR/pmns/*
161 default PMNS specification files
162
164 Environment variables with the prefix PCP_ are used to parameterize the
165 file and directory names used by PCP. On each installation, the file
166 /etc/pcp.conf contains the local values for these variables. The
167 $PCP_CONF variable may be used to specify an alternative configuration
168 file, as described in pcp.conf(5).
169
171 cpp(1), PMAPI(3), pmFetch(3), pmLookupName(3), pmNewContext(3),
172 pcp.conf(5), pcp.env(5) and PMNS(5).
173Performance Co-Pilot PCP PMGENMAP(1)