2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
236 lines
6.3 KiB
Groff
236 lines
6.3 KiB
Groff
.\" $NetBSD: pmc_control.2,v 1.7 2005/10/31 11:34:16 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 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 October 27, 2005
|
|
.Dt PMC_CONTROL 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pmc_control ,
|
|
.Nm pmc_get_info
|
|
.Nd Hardware Performance Monitoring Interface
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/pmc.h
|
|
.Ft int
|
|
.Fn pmc_control "int ctr" "int op" "void *argp"
|
|
.Ft int
|
|
.Fn pmc_get_info "int ctr" "int op" "void *argp"
|
|
.Sh DESCRIPTION
|
|
.Fn pmc_get_info
|
|
returns the number of counters in the system or information on a specified
|
|
counter
|
|
.Fa ctr .
|
|
The possible values for
|
|
.Fa op
|
|
are:
|
|
.Bl -tag -width width
|
|
.It Dv PMC_INFO_NCOUNTERS
|
|
When querying the number of counters in the system,
|
|
.Fa ctr
|
|
is ignored and
|
|
.Fa argp
|
|
is of type
|
|
.Ft int * .
|
|
Upon return, the integer pointed to by
|
|
.Fa argp
|
|
will contain the number of counters that are available in the system.
|
|
.It Dv PMC_INFO_CPUCTR_TYPE
|
|
When querying the type of a counter in the system,
|
|
.Fa ctr
|
|
refers to the counter being queried, and
|
|
.Fa argp
|
|
is of type
|
|
.Ft int * .
|
|
Upon return, the integer pointed to by
|
|
.Fa argp
|
|
will contain the implementation-dependent type of the specified counter.
|
|
.Pp
|
|
If
|
|
.Fa ctr
|
|
is \-1, the integer pointed to by
|
|
.Fa argp
|
|
will contain the machine-dependent type
|
|
describing the CPU or counter configuration.
|
|
.It Dv PMC_INFO_COUNTER_VALUE
|
|
When querying the value of a counter in the system,
|
|
.Fa ctr
|
|
refers to the counter being queried, and
|
|
.Fa argp
|
|
is of type
|
|
.Ft uint64_t * .
|
|
Upon return, the 64-bit integer pointed to by
|
|
.Fa argp
|
|
will contain the value of the specified counter.
|
|
.It Dv PMC_INFO_ACCUMULATED_COUNTER_VALUE
|
|
When querying the value of a counter in the system,
|
|
.Fa ctr
|
|
refers to the counter being queried, and
|
|
.Fa argp
|
|
is of type
|
|
.Ft uint64_t * .
|
|
Upon return, the 64-bit integer pointed to by
|
|
.Fa argp
|
|
will contain the sum of the accumulated values of specified counter in
|
|
all exited subprocesses of the current process.
|
|
.El
|
|
.Pp
|
|
.Fn pmc_control
|
|
manipulates the specified counter
|
|
.Fa ctr
|
|
in one of several fashions.
|
|
The
|
|
.Fa op
|
|
parameter determines the action taken by the kernel and also the interpretation of the
|
|
.Fa argp
|
|
parameter.
|
|
The possible values for
|
|
.Fa op
|
|
are:
|
|
.Bl -tag -width width
|
|
.It Dv PMC_OP_START
|
|
Starts the specified
|
|
.Fa ctr
|
|
running.
|
|
It must be preceded by a call with
|
|
.Dv PMC_OP_CONFIGURE .
|
|
.Fa argp
|
|
is ignored in this case and may be
|
|
.Dv NULL .
|
|
.It Dv PMC_OP_STOP
|
|
Stops the specified
|
|
.Fa ctr
|
|
from running.
|
|
.Fa argp
|
|
is ignored in this case and may be
|
|
.Dv NULL .
|
|
.It Dv PMC_OP_CONFIGURE
|
|
Configures the specified
|
|
.Fa ctr
|
|
prior to running.
|
|
.Fa argp
|
|
is a pointer to a
|
|
.Ft struct pmc_counter_cfg .
|
|
.Bd -literal
|
|
struct pmc_counter_cfg {
|
|
pmc_evid_t event_id;
|
|
pmc_ctr_t reset_value;
|
|
uint32_t flags;
|
|
};
|
|
.Ed
|
|
.Bl -tag -width width
|
|
.It Dv event_id
|
|
is the event ID to be counted.
|
|
.It Dv reset_value
|
|
is a value to which the counter should be reset on overflow (if supported
|
|
by the implementation).
|
|
This is most useful when profiling (see
|
|
.Dv PMC_OP_PROFSTART ,
|
|
below).
|
|
This value is defined to be the number of counter ticks before
|
|
the next overflow.
|
|
So, to get a profiling tick on every hundredth data cache miss, set the
|
|
.Dv event_id
|
|
to the proper value for
|
|
.Dq dcache-miss
|
|
and set
|
|
.Dv reset_value
|
|
to 100.
|
|
.It Dv flags
|
|
Currently unused.
|
|
.El
|
|
.It Dv PMC_OP_PROFSTART
|
|
Configures the specified
|
|
.Fa ctr
|
|
for use in profiling.
|
|
.Fa argp
|
|
is a pointer to a
|
|
.Ft struct pmc_counter_cfg
|
|
as in
|
|
.Dv PMC_OP_CONFIGURE ,
|
|
above.
|
|
This request allocates a kernel counter, which will fail if any
|
|
process is using the requested counter.
|
|
Not all implementations or counters may support this option.
|
|
.It Dv PMC_OP_PROFSTOP
|
|
Stops the specified
|
|
.Fa ctr
|
|
from being used for profiling.
|
|
.Fa argp
|
|
is ignored in this case and may be
|
|
.Dv NULL .
|
|
.El
|
|
.Sh RETURN VALUES
|
|
A return value of 0 indicates that the call succeeded.
|
|
Otherwise, \-1 is returned and the global variable
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh ERRORS
|
|
Among the possible error codes from
|
|
.Fn pmc_control
|
|
and
|
|
.Fn pmc_get_info
|
|
are
|
|
.Bl -tag -width Er
|
|
.It Bq Er EFAULT
|
|
The address specified for the
|
|
.Fa argp
|
|
is invalid.
|
|
.It Bq Er ENXIO
|
|
Specified counter is not yet configured.
|
|
.It Bq Er EINPROGRESS
|
|
.Dv PMC_OP_START
|
|
was passed for a counter that is already running.
|
|
.It Bq Er EINVAL
|
|
Specified counter was invalid.
|
|
.It Bq Er EBUSY
|
|
If the requested counter is already in use--either by the current process
|
|
or by the kernel.
|
|
.It Bq Er ENODEV
|
|
If and only if the specified counter event is not valid for the specified
|
|
counter when configuring a counter or starting profiling.
|
|
.It Bq Er ENOMEM
|
|
If the kernel is unable to allocate memory.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pmc 1 ,
|
|
.Xr pmc 9
|
|
.Sh HISTORY
|
|
The
|
|
.Fn pmc_control
|
|
and
|
|
.Fn pmc_get_info
|
|
system calls appeared in
|
|
.Nx 2.0 .
|