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