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 .\" $FreeBSD$
  26 .\"
  27 .Dd Mar 26, 2015
  28 .Dt PMCSTUDY 8
  29 .Os
  30 .Sh NAME
  31 .Nm pmcstudy
  32 .Nd Perform various studies on a system's overall PMCs
  33 .Sh SYNOPSIS
  34 .Nm
  35 .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
  36 .Nm
  37 .Fl i Ar inputfile
  38 .Nm
  39 .Fl v
  40 .Nm
  41 .Fl m Ar max
  42 .Nm
  43 .Fl e Ar exp-name
  44 .Nm
  45 .Fl E Ar your-expr
  46 .Nm
  47 .Fl h
  48 .Nm
  49 .Fl H
  50 .Nm
  51 .Fl T
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 program is designed to run various tests against your systems
  56 performance.
  57 There are roughly 20-22 canned tests that setup specific
  58 PMCs and then run various formulas on the output information.
  59 These formulas can be found in Intel documentation "Using Intel Vtune
  60 amplifier xe on NNN Generation Intel Core Processors".
  61 The NNN is either
  62 2nd, 3rd, 4th or 5th generation i.e., Sandy Bridge, Ivy Bridge, Haswell and Broadwell.
  63 Currently the program only works on these four Intel processor types.
  64 .Sh OPTIONS
  65 The following options are available:
  66 .Bl -tag -width indent
  67 .It Fl i Ar filename
  68 If this option is supplied, instead of running a
  69 .Xr pmcstat 8
  70 command to collect the current running information the filename will be read
  71 in as input instead.
  72 .It Fl H
  73 This option will display the complete list of canned formulas that can be run including
  74 their names which can be input to the
  75 .Fl e
  76 option.
  77 .It Fl e Ar name
  78 Execute the canned test
  79 .Ar name
  80 on the running kernel.
  81 .It Fl h
  82 If you add this option to the
  83 .Fl e
  84 option the test will not execute but instead give you a small description
  85 of the test that would run.
  86 .It Fl T
  87 This option will execute a test of every PMC to validate that they are working
  88 on your system.
  89 If a PMC does not show up in this test chances
  90 are the kernel
  91 .Xr hwpmc 4
  92 driver needs updating with new PMC information.
  93 .It Fl m Ar num
  94 This option can restrict the number of one second samples that will
  95 be collected by your system when running a test (it bounds the
  96 time the test will run).
  97 Without this option the test will run
  98 for 1024 seconds or until the user types ctrl-c.
  99 .It Fl v
 100 The verbose option adds debugging output to the command.
 101 .It Fl E Ar expression
 102 This option can be used by those that have their own ideas
 103 on what formulas they want to run.
 104 The expression given to the
 105 .Fl E
 106 option is a "formula".
 107 The formula can declare directly the PMCs by name
 108 or you can use an abbreviation %NNN.
 109 To find out the abbreviations
 110 on your system you may run the
 111 .Fl L
 112 option.
 113 An example of a formula of your own might be
 114 .Fl E
 115 "FP_ASSIST.ANY / INST_RETIRED.ANY_P" or using the abbreviations on a
 116 Haswell machine you would type
 117 .Fl E
 118 " %176 / %150".
 119 You must have spaces between each entry and
 120 you may use parentheses to prioritize the operators.
 121 Add (+), Subtract (-),
 122 Divide (/) and Multiplication (*) are supported.
 123 You may also introduce
 124 constant numbers.
 125 For example you can do a standard efficiency
 126 test like
 127 .Fl E
 128 "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
 129 .It Fl L
 130 This option will list all known PMCs and their abbreviation (%NNN).
 131 .It Fl A
 132 Run all canned tests.
 133 .El
 134 .Sh SEE ALSO
 135 .Xr pmc 3 ,
 136 .Xr pmclog 3 ,
 137 .Xr hwpmc 4 ,
 138 .Xr pmcstat 8
 139 .Sh HISTORY
 140 The
 141 .Nm
 142 utility first appeared in
 143 .Fx 11.0.
 144 .Sh AUTHORS
 145 .An Randall Stewart Aq Mt rrs@FreeBSD.org