2 .\" Copyright (c) 2015 Netflix, Inc.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .Nd Perform various studies on a system's overall PMCs
33 .Oo Fl i Ar inputfile | Fl A | Fl T | Fl v | Fl m Ar max | Fl e exp | Fl Ar E | Fl h | fl H Oc
53 program is designed to run various tests against your systems
55 There are roughly 20-22 canned tests that setup specific
56 PMCs and then run various formulas on the output information.
57 These formulas can be found in Intel documentation "Using Intel Vtune
58 amplifier xe on NNN Generation Intel Core Processors".
60 2nd, 3rd, 4th or 5th generation i.e., Sandy Bridge, Ivy Bridge, Haswell and Broadwell.
61 Currently the program only works on these four Intel processor types.
63 The following options are available:
64 .Bl -tag -width indent
66 If this option is supplied, instead of running a
68 command to collect the current running information the filename will be read
71 This option will display the complete list of canned formulas that can be run including
72 their names which can be input to the
76 Execute the canned test
78 on the running kernel.
80 If you add this option to the
82 option the test will not execute but instead give you a small description
83 of the test that would run.
85 This option will execute a test of every PMC to validate that they are working
87 If a PMC does not show up in this test chances
90 driver needs updating with new PMC information.
92 This option can restrict the number of one second samples that will
93 be collected by your system when running a test (it bounds the
94 time the test will run).
95 Without this option the test will run
96 for 1024 seconds or until the user types ctrl-c.
98 The verbose option adds debugging output to the command.
99 .It Fl E Ar expression
100 This option can be used by those that have their own ideas
101 on what formulas they want to run.
102 The expression given to the
104 option is a "formula".
105 The formula can declare directly the PMCs by name
106 or you can use an abbreviation %NNN.
107 To find out the abbreviations
108 on your system you may run the
111 An example of a formula of your own might be
113 "FP_ASSIST.ANY / INST_RETIRED.ANY_P" or using the abbreviations on a
114 Haswell machine you would type
117 You must have spaces between each entry and
118 you may use parentheses to prioritize the operators.
119 Add (+), Subtract (-),
120 Divide (/) and Multiplication (*) are supported.
121 You may also introduce
123 For example you can do a standard efficiency
126 "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
128 This option will list all known PMCs and their abbreviation (%NNN).
130 Run all canned tests.
140 utility first appeared in
143 .An Randall Stewart Aq Mt rrs@FreeBSD.org