diff options
Diffstat (limited to 'lib/libpmc/pmclog.3')
| -rw-r--r-- | lib/libpmc/pmclog.3 | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/lib/libpmc/pmclog.3 b/lib/libpmc/pmclog.3 new file mode 100644 index 0000000..1487e90 --- /dev/null +++ b/lib/libpmc/pmclog.3 @@ -0,0 +1,276 @@ +.\" Copyright (c) 2005 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $FreeBSD$ +.\" +.Dd Jun 1, 2005 +.Os +.Dt PMCLOG 3 +.Sh NAME +.Nm pmclog_open , +.Nm pmclog_close , +.Nm pmclog_read , +.Nm pmclog_feed +.Nd parse event log data generated by +.Xr hwpmc 4 +.Sh LIBRARY +.Lb libpmc +.Sh SYNOPSIS +.In pmclog.h +.Ft "void *" +.Fn pmclog_open "int fd" +.Ft void +.Fn pmclog_close "void *cookie" +.Ft int +.Fn pmclog_read "void *cookie" "struct pmclog_ev *ev" +.Ft int +.Fn pmclog_feed "void *cookie" "char *data" "int len" +.Sh DESCRIPTION +These functions provide a way for application programs to extract +events from an event stream generated by +.Xr hwpmc 4 . +.Pp +A new event log parser is allocated using +.Fn pmclog_open . +Argument +.Fa fd +may be a file descriptor opened for reading if the event stream is +present in a file, or the constant +.Dv PMCLOG_FD_NONE +for an event stream present in memory. +This function returns a cookie that is passed into the other functions +in this API set. +.Pp +Function +.Fn pmclog_read +returns the next available event in the event stream associated with +argument +.Fa cookie . +Argument +.Fa ev +points to an event descriptor that which will contain the result of a +successfully parsed event. +.Pp +An event descriptor returned by +.Fn pmclog_read +has the following structure: +.Bd -literal +struct pmclog_ev { + enum pmclog_state pl_state; /* parser state after 'get_event()' */ + off_t pl_offset; /* byte offset in stream */ + size_t pl_count; /* count of records so far */ + struct timespec pl_ts; /* log entry timestamp */ + enum pmclog_type pl_type; /* log entry kind */ + union { /* log entry data */ + struct pmclog_ev_allocate pl_a; + struct pmclog_ev_proccsw pl_c; + struct pmclog_ev_dropnotify pl_d; + struct pmclog_ev_procexit pl_e; + struct pmclog_ev_initialize pl_i; + struct pmclog_ev_pcsample pl_s; + struct pmclog_ev_pmcattach pl_t; + struct pmclog_ev_userdata pl_u; + struct pmclog_ev_procexec pl_x; + } pl_u; +}; +.Ed +.Pp +The current state of the parser is recorded in +.Va pl_state . +This field can take on the following values: +.Bl -tag -width "PMCLOG_REQUIRE_DATA" -compact +.It Dv PMCLOG_EOF +.Pq For file based parsers only +An end-of-file condition was encountered on the configured file +descriptor. +.It Dv PMCLOG_ERROR +An error occurred during parsing. +.It Dv PMCLOG_OK +A complete event record was read into +.Fa "*ev" . +.It Dv PMCLOG_REQUIRE_DATA +There was insufficient data in the event stream to assemble a complete +event record. +For memory based parsers, more data can be fed to the +parser using function +.Fn pmclog_feed . +For file based parsers, function +.Fn pmclog_read +may be retried when data is available on the configured file +descriptor. +.El +.Pp +The rest of the event structure is valid only if field +.Va pl_state +contains +.Dv PMCLOG_OK . +Field +.Va pl_offset +contains the offset of the current record in the byte stream. +Field +.Va pl_count +contains the serial number of this event. +Field +.Va pl_ts +contains a timestamp with the system time when the event occurred. +Field +.Va pl_type +denotes the kind of the event returned in argument +.Fa *ev +and is one of the following: +.Bl -tag -width XXXXXXXXXXXXXXXXXXXXXXX -compact +.It Dv PMCLOG_TYPE_DROPNOTIFY +a marker indicating that +.Xr hwpmc 4 +had to drop data due to a resource constraint. +.It Dv PMCLOG_TYPE_INITIALIZE +an initialization record. +This is usually the first record in a log file. +.It Dv PMCLOG_TYPE_PCSAMPLE +A record containing an instruction pointer sample. +.It Dv PMCLOG_TYPE_PMCALLOCATE +A record describing a PMC allocation operation. +.It Dv PMCLOG_TYPE_PMCATTACH +A record describing a PMC attach operation. +.It Dv PMCLOG_TYPE_PROCCSW +A record describing a PMC reading at the time of a process context switch. +.It Dv PMCLOG_TYPE_PROCEXIT +A record describing the accumulated PMC reading for a process at the +time of +.Xr _exit 2 . +.It Dv PMCLOG_TYPE_PROCEXEC +A record describing an +.Xr execve 2 +by a target process. +.It Dv PMCLOG_TYPE_USERDATA +A record containing user data. +.El +.Pp +Function +.Fn pmclog_feed +is used with parsers configured to parse memory based event streams. +It is intended to be called when function +.Fn pmclog_read +indicates the need for more data by a returning +.Dv PMCLOG_REQUIRE_DATA +in field +.Va pl_state +of its event structure argument. +Argument +.Fa data +points to the start of a memory buffer containing fresh event data. +Argument +.Fa len +indicates the number of bytes of data available. +The memory range +.Bq data , data+len +must remain valid till the next time +.Fn pmclog_read +returns an error. +It is an error to use +.Fn pmclog_feed +on a parser configured to parse file data. +.Pp +Function +.Fn pmclog_close +releases the internal state allocated by a prior call +to +.Fn pmclog_open . +.Sh RETURN VALUES +Function +.Fn pmclog_open +will return a non-NULL value if successful or NULL otherwise. +.Pp +Function +.Fn pmclog_read +will return 0 in case a complete event record was successfully read, +or will return -1 and will set the +.Va pl_state +field of the event record to the appropriate code in case of an error. +.Pp +Function +.Fn pmclog_feed +will return 0 on success or -1 in case of failure. +.Sh EXAMPLES +A template for using the log file parsing API is shown below in psuedocode: +.Bd -literal +void *parser; /* cookie */ +struct pmclog_ev ev; /* parsed event */ +int fd; /* file descriptor */ + +fd = open(filename, O_RDONLY); /* open log file */ +parser = pmclog_open(fd); /* initialize parser */ +if (parser == NULL) + --handle an out of memory error--; + +/* read and parse data */ +while (pmclog_read(parser, &ev) == 0) { + assert(ev.pl_state == PMCLOG_OK); + /* process the event */ + switch (ev.pl_type) { + case PMCLOG_TYPE_ALLOCATE: + --process a pmc allocation record-- + break; + case PMCLOG_TYPE_PROCCSW: + --process a thread context switch record-- + break; + case PMCLOG_TYPE_PCSAMPLE: + --process a PC sample-- + break; + --and so on-- + } +} + +/* examine parser state */ +switch (ev.pl_state) { +case PMCLOG_EOF: + --normal termination-- + break; +case PMCLOG_ERROR: + --look at errno here-- + break; +case PMCLOG_REQUIRE_DATA: + --arrange for more data to be available for parsing-- + break; +default: + assert(0); + /*NOTREACHED*/ +} + +pmclog_close(parser); /* cleanup */ +.Ed +.Sh ERRORS +A call to +.Fn pmclog_init_parser +may fail with any of the errors returned by +.Xr malloc 3 . +.Pp +A call to +.Fn pmclog_read +for a file based parser may fail with any of the errors returned by +.Xr read 2 . +.Sh SEE ALSO +.Xr read 2 , +.Xr malloc 3 , +.Xr pmc 3 , +.Xr hwpmc 4 |
