caliper.1 (2010 09)

c
caliper(1)
Integrity Systems
caliper(1)
(Requires Optional HP Caliper Software)
By default, HP Caliper measures PMU events for your entire program. However using
--user-
regions=rum-sum allows you to restrict measurements to performance-sensitive regions of code.
To use this feature:
• Modify the application source code to use the header file provided with HP Caliper. The default loca-
tion of the header file is caliper_root
/include/caliper_control.h
.
• In your source code, add the HP Caliper macros to enable and disable the Itanium PMU.
• To enable the PMU, insert:
CALIPER_PMU_ENABLE();
Using CALIPER_PMU_ENABLE()
enables the PMU for the current thread until the next
CALIPER_PMU_DISABLE()
. When the PMU is already enabled,
CALIPER_PMU_ENABLE()
does not have any effect.
• To disable the PMU, insert:
CALIPER_PMU_DISABLE();
When the PMU is already disabled, CALIPER_PMU_DISABLE()
does not have any effect.
• Use the command-line option
--user-regions=rum-sum
or place user_regions="rum-sum"
in a measurement configuration file.
This option causes HP Caliper to allow the measured applications to control the PMU. When specified,
the PMU is initially disabled and HP Caliper will not measure the application until the first
CALIPER_PMU_ENABLE()
is executed.
If you do not specify the
--user-regions=rum-sum
option, CALIPER_PMU_ENABLE() and
CALIPER_PMU_DISABLE()
do not have any effect and the instructions behave as no-ops.
Metrics for Sorts/Cutoffs Specific to HP-UX
Here is additional information on "Metrics for Sorts/Cutoffs" specific to HP-UX.
The following additional report types support the use of the following metrics for sorting and applying
cutoffs, where the default metric for sorting is enclosed in [ ]:
cgprof [samples], seconds, call-count, msecs-per-call
fcount [call-count]
fcover address, name, reached-count
, reached-percent, unreached-count
,
[
unreached-percent
]
Additional Environmental Variable on HP-UX
The following additional environment variable is available on HP-UX:
CALIPER_HOME Specifies the (non-default) caliper_root location when
caliper is automatically
invoked.
This is only needed when
caliper is not installed in its default location
(/opt/caliper) and a program compiled with the +Oprofile=collect
option
(profile based optimization) is run.
Limitations
The current HP-UX version of
caliper has the following limitations:
• Only aggregated results can be produced for multi-threaded programs by the
cgprof, ecount,
fcount, and fcover measurements.
• Handwritten assembly functions which do not follow the standard language runtime conventions may
not be properly measured for instrumentation-based reports:
cgprof, fcount, and fcover.
• Only native Itanium programs produced by the HP C, C++ and Fortran 9x compilers can be measured.
PA-RISC programs, although they can run on Itanium systems, cannot be measured.
• The option
--scope=system is only supported on HP-UX B.11.23.0409 or later.
• The option
--scope=system can not be used while any other PMU measurement is running on the
system.
• The option
--scope=system can only be used by privileged users, unless this security measure is
disabled by setting the kernel tunable perfmon_allow_user_per_cpu to the value 1.
• DLKM components are only listed if the user is privileged. Function-level information is not available
for those modules.
22 Hewlett-Packard Company − 22 − HP-UX 11i Version 3: September 2010