49874f6ea3
Kernel changes: Inform hwpmc of executable objects brought into the system by kldload() and mmap(), and of their removal by kldunload() and munmap(). A helper function linker_hwpmc_list_objects() has been added to "sys/kern/kern_linker.c" and is used by hwpmc to retrieve the list of currently loaded kernel modules. The unused `MAPPINGCHANGE' event has been deprecated in favour of separate `MAP_IN' and `MAP_OUT' events; this change reduces space wastage in the log. Bump the hwpmc's ABI version to "2.0.00". Teach hwpmc(4) to handle the map change callbacks. Change the default per-cpu sample buffer size to hold 32 samples (up from 16). Increment __FreeBSD_version. libpmc(3) changes: Update libpmc(3) to deal with the new events in the log file; bring the pmclog(3) manual page in sync with the code. pmcstat(8) changes: Introduce new options to pmcstat(8): "-r" (root fs path), "-M" (mapfile name), "-q"/"-v" (verbosity control). Option "-k" now takes a kernel directory as its argument but will also work with the older invocation syntax. Rework string handling in pmcstat(8) to use an opaque type for interned strings. Clean up ELF parsing code and add support for tracking dynamic object mappings reported by a v2.0.00 hwpmc(4). Report statistics at the end of a log conversion run depending on the requested verbosity level. Reviewed by: jhb, dds (kernel parts of an earlier patch) Tested by: gallatin (earlier patch)
321 lines
8.6 KiB
Groff
321 lines
8.6 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 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 March 26, 2006
|
|
.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_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_pcsample pl_s;
|
|
struct pmclog_ev_pmcallocate pl_a;
|
|
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_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 .
|