Event Configuration from the Command Line

Submit New Article

	June 7, 2011 9:00 PM PDT

With the release of the VTune™ Amplifier XE 2011 Update 3, you can now collect hardware-based sampling data by configuring specific events via the command-line interface.  The help file includes information under the -event-config option of the Command-line Reference.  This article documents additional information about configuring those events.

The event-config "knob", or switch, allows you to configure the events to collect and, optionally, the sample-after value for each event.  The event-config knob is only valid when used in conjunction with the -collect-with option of the command line and passing the value 'runsa'.   For example (note, command is split over two lines for ease of reading; enter all options on one line):

$ amplxe-cl -collect-with runsa -knob event-config=CPU_CLK_UNHALTED.CORE,
CPU_CLK_UNHALTED.REF,INST_RETIRED.ANY -- C:\test\sample.exe

In this case, the default sample-after values will be used for the events specified.  To set the sample after values, use this syntax:

-event-config=<event-name>:sa=<sample-after value>,...

For example,

$ amplxe-cl -collect-with runsa -knob event-config=CPU_CLK_UNHALTED.CORE:sa=1000000,
INST_RETIRED.ANY:sa=100000 -- C:\test\sample.exe

Usually, for the CPU_CLK_* events, the default sample-after value is based on the frequency of the processor and is sufficient to collect a statistically-signification rate of 1000 samples per second.  Other events may not occur frequently enough to be statistically significant and setting the sample-after value lower than the default can help to improve the data collection.  Please see the Manual Calibration section of the Introduction to Sampling and Time white paper.  Although this paper is based on the older VTune Performance Analyzer, the technique described is still applicable.

Currently, the only way to view the sample-after values is to display the results of a run with the default values using the 'sfdump' report type, e.g.,

Event Summary
CPU_CLK_UNHALTED.CORE
368 = Samples collected due to this event
2000000 = Sample after value used during collection
736000000 = Total events (samples*SAV)
CPU_CLK_UNHALTED.REF
806 = Samples collected due to this event
1000000 = Sample after value used during collection
806000000 = Total events (samples*SAV)
INST_RETIRED.ANY
229 = Samples collected due to this event
2000000 = Sample after value used during collection
458000000 = Total events (samples*SAV)

Do you need more help?

Search knowledge base
Visit user forums
Find additional support