usr.sbin/pmcstudy/pmcstudy.8

   1 .\" Copyright (c) 2015
   2 .\"             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 study's on a systems overall PMC's.
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Oo Fl i Ar inputfile | 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. There are roughly 20-22 canned tests that setup specific
  57 PMC's and then run various formulas on the output information.
  58 These formulas can be found in Intel documentation "Using Intel Vtune
  59 amplifier xe on NNN Generation Intel Core Processors". The NNN is either
  60 2nd, 3rd or 4th generation i.e. Sandy Bridge, Ivy Bridge and Haswell.
  61 Currently the program only works on these three 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 collecte 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 there 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. If a PMC does not show up in this test chances
  87 are the kernel hwpmc driver needs updating with new PMC information.
  88 .It Fl m Ar num
  89 This option can restrict the number of one second samples that will
  90 be collected by your system when running a test (it bounds the
  91 time the test will run). Without this option the test will run
  92 for 1024 seconds or until the user types ctrl-c.
  93 .It Fl v
  94 The verbose option adds debugging output to the command.
  95 .It Fl E Ar expression
  96 This option can be used by those that have there own ideas
  97 on what formulas that you want to run. The expression given to
  98 the
  99 .Fl E
 100 option is a "formula". The formula can declare directly the PMC's by name
 101 or you can use an abbreviation %NNN. To find out the abbreviations
 102 on your system you may run the
 103 .Fl L
 104 option.
 105 An example of a formula of your own might be
 106 .Fl E
 107 "FP_ASSIST.ANY / INST_RETIRED.ANY_P" or using the abbreviations on a
 108 Haswell machine you would type
 109 .Fl E
 110 " %176 / %150". You must have spaces between each entry and
 111 you may use paraenthisis to prioritize the operators. Add (+), Subtract (-),
 112 Divide (/) and Multiplication (*) are supported. You may also introduce
 113 constant numbers as well. So for example you can do a standard efficency
 114 test like
 115 .FL E
 116 "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
 117
 118 .It Fl L
 119 This option will list all known PMC's and there abbreviation (%NNN).
 120 .Sh SEE ALSO
 121 .Xr pmc 3 ,
 122 .Xr pmclog 3 ,
 123 .Xr hwpmc 4 ,
 124 .Xr pmcstat 8 ,
 125 .Sh HISTORY
 126 The
 127 .Nm
 128 utility first appeared in
 129 .Fx 11.0.
 130 .Sh AUTHORS
 131 .An Randall Stewart Aq Mt rrs@FreeBSD.org