pmcstat(8)

NAME

pmcstat - performance measurement with performance monitor

ing hardware

SYNOPSIS

pmcstat   [-C]  [-D  pathname]  [-E]  [-O  logfilename]  [-P
event-spec]
        [-R logfilename] [-S event-spec] [-W] [-c cpu]  [-d]
[-g]
        [-k   kernelfile]  [-n  rate]  [-o  outputfile]  [-p
event-spec]
        [-s event-spec] [-t pid] [-w secs] [command [args]]

DESCRIPTION

The pmcstat utility measures system performance using the

facilities provided by hwpmc(4).

The pmcstat utility can measure both hardware events seen by

the system
as a whole, and those seen when a specified process is exe

cuting on the
system's CPUs. If a specific process is being targeted (for

example, if
the -t pid option is specified, or if a command line is

specified using
command), then measurement occurs till the target process

exits or the
pmcstat utility is interrupted by the user. If a specific

process is not
targeted for measurement, then pmcstat will perform system

wide measurements till interrupted by the user.

A given invocation of pmcstat can mix allocations of system

mode and process-mode PMCs, of both counting and sampling flavors. The

values of all
counting PMCs are printed in human readable form at regular

intervals by
pmcstat. The output of sampling PMCs may be configured to

go to a log
file for subsequent offline analysis, or, at the expense of

greater overhead, may be configured to be printed in text form on the

fly.

Hardware events to measure are specified to pmcstat using

event specifier
strings event-spec. The syntax of these event specifiers is

machine
dependent and is documented in pmc(3).

A process-mode PMC may be configured to be inheritable by

the target process' current and future children.

OPTIONS

The following options are available:

-C Toggle between showing cumulative or incremental

counts for sub

sequent counting mode PMCs specified on the command

line. The
default is to show incremental counts.

-D pathname

Create files with per-program samples in the direc

tory named by
pathname. The default is to create these files in

the current
directory.

-E Toggle showing per-process counts at the time a

tracked process

exits for subsequent process-mode PMCs specified on

the command
line. This option is useful for mapping the perfor

mance characteristics of a complex pipeline of processes when

used in conjunction with the -d option. The default is to not

to enable
per-process tracking.

-O logfilename

Send logging output to file logfilename. If this

option is not
specified and one of the logging options is request

ed, then
pmcstat will print a textual form of the logged

events to the
configured output file.

-P event-spec

Allocate a process mode sampling PMC measuring hard

ware events
specified in event-spec.

-R logfilename

Perform offline analysis using sampling data in file

logfilename.

-S event-spec

Allocate a system mode sampling PMC measuring hard

ware events
specified in event-spec.

-W Toggle logging the incremental counts seen by the

threads of a

tracked process each time they are scheduled on a

CPU. This is
an experimental feature intended to help analyse the

dynamic
behaviour of processes in the system. It may incur

substantial
overhead if enabled. The default is for this fea

ture to be disabled.

-c cpu Set the cpu for subsequent system mode PMCs speci

fied on the com

mand line to cpu. The default is to allocate system

mode PMCs on
CPU zero.

-d Toggle between process mode PMCs measuring events

for the target

process' current and future children or only measur

ing events for
the target process. The default is to measure

events for the
target process alone.

-g Produce flat execution profiles in a format compati

ble with

gprof(1). A separate profile file is generated for

each executable object encountered. Profile files are

placed in subdirectories named by their PMC event name.

-k kernelfile

Set the pathname of the kernel to argument

kernelfile. The
default is /boot/kernel/kernel.

-n rate

Set the default sampling rate for subsequent sam

pling mode PMCs
specified on the command line. The default is to

configure PMCs
to sample the CPU's instruction pointer every 65536

events.

-o outputfile

Send counter readings and textual representations of

logged data
to file outputfile. The default is to send output

to stderr.

-p event-spec

Allocate a process mode counting PMC measuring hard

ware events
specified in event-spec.

-s event-spec

Allocate a system mode counting PMC measuring hard

ware events
specified in event-spec.

-t pid Attach all process mode PMCs allocated to the pro

cess with PID

pid. The option is not allowed in conjunction with

specifying a
command using command.

-w secs

Print the values of all counting mode PMCs every

secs seconds.
The argument secs may be a fractional value. The

default interval is 5 seconds.

If command is specified, it is executed using execvp(3).

EXAMPLES

To perform system-wide statistical sampling on an AMD Athlon

CPU with
samples taken every 32768 instruction retirals and data be

ing sampled to
file sample.stat, use:

pmcstat -O sample.stat -n 32768 -S k7-retired-instruc

tions

To execute mozilla and measure the number of data cache

misses suffered
by it and its children every 12 seconds on an AMD Athlon,

use:

pmcstat -d -w 12 -p k7-dc-misses mozilla

To collect a system-wide samples driven by processor in

structions executed use:

pmcstat -S instructions -O /tmp/sample.out

To generate gprof(1) compatible flat profiles from a sample

file use:

pmcstat -R /tmp/sample.out -g

DIAGNOSTICS SEE ALSO

gprof(1), execvp(3), pmc(3), pmclog(3), hwpmc(4), pmccon

trol(8),
sysctl(8)

HISTORY

The pmcstat utility first appeared in FreeBSD 6.0. It is

currently under
development.

AUTHORS

Joseph Koshy <jkoshy@FreeBSD.org>

BSD July 1, 2005

BSD