1.\" Copyright (c) 2005 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 Joseph Koshy ``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 Joseph Koshy 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 June 1, 2005 27.Os 28.Dt PMCLOG 3 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_allocate pl_a; 86 struct pmclog_ev_proccsw pl_c; 87 struct pmclog_ev_dropnotify pl_d; 88 struct pmclog_ev_procexit pl_e; 89 struct pmclog_ev_initialize pl_i; 90 struct pmclog_ev_pcsample pl_s; 91 struct pmclog_ev_pmcattach pl_t; 92 struct pmclog_ev_userdata pl_u; 93 struct pmclog_ev_procexec pl_x; 94 } pl_u; 95}; 96.Ed 97.Pp 98The current state of the parser is recorded in 99.Va pl_state . 100This field can take on the following values: 101.Bl -tag -width ".Dv PMCLOG_REQUIRE_DATA" 102.It Dv PMCLOG_EOF 103(For file based parsers only) 104An end-of-file condition was encountered on the configured file 105descriptor. 106.It Dv PMCLOG_ERROR 107An error occurred during parsing. 108.It Dv PMCLOG_OK 109A complete event record was read into 110.Fa *ev . 111.It Dv PMCLOG_REQUIRE_DATA 112There was insufficient data in the event stream to assemble a complete 113event record. 114For memory based parsers, more data can be fed to the 115parser using function 116.Fn pmclog_feed . 117For file based parsers, function 118.Fn pmclog_read 119may be retried when data is available on the configured file 120descriptor. 121.El 122.Pp 123The rest of the event structure is valid only if field 124.Va pl_state 125contains 126.Dv PMCLOG_OK . 127Field 128.Va pl_offset 129contains the offset of the current record in the byte stream. 130Field 131.Va pl_count 132contains the serial number of this event. 133Field 134.Va pl_ts 135contains a timestamp with the system time when the event occurred. 136Field 137.Va pl_type 138denotes the kind of the event returned in argument 139.Fa *ev 140and is one of the following: 141.Bl -tag -width ".Dv PMCLOG_TYPE_PMCALLOCATE" 142.It Dv PMCLOG_TYPE_CLOSELOG 143A marker indicating a successful close of a log file. 144This record will be the last record of a log file. 145.It Dv PMCLOG_TYPE_DROPNOTIFY 146A marker indicating that 147.Xr hwpmc 4 148had to drop data due to a resource constraint. 149.It Dv PMCLOG_TYPE_INITIALIZE 150An initialization record. 151This is the first record in a log file. 152.It Dv PMCLOG_TYPE_MAPPINGCHANGE 153A record describing an address space change for a process. 154.It Dv PMCLOG_TYPE_PCSAMPLE 155A record containing an instruction pointer sample. 156.It Dv PMCLOG_TYPE_PMCALLOCATE 157A record describing a PMC allocation operation. 158.It Dv PMCLOG_TYPE_PMCATTACH 159A record describing a PMC attach operation. 160.It Dv PMCLOG_TYPE_PMCDETACH 161A record describing a PMC detach operation. 162.It Dv PMCLOG_TYPE_PROCCSW 163A record describing a PMC reading at the time of a process context switch. 164.It Dv PMCLOG_TYPE_PROCEXEC 165A record describing an 166.Xr execve 2 167by a target process. 168.It Dv PMCLOG_TYPE_PROCEXIT 169A record describing the accumulated PMC reading for a process at the 170time of 171.Xr _exit 2 . 172.It Dv PMCLOG_TYPE_PROCFORK 173A record describing a 174.Xr fork 2 175by a target process. 176.It Dv PMCLOG_TYPE_SYSEXIT 177A record describing a process exit, sent to processes 178owning system-wide sampling PMCs. 179.It Dv PMCLOG_TYPE_USERDATA 180A record containing user data. 181.El 182.Pp 183Function 184.Fn pmclog_feed 185is used with parsers configured to parse memory based event streams. 186It is intended to be called when function 187.Fn pmclog_read 188indicates the need for more data by a returning 189.Dv PMCLOG_REQUIRE_DATA 190in field 191.Va pl_state 192of its event structure argument. 193Argument 194.Fa data 195points to the start of a memory buffer containing fresh event data. 196Argument 197.Fa len 198indicates the number of data bytes available. 199The memory range 200.Bq Fa data , Fa data No + Fa len 201must remain valid till the next time 202.Fn pmclog_read 203returns an error. 204It is an error to use 205.Fn pmclog_feed 206on a parser configured to parse file data. 207.Pp 208Function 209.Fn pmclog_close 210releases the internal state allocated by a prior call 211to 212.Fn pmclog_open . 213.Sh RETURN VALUES 214Function 215.Fn pmclog_open 216will return a 217.No non- Ns Dv NULL 218value if successful or 219.Dv NULL 220otherwise. 221.Pp 222Function 223.Fn pmclog_read 224will return 0 in case a complete event record was successfully read, 225or will return \-1 and will set the 226.Va pl_state 227field of the event record to the appropriate code in case of an error. 228.Pp 229Function 230.Fn pmclog_feed 231will return 0 on success or \-1 in case of failure. 232.Sh EXAMPLES 233A template for using the log file parsing API is shown below in pseudocode: 234.Bd -literal 235void *parser; /* cookie */ 236struct pmclog_ev ev; /* parsed event */ 237int fd; /* file descriptor */ 238 239fd = open(filename, O_RDONLY); /* open log file */ 240parser = pmclog_open(fd); /* initialize parser */ 241if (parser == NULL) 242 --handle an out of memory error--; 243 244/* read and parse data */ 245while (pmclog_read(parser, &ev) == 0) { 246 assert(ev.pl_state == PMCLOG_OK); 247 /* process the event */ 248 switch (ev.pl_type) { 249 case PMCLOG_TYPE_ALLOCATE: 250 --process a pmc allocation record-- 251 break; 252 case PMCLOG_TYPE_PROCCSW: 253 --process a thread context switch record-- 254 break; 255 case PMCLOG_TYPE_PCSAMPLE: 256 --process a PC sample-- 257 break; 258 --and so on-- 259 } 260} 261 262/* examine parser state */ 263switch (ev.pl_state) { 264case PMCLOG_EOF: 265 --normal termination-- 266 break; 267case PMCLOG_ERROR: 268 --look at errno here-- 269 break; 270case PMCLOG_REQUIRE_DATA: 271 --arrange for more data to be available for parsing-- 272 break; 273default: 274 assert(0); 275 /*NOTREACHED*/ 276} 277 278pmclog_close(parser); /* cleanup */ 279.Ed 280.Sh ERRORS 281A call to 282.Fn pmclog_init_parser 283may fail with any of the errors returned by 284.Xr malloc 3 . 285.Pp 286A call to 287.Fn pmclog_read 288for a file based parser may fail with any of the errors returned by 289.Xr read 2 . 290.Sh SEE ALSO 291.Xr read 2 , 292.Xr malloc 3 , 293.Xr pmc 3 , 294.Xr hwpmc 4 , 295.Xr pmcstat 8 296.Sh HISTORY 297The 298.Nm pmclog 299API 300.Ud 301It first appeared in 302.Fx 6.0 . 303