blob: 27ee3728358eade46e1165889ab3f288bd5e1cf8 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>PTP ETFw PerfSuite Feedback View</title>
<link rel="stylesheet" type="text/css" href="help.css">
<h1 id="top"><img src="images/feedback_view_icon.gif">PTP ETFw PerfSuite Feedback View</h1>
PerfSuite is a collection of tools and libraries
for software performance analysis on Linux-based systems.
It supports counting and profiling using CPU and other (such as network, thermal)
hardware performance counters, and interval timer profiling.
The <a href="PLUGINS_ROOT/org.eclipse.ptp.doc.user/html/toc.html">Parallel Tools Platform</a> (PTP) External Tools Framework Feedback View
(PTP ETFw Feedback View)
is part of the PTP <a href="PLUGINS_ROOT/org.eclipse.ptp.etfw.doc.user/html/toc.html">External Tools Framework</a>,
and provides a convenient
way to use the file name and line number information contained in an XML file
to allow a user to easily navigate to the lines in the files.
<p>The PTP ETFw PerfSuite Feedback View plug-in is based on the above feature.
Specifically, it provides an Eclipse view, exposing information found
in an XML file
of the type "multihwpcprofilereport" -- a specific type of XML file that
PerfSuite generates --
with convenient mapping and navigation to source lines referenced in the XML file.
With this, a user may find it easier to correlate the source code with the
information contained in the
XML file -- the hot spots, where the most samples are collected during a previous
<li>First you need to run PerfSuite to measure and provide analysis files for your application.
You can
<li>use tools inside Eclipse such as PTP ETFw - see <a href="perfsuite-example.html">an example running Perfsuite from PTP</a> </li>
or use tools outside Eclipse such as
on the command line, to perform PerfSuite runs to measure and analyze the results, and
create a file of the type "multihwpcprofilereport". </li>
One way to create such files
is to run "psrun &lt;options&gt; myprog myargs" with a profiling configuration file
to profile the program, then run "psprocess -x -o mhpr.xml myprog.*.xml" to do the
source code mapping and combine the results of multiple processes/threads into
one file "mhpr.xml".
<li>Select the file "mhpr.xml" in the Project Explorer view.
<li>Click the mouse's right button and select the menu item "Display PerfSuite Feedback",
or type the keyboard shortcut CTRL-7.
The PerfSuite Feedback View Plugin parses the xml file, creates markers that are associated
with the source code files, and create a feedback view with line items which are associated
with the markers.
The line items are initially all collapsed. You can click on the triangle symbol in front of
the individual parent nodes to expand them, or use the
"Expand All" button (<img src="images/expandall.gif"></img>) in the view's toolbar.
The line items are grouped by the files.
The format of the section is "&lt;hostname&gt;-PID_&lt;pid&gt;-thread_&lt;threadid&gt;".
In an MPI run, the thread IDs are all 0s,
but the PIDs are different. In a pure OpenMP run, the PIDs will be the same, and the
thread IDs will be different numbers instead of all 0s.
<li>To see the source file line referred to by a line item, double-click on the line in the Feedback
view. The Eclipse editor window will load the source file if it's not loaded or bring it to front
if it is loaded, and the cursor/focus goes to the line number referred in the line item.
The line items are sorted in the order from the most samples to the least. Since the line items
must have associated markers, which in turn associate with the files inside of the Eclipse work space,
for the files which PerfSuite's psrun collected samples from but are not inside of the Eclipse
work space, the line items will not appear in the view. This typically happens for the
shared libraries used by the program.
<li>You can double-click on the line items one by one to review the hot spots in the file,
or navigate by clicking the markers in the overview ruler of the text editor window, which is
vertical space at the far right side of the editor window.
<li>In this example, we created a Makefile MPI C project named "testfeedback" inside of Eclipse.
We have both MPI and
PerfSuite installed on the machine. Inside of Eclipse, we used the makefile to drive the process
of building the program, running the program with PerfSuite, and post-processing the result, and
created a PerfSuite "multihwpcprofile" report.
The following is the content of the Makefile:
all: build run process
mpicc -g -O2 -o testfeedback testfeedback.c
source /home/ruiliu/tmp/nightly-test/perfsuite-install/bin/; \
mpirun -np 4 /home/ruiliu/tmp/nightly-test/perfsuite-install/bin/psrun -f -C -c papi_profile_cycles.xml ./testfeedback
/home/ruiliu/tmp/nightly-test/perfsuite-install/bin/psprocess -x -o mhpr.xml testfeedback.*.xml
rm -rf testfeedback mhpr.xml testfeedback.*.xml
We selected the menu item "Project -> Clean", followed by "Project -> Build All".
After that, the "testfeedback" program was built, run with "psrun", and the generated
"testfeedback.*.xml" files were processed by "psprocess" and combined into "mhpr.xml".
<li>We selected the file "mhpr.xml" in the Project Explorer view.
<li>We typed "CTRL-7", and the plug-in created a new view. We then clicked the "Expand All"
button to see the line items. The line items are grouped by the files.
The format is "&lt;hostname&gt;-PID_&lt;pid&gt;-thread_&lt;threadid&gt;".
In the case of the first one "Amituofo-PID_8950-thread_0", the host name is "Amituofo".
Since it's an MPI run, the thread IDs are all 0s,
but the PIDs are different.<br/>
<a href="images/result-view.png"><img src="images/result-view.png" alt="View of results" width=75%></img></a>
<li>We double-clicked on the line corresponding to line 40 in the "Amituofo-PID_8950-thread_0"
section. The editor window brought the file "testfeedback.c" to front, and focused on line 40.<br>
<a href="images/double-clicked.png"><img src="images/double-clicked.png" alt="Screenshot when an item in the view is double clicked" width=75%></img></a>
<li>We also tried to click the markers in the editor window's overview ruler (on the right edge of the editor) to go to other
hot spot locations.<br/>
<a href="images/overview-ruler.png"><img src="images/overview-ruler.png" alt="Using overview ruler to go to lines" width=75%></img></a>
<h2>GUI Items Added In This Feature</h2>
Several GUI items were added by this feature, as shown in the following screen shots.
<li>A new context menu entry "Display PerfSuite Feedback"
and a keyboard combination shortcut "CTRL-7" can be selected on an XML file in the Project Explorer<br/>
<a href="images/context-menu.png"><img src="images/context-menu.png" alt="New Context Menu Entry: Display PerfSuite Feedback" width=75%></a>
<li>The view can be explicitly displayed by selecting Window > Show View to find "PTP ETFw Feedback View" in its own category.<br/>
<a href="images/show-view.png"><img src="images/show-view.png" alt="New View Category and View" width=75%></a>
<li>A new annotation type "PerfSuite Feedback Marker" and its preferences
in "General -> Editors -> Text Editors -> Annotations -> PerfSuite Feedback Marker"<br/>
The preference items allow a user to choose for the lines associated with
the markers: whether the markers appear in the
vertical ruler, the overview ruler or neither, whether the text is highlighted or
underlined with squiggly lines or neither, and the background color
of the lines.<br/>
<a href="images/prefs.png"><img src="images/prefs.png" alt="New Annotation Preference" width=75%></a>
<li><p>See the <a href="perfsuite-example.html">PerfSuite Example with PTP</a> for more information on launching PerfSuite from within Eclipse and PTP.
<li>Eclipse PTP ETFw Feedback View page on Eclipse Wiki:<br/>
<a href=""></a>
<li>PerfSuite web site:<br/>
At NCSA: <a href=""></a><br/>
At Source Forge: <a href=""></a>
<p><a href="#top">Back to Top</a>