Page MenuHomeFreeBSD
Files F177478985

D61445.1794524275.diff
No OneTemporary
Actions

Authored By
Unknown
Size
12 KB
Referenced Files
None
Subscribers
None

D61445.1794524275.diff
View Options

diff --git a/usr.sbin/pmc/Makefile b/usr.sbin/pmc/Makefile
--- a/usr.sbin/pmc/Makefile
+++ b/usr.sbin/pmc/Makefile
@@ -2,7 +2,7 @@
PACKAGE= pmc
PROG_CXX= pmc
-MAN=
+MAN= pmc.8
CWARNFLAGS.gcc+= -Wno-redundant-decls
CFLAGS+= -I${SRCTOP}/lib/libpmcstat
CXXSTD= c++20
diff --git a/usr.sbin/pmc/pmc.8 b/usr.sbin/pmc/pmc.8
new file mode 100644
--- /dev/null
+++ b/usr.sbin/pmc/pmc.8
@@ -0,0 +1,507 @@
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2026, Netflix, Inc.
+.\" All rights reserved.
+.\"
+.\" This software was developed by Ali Mashtizadeh under the sponsorship from
+.\" Netflix, 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+.\"
+.Dd November 9, 2026
+.Dt PMC 8
+.Os
+.Sh NAME
+.Nm pmc
+.Nd record and analyze hardware performance monitoring samples
+.Sh SYNOPSIS
+.Nm
+.Aq Ar command
+.Op Ar options
+.Op Ar arguments
+.Nm
+.Ic record
+.Op Fl u
+.Op Fl c Ar event
+.Op Fl r Ar rate
+.Op Fl s Ar study
+.Op Fl t Ar seconds
+.Op Ar output.pmc
+.Nm
+.Ic list-events
+.Op Fl f | u | U
+.Op Ar event
+.Nm
+.Ic info
+.Op Fl F Ar format
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic system
+.Op Fl F Ar format
+.Op Fl s Ar column
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic program
+.Op Fl F Ar format
+.Op Fl s Ar column
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic annotate
+.Op Fl F Ar format
+.Op Ar filter options
+.Ar binary
+.Ar function
+.Op Ar pmclog
+.Nm
+.Ic calltree
+.Op Fl F Ar format
+.Op Fl -pct Ar percent
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic flamegraph
+.Op Fl F Ar format
+.Op Fl -pct Ar percent
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic branch
+.Op Fl F Ar format
+.Op Fl s Ar column
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic frontend
+.Op Fl F Ar format
+.Op Fl s Ar column
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic memory
+.Op Fl F Ar format
+.Op Fl s Ar column
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic c2c
+.Op Fl F Ar format
+.Op Fl -hitm Ar threshold
+.Op Fl -mincpus Ar threshold
+.Op Ar filter options
+.Op Ar pmclog
+.Nm
+.Ic ibs
+.Op Fl F Ar format
+.Op Ar filter options
+.Op Ar pmclog
+.Sh DESCRIPTION
+The
+.Nm
+utility records and analyzes performance monitoring samples collected using
+the facilities provided by
+.Xr hwpmc 4 .
+Analysis is performed offline: the
+.Ic record
+command writes samples to a log file, and all other commands read a log file
+and present a report.
+.Pp
+Running
+.Nm
+.Cm help
+displays a summary of the commands.
+Every command also accepts
+.Fl h
+or
+.Fl -help ,
+which displays the usage of that command and exits.
+.Pp
+The first argument selects a command.
+The remaining arguments are interpreted by that command.
+Every analysis command accepts the filter options described in
+.Sx FILTER OPTIONS
+and reads its input from
+.Ar pmclog ,
+which defaults to
+.Pa default.log
+in the current directory.
+.Pp
+The log format contains headers that make it incompatible with existing pmcstat
+logs.
+These headers store additional information about the host to enable correcting
+errata and are available through the
+.Cm info
+command.
+.Pp
+The output format of a report is selected with
+.Fl F
+and is described in
+.Sx OUTPUT FORMATS .
+.Pp
+Not all commands are available on all platforms.
+As of now branch, c2c, frontend, memory and ibs all require AMD IBS (See
+.Xr pmc.ibs 3 )
+to collect the necessary performance information.
+.Pp
+The commands are:
+.Bl -tag -width list-events
+.It Ic record
+Record samples to
+.Ar output.pmc ,
+which defaults to
+.Pa default.log .
+The file must not already exist.
+At least one
+.Fl c
+or
+.Fl s
+option is required.
+Recording continues until the time limit given by
+.Fl t
+expires or the command is interrupted.
+.Bl -tag -width 4n
+.It Fl c , Fl -counter Ar event
+Add a sampling counter for
+.Ar event .
+The event syntax is documented in
+.Xr pmc 3 ;
+use
+.Ic list-events
+to see the available events.
+May be specified multiple times.
+.It Fl r , Fl -rate Ar rate
+Set the sampling rate, in events per sample, for counters and studies that
+follow on the command line.
+The default is 1000000.
+.It Fl s , Fl -study Ar study
+Add the counters required by a predefined study.
+May be specified multiple times.
+The available studies are:
+.Bl -tag -width flamegraph
+.It Cm default
+Instruction sampling for general analysis.
+.It Cm flamegraph
+Instruction sampling with call stacks for flame graphs.
+.It Cm branches
+Study branch misprediction.
+Requires AMD IBS.
+.It Cm c2c
+Study cache-to-cache communication.
+Requires AMD IBS.
+.It Cm frontend
+Study front-end stalls.
+Requires AMD IBS.
+.It Cm memory
+Study memory operations.
+Requires AMD IBS.
+.El
+.Pp
+The IBS-based studies are available only on amd64.
+.It Fl t , Fl -time Ar seconds
+Stop recording after
+.Ar seconds
+seconds.
+The default is to record until interrupted.
+.It Fl u , Fl -userstack
+Capture joint kernel and user call stacks.
+.El
+.It Ic list-events
+List the events supported by the processor.
+If
+.Ar event
+is given, only events whose names contain it are listed.
+One of the following options requires
+.Ar event :
+.Bl -tag -width 4n
+.It Fl f , Fl -full
+Show full event details.
+.It Fl u , Fl -desc
+Show a short description of each event.
+.It Fl U , Fl -long-desc
+Show a long description of each event.
+.El
+.It Ic info
+Display the system and CPU information, the counters, and a summary of the
+samples in the log.
+Only the
+.Cm console
+format is supported.
+.It Ic system
+Show a per-process summary of the samples in the log.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.It Fl s , Fl -sort Ar column
+Sort by the given event column.
+.El
+.It Ic program
+Show a per-function summary of the samples in the log.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.It Fl s , Fl -sort Ar column
+Sort by the given event column.
+.El
+.It Ic annotate
+Show the disassembly of
+.Ar function
+from
+.Ar binary
+annotated with the samples attributed to each instruction.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.El
+.It Ic calltree
+Print a call tree built from the call stacks in the log.
+.Bl -tag -width 4n
+.It Fl -pct Ar percent
+Do not show entries that account for less than
+.Ar percent
+of the samples.
+.It Fl F , Fl -format Ar format
+Only the
+.Cm console
+format is supported.
+.El
+.It Ic flamegraph
+Display a flame graph built from the call stacks in the log.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm html
+(the default) or
+.Cm tui .
+In the
+.Cm tui
+format, press
+.Ql h
+for help and
+.Ql q
+to quit.
+.It Fl -pct Ar percent
+Do not show entries that account for less than
+.Ar percent
+of the samples.
+.El
+.It Ic branch
+Analyze branch mispredictions.
+Requires a log recorded with the
+.Cm branches
+study.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.It Fl s , Fl -sort Ar column
+Sort by the given event column.
+.El
+.It Ic frontend
+Analyze front-end stalls.
+Requires a log recorded with the
+.Cm frontend
+study.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.It Fl s , Fl -sort Ar column
+Sort by the given event column.
+.El
+.It Ic memory
+Show the most expensive memory operations.
+Requires a log recorded with the
+.Cm memory
+study.
+.Bl -tag -width 4n
+.It Fl F , Fl -format Ar format
+Select the output format: \c
+.Cm console
+(the default) or
+.Cm tui .
+.It Fl s , Fl -sort Ar column
+Sort by the given column.
+.El
+.It Ic c2c
+Analyze core-to-core communication.
+Requires a log recorded with the
+.Cm c2c
+study.
+.Bl -tag -width 4n
+.It Fl -hitm Ar threshold
+Only report cache lines with at least
+.Ar threshold
+HitM events.
+.It Fl -mincpus Ar threshold
+Only report cache lines accessed by at least
+.Ar threshold
+CPUs.
+.It Fl F , Fl -format Ar format
+Only the
+.Cm console
+format is supported.
+.El
+.It Ic ibs
+Show a breakdown of the statistics in an AMD IBS trace.
+The IBS-specific filters in
+.Sx FILTER OPTIONS
+are particularly useful with this command.
+Only the
+.Cm console
+format is supported.
+.El
+.Sh OUTPUT FORMATS
+Commands that display a report accept the following option:
+.Bl -tag -width indent
+.It Fl F , Fl -format Ar format
+Select the output format.
+The available formats are:
+.Pp
+.Bl -tag -width console -compact
+.It Cm console
+Write the report to standard output.
+.It Cm tui
+Display an interactive ncurses interface.
+.It Cm html
+Generate an HTML document.
+.El
+.El
+.Pp
+Not every command supports every format.
+If the requested format is not supported by a command,
+.Nm
+prints a warning and uses the default instead.
+If the format flag is not passed in, the format named by the
+.Ev PMC_FORMAT
+environment variable is used.
+.Sh FILTER OPTIONS
+The following options are accepted by all commands that read a log, and
+restrict the samples that are analyzed.
+They may be combined, in which case a sample must satisfy all of them.
+.Pp
+Options that take a list may be given more than once.
+.Bl -tag -width indent
+.It Fl t , Fl -lwps Ar tids
+Only include samples from the given thread IDs.
+.It Fl p , Fl -pids Ar pids
+Only include samples from the given process IDs.
+.It Fl T , Fl -threads Ar names
+Only include samples from threads with the given names.
+.It Fl P , Fl -processes Ar names
+Only include samples from processes with the given names.
+.It Fl e , Fl -event Ar events
+Only include samples for the given events.
+.It Fl c , Fl -cpus Ar cpus
+Only include samples taken on the given CPUs.
+.It Fl k , Fl -kernel
+Only include samples taken in the kernel.
+.It Fl u , Fl -user
+Only include samples taken in user mode.
+.El
+.Ss IBS Options
+These options are accepted only by long name, and apply only to samples
+produced by AMD IBS.
+.Bl -tag -width indent
+.It Fl -ldlat Ar latency
+Filter by load latency.
+.It Fl -oplat Ar latency
+Filter by operation latency.
+.It Fl -mmio
+Only include memory-mapped I/O events.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width ".Ev SYMROOT"
+.It Ev CLICOLOR
+Enable colored graphs.
+.It Ev PMC_FORMAT
+The preferred output format, used when
+.Fl F
+is not given.
+See
+.Sx OUTPUT FORMATS .
+.It Ev PAGER
+The pager used to display non-interactive reports.
+.It Ev SYMROOT
+The path to debug symbols.
+.It Ev SYSROOT
+The path to the system root, which is prepended when locating binaries
+referenced by a log.
+.It Ev TERM
+Controls the symbols and color palettes used by interactive displays.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Record 30 seconds of general purpose samples, then summarize them by process
+and by function:
+.Bd -literal -offset indent
+pmc record -s default -t 30 samples.pmc
+pmc system samples.pmc
+pmc program samples.pmc
+.Ed
+.Pp
+Browse a flame graph of kernel activity only:
+.Bd -literal -offset indent
+pmc record -s flamegraph -t 10 flame.pmc
+pmc flamegraph --format tui -k flame.pmc
+.Ed
+.Pp
+Annotate a function in a binary using samples from one process:
+.Bd -literal -offset indent
+pmc annotate -p 1234 /usr/bin/ls main samples.pmc
+.Ed
+.Pp
+List events containing the string
+.Dq cycles
+with their descriptions:
+.Bd -literal -offset indent
+pmc list-events -u cycles
+.Ed
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr pmc.ibs 3 ,
+.Xr pmclog 3 ,
+.Xr hwpmc 4
+.Sh HISTORY
+An early version of the
+.Nm
+command was introduced in 2018 by Matthew Macy, but it was abandoned and
+replaced by the work done by Ali Mashtizadeh.
+.Sh AUTHORS
+The new pmc command and this manual page were written by
+.An Ali Mashtizadeh Aq Mt ali@mashtizadeh.com
+and sponsored by Netflix, Inc.

File Metadata

Mime Type
text/plain
Expires
Thu, Nov 12, 10:57 PM (18 h, 34 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
41685870
Default Alt Text
D61445.1794524275.diff (12 KB)

Event Timeline