NetBSD/usr.bin/pmc/pmc.1

.\"	$NetBSD: pmc.1,v 1.13 2017/07/13 10:59:53 wiz Exp $
.\"
.\" Copyright (c) 2017 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Maxime Villard.
.\"
.\" 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 THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``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 THE FOUNDATION OR CONTRIBUTORS
.\" 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.
.\"
.\" Copyright (c) 2000 Zembu Labs, Inc.
.\" All rights reserved.
.\"
.\" Author: Jason R. Thorpe <thorpej@zembu.com>
.\"
.\" 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 by Zembu Labs, Inc.
.\" 4. Neither the name of Zembu Labs nor the names of its employees may
.\"    be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY ZEMBU LABS, INC. ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR-
.\" RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS-
.\" CLAIMED.  IN NO EVENT SHALL ZEMBU LABS 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 12, 2017
.Dt PMC 1
.Os
.Sh NAME
.Nm pmc
.Nd performance-monitoring counter interface
.Sh SYNOPSIS
.Nm pmc
.Ar command
.Op Ar arguments
.Sh DESCRIPTION
The
.Nm
tool can be used to control and inspect the state of the
Performance-Monitoring Counters (PMCs) in the system.
.Pp
The first argument,
.Ar command ,
specifies the action to take.
Valid commands are:
.Bl -tag -width offline
.It list
Display a list of performance counter events available on the system.
.It start Ar name:option Op Ar name:option ...
Start one or several counters.
.Ar name
specifies the name of the event to count; it must be taken from the list of
available events.
.Ar option
specifies the source of the event; it must be a combination of
.Ar u
(userland) and
.Ar k
(kernel).
.It stop
Stop any performance counters that are currently running, and display the
values of these counters.
.El
.Sh FILES
.Pa src/sys/arch/x86/x86/pmc.c
x86 implementation.
.Pp
.Pa src/usr.bin/pmc/pmc.c
pmc tool.
.Sh EXAMPLES
The following command prints the available counters.
.Dl # pmc list
.Pp
The following command starts two counters.
The former will count the 'l2cache-access' events that are triggered from
userland, the latter will count the 'l1cache-access' events triggered from
both userland and the kernel.
.Dl # pmc start l2cache-access:u l1cache-access:uk
.Pp
Note that the two following commands are not exactly identical.
.Dl # pmc start l1cache-access:u l1cache-access:k
.Dl # pmc start l1cache-access:uk
The former will start two different counters that have a different source but
track the same event.
The latter will start one counter that tracks the event from all sources;
it therefore does the sum of the two counters from the first command, but
takes only one counter to do so.
.Sh INTERPRETING RESULTS
For each PMC on each CPU, the value reported by the
.Nm
tool is the number of events counted, encoded in a 64bit integer.
.Sh DIAGNOSTICS
.Bl -diag
.It PMC support not compiled into the kernel
Performance-monitoring counter support has not been compiled into the
kernel.
It may be included using the
.Em PMC
option.
See
.Xr options 4
for details.
.El
.Sh SEE ALSO
.Xr options 4
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 1.6 .
It was revamped in
.Nx 8.0 .
.Sh BUGS
The
.Nm
command currently only supports performance-monitoring counters
on the i386 and amd64 architectures.