xref: /freebsd/lib/libpmc/pmclog.3 (revision f7c32ed617858bcd22f8d1b03199099d50125721)
1.\" Copyright (c) 2005-2006 Joseph Koshy.  All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd March 26, 2006
27.Dt PMCLOG 3
28.Os
29.Sh NAME
30.Nm pmclog_open ,
31.Nm pmclog_close ,
32.Nm pmclog_read ,
33.Nm pmclog_feed
34.Nd parse event log data generated by
35.Xr hwpmc 4
36.Sh LIBRARY
37.Lb libpmc
38.Sh SYNOPSIS
39.In pmclog.h
40.Ft "void *"
41.Fn pmclog_open "int fd"
42.Ft void
43.Fn pmclog_close "void *cookie"
44.Ft int
45.Fn pmclog_read "void *cookie" "struct pmclog_ev *ev"
46.Ft int
47.Fn pmclog_feed "void *cookie" "char *data" "int len"
48.Sh DESCRIPTION
49These functions provide a way for application programs to extract
50events from an event stream generated by
51.Xr hwpmc 4 .
52.Pp
53A new event log parser is allocated using
54.Fn pmclog_open .
55Argument
56.Fa fd
57may be a file descriptor opened for reading if the event stream is
58present in a file, or the constant
59.Dv PMCLOG_FD_NONE
60for an event stream present in memory.
61This function returns a cookie that is passed into the other functions
62in this API set.
63.Pp
64Function
65.Fn pmclog_read
66returns the next available event in the event stream associated with
67argument
68.Fa cookie .
69Argument
70.Fa ev
71points to an event descriptor that which will contain the result of a
72successfully parsed event.
73.Pp
74An event descriptor returned by
75.Fn pmclog_read
76has the following structure:
77.Bd -literal
78struct pmclog_ev {
79       enum pmclog_state pl_state;	/* parser state after 'get_event()' */
80       off_t             pl_offset;	/* byte offset in stream */
81       size_t            pl_count;	/* count of records so far */
82       struct timespec   pl_ts;		/* log entry timestamp */
83       enum pmclog_type  pl_type;	/* log entry kind */
84       union {				/* log entry data */
85		struct pmclog_ev_callchain   pl_cc;
86		struct pmclog_ev_closelog    pl_cl;
87		struct pmclog_ev_dropnotify  pl_d;
88		struct pmclog_ev_initialize  pl_i;
89		struct pmclog_ev_map_in      pl_mi;
90		struct pmclog_ev_map_out     pl_mo;
91		struct pmclog_ev_pmcallocate pl_a;
92		struct pmclog_ev_pmcallocatedyn	pl_ad;
93		struct pmclog_ev_pmcattach   pl_t;
94		struct pmclog_ev_pmcdetach   pl_d;
95		struct pmclog_ev_proccsw     pl_c;
96		struct pmclog_ev_procexec    pl_x;
97		struct pmclog_ev_procexit    pl_e;
98		struct pmclog_ev_procfork    pl_f;
99		struct pmclog_ev_sysexit     pl_e;
100		struct pmclog_ev_userdata    pl_u;
101       } pl_u;
102};
103.Ed
104.Pp
105The current state of the parser is recorded in
106.Va pl_state .
107This field can take on the following values:
108.Bl -tag -width ".Dv PMCLOG_REQUIRE_DATA"
109.It Dv PMCLOG_EOF
110(For file based parsers only)
111An end-of-file condition was encountered on the configured file
112descriptor.
113.It Dv PMCLOG_ERROR
114An error occurred during parsing.
115.It Dv PMCLOG_OK
116A complete event record was read into
117.Fa *ev .
118.It Dv PMCLOG_REQUIRE_DATA
119There was insufficient data in the event stream to assemble a complete
120event record.
121For memory based parsers, more data can be fed to the
122parser using function
123.Fn pmclog_feed .
124For file based parsers, function
125.Fn pmclog_read
126may be retried when data is available on the configured file
127descriptor.
128.El
129.Pp
130The rest of the event structure is valid only if field
131.Va pl_state
132contains
133.Dv PMCLOG_OK .
134Field
135.Va pl_offset
136contains the offset of the current record in the byte stream.
137Field
138.Va pl_count
139contains the serial number of this event.
140Field
141.Va pl_ts
142contains a timestamp with the system time when the event occurred.
143Field
144.Va pl_type
145denotes the kind of the event returned in argument
146.Fa *ev
147and is one of the following:
148.Bl -tag -width ".Dv PMCLOG_TYPE_PMCALLOCATE"
149.It Dv PMCLOG_TYPE_CLOSELOG
150A marker indicating a successful close of a log file.
151This record will be the last record of a log file.
152.It Dv PMCLOG_TYPE_DROPNOTIFY
153A marker indicating that
154.Xr hwpmc 4
155had to drop data due to a resource constraint.
156.It Dv PMCLOG_TYPE_INITIALIZE
157An initialization record.
158This is the first record in a log file.
159.It Dv PMCLOG_TYPE_MAP_IN
160A record describing the introduction of a mapping to an executable
161object by a
162.Xr kldload 2
163or
164.Xr mmap 2
165system call.
166.It Dv PMCLOG_TYPE_MAP_OUT
167A record describing the removal of a mapping to an executable
168object by a
169.Xr kldunload 2
170or
171.Xr munmap 2
172system call.
173.It Dv PMCLOG_TYPE_PCSAMPLE
174A record containing an instruction pointer sample.
175.It Dv PMCLOG_TYPE_PMCALLOCATE
176A record describing a PMC allocation operation.
177.It Dv PMCLOG_TYPE_PMCATTACH
178A record describing a PMC attach operation.
179.It Dv PMCLOG_TYPE_PMCDETACH
180A record describing a PMC detach operation.
181.It Dv PMCLOG_TYPE_PROCCSW
182A record describing a PMC reading at the time of a process context switch.
183.It Dv PMCLOG_TYPE_PROCEXEC
184A record describing an
185.Xr execve 2
186by a target process.
187.It Dv PMCLOG_TYPE_PROCEXIT
188A record describing the accumulated PMC reading for a process at the
189time of
190.Xr _exit 2 .
191.It Dv PMCLOG_TYPE_PROCFORK
192A record describing a
193.Xr fork 2
194by a target process.
195.It Dv PMCLOG_TYPE_SYSEXIT
196A record describing a process exit, sent to processes
197owning system-wide sampling PMCs.
198.It Dv PMCLOG_TYPE_USERDATA
199A record containing user data.
200.El
201.Pp
202Function
203.Fn pmclog_feed
204is used with parsers configured to parse memory based event streams.
205It is intended to be called when function
206.Fn pmclog_read
207indicates the need for more data by a returning
208.Dv PMCLOG_REQUIRE_DATA
209in field
210.Va pl_state
211of its event structure argument.
212Argument
213.Fa data
214points to the start of a memory buffer containing fresh event data.
215Argument
216.Fa len
217indicates the number of data bytes available.
218The memory range
219.Bq Fa data , Fa data No + Fa len
220must remain valid till the next time
221.Fn pmclog_read
222returns an error.
223It is an error to use
224.Fn pmclog_feed
225on a parser configured to parse file data.
226.Pp
227Function
228.Fn pmclog_close
229releases the internal state allocated by a prior call
230to
231.Fn pmclog_open .
232.Sh RETURN VALUES
233Function
234.Fn pmclog_open
235will return a
236.No non- Ns Dv NULL
237value if successful or
238.Dv NULL
239otherwise.
240.Pp
241Function
242.Fn pmclog_read
243will return 0 in case a complete event record was successfully read,
244or will return \-1 and will set the
245.Va pl_state
246field of the event record to the appropriate code in case of an error.
247.Pp
248Function
249.Fn pmclog_feed
250will return 0 on success or \-1 in case of failure.
251.Sh EXAMPLES
252A template for using the log file parsing API is shown below in pseudocode:
253.Bd -literal
254void *parser;			/* cookie */
255struct pmclog_ev ev;		/* parsed event */
256int fd;				/* file descriptor */
257
258fd = open(filename, O_RDONLY);	/* open log file */
259parser = pmclog_open(fd);	/* initialize parser */
260if (parser == NULL)
261	--handle an out of memory error--;
262
263/* read and parse data */
264while (pmclog_read(parser, &ev) == 0) {
265	assert(ev.pl_state == PMCLOG_OK);
266	/* process the event */
267	switch (ev.pl_type) {
268	case PMCLOG_TYPE_ALLOCATE:
269		--process a pmc allocation record--
270		break;
271	case PMCLOG_TYPE_PROCCSW:
272		--process a thread context switch record--
273		break;
274	case PMCLOG_TYPE_CALLCHAIN:
275		--process a callchain sample--
276		break;
277	--and so on--
278	}
279}
280
281/* examine parser state */
282switch (ev.pl_state) {
283case PMCLOG_EOF:
284	--normal termination--
285	break;
286case PMCLOG_ERROR:
287	--look at errno here--
288	break;
289case PMCLOG_REQUIRE_DATA:
290	--arrange for more data to be available for parsing--
291	break;
292default:
293	assert(0);
294	/*NOTREACHED*/
295}
296
297pmclog_close(parser);		/* cleanup */
298.Ed
299.Sh ERRORS
300A call to
301.Fn pmclog_init_parser
302may fail with any of the errors returned by
303.Xr malloc 3 .
304.Pp
305A call to
306.Fn pmclog_read
307for a file based parser may fail with any of the errors returned by
308.Xr read 2 .
309.Sh SEE ALSO
310.Xr read 2 ,
311.Xr malloc 3 ,
312.Xr pmc 3 ,
313.Xr hwpmc 4 ,
314.Xr pmcstat 8
315.Sh HISTORY
316The
317.Nm pmclog
318API
319.Ud
320It first appeared in
321.Fx 6.0 .
322