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