mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-11-26 20:12:44 +00:00
318 lines
8.7 KiB
Groff
318 lines
8.7 KiB
Groff
.\" Copyright (c) 2005-2006 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 THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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.
|
|
.\"
|
|
.Dd March 26, 2006
|
|
.Dt PMCLOG 3
|
|
.Os
|
|
.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_callchain pl_cc;
|
|
struct pmclog_ev_closelog pl_cl;
|
|
struct pmclog_ev_dropnotify pl_d;
|
|
struct pmclog_ev_initialize pl_i;
|
|
struct pmclog_ev_map_in pl_mi;
|
|
struct pmclog_ev_map_out pl_mo;
|
|
struct pmclog_ev_pmcallocate pl_a;
|
|
struct pmclog_ev_pmcallocatedyn pl_ad;
|
|
struct pmclog_ev_pmcattach pl_t;
|
|
struct pmclog_ev_pmcdetach pl_d;
|
|
struct pmclog_ev_proccsw pl_c;
|
|
struct pmclog_ev_procexec pl_x;
|
|
struct pmclog_ev_procexit pl_e;
|
|
struct pmclog_ev_procfork pl_f;
|
|
struct pmclog_ev_sysexit pl_e;
|
|
struct pmclog_ev_userdata pl_u;
|
|
} 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_MAP_IN
|
|
A record describing the introduction of a mapping to an executable
|
|
object by a
|
|
.Xr kldload 2
|
|
or
|
|
.Xr mmap 2
|
|
system call.
|
|
.It Dv PMCLOG_TYPE_MAP_OUT
|
|
A record describing the removal of a mapping to an executable
|
|
object by a
|
|
.Xr kldunload 2
|
|
or
|
|
.Xr munmap 2
|
|
system call.
|
|
.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_CALLCHAIN:
|
|
--process a callchain 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 first appeared in
|
|
.Fx 6.0 .
|