NAME
pmc,
pmc_get_num_counters,
pmc_get_counter_type,
pmc_save_context,
pmc_restore_context,
pmc_enable_counter,
pmc_disable_counter,
pmc_counter_isrunning,
pmc_counter_isconfigured,
pmc_configure_counter,
pmc_get_counter_value,
pmc_accumulate,
pmc_alloc_kernel_counter,
pmc_free_kernel_counter,
pmc_start_profiling,
pmc_stop_profiling,
PMC_ENABLED —
Hardware Performance
Monitoring Interface
SYNOPSIS
#include <sys/pmc.h>
int
pmc_get_num_counters(
void);
int
pmc_get_counter_type(
int
ctr);
void
pmc_save_context(
struct
lwp *l);
void
pmc_restore_context(
struct
lwp *l);
int
pmc_enable_counter(
struct
lwp *l,
int ctr);
int
pmc_disable_counter(
struct
lwp *l,
int ctr);
int
pmc_counter_isrunning(
struct
lwp *l,
int ctr);
int
pmc_counter_isconfigured(
struct
lwp *l,
int ctr);
int
pmc_configure_counter(
struct
lwp *l,
int ctr,
struct pmc_counter_cfg
*cfg);
int
pmc_get_counter_value(
struct
lwp *l,
int ctr,
int flags,
uint64_t *pval);
int
pmc_accumulate(
struct
lwp *l_parent,
struct lwp
*l_exiting);
int
pmc_alloc_kernel_counter(
int
ctr,
struct pmc_counter_cfg
*cfg);
int
pmc_free_kernel_counter(
int
ctr);
int
pmc_start_profiling(
int
ctr,
struct pmc_counter_cfg
*cfg);
int
pmc_stop_profiling(
int
ctr);
int
PMC_ENABLED(
struct
lwp *l);
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.
The
pmc 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.
IMPLEMENTATION NOTES
All function calls in this interface may be defined as
cpp(1) macros. If any function is
not implemented as a macro, its prototype must be defined by the port-specific
header
<machine/pmc.h>.
Counters are numbered from 0 to
N-1
where
N
is the number of counters available on the system
(see
pmc_get_num_counters() below).
Upon a process fork, implementations must
- Zero performance counters for the new process, and
- Inherit any enabled performance counters.
DATA TYPES
Each implementation must specify two new types:
-
-
- pmc_evid_t
- An integer type which can contain the event IDs for a given
processor.
-
-
- pmc_ctr_t
- An integer type defining the value which may be contained
in a given counter register.
Counters are configured with the
struct pmc_counter_cfg.
This structure is defined as
struct pmc_counter_cfg {
pmc_evid_t event_id;
pmc_ctr_t reset_value;
uint32_t flags;
};
flags are currently unused.
FUNCTIONS
-
-
- pmc_get_num_counters(void)
- Returns the number of counters present on the current
system. Valid values for ctr in the interface entry
points below are from zero to one less than the return value from this
function.
-
-
- pmc_get_counter_type(int
ctr)
- Returns an implementation-dependent type describing the
specified counter. If 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.
-
-
- pmc_save_context(struct
lwp *l)
- Saves the PMC context for the current process. This is
called just before
cpu_switchto(9). If
there is kernel PMC state, it must be maintained across this call.
-
-
- pmc_restore_context(struct
lwp *l)
- Restores the PMC context for the current process. This is
called just after
cpu_switchto(9)
returns. If there is kernel PMC state, it must be maintained across this
call.
-
-
- pmc_enable_counter(struct
lwp *l, int ctr)
- Enables counter ctr for the specified
process. The counter should have already been configured with a call to
pmc_configure_counter(). This starts the counter running
if it is not already started and enables any interrupts, as
appropriate.
-
-
- pmc_disable_counter(struct
lwp *l, int ctr)
- Disables counter ctr for the
specified process. This stops the counter from running, and disables any
interrupts, as appropriate.
-
-
- 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.
-
-
- 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.
-
-
- pmc_configure_counter(struct
lwp *l, int ctr, struct
pmc_counter_cfg *cfg)
- Configures counter ctr according to
the configuration information stored in cfg.
-
-
- pmc_get_counter_value(struct
lwp *l, int ctr, int
flags, uint64_t *pval)
- Returns the value of counter ctr in
the space pointed to by pval. The only recognized
flag is PMC_VALUE_FLAGS_CHILDREN which specifies
that the returned counts should be accumulated values for any exited child
processes.
-
-
- pmc_accumulate(struct
lwp *l_parent, struct lwp *l_exiting)
- Accumulates any counter data from the exiting process
p_exiting into the counters for the parent process
p_parent.
-
-
- pmc_alloc_kernel_counter(int
ctr, struct pmc_counter_cfg *cfg)
- Allocates counter ctr for use by the
kernel and configures it with cfg.
-
-
- pmc_free_kernel_counter(int
ctr)
- Returns counter ctr to the available
pool of counters that may be used by processes.
-
-
- pmc_start_profiling(int
ctr, struct pmc_counter_cfg *cfg)
- Allocates counter ctr for use by the
kernel for profiling and configures it with
cfg.
-
-
- pmc_stop_profiling(int
ctr)
- Stops profiling with counter
ctr.
-
-
- PMC_ENABLED(struct
lwp *l)
- Returns non-zero if the given process or the kernel is
using the PMC at all.
SEE ALSO
pmc(1),
pmc_control(2),
pmc_get_info(2)
HISTORY
The
pmc interface appeared in
NetBSD
2.0.
AUTHORS
The
pmc interface was designed and implemented by
Allen Briggs for Wasabi Systems, Inc. Additional input
on the
pmc design was provided by
Jason R.
Thorpe.