PMCSTUDY(8)             FreeBSD System Manager's Manual            PMCSTUDY(8)

NAME
     pmcstudy - Perform various studies on a system's overall PMCs

SYNOPSIS
     pmcstudy [-i inputfile | -A | -T | -v | -m max | -e -exp | -E | -h | -fl -H]
     pmcstudy -i inputfile
     pmcstudy -v
     pmcstudy -m max
     pmcstudy -e exp-name
     pmcstudy -E your-expr
     pmcstudy -h
     pmcstudy -H
     pmcstudy -T

DESCRIPTION
     The pmcstudy program is designed to run various tests against your
     systems performance.  There are roughly 20-22 canned tests that setup
     specific PMCs and then run various formulas on the output information.
     These formulas can be found in Intel documentation "Using Intel Vtune
     amplifier xe on NNN Generation Intel Core Processors".  The NNN is either
     2nd, 3rd, 4th or 5th generation i.e., Sandy Bridge, Ivy Bridge, Haswell
     and Broadwell.  Currently the program only works on these four Intel
     processor types.

OPTIONS
     The following options are available:

     -i filename
             If this option is supplied, instead of running a pmcstat(8)
             command to collect the current running information the filename
             will be read in as input instead.

     -H      This option will display the complete list of canned formulas
             that can be run including their names which can be input to the
             -e option.

     -e name
             Execute the canned test name on the running kernel.

     -h      If you add this option to the -e option the test will not execute
             but instead give you a small description of the test that would
             run.

     -T      This option will execute a test of every PMC to validate that
             they are working on your system.  If a PMC does not show up in
             this test chances are the kernel hwpmc(4) driver needs updating
             with new PMC information.

     -m num  This option can restrict the number of one second samples that
             will be collected by your system when running a test (it bounds
             the time the test will run).  Without this option the test will
             run for 1024 seconds or until the user types ctrl-c.

     -v      The verbose option adds debugging output to the command.

     -E expression
             This option can be used by those that have their own ideas on
             what formulas they want to run.  The expression given to the -E
             option is a "formula".  The formula can declare directly the PMCs
             by name or you can use an abbreviation %NNN.  To find out the
             abbreviations on your system you may run the -L option.  An
             example of a formula of your own might be -E "FP_ASSIST.ANY /
             INST_RETIRED.ANY_P" or using the abbreviations on a Haswell
             machine you would type -E " %176 / %150".  You must have spaces
             between each entry and you may use parentheses to prioritize the
             operators.  Add (+), Subtract (-), Divide (/) and Multiplication
             (*) are supported.  You may also introduce constant numbers.  For
             example you can do a standard efficiency test like -E
             "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".

     -L      This option will list all known PMCs and their abbreviation
             (%NNN).

     -A      Run all canned tests.

SEE ALSO
     pmc(3), pmclog(3), hwpmc(4), pmcstat(8)

HISTORY
     The pmcstudy utility first appeared in FreeBSD 11.0.

AUTHORS
     Randall Stewart <rrs@FreeBSD.org>

FreeBSD 13.1-RELEASE-p6         March 26, 2015         FreeBSD 13.1-RELEASE-p6