303 lines
8.2 KiB
Groff
303 lines
8.2 KiB
Groff
.\" 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 June 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 ".Dv PMCLOG_REQUIRE_DATA"
|
|
.It Dv PMCLOG_EOF
|
|
(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 ".Dv PMCLOG_TYPE_PMCALLOCATE"
|
|
.It Dv PMCLOG_TYPE_CLOSELOG
|
|
A marker indicating a successful close of a log file.
|
|
This record will be the last record of a log file.
|
|
.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 the first record in a log file.
|
|
.It Dv PMCLOG_TYPE_MAPPINGCHANGE
|
|
A record describing an address space change for a process.
|
|
.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_PMCDETACH
|
|
A record describing a PMC detach operation.
|
|
.It Dv PMCLOG_TYPE_PROCCSW
|
|
A record describing a PMC reading at the time of a process context switch.
|
|
.It Dv PMCLOG_TYPE_PROCEXEC
|
|
A record describing an
|
|
.Xr execve 2
|
|
by a target process.
|
|
.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_PROCFORK
|
|
A record describing a
|
|
.Xr fork 2
|
|
by a target process.
|
|
.It Dv PMCLOG_TYPE_SYSEXIT
|
|
A record describing a process exit, sent to processes
|
|
owning system-wide sampling PMCs.
|
|
.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 data bytes available.
|
|
The memory range
|
|
.Bq Fa data , Fa data No + Fa 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
|
|
.No non- Ns Dv NULL
|
|
value if successful or
|
|
.Dv 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 pseudocode:
|
|
.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 ,
|
|
.Xr pmcstat 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm pmclog
|
|
API
|
|
.Ud
|
|
It first appeared in
|
|
.Fx 6.0 .
|