usr.sbin/pmcstudy/pmcstudy.8

   1 .\"
   2 .\" Copyright (c) 2015 Netflix, Inc.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd March 26, 2015
  26 .Dt PMCSTUDY 8
  27 .Os
  28 .Sh NAME
  29 .Nm pmcstudy
  30 .Nd Perform various studies on a system's overall PMCs
  31 .Sh SYNOPSIS
  32 .Nm
  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
  34 .Nm
  35 .Fl i Ar inputfile
  36 .Nm
  37 .Fl v
  38 .Nm
  39 .Fl m Ar max
  40 .Nm
  41 .Fl e Ar exp-name
  42 .Nm
  43 .Fl E Ar your-expr
  44 .Nm
  45 .Fl h
  46 .Nm
  47 .Fl H
  48 .Nm
  49 .Fl T
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 program is designed to run various tests against your systems
  54 performance.
  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".
  59 The NNN is either
  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.
  62 .Sh OPTIONS
  63 The following options are available:
  64 .Bl -tag -width indent
  65 .It Fl i Ar filename
  66 If this option is supplied, instead of running a
  67 .Xr pmcstat 8
  68 command to collect the current running information the filename will be read
  69 in as input instead.
  70 .It Fl H
  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
  73 .Fl e
  74 option.
  75 .It Fl e Ar name
  76 Execute the canned test
  77 .Ar name
  78 on the running kernel.
  79 .It Fl h
  80 If you add this option to the
  81 .Fl e
  82 option the test will not execute but instead give you a small description
  83 of the test that would run.
  84 .It Fl T
  85 This option will execute a test of every PMC to validate that they are working
  86 on your system.
  87 If a PMC does not show up in this test chances
  88 are the kernel
  89 .Xr hwpmc 4
  90 driver needs updating with new PMC information.
  91 .It Fl m Ar num
  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.
  97 .It Fl v
  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
 103 .Fl E
 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
 109 .Fl L
 110 option.
 111 An example of a formula of your own might be
 112 .Fl E
 113 "FP_ASSIST.ANY / INST_RETIRED.ANY_P" or using the abbreviations on a
 114 Haswell machine you would type
 115 .Fl E
 116 " %176 / %150".
 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
 122 constant numbers.
 123 For example you can do a standard efficiency
 124 test like
 125 .Fl E
 126 "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
 127 .It Fl L
 128 This option will list all known PMCs and their abbreviation (%NNN).
 129 .It Fl A
 130 Run all canned tests.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr pmc 3 ,
 134 .Xr pmclog 3 ,
 135 .Xr hwpmc 4 ,
 136 .Xr pmcstat 8
 137 .Sh HISTORY
 138 The
 139 .Nm
 140 utility first appeared in
 141 .Fx 11.0 .
 142 .Sh AUTHORS
 143 .An Randall Stewart Aq Mt rrs@FreeBSD.org