275 lines
8.5 KiB
Groff
275 lines
8.5 KiB
Groff
.\" $NetBSD: pmc.9,v 1.8 2006/01/29 02:40:40 rpaulo Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002, 2005 Wasabi Systems, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Written by Allen Briggs for Wasabi Systems, Inc.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the NetBSD Project by
|
|
.\" Wasabi Systems, Inc.
|
|
.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
|
|
.\" or promote products derived from this software without specific prior
|
|
.\" written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC
|
|
.\" 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 December 20, 2005
|
|
.Dt PMC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pmc ,
|
|
.Nm pmc_get_num_counters ,
|
|
.Nm pmc_get_counter_type ,
|
|
.Nm pmc_save_context ,
|
|
.Nm pmc_restore_context ,
|
|
.Nm pmc_enable_counter ,
|
|
.Nm pmc_disable_counter ,
|
|
.Nm pmc_counter_isrunning ,
|
|
.Nm pmc_counter_isconfigured ,
|
|
.Nm pmc_configure_counter ,
|
|
.Nm pmc_get_counter_value ,
|
|
.Nm pmc_accumulate ,
|
|
.Nm pmc_alloc_kernel_counter ,
|
|
.Nm pmc_free_kernel_counter ,
|
|
.Nm pmc_start_profiling ,
|
|
.Nm pmc_stop_profiling ,
|
|
.Nm PMC_ENABLED
|
|
.Nd Hardware Performance Monitoring Interface
|
|
.Sh SYNOPSIS
|
|
.In sys/pmc.h
|
|
.Ft int
|
|
.Fn pmc_get_num_counters "void"
|
|
.Ft int
|
|
.Fn pmc_get_counter_type "int ctr"
|
|
.Ft void
|
|
.Fn pmc_save_context "struct lwp *l"
|
|
.Ft void
|
|
.Fn pmc_restore_context "struct lwp *l"
|
|
.Ft int
|
|
.Fn pmc_enable_counter "struct lwp *l" "int ctr"
|
|
.Ft int
|
|
.Fn pmc_disable_counter "struct lwp *l" "int ctr"
|
|
.Ft int
|
|
.Fn pmc_counter_isrunning "struct lwp *l" "int ctr"
|
|
.Ft int
|
|
.Fn pmc_counter_isconfigured "struct lwp *l" "int ctr"
|
|
.Ft int
|
|
.Fn pmc_configure_counter "struct lwp *l" "int ctr" \
|
|
"struct pmc_counter_cfg *cfg"
|
|
.Ft int
|
|
.Fn pmc_get_counter_value "struct lwp *l" "int ctr" "int flags" \
|
|
"uint64_t *pval"
|
|
.Ft int
|
|
.Fn pmc_accumulate "struct lwp *l_parent" "struct lwp *l_exiting"
|
|
.Ft int
|
|
.Fn pmc_alloc_kernel_counter "int ctr" "struct pmc_counter_cfg *cfg"
|
|
.Ft int
|
|
.Fn pmc_free_kernel_counter "int ctr"
|
|
.Ft int
|
|
.Fn pmc_start_profiling "int ctr" "struct pmc_counter_cfg *cfg"
|
|
.Ft int
|
|
.Fn pmc_stop_profiling "int ctr"
|
|
.Ft int
|
|
.Fn PMC_ENABLED "struct lwp *l"
|
|
.Sh DESCRIPTION
|
|
Provides a machine-independent interface to the hardware performance counters
|
|
which are available on several CPU families.
|
|
The capabilities of these counters vary from CPU to CPU, but they
|
|
basically count hardware events such as data cache hits or misses,
|
|
branches taken, branched mispredicted, and so forth.
|
|
Some can interrupt the processor when a certain threshold has been reached.
|
|
Some can count events in user space and kernel space independently.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
interface is intended to allow monitoring from within the kernel as well
|
|
as monitoring of userland applications.
|
|
If the hardware can interrupt the CPU in a specific implementation,
|
|
then it may also be used as a profiling source instead of the clock.
|
|
.Sh NOTES
|
|
All function calls in this interface may be defined as
|
|
.Xr cpp 1
|
|
macros.
|
|
If any function is not implemented as a macro, its prototype must be
|
|
defined by the port-specific header
|
|
.Aq Pa machine/pmc.h .
|
|
.Pp
|
|
Counters are numbered from 0 to
|
|
.Dv N\-1
|
|
where
|
|
.Dv N
|
|
is the number of counters available on the system
|
|
(see
|
|
.Fn pmc_get_num_counters
|
|
below).
|
|
.Pp
|
|
Upon a process fork, implementations must
|
|
.Bl -bullet
|
|
.It
|
|
Zero performance counters for the new process, and
|
|
.It
|
|
Inherit any enabled performance counters.
|
|
.El
|
|
.Sh DATA TYPES
|
|
Each implementation must specify two new types:
|
|
.Bl -tag -width pmc_evid_t
|
|
.It Fa pmc_evid_t
|
|
An integer type which can contain the event IDs for a given processor.
|
|
.It Fa pmc_ctr_t
|
|
An integer type defining the value which may be contained in a given
|
|
counter register.
|
|
.El
|
|
.Pp
|
|
Counters are configured with the
|
|
.Fa struct pmc_counter_cfg .
|
|
This structure is defined as
|
|
.Bd -literal
|
|
struct pmc_counter_cfg {
|
|
pmc_evid_t event_id;
|
|
pmc_ctr_t reset_value;
|
|
uint32_t flags;
|
|
};
|
|
.Ed
|
|
.sp
|
|
.Fa flags
|
|
are currently unused.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width width -compact
|
|
.It Fn pmc_get_num_counters "void"
|
|
Returns the number of counters present on the current system.
|
|
Valid values for
|
|
.Fa ctr
|
|
in the interface entry points below are from zero to one less than the
|
|
return value from this function.
|
|
.sp
|
|
.It Fn pmc_get_counter_type "int ctr"
|
|
Returns an implementation-dependent type describing the specified counter.
|
|
If
|
|
.Fa ctr
|
|
is specified as \-1, returns a machine-dependent type describing the
|
|
CPU or counter configuration.
|
|
For example, on an ia32 architecture, it may distinguish between
|
|
586-, 686-, and K7-style counters.
|
|
.sp
|
|
.It Fn pmc_save_context "struct lwp *l"
|
|
Saves the PMC context for the current process.
|
|
This is called just before
|
|
.Xr cpu_switch 9 .
|
|
If there is kernel PMC state, it must be maintained across this call.
|
|
.sp
|
|
.It Fn pmc_restore_context "struct lwp *l"
|
|
Restores the PMC context for the current process.
|
|
This is called just after
|
|
.Xr cpu_switch 9
|
|
returns.
|
|
If there is kernel PMC state, it must be maintained across this call.
|
|
.sp
|
|
.It Fn pmc_enable_counter "struct lwp *l" "int ctr"
|
|
Enables counter
|
|
.Fa ctr
|
|
for the specified process.
|
|
The counter should have already been configured with a call to
|
|
.Fn pmc_configure_counter .
|
|
This starts the counter running if it is not already started and enables
|
|
any interrupts, as appropriate.
|
|
.sp
|
|
.It Fn pmc_disable_counter "struct lwp *l" "int ctr"
|
|
Disables counter
|
|
.Fa ctr
|
|
for the specified process.
|
|
This stops the counter from running, and disables any interrupts,
|
|
as appropriate.
|
|
.sp
|
|
.It Fn pmc_counter_isrunning "struct lwp *l" "int ctr"
|
|
Returns non-zero if the specified counter in the specified process is
|
|
running or if the counter is running in the kernel.
|
|
.sp
|
|
.It Fn pmc_counter_isconfigured "struct lwp *l" "int ctr"
|
|
Returns non-zero if the specified counter in the specified process is
|
|
configured or if the counter is in use by the kernel.
|
|
.sp
|
|
.It Fn pmc_configure_counter "struct lwp *l" "int ctr" \
|
|
"struct pmc_counter_cfg *cfg"
|
|
Configures counter
|
|
.Fa ctr
|
|
according to the configuration information stored in
|
|
.Fa cfg .
|
|
.sp
|
|
.It Fn pmc_get_counter_value "struct lwp *l" "int ctr" "int flags" \
|
|
"uint64_t *pval"
|
|
Returns the value of counter
|
|
.Fa ctr
|
|
in the space pointed to by
|
|
.Fa pval .
|
|
The only recognized flag is
|
|
.Fa PMC_VALUE_FLAGS_CHILDREN
|
|
which specifies that the returned counts should be accumulated values
|
|
for any exited child processes.
|
|
.sp
|
|
.It Fn pmc_accumulate "struct lwp *l_parent" "struct lwp *l_exiting"
|
|
Accumulates any counter data from the exiting process
|
|
.Fa p_exiting
|
|
into the counters for the parent process
|
|
.Fa p_parent .
|
|
.sp
|
|
.It Fn pmc_alloc_kernel_counter "int ctr" "struct pmc_counter_cfg *cfg"
|
|
Allocates counter
|
|
.Fa ctr
|
|
for use by the kernel and configures it with
|
|
.Fa cfg .
|
|
.sp
|
|
.It Fn pmc_free_kernel_counter "int ctr"
|
|
Returns counter
|
|
.Fa ctr
|
|
to the available pool of counters that may be used by processes.
|
|
.sp
|
|
.It Fn pmc_start_profiling "int ctr" "struct pmc_counter_cfg *cfg"
|
|
Allocates counter
|
|
.Fa ctr
|
|
for use by the kernel for profiling and configures it with
|
|
.Fa cfg .
|
|
.sp
|
|
.It Fn pmc_stop_profiling "int ctr"
|
|
Stops profiling with counter
|
|
.Fa ctr .
|
|
.sp
|
|
.It Fn PMC_ENABLED "struct lwp *l"
|
|
Returns non-zero if the given process or the kernel is using the PMC at all.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pmc 1 ,
|
|
.Xr pmc_control 2 ,
|
|
.Xr pmc_get_info 2
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
interface appeared in
|
|
.Nx 2.0 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
interface was designed and implemented by Allen Briggs for Wasabi Systems, Inc.
|
|
Additional input on the
|
|
.Nm
|
|
design was provided by Jason R. Thorpe.
|