[src/trunk]: src/share/man/man9 Document new performance monitoring interface.

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man9 Document new performance monitoring interface.
From: briggs <briggs%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 11:49:46 +0000
details:   https://anonhg.NetBSD.org/src/rev/839944eb57be
branches:  trunk
changeset: 534949:839944eb57be
user:      briggs <briggs%NetBSD.org@localhost>
date:      Wed Aug 07 04:48:55 2002 +0000

description:
Document new performance monitoring interface.

diffstat:

 share/man/man9/Makefile |   20 +++-
 share/man/man9/pmc.9    |  262 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 280 insertions(+), 2 deletions(-)

diffs (truncated from 307 to 300 lines):

diff -r 1794ad72bd27 -r 839944eb57be share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed Aug 07 04:42:42 2002 +0000
+++ b/share/man/man9/Makefile   Wed Aug 07 04:48:55 2002 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.119 2002/08/04 01:03:12 gmcgarry Exp $
+#       $NetBSD: Makefile,v 1.120 2002/08/07 04:48:55 briggs Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -20,7 +20,7 @@
        microtime.9 mstohz.9 namecache.9 namei.9 \
        panic.9 pci.9 pci_configure_bus.9 pci_intr.9 \
        pcmcia.9 pfil.9 physio.9 \
-       pmap.9 pool.9 powerhook_establish.9 ppsratecheck.9 properties.9 \
+       pmap.9 pmc.9 pool.9 powerhook_establish.9 ppsratecheck.9 properties.9 \
        radio.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
        scsipi.9 setjmp.9 setrunqueue.9 shutdownhook_establish.9 \
        signal.9 sleep.9 softintr.9 \
@@ -273,6 +273,22 @@
        pfil.9 pfil_head_unregister.9 \
        pfil.9 pfil_get_head.9 \
        pfil.9 pfil_run_hooks.9
+MLINKS+=pmc.9 pmc_get_num_counters \
+       pmc.9 pmc_get_counter_type \
+       pmc.9 pmc_save_context \
+       pmc.9 pmc_restore_context \
+       pmc.9 pmc_enable_counter \
+       pmc.9 pmc_disable_counter \
+       pmc.9 pmc_counter_isrunning \
+       pmc.9 pmc_counter_isconfigured \
+       pmc.9 pmc_configure_counter \
+       pmc.9 pmc_get_counter_value \
+       pmc.9 pmc_accumulate \
+       pmc.9 pmc_alloc_kernel_counter \
+       pmc.9 pmc_free_kernel_counter \
+       pmc.9 pmc_start_profiling \
+       pmc.9 pmc_stop_profiling \
+       pmc.9 PMC_ENABLED
 MLINKS+=pool.9 pool_create.9 pool.9 pool_destroy.9 pool.9 pool_get.9 \
        pool.9 pool_init.9 pool.9 pool_put.9 pool.9 pool_prime.9 \
        pool.9 pool_sethiwat.9 pool.9 pool_setlowat.9
diff -r 1794ad72bd27 -r 839944eb57be share/man/man9/pmc.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pmc.9      Wed Aug 07 04:48:55 2002 +0000
@@ -0,0 +1,262 @@
+.\" $NetBSD: pmc.9,v 1.1 2002/08/07 04:48:56 briggs 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 July 22, 2002
+.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
+.Fd #include \*[Lt]sys/pmc.h\*[Gt]
+.Ft int
+.Fn pmc_get_num_counters "void"
+.Ft int
+.Fn pmc_get_counter_type "int ctr"
+.Ft void
+.Fn pmc_save_context "struct proc *p"
+.Ft void
+.Fn pmc_restore_context "struct proc *p"
+.Ft int
+.Fn pmc_enable_counter "struct proc *p" "int ctr"
+.Ft int
+.Fn pmc_disable_counter "struct proc *p" "int ctr"
+.Ft int
+.Fn pmc_counter_isrunning "struct proc *p" "int ctr"
+.Ft int
+.Fn pmc_counter_isconfigured "struct proc *p" "int ctr"
+.Ft int
+.Fn pmc_configure_counter "struct proc *p" "int ctr" \
+"struct pmc_counter_cfg *cfg"
+.Ft int
+.Fn pmc_get_counter_value "struct proc *p" "int ctr" "int flags" \
+"uint64_t *pval"
+.Ft int
+.Fn pmc_accumulate "struct proc *p_parent" "struct proc *p_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 proc *p"
+.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
+.Pa Aq machine/pmc.h .
+.Pp
+Counters are numbered from 0..N-1 where N is the number of counters
+available on the system.
+.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 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 proc *p"
+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 proc *p"
+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 proc *p" "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 proc *p" "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 proc *p" "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 proc *p" "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 proc *p" "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 proc *p" "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 proc *p_parent" "struct proc *p_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 proc *p"
+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 .
Prev by Date: [src/trunk]: src/lib/libc/locale Rearrange code to avoid core dump and just r...
Next by Date: [src/trunk]: src/sys/dev/pci Fix a typo in a comment.
Previous by Thread: [src/trunk]: src/lib/libc/locale Rearrange code to avoid core dump and just r...
Next by Thread: [src/trunk]: src/sys/dev/pci Fix a typo in a comment.
Indexes:
Home | Main Index | Thread Index | Old Index