This table lists the files/information you need and what VTune Performance Analyzer features they enable.

Transcription

1 Command-line Quick Reference Guide

2 Before You Begin This table lists the files/information you need and what VTune Performance Analyzer features they enable. File/Information Binary program Symbol information Line number information Source files Compilation information Enables Launching and analyzing the application's performance, and displaying disassembly code. The binary program is an executable file, extension, library or object for example,.exe,.obj,.ocx,.dll,,.vxd,.o or.so file. To analyze the performance of your program using sampling or call graph data collection, specify the executable file that you want to analyze, or the executable file that launches other modules you want to analyze. Instrumentation in call graph, display of symbol names in static module analysis, Hotspot, Source, and Assembly Views. Instrumention, call graph, Function and Hotspot Views of sampling data collection, and Source View. Line number and symbol information, also referred to as debug information, is generated by your compiler and provided either in a separate file or as part of the binary file. If your binary file does not contain line number information, you must supply a symbol file containing line number and symbol information for example:.pdb,.dbg and.sym file formats. Source code display. To view source code, the source files must be available. Intel Tuning Assistant and source code advice. The Tuning Assistant uses compilation information to display tuning advice for your C, C++, and Java* source code. You need to provide this information in one of these formats: C++ project file (.dsp). Makefile (makefile or.mak) and the make utility used to build the executable. Preprocessor (.i) file or source files with compiler options. See the Release Notes for the complete list of compilers supported. Getting Help Online Help (Windows Only) To view online help: Select Start Programs Intel VTune Performance Analyzer Help for the Command Line. From the command line, use hh.exe to view the WindowsCli.chm file: hh.exe <install-dir>\help\windowscli.chm Command-line Help (Windows and Linux) The command-line help provides brief descriptions and syntax of vtl commands and options. To view the command line help, enter: vtl help To view help for data collector options, enter: vtl help [ c collector <name>] vtl help c sampling To view the command line help for view options, enter: vtl help [ v view <name>] vtl help v sampling Note: Use double quotes if there are spaces in the data collector/view name. For example: vtl help v "Tuning Assistant" Page 2

3 Man Pages (Linux Only) VTune Performance Analyzer The VTune analyzer manual pages provide descriptions of the vtl command, the ActivityController, the Source view, sampling and call graph via the following commands: man vtl man ActivityController man sampling man callgraph man source man 7 source man code Working with Projects and Activities The following commands are available for the Linux* and Windows* operating systems using the vtl command: Command activity delete global-options pack import query run show version view Description Creates an Activity. Deletes the project or an Activity. Displays or modifies default option values for all Activities in a project. Packs the project's contents into file. Imports a file into a project. Provides information about available collectors and views. Runs the Activity defined in the project file. Shows the contents of the project. Shows version information. Shows the Activity result in an ASCII format. The following command is supported only with the Windows command-line interface using the vtl command: merge Merges Activity results. Note: You can enter multiple commands in a single command line. vtl show activity c sampling show run a1 show Quick Start with Sampling Use the VTune TM Performance Analyzer's sampling collector to find the performance bottlenecks in your code. From the command line you can create an Activity, add the sampling collector to the Activity, and then run the Activity to collect data. Using default configuration, the VTune analyzer configures the collector, launches the specified application, and collects the data. You can view the data directly at the command line, or output it to a text file. To quickly create a project, collect sampling data using the default configuration, and then view the results, do the following: 1. Create an Activity with a sampling collector using default configuration, specify the application you wish to tune, and run the Activity using the following command: vtl activity [<name>] d <#> c sampling app [<app_name>] run Page 3

4 where <name> is the name of the Activity, <#> is the length of time the Activity is run, and <app_name> is the path and name of the application to launch. The application will be executed and the Activity and sampling data collection will start and continue till the end of the specified time. By default, the collected sampling data are stored in your directory. vtl activity d 25 c sampling run The Activity is running. Tue Nov 26 16:41: <localhost> (Run 1) The Sampling Collector is calibrating its collection parameters for the following event(s): Instructions Retired, Clockticks. Tue Nov 26 16:41: <localhost> (Run 1) The Sampling Collector is collecting samples based on the following event(s): Instructions Retired, Clockticks. Tue Nov 26 16:42: <localhost> (Run 1) Sampling data was successfully collected. The Activity has finished running. 2. View the contents of the project and check whether the Activity result was created by using the show command. vtl show a1 Activity1 r1 Sampling Results Tue Nov 26 16:42: View the results in the appropriate sampling view with: view <ActivityName::ActivityResultName> [<option>] where <option> could be processes, modules, hotspot-address ( or ha), hotspot-function (or hf), hotspot-class (or hc), or hotspot-source (or hs). vtl view a1::r1 processes The output will contain the total samples collected and selected, an event summary, and a list of the processes sampled during the collection. 4. Optionally, export collected data to a spreadsheet format for viewing and editing. Use the column delimiter option ( cd) to separate columns. vtl view a1::r1 processes cd ',' > smp_pv.csv Note: To sample particular events with your application, do the following: 1. To view the list of events available for your processor, enter: vtl help c sampling 2. When creating an Activity, use o [ ec event-config [)] en event-name='<event name>' to specify events to sample, and [:sa sample-after=<sample after> to specify the sample after value for events. Event names should be embedded within single quotes and sampling configuration options should be embedded within double quotes. vtl activity d 30 c sampling o " ec en='clockticks':sa=2" run This invocation creates an Activity with the sampling collector, runs event-based sampling for 30 seconds using the default settings, and samples only the clockticks event. Page 4

5 Quick Start with Call Graph (Linux Command-line Only) 1 Use the VTune TM Performance Analyzer's call graph collector to gather function call data for your program, track how much time each function spends on each call, and identify the most critical path in the program. From the command line, you can create an Activity, add the call graph collector to the Activity, and then run the Activity to collect data. Using the default configuration, the VTune analyzer configures the collector, launches the specified application, and collects the data. You can view the data directly at the command line, or redirect the output to a text file. To quickly create a project, collect call graph data using default configuration, and then view the results, do the following: 1. Create an Activity with a call graph collector using the default configuration, specify the application you wish to tune, and run the Activity using the following command: vtl activity [<name>] c callgraph app <app_name> moi <app_name> run where <name> is the name of the Activity, <app_name> is the name and path of the application to launch and the module of interest. The application will be instrumented and the Activity and data collection will start and continue until the application terminates or until you stop the Activity with the ActivityController. vtl activity c callgraph app./vtundemo moi./vtundemo run The Activity is running. Discovery Summary Found 17 procedures. Fail to instrument 9 of them. Starting VTunDemo Program Wait for Completion. Fri Oct 25 17:47: Static instrumentation started. Fri Oct 25 17:47: All function instrumentation of module vtundemo was successful. [...] Fri Oct 25 17:48: Data collection finished... Fri Oct 25 17:48: Updating callgraph database... Fri Oct 25 17:48: Done. The Activity has finished running. 2. View the contents of the project and check whether the Activity result was created by using the show command: vtl show a1 Activity1 r1 callgraph Results Fri Oct 25 17:48: View the Activity result in the appropriate call graph view with: vtl view <ActivityName::ActivityResultName> [<option>] where [<option>] could be processes (process view), threads (thread view), modules (module view), or functions (function view). vtl view a1::r1 modules [MODULE] /home/vtune/tst2/vtundemo /tmp/vtune_vtune/cache/libcgraphinst.so /lib/libpthread-0.9.so /lib/libc so The output contains the list of modules in the vtundemo application. 1 Call graph data collection is not yet supported using the Windows* Command-line interface of the VTune analyzer. Use the VTune analyzer GUI for call graph data collection on Windows* platforms. Page 5

6 Redirecting Input, Output and Standard Error VTune Performance Analyzer The command-line interface supports shell redirection. vtl activity d 5 c sampling o " cal no" app wc,'< in.txt > out.txt 2> err.txt',/home/vtune run Using the Intel Tuning Assistant The Intel Tuning Assistant enables you to determine which Activity result(s) to analyze and the types of advice the Tuning Assistant displays. Note: The Tuning Assistant only works on certain processors. See the product Release Notes for the list of supported processors. To invoke the Tuning Assistant from the command line, enter: vtl view ar [<ActivityName::ActivityResultName>] ta [<options>] where: [<ActivityName::ActivityResultName>] is the name of the Activity and Activity result for example: a2::r1. If no arguments are specified, the VTune TM Performance Analyzer displays data of the most recent Activity result. [<options>] is the tuning assistant option(s) (see following table) used to filter and analyze the collected data. Tuning Assistant Option [ cmp-ar] [ ta-context] [ bin aha-bin-size [ minctp minimumclockticks-percentage] [ rgn-insight-only show-regions-withinsights-only] [ thresh] Details A comma-separated list of Activity results. vtl view ar a1::r1 ta cmp-ar a2::r1,a3::r1 Arguments are <context1,context2,...> option where <context> is a following sub-option: pn process-name=<name> mn module-name=<name> rva rva-range=<start+stop> vtl view ta cmp-ar a1::r1,a2::r1 ta-context pn=vtundemo.exe Specify the size of the code regions the Intel Tuning Assistant will use to compare different executables and provide tuning advice on. The code regions can be defined at the function level or by lines of source code. vtl view ar a2::r1 ta ta-cmp a3::r1 bin 128 Use the minimum-clockticks-percentage (or minctp) option to set the minimum percentage of the workload clockticks that must be present in a code region in order for it to be included in the Tuning Assistant report. vtl view ta ar a2::r1 minctp 10 If you use the show-regions-with-insights-only (or rgn-insight-only) option with the [true] argument, only code regions that have relevant insights will be displayed in the tuning advice report. This is also the default if no Tuning Assistant options are included. vtl view ta ar a2::r1 rgn-insight-only false Set the thresh option to the required value (1 100) to display insights only if their relevance score is at or above the threshold value you specify. The Tuning Assistant assigns a relevance score to each insight according to the values measured during a sampling session. vtl view ar a3::r1 ta cmp-ar a2::r1 thresh 10 Page 6

7 Tuning Assistant Option [ rf report-format] [ it insight-types] Details Use the report-format (or rf) option to specify the desired output format of the tuning advice report: HTML or CSV (comma-separated values). vtl view ar a3::r1 ta cmp-ar a2::r1 rf csv In this example, the tuning advice report comparing two Activity results a3::r1 and a2::r1 will be provided in the CSV format. If not specified, the default format is HTML. To specify the insight types that should be displayed in the report, use the insight-types (or it) option. The following insights types are available: tb time-based coding pitfalls op other possible problems ch characterization insights ts time statistics ev raw event counts er event ratios If not specified, the tb, op, ch, and ts insight types are displayed by default. vtl view ar a3::r1 ta cmp-ar a2::r1 it ts,ev,ch In this example, the tuning advice report comparing two Activity results a3::r1 and a2::r1 will display the following insight types: Time Statistics, Event Ratios, and Characterization insights. [ nti num-top-insights] You can specify the number of top insights to display at the top of the HTML report by using the num-top-insights (or nti) option. The top insights have hyperlinks to the associated code regions deeper within the report. By default, 5 top insights are displayed. vtl view ta cmp-ar a3::r1 nti 3 [ bsp bus-speed-primary] [ bsr1 bus-speed-ref1] [ bsr2 bus-speed-ref2] [ sep sort-event-primary] [ ser1 sort-event-ref1] [ ser2 sort-event-ref2] Specifies the front-side bus speed for the Primary Activity result. Specifies the front-side bus speed for the Reference 1 Activity result. Specifies the front-side bus speed for the Reference 2 Activity result. vtl view a1::r1 ta cmp-ar a3::r1,a2::r1 bsp 667 bsr1 400 bsr2 800 In this example, tuning advice will be based on comparing Activity results a1::r1, a3::r1, and a2::r1 collected on systems with the front side speeds equal to 667 MHz, 400 MHz, and 800 MHz, respectively. Specifies the sorting event for the Primary Activity result. Specifies the sorting event for the Reference 1 Activity result. Specifies the sorting event for the Reference 2 Activity result. vtl view a1::r1 ta cmp-ar a3::r1,a2::r1 sep Clockticks ser1 CPU Cycles ser2 CPU Cycles In this example, the matching code regions for Activity results a1::r1 and a3::r1 will be sorted by the difference of Clockticks and CPU_CYCLES, operating under the assumption that Clockticks and CPU_CYCLES are essentially equivalent events. Time statistics in the tuning advice report will use Clockticks for a1::r1 and CPU_CYCLES for a3::r1 and a2::r1. Tips: You can also configure the Tuning Assistant by using the configuration options saved to a file. For reference documentation on the Tuning Assistant options (similar to the previous table), enter: vtl help v "Tuning Assistant" Page 7

8 Controlling Activities VTune Performance Analyzer Use the ActivityController tool to manage the Activity while it is running. The ActivityController has two user-interface modes: interactive and non-interactive. In the interactive mode, the ActivityController displays a list of actions to perform on the currently running Activity. Select the desired action. In the non-interactive mode, specify the action in the command line. To invoke the ActivityController, enter ActivityController at the prompt. You may have to start another shell to do this. Interactive Mode At the prompt, enter: ActivityController The output is the following: You are controlling the following Activity: [Activity name goes here] Please select one of the following actions to use with the Activity: 1. Stop Activity 2. Cancel Activity 3. Pause Activity 4. Resume Activity 5. Activity Status 6. Activity Information 7. Quit Type in the number corresponding to the action for the ActivityController to perform. It displays status messages for the first four actions. Both Stop (1) and Cancel (2) cause the ActivityController to exit. Activity Status (5) shows the current state of the Activity. Activity Information (6) displays information about the contents of the Activity: data collectors. Non-Interactive Mode The non-interactive mode supports the same commands as interactive mode. However, after the action is performed, the ActivityController exits, returning to the command line prompt. To invoke the non-interactive mode, launch the ActivityController executable with the required command line option: stop, cancel, pause, resume, status or info. ActivityController cancel Notes: Only the first 35 characters of the Activity name are displayed. You can only control the Activity you are currently running. This allows multiple users to run the ActivityController independently of other users controlling their own Activities. You cannot use several instances of the ActivityController to manage the same Activity at the same time. Tip: To review the command line arguments that can be used in the non-interactive mode, enter: ActivityController help Notes for the Linux* operating system: The Pause/Resume actions are supported for call graph data collection only. View the manual page for the brief reference on ActivityController options: man ActivityController Copyright 2003, Intel Corporation, All Rights Reserved. * Other names and brands may be claimed as the property of others. Page 8