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 union { 81 uint64_t pl_tsc; /* TSC timestamp */ 82 struct timespec pl_ts; /* log entry timestamp (legacy) */ 83 }; 84 enum pmclog_type pl_type; /* log entry kind */ 85 union { /* log entry data */ 86 struct pmclog_ev_callchain pl_cc; 87 struct pmclog_ev_closelog pl_cl; 88 struct pmclog_ev_dropnotify pl_d; 89 struct pmclog_ev_initialize pl_i; 90 struct pmclog_ev_map_in pl_mi; 91 struct pmclog_ev_map_out pl_mo; 92 struct pmclog_ev_pmcallocate pl_a; 93 struct pmclog_ev_pmcallocatedyn pl_ad; 94 struct pmclog_ev_pmcattach pl_t; 95 struct pmclog_ev_pmcdetach pl_d; 96 struct pmclog_ev_proccsw pl_c; 97 struct pmclog_ev_procexec pl_x; 98 struct pmclog_ev_procexit pl_e; 99 struct pmclog_ev_procfork pl_f; 100 struct pmclog_ev_sysexit pl_e; 101 struct pmclog_ev_userdata pl_u; 102 } pl_u; 103}; 104.Ed 105.Pp 106The current state of the parser is recorded in 107.Va pl_state . 108This field can take on the following values: 109.Bl -tag -width ".Dv PMCLOG_REQUIRE_DATA" 110.It Dv PMCLOG_EOF 111(For file based parsers only) 112An end-of-file condition was encountered on the configured file 113descriptor. 114.It Dv PMCLOG_ERROR 115An error occurred during parsing. 116.It Dv PMCLOG_OK 117A complete event record was read into 118.Fa *ev . 119.It Dv PMCLOG_REQUIRE_DATA 120There was insufficient data in the event stream to assemble a complete 121event record. 122For memory based parsers, more data can be fed to the 123parser using function 124.Fn pmclog_feed . 125For file based parsers, function 126.Fn pmclog_read 127may be retried when data is available on the configured file 128descriptor. 129.El 130.Pp 131The rest of the event structure is valid only if field 132.Va pl_state 133contains 134.Dv PMCLOG_OK . 135Field 136.Va pl_offset 137contains the offset of the current record in the byte stream. 138Field 139.Va pl_count 140contains the serial number of this event. 141Field 142.Va pl_tsc 143carries the raw CPU Time Stamp Counter (TSC) value recorded at the time 144of the event. 145This is not a wall-clock time; to convert to nanoseconds divide the TSC 146delta between two events by the TSC frequency 147.Pq Va pl_u.pl_i.pl_tsc_freq 148reported in the 149.Dv PMCLOG_TYPE_INITIALIZE 150record. 151The legacy 152.Va pl_ts 153member aliases the same storage for ABI compatibility, but its contents 154no longer represent a wall-clock timestamp. 155.Pp 156Note that TSC-based timestamps and 157.Va pl_u.pl_i.pl_tsc_freq 158are only meaningful on x86 architectures 159.Pq amd64 and i386 . 160On all other architectures 161.Pq including arm64 and powerpc , 162.Va pl_tsc 163and 164.Va pl_u.pl_i.pl_tsc_freq 165are set to zero. 166Field 167.Va pl_type 168denotes the kind of the event returned in argument 169.Fa *ev 170and is one of the following: 171.Bl -tag -width ".Dv PMCLOG_TYPE_PMCALLOCATE" 172.It Dv PMCLOG_TYPE_CLOSELOG 173A marker indicating a successful close of a log file. 174This record will be the last record of a log file. 175.It Dv PMCLOG_TYPE_DROPNOTIFY 176A marker indicating that 177.Xr hwpmc 4 178had to drop data due to a resource constraint. 179.It Dv PMCLOG_TYPE_INITIALIZE 180An initialization record. 181This is the first record in a log file. 182.It Dv PMCLOG_TYPE_MAP_IN 183A record describing the introduction of a mapping to an executable 184object by a 185.Xr kldload 2 186or 187.Xr mmap 2 188system call. 189.It Dv PMCLOG_TYPE_MAP_OUT 190A record describing the removal of a mapping to an executable 191object by a 192.Xr kldunload 2 193or 194.Xr munmap 2 195system call. 196.It Dv PMCLOG_TYPE_PCSAMPLE 197A record containing an instruction pointer sample. 198.It Dv PMCLOG_TYPE_PMCALLOCATE 199A record describing a PMC allocation operation. 200.It Dv PMCLOG_TYPE_PMCATTACH 201A record describing a PMC attach operation. 202.It Dv PMCLOG_TYPE_PMCDETACH 203A record describing a PMC detach operation. 204.It Dv PMCLOG_TYPE_PROCCSW 205A record describing a PMC reading at the time of a process context switch. 206.It Dv PMCLOG_TYPE_PROCEXEC 207A record describing an 208.Xr execve 2 209by a target process. 210.It Dv PMCLOG_TYPE_PROCEXIT 211A record describing the accumulated PMC reading for a process at the 212time of 213.Xr _exit 2 . 214.It Dv PMCLOG_TYPE_PROCFORK 215A record describing a 216.Xr fork 2 217by a target process. 218.It Dv PMCLOG_TYPE_SYSEXIT 219A record describing a process exit, sent to processes 220owning system-wide sampling PMCs. 221.It Dv PMCLOG_TYPE_USERDATA 222A record containing user data. 223.El 224.Pp 225Function 226.Fn pmclog_feed 227is used with parsers configured to parse memory based event streams. 228It is intended to be called when function 229.Fn pmclog_read 230indicates the need for more data by a returning 231.Dv PMCLOG_REQUIRE_DATA 232in field 233.Va pl_state 234of its event structure argument. 235Argument 236.Fa data 237points to the start of a memory buffer containing fresh event data. 238Argument 239.Fa len 240indicates the number of data bytes available. 241The memory range 242.Bq Fa data , Fa data No + Fa len 243must remain valid till the next time 244.Fn pmclog_read 245returns an error. 246It is an error to use 247.Fn pmclog_feed 248on a parser configured to parse file data. 249.Pp 250Function 251.Fn pmclog_close 252releases the internal state allocated by a prior call 253to 254.Fn pmclog_open . 255.Sh RETURN VALUES 256Function 257.Fn pmclog_open 258will return a 259.No non- Ns Dv NULL 260value if successful or 261.Dv NULL 262otherwise. 263.Pp 264Function 265.Fn pmclog_read 266will return 0 in case a complete event record was successfully read, 267or will return \-1 and will set the 268.Va pl_state 269field of the event record to the appropriate code in case of an error. 270.Pp 271Function 272.Fn pmclog_feed 273will return 0 on success or \-1 in case of failure. 274.Sh EXAMPLES 275A template for using the log file parsing API is shown below in pseudocode: 276.Bd -literal 277void *parser; /* cookie */ 278struct pmclog_ev ev; /* parsed event */ 279int fd; /* file descriptor */ 280 281fd = open(filename, O_RDONLY); /* open log file */ 282parser = pmclog_open(fd); /* initialize parser */ 283if (parser == NULL) 284 --handle an out of memory error--; 285 286/* read and parse data */ 287while (pmclog_read(parser, &ev) == 0) { 288 assert(ev.pl_state == PMCLOG_OK); 289 /* process the event */ 290 switch (ev.pl_type) { 291 case PMCLOG_TYPE_ALLOCATE: 292 --process a pmc allocation record-- 293 break; 294 case PMCLOG_TYPE_PROCCSW: 295 --process a thread context switch record-- 296 break; 297 case PMCLOG_TYPE_CALLCHAIN: 298 --process a callchain sample-- 299 break; 300 --and so on-- 301 } 302} 303 304/* examine parser state */ 305switch (ev.pl_state) { 306case PMCLOG_EOF: 307 --normal termination-- 308 break; 309case PMCLOG_ERROR: 310 --look at errno here-- 311 break; 312case PMCLOG_REQUIRE_DATA: 313 --arrange for more data to be available for parsing-- 314 break; 315default: 316 assert(0); 317 /*NOTREACHED*/ 318} 319 320pmclog_close(parser); /* cleanup */ 321.Ed 322.Sh ERRORS 323A call to 324.Fn pmclog_init_parser 325may fail with any of the errors returned by 326.Xr malloc 3 . 327.Pp 328A call to 329.Fn pmclog_read 330for a file based parser may fail with any of the errors returned by 331.Xr read 2 . 332.Sh SEE ALSO 333.Xr read 2 , 334.Xr malloc 3 , 335.Xr pmc 3 , 336.Xr hwpmc 4 , 337.Xr pmcstat 8 338.Sh HISTORY 339The 340.Nm pmclog 341API first appeared in 342.Fx 6.0 . 343