summaryrefslogtreecommitdiffstats
path: root/lib/libpmc/pmclog.3
blob: dcce57a4c1adfb6a75266470ad22462a04544b33 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
.\" Copyright (c) 2005 Joseph Koshy.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed.  in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $FreeBSD$
.\"
.Dd June 1, 2005
.Os
.Dt PMCLOG 3
.Sh NAME
.Nm pmclog_open ,
.Nm pmclog_close ,
.Nm pmclog_read ,
.Nm pmclog_feed
.Nd parse event log data generated by
.Xr hwpmc 4
.Sh LIBRARY
.Lb libpmc
.Sh SYNOPSIS
.In pmclog.h
.Ft "void *"
.Fn pmclog_open "int fd"
.Ft void
.Fn pmclog_close "void *cookie"
.Ft int
.Fn pmclog_read "void *cookie" "struct pmclog_ev *ev"
.Ft int
.Fn pmclog_feed "void *cookie" "char *data" "int len"
.Sh DESCRIPTION
These functions provide a way for application programs to extract
events from an event stream generated by
.Xr hwpmc 4 .
.Pp
A new event log parser is allocated using
.Fn pmclog_open .
Argument
.Fa fd
may be a file descriptor opened for reading if the event stream is
present in a file, or the constant
.Dv PMCLOG_FD_NONE
for an event stream present in memory.
This function returns a cookie that is passed into the other functions
in this API set.
.Pp
Function
.Fn pmclog_read
returns the next available event in the event stream associated with
argument
.Fa cookie .
Argument
.Fa ev
points to an event descriptor that which will contain the result of a
successfully parsed event.
.Pp
An event descriptor returned by
.Fn pmclog_read
has the following structure:
.Bd -literal
struct pmclog_ev {
       enum pmclog_state pl_state;	/* parser state after 'get_event()' */
       off_t             pl_offset;	/* byte offset in stream */
       size_t            pl_count;	/* count of records so far */
       struct timespec   pl_ts;		/* log entry timestamp */
       enum pmclog_type  pl_type;	/* log entry kind */
       union {				/* log entry data */
		struct pmclog_ev_allocate   pl_a;
		struct pmclog_ev_proccsw    pl_c;
		struct pmclog_ev_dropnotify pl_d;
		struct pmclog_ev_procexit   pl_e;
		struct pmclog_ev_initialize pl_i;
		struct pmclog_ev_pcsample   pl_s;
		struct pmclog_ev_pmcattach  pl_t;
		struct pmclog_ev_userdata   pl_u;
		struct pmclog_ev_procexec   pl_x;
       } pl_u;
};
.Ed
.Pp
The current state of the parser is recorded in
.Va pl_state .
This field can take on the following values:
.Bl -tag -width ".Dv PMCLOG_REQUIRE_DATA"
.It Dv PMCLOG_EOF
(For file based parsers only)
An end-of-file condition was encountered on the configured file
descriptor.
.It Dv PMCLOG_ERROR
An error occurred during parsing.
.It Dv PMCLOG_OK
A complete event record was read into
.Fa *ev .
.It Dv PMCLOG_REQUIRE_DATA
There was insufficient data in the event stream to assemble a complete
event record.
For memory based parsers, more data can be fed to the
parser using function
.Fn pmclog_feed .
For file based parsers, function
.Fn pmclog_read
may be retried when data is available on the configured file
descriptor.
.El
.Pp
The rest of the event structure is valid only if field
.Va pl_state
contains
.Dv PMCLOG_OK .
Field
.Va pl_offset
contains the offset of the current record in the byte stream.
Field
.Va pl_count
contains the serial number of this event.
Field
.Va pl_ts
contains a timestamp with the system time when the event occurred.
Field
.Va pl_type
denotes the kind of the event returned in argument
.Fa *ev
and is one of the following:
.Bl -tag -width ".Dv PMCLOG_TYPE_PMCALLOCATE"
.It Dv PMCLOG_TYPE_DROPNOTIFY
a marker indicating that
.Xr hwpmc 4
had to drop data due to a resource constraint.
.It Dv PMCLOG_TYPE_INITIALIZE
an initialization record.
This is usually the first record in a log file.
.It Dv PMCLOG_TYPE_PCSAMPLE
A record containing an instruction pointer sample.
.It Dv PMCLOG_TYPE_PMCALLOCATE
A record describing a PMC allocation operation.
.It Dv PMCLOG_TYPE_PMCATTACH
A record describing a PMC attach operation.
.It Dv PMCLOG_TYPE_PROCCSW
A record describing a PMC reading at the time of a process context switch.
.It Dv PMCLOG_TYPE_PROCEXIT
A record describing the accumulated PMC reading for a process at the
time of
.Xr _exit 2 .
.It Dv PMCLOG_TYPE_PROCEXEC
A record describing an
.Xr execve 2
by a target process.
.It Dv PMCLOG_TYPE_USERDATA
A record containing user data.
.El
.Pp
Function
.Fn pmclog_feed
is used with parsers configured to parse memory based event streams.
It is intended to be called when function
.Fn pmclog_read
indicates the need for more data by a returning
.Dv PMCLOG_REQUIRE_DATA
in field
.Va pl_state
of its event structure argument.
Argument
.Fa data
points to the start of a memory buffer containing fresh event data.
Argument
.Fa len
indicates the number of data bytes available.
The memory range
.Bq Fa data , Fa data No + Fa len
must remain valid till the next time
.Fn pmclog_read
returns an error.
It is an error to use
.Fn pmclog_feed
on a parser configured to parse file data.
.Pp
Function
.Fn pmclog_close
releases the internal state allocated by a prior call
to
.Fn pmclog_open .
.Sh RETURN VALUES
Function
.Fn pmclog_open
will return a
.No non- Ns Dv NULL
value if successful or
.Dv NULL
otherwise.
.Pp
Function
.Fn pmclog_read
will return 0 in case a complete event record was successfully read,
or will return \-1 and will set the
.Va pl_state
field of the event record to the appropriate code in case of an error.
.Pp
Function
.Fn pmclog_feed
will return 0 on success or \-1 in case of failure.
.Sh EXAMPLES
A template for using the log file parsing API is shown below in pseudocode:
.Bd -literal
void *parser;			/* cookie */
struct pmclog_ev ev;		/* parsed event */
int fd;				/* file descriptor */

fd = open(filename, O_RDONLY);	/* open log file */
parser = pmclog_open(fd);	/* initialize parser */
if (parser == NULL)
	--handle an out of memory error--;

/* read and parse data */
while (pmclog_read(parser, &ev) == 0) {
	assert(ev.pl_state == PMCLOG_OK);
	/* process the event */
	switch (ev.pl_type) {
	case PMCLOG_TYPE_ALLOCATE:
		--process a pmc allocation record--
		break;
	case PMCLOG_TYPE_PROCCSW:
		--process a thread context switch record--
		break;
	case PMCLOG_TYPE_PCSAMPLE:
		--process a PC sample--
		break;
	--and so on--
	}
}

/* examine parser state */
switch (ev.pl_state) {
case PMCLOG_EOF:
	--normal termination--
	break;
case PMCLOG_ERROR:
	--look at errno here--
	break;
case PMCLOG_REQUIRE_DATA:
	--arrange for more data to be available for parsing--
	break;
default:
	assert(0);
	/*NOTREACHED*/
}

pmclog_close(parser);		/* cleanup */
.Ed
.Sh ERRORS
A call to
.Fn pmclog_init_parser
may fail with any of the errors returned by
.Xr malloc 3 .
.Pp
A call to
.Fn pmclog_read
for a file based parser may fail with any of the errors returned by
.Xr read 2 .
.Sh SEE ALSO
.Xr read 2 ,
.Xr malloc 3 ,
.Xr pmc 3 ,
.Xr hwpmc 4 ,
.Xr pmcstat 8
OpenPOWER on IntegriCloud