dcpid - DCPI daemon.
dcpid [options] database
Dcpid continuously extracts raw samples from the specified performance
counter device, associates them with their corresponding images, and updates
disk-based image profiles in the specified profile database. A new profile
database can be created by specifying an empty directory.
Dcpid also supports an alternate operating mode which allows "Dynamic
Access to DCPI Data (DADD)". When run in this mode, the daemon does not
write data to a profile database, but delivers it interactively to a
registered set of client programs through the use of shared memory.
Dcpid is normally terminated using
dcpiquit(1). Dcpid shuts down gracefully in response to termination
signals, flushing all unsaved samples to their corresponding profiles before
Dcpid must be executed with root privileges. If desired, dcpid
can be installed as a setuid-root program.
Dcpid can be configured to automatically delete old epochs and profiles
(via the -gc option.) This deletion occurs every day sometime between 3am
and 5am. All epochs that were started more than seven days ago, and are not
one of the three latest epochs are deleted. Therefore the three most recent
epochs are always preserved, and all epochs are preserved for at least seven
days after their creation.
- -slot type[:period]+...+type[:period]
- -event type[:period]
- -t is shorthand for -event
- The -event option is deprecated, and may be used to specify
only a single event to avoid confusion with earlier versions of
The -slot option selects a set of event types to monitor
simultaneously using the set of available hardware performance counters.
Each event includes a type and an optional period specification. The
-slot option may be repeated to specify a sequence of slots which
are time-multiplexed onto the hardware counters, allowing a larger set
of events to be monitored.
If no -slot arguments are specified on the command line, the
default is to monitor cycles and imiss events on Alpha
21064/EV4 and 21164/EV5 processors and to multiplex between cycles
and ProfileMe statistics on 21264a/EV67 and later processors;
using default sampling periods in either case.
for information on ProfileMe event types supported on Alpha
21264a/EV67 and later processors. Non-ProfileMe event types
supported on Alpha 21264a/EV67 and later processors are:
- cycles = processor cycles (c1)
- retires = retired instructions (c0)
- replaytrap = mbox replay traps (c1)
- bmiss = bcache misses or long-latency probes (c1)
Event types supported on Alpha 21264/EV6 processors:
- cycles = processor cycles (c0 or c1)
- retires = retired instructions (c0)
- replaytrap = mbox replay traps (c1)
- itbmiss = retired itb misses (c1)
- dtbmiss = retired dtb single misses (c1)
- dtbdblmiss = retired dtb double misses (c1)
- retcondbr = retired conditional branches (c1)
- retunalign = retired unaligned traps (c1)
Event types supported on both 21064/EV4 and 21164/EV5 Alpha
- cycles = processor cycles
- issues = instruction issues
- nonissue = non-issue cycles
- imiss = instruction cache misses
- dmiss = data cache misses
- branchmp = branch mispredicts
- flow = flow control changes (see Caveats below)
- pipelinedry = pipeline dry cycles (no valid I-stream data)
- issue2 = cycles with 2 issues
- intop = integer operations (excluding loads/stores)
- fpop = floating point operations (excluding
- load = load instructions
- store = store instructions
Additional event types supported on Alpha 21164/EV5 processors:
- itbmiss = instruction translation buffer misses
- dtbmiss = data translation buffer misses
- pcmp = PC mispredicts
- iaccess = instruction cache accesses
- daccess = data cache accesses
- smiss = on-chip secondary cache misses
- srmiss = on-chip secondary cache read misses
- swmiss = on-chip secondary cache write misses
- saccess = on-chip secondary cache accesses
- sread = on-chip secondary cache reads
- swrite = on-chip secondary cache writes
- svictim = on-chip secondary cache victims
- sshwrite = on-chip secondary cache shared writes
- bmiss = board-level cache misses
- bhit = board-level cache hits
- bvictim = board-level cache victims
- bref = board-level cache references
- sysinv = system invalidates
- sysread = system read requests
- sysreq = system requests
- splitissue = split issue cycles
- replaytrap = replay traps
- issue1 = cycles with 1 issue
- issue3 = cycles with 3 issues
- issue4 = cycles with 4 issues
- mb = memory barriers
- loadmerged = loads merged (in MAF)
- ldureplay = load/use (ldu) replays
- wbmafreplay = write buffer or maf full replays
- loadlocked = LDx_L instructions
- longstall = stall longer than 12 cycles
- external = external event (system-specific or unused)
Additional event types supported on Alpha 21064/EV4 processors:
- palmode = cycles executing palcode
- pipefrozen = pipeline frozen due to resource conflict
The optional event period follows the event type, and has the format
:Mperiod, where M is a period modifier, and period is
the sampling period. If the event period is omitted, reasonable defaults
are automatically chosen based on the particular event type and the
The period modifier must be R, denoting a random
sampling interval with a mean equal to period events, or F,
denoting a fixed sampling interval equal to period events. If
omitted, the default is to use a random sampling interval on hardware
that supports it, or a fixed sampling interval otherwise.
The sampling period specifies how often the event should be
sampled, expressed as a decimal number. The suffix K can be used
to scale the specified period by 1024.
The period modifier and period specifications are
limited on the Alpha 21064/EV4 processor, which uses a fixed sampling
period (65536 for cycles, issues, and flow,
and 4096 for the other events). Later Alpha processors such as the
21164/EV5 have hardware support for modifying the sampling period and
can support arbitrary fixed periods, as well as randomized periods.
Randomization of the sampling interval helps avoid undesirable
synchronization effects with periodic code execution. Caveat: The
current driver implementation restricts the set of valid randomized
periods. For the cycles event, a valid randomized period must
have the form (65536 - 2^n). Future versions of the driver may allow
- -slot cycles:R63488+imiss
- Monitor cycle counter events, with a randomized sampling period
whose mean is one sample every 63488 cycles. In addition, simultaneously
monitor imiss events using the default period.
- -slot cycles+imiss:F4096 -slot cycles+dmiss -slot
- Always monitor cycle counter events with the default sampling
period. In addition, rotate among gathering imiss,
dmiss, and branchmp events, using a fixed 4K sampling
period for imiss, and the default sampling rates for
dmiss and branchmp.
- -slot cycles+imiss -slot cycles+imiss -slot cycles+dmiss
- Always sample cycles with the default sampling period.
Switch between sampling imiss events 2/3 of the time and
dmiss events 1/3 of the time, using the default sampling rate
for those events. In this example, one event is repeated across
multiple -slot options, in order to sample it more
frequently than the other kinds of events.
Alpha aggregate performance counter interrupts are not precise for
events other than cycles and dtbmiss, so a sample for
some other event may not be correctly attributed to the instruction
which generated the event. On 21264/EV6 processors, none of the events
are guaranteed to be precise, but the replaytrap event usually seems to
be. ProfileMe performance counter interrupts are also not
precise; but the PC of the profiled instruction is latched so that the
attributions are always correct.
There are only a limited number of hardware performance counters (3 on
Alpha 21164/EV5 processors and 2 on all other Alpha implementations),
and each counter can only count a subset of all events. Thus, certain
combinations of events cannot be simultaneously monitored. Consult the
Alpha AXP Architecture Reference Manual by Sites & Witek, Appendix D,
for detailed information about legal event combinations. dcpid
uses a simplistic algorithm to select a counter for each event on the
command line, so the order of the events on the command line can affect
whether dcpid finds a counter for each event. It is better to
list events that can be counted only on a single counter before other
When multiplexing events, the cycles event type must always
be monitored, since cycle sample interrupts are used to decide when to
switch to the next multiplexed event type. This switching interval is
controlled by the -mux option (see below).
On the Alpha 21064/EV4 processor, issues counts the total
number of instruction issues divided by 2, and nonissues counts
the total number of nonissues divided by 2.
On the Alpha 21164/EV5, the meaning of the "flow" event is altered by
whether the "branchmp" or "pcmp" events are samples at the same time as
the "flow" event: With "branchmp" sampling, "flow" events happen only at
conditional branches. With "pcmp" sampling, "flow" events happened only
at jsr and ret instructions. (Simultaneous sampling of "branchmp" and
"pcmp" events is not possible, though multiplexed sampling of these
events is possible.)
- -mux interval
- -I is shorthand for -mux
- For slot multiplexing, switch the events being monitored every
interval units of 64K cycles. The default multiplexing
interval is 10; i.e. the monitored events will be switched about
every 640K cycles.
Note: the default multiplexing interval is 100 for
Alpha 21064/EV4-based machines. On the 21064/EV4, counter values
cannot be read and restored. During event multiplexing, this
means that the counter values are reset to zero whenever a
multiplexing interval expires. With frequent
time-multiplexed switching, this can result in distortion in the
sampling of events. For this reason, it is recommended that the
multiplexing interval not be set below about 20 for this
IMAGE ASSOCIATION OPTIONS
- -bypid image
- -i is shorthand for -bypid
- Store separate profiles for each process that loads the specified
executable image. By default, the profile associated with an executable
image contains aggregated samples for all processes that execute that
image. This option allows samples to be identified by process as well as by
image. The filenames for per-process profiles have the suffix "_PID", where
PID is a local process identifier. This option can be repeated to specify
per-process profiling for multiple executable images.
- -map mapfile
- -m is shorthand for -map
- Use specified map file generated by
dcpiscan(1) for associating processes with named images. This option can
be repeated, allowing several map files to be specified; information from
all of the supplied map files is merged.
Dcpiscan is automatically run at installation time to create the
default local map of images found in the usual places (e.g. /usr/bin,
/usr/shlib, et cetera). Note: The default map does not include any
images found in /usr/local. If there are significant images in
/usr/local or other non-standard local directories, you should use
dcpiscan to create a map for those files.
- -forkid seconds
- A hook in the kernel exec path provides information to dcpid
about image loadmaps for statically-loaded processes. The system loader
provides information to dcpid about image loadmaps for
dynamically-loaded processes (unless the user's environment variable
RLD_DCPI_DISABLE is set). Unfortunately, there is no convenient hook for
capturing information about processes that are created via fork(2) which
do not subsequently invoke exec(2).
To obtain loadmap information for such forked processes that are
relatively long-lived, periodic scans of system tables are performed to
match unknown forked processes with information known about their
parents. By default, a scan is performed every 30 seconds. This feature
can be disabled by specifying a scan period of 0 seconds.
- -u is shorthand for -unknown
- Store separate per-process profiles for samples that cannot be
associated with any image. Unknown samples will be stored in profiles
associated with 1MB regions of each process address space; these
"anonymous" profiles are given names of the form hostPID@address.
If this option is not specified, a count of all unknown samples is
stored in a single profile named unknown@host.
PROFILE DATABASE OPTIONS
- -e is shorthand for -epoch
- Use the most recent existing epoch for storing new profiles. By
default, a new epoch is created each time dcpid is restarted. New
epochs can also be started using
- -ce is shorthand for -create_epoch
- Create a new profiling epoch within the named database. Specifying
-create_epoch does not result in a full invocation of the daemon. Instead,
the daemon shuts down immediately once the new epoch has been created. This
option is intended for use in a cluster environment, where it should precede
the launch of daemons on multiple nodes. The daemon invocations which follow
should all specify the -epoch option, with the result being that all profile
data will be written to the same epoch within a centralized database.
- By default, dcpid never deletes profile data. If this option
is supplied, dcpid will delete old epochs. It will still keep
at least the three latest epochs, as well as any epoch that was created
within the last seven days.
- -merge seconds
- -M is shorthand for -merge
- Merge buffered profile samples from dcpid to the
non-volatile profile database every seconds seconds. Defaults to
every 600 seconds (10 minutes).
- -flush seconds
- -F is shorthand for -flush
- Flush samples from the performance counter device driver to dcpid
every seconds seconds. Defaults to every 300 seconds (5 minutes).
Samples are also automatically flushed from the driver to dcpid
whenever remaining driver buffer space is low.
- -hash bytes
- -H is shorthand for -hash
- Specifies the desired size of the driver hash table data structure in
bytes. The default is 524288 (512K bytes). The driver treats the specified
size as a hint, and may impose additional constraints, such as forcing the
actual size to be a power of two.
- -chunk bytes
- -C is shorthand for -chunk
- Specifies the desired chunk size to use when flushing driver hash
table data structure. The default is 16384 (16K bytes). The driver
treats the specified size as a hint, and may impose additional
constraints, such as forcing the actual size to be a power of two.
- -log logfile
- -l is shorthand for -log
- Use specified file for logging warnings, errors, debugging information,
and other messages. Defaults to dcpid-host.log in the specified
profile database directory, where host is the local hostname. The log file
is written using append mode, so it is safe to reuse the same log file
across dcpid invocations.
Note: the Unix command tail -f is useful for watching the log
as it is written.
- -q is shorthand for -quiet
- Operate in quiet mode, disabling most message logging. By default,
dcpid logs errors, debugging information, and other messages to the
specified log file.
- -v is shorthand for -verbose
- Operate in verbose mode, enabling extra message logging.
- -status seconds
- -L is shorthand for -status
- Log dcpid status information to the log file every
seconds seconds. The default period is 0 (i.e. disabled).
- -x is shorthand for -logmaps
- Log image loadmap information as it becomes available.
- Enables value-profiling, if supported by the driver. Value profiling is
an extension to DCPI data collection that captures register values for
profiled user-mode instructions. Value profiling imposes additional
overhead, with a typical slowdown of approximately 10%.
- Enables value-profiling for detecting potential replay traps, if
supported by the driver. This value profiling mode captures the PC
values for recent memory operations accessing either (1) the same
effective address as the profiled instruction, or (2) an effective
address that would map to the same 64-byte cache line in a 32-direct
mapped cache. Case (1) identifies instructions that might trigger order
and wrong-size replay traps on the 21264/EV6. Case (2) identifies
instructions that might trigger what is sometime called a "troll trap"
or "cache synonym trap" on the 21264/EV6. For more details about replay
traps, see the
Compiler Writer's Guide for the Alpha 21264 (Document part #
EC-RJ66A-TE) available from
- -vtrace library
- -vtrace 'library arg'
- Enables trace value-profiling, if supported by the driver. (Note that
library must be specified as an absolute pathname.) This
value-profiling mode allows you to specify what values are captured, how
they are processed before being merged into the profile files, and how
the values are formatted for printing. library should be a shared
library implementing an interface to perform these functions. See
dcpivfilter(1) for more details on the interface that library
is expected to implement.
An optional argument, arg, may be specified for use by the
library initialization routine. However, note that both the
library and arg must occur together as part of the same
option string, which can be specified by using shell quoting
conventions, e.g. 'library arg'.
CAVEAT: When this or other forms of value profiling are enabled,
dcpid has to spend considerable memory resources to remember the
lists of most frequent values for all profiled instructions. In the
current implementation, this could cause dcpid to run out of
memory on some occasions. If this occurs, you may want to enable only
one value profiling mode at a time.
- Enables value-profiling for kernel-mode instructions.
- Captures additional context information with each value sample.
Currently, the values of the ra register and memory
location 0(sp) are captured to identify the call site
associated with each sample.
- -vinterp n
- Specifies that n instructions should be interpreted for
each sample. This is a low-level option that may not be supported in
- -vfraction n
- Specifies that interpretation should happen once every
n sampling interrupts. n will be rounded down to
the nearest power of 2.
DYNAMIC ACCESS TO DCPI DATA (DADD) OPTIONS
- Specifies that the daemon is to run in a mode which allows "Dynamic
Access to DCPI Data (DADD)". In this mode, the daemon collects and delivers
performance data for specifically identified processes. The collected data
is not written to a profile database, but is provided interactively (via
shared memory) to client programs which have registered interest in such
- -DF milliseconds
- Flush samples from the performance counter driver to dcpid and write
updated data to the appropriate shared memory regions every milliseconds
milliseconds. Defaults to every 10 milliseconds. Update periods shorter than
the default should only be used when dictated by specific user requirements.
In general, shorter periods are not recommended because the resulting
increase in system overhead can be significant.
For complete information regarding DADD, please see "DCPI/DADD: User's
and Administrator's Guide".
- Print dcpid usage message and then terminate.
- -V is shorthand for -version
- Print dcpid version string.
- -D is shorthand for -nodaemon
- Do not run dcpid as a daemon. By default, dcpid
places itself in the background, detaches from its terminal, and
redirects all output to its log file.
- -nice priority
- Adjusts the scheduling priority for dcpid.
Positive priority values result in lower scheduling
priority; negative priority values result in higher
scheduling priority. See nice(1) for more information
about Unix priority scheduling.
- -socket socket
- -s is shorthand for -socket
- Use specified local Unix socket pathname for incoming
messages from client applications such as
dcpiquit(1). Defaults to /dev/.dcpid0, the default
path used by these client applications and the loader. This is a
low-level option that may not be supported in future releases.
When collecting data using multiple "-slot"s, each slot must have at least
one event that occurs at least every 2^30 cycles, e.g., retires, cycles,
issues, or profileme mode. Dcpid does not check this requirement.
For more information, see the DCPI project home page
Hewlett-Packard Company. All rights reserved.