MFC of r280697 and r280698

Sponsored by:	Netflix Inc.

4 files changed, 137 insertions, 66 deletions

diff --git a/usr.sbin/pmcstudy/Makefile b/usr.sbin/pmcstudy/Makefile
index 87a6d66..5ff3ba7 100644
--- a/usr.sbin/pmcstudy/Makefile
+++ b/usr.sbin/pmcstudy/Makefile
@@ -2,6 +2,7 @@
 # $FreeBSD$
 
 PROG=	pmcstudy
+MAN=	pmcstudy.8
 SRCS= pmcstudy.c eval_expr.c
 CFLAGS+= -Wall -Werror
 
diff --git a/usr.sbin/pmcstudy/pmcstudy.1 b/usr.sbin/pmcstudy/pmcstudy.1
deleted file mode 100644
index ad779b9..0000000
--- a/usr.sbin/pmcstudy/pmcstudy.1
+++ /dev/null
@@ -1,65 +0,0 @@
-.\" Copyright (c) 2015
-.\"		Netflix Inc.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" $FreeBSD$
-.\"
-.Dd Dec 2, 2014
-.Dt PMC_COUNTER_STUDY 1
-.Os
-.Sh NAME
-.Nm pmc_counter_study
-.Nd Perform various study's on a systems overall PMC's.
-.Sh SYNOPSIS
-.Nm
-.Sh DESCRIPTION
-The
-.Nm
-The pmc_counter_study program is designed to run various tests against
-your systems performance. There are roughly 20-22 canned tests that
-setup specific PMC's 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 or 4th generation i.e. Sandy Bridge, Ivy Bridge and Haswell. 
-Currently the program only works on these three Intel processor types.
-You can see the complete list of formula's by running the program
-with the -H option. If you know a formula name you can run it by
-typing -e name. If you know a name and want what the formula is you
-can run the program with -e name -h and the program will not run but
-it will tell you what that name will do (if known). The -T option can
-be used to test all PMC's that are known to your system. When running a
-test you will want to specify -m N where N is the number of 1 second samples
-to collect and analize (it bounds the time the test runs). Finally for
-those that have there own ideas on what formulas that you want to run
-you can type your own formula in with -E "formula". The formula can
-declare directly the PMC's by name or you can use an abbreviation
-%NNN. To find out the abbreviations on your system you may run
-pmc_counter_study -L and it will tell you each PMC name and the 
-abbreviation you can use. An example of a formula of your own might
-be -E "FP_ASSIST.ANY / INST_RETIRED.ANY_P" <or short hand on Haswell>
--E " %176 / %150". You must have spaces between each entry and
-you may use paraenthisis to prioritize the operators. Add (+), Subtract (-1),
-Divide (/) and Multiplication (*) is supported. You may also introduce
-constant numbers as well. So for example you can do a standard efficency
-test like -E "UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
-
diff --git a/usr.sbin/pmcstudy/pmcstudy.8 b/usr.sbin/pmcstudy/pmcstudy.8
new file mode 100644
index 0000000..a0da935
--- /dev/null
+++ b/usr.sbin/pmcstudy/pmcstudy.8
@@ -0,0 +1,131 @@
+.\" Copyright (c) 2015
+.\"		Netflix Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd Mar 26, 2015
+.Dt PMCSTUDY 8
+.Os
+.Sh NAME
+.Nm pmcstudy
+.Nd Perform various study's on a systems overall PMC's.
+.Sh SYNOPSIS
+.Nm
+.Oo Fl i Ar inputfile | Fl T | Fl v | Fl m Ar max | Fl e exp | Fl Ar E | Fl h | fl H Oc
+.Nm 
+.Fl i Ar inputfile 
+.Nm
+.Fl v 
+.Nm
+.Fl m Ar max
+.Nm
+.Fl e Ar exp-name
+.Nm
+.Fl E Ar your-expr
+.Nm
+.Fl h
+.Nm
+.Fl H
+.Nm
+.Fl T
+.Sh DESCRIPTION
+The
+.Nm
+program is designed to run various tests against your systems
+performance. There are roughly 20-22 canned tests that setup specific
+PMC's 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 or 4th generation i.e. Sandy Bridge, Ivy Bridge and Haswell. 
+Currently the program only works on these three Intel processor types.
+.Sh OPTIONS
+The following options are available:
+.Bl -tag -width indent
+.It Fl i Ar filename
+If this option is supplied, instead of running a
+.Xr pmcstat 8 
+command to collecte the current running information the filename will be read
+in as input instead.
+.It Fl H
+This option will display the complete list of canned formulas that can be run including
+there names which can be input to the
+.Fl e
+option.
+.It Fl e Ar name
+Execute the canned test
+.Ar name
+on the running kernel.
+.It Fl h
+If you add this option to the
+.Fl e
+option the test will not execute but instead give you a small description
+of the test that would run.
+.It Fl 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 driver needs updating with new PMC information.
+.It Fl m Ar 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.
+.It Fl v
+The verbose option adds debugging output to the command.
+.It Fl E Ar expression
+This option can be used by those that have there own ideas
+on what formulas that you want to run. The expression given to
+the
+.Fl E
+option is a "formula". The formula can declare directly the PMC's by name
+or you can use an abbreviation %NNN. To find out the abbreviations
+on your system you may run the
+.Fl L
+option.
+An example of a formula of your own might be
+.Fl E
+"FP_ASSIST.ANY / INST_RETIRED.ANY_P" or using the abbreviations on a
+Haswell machine you would type
+.Fl E
+" %176 / %150". You must have spaces between each entry and
+you may use paraenthisis to prioritize the operators. Add (+), Subtract (-),
+Divide (/) and Multiplication (*) are supported. You may also introduce
+constant numbers as well. So for example you can do a standard efficency
+test like
+.FL E
+"UOPS_RETIRED.RETIRE_SLOTS / (4 * CPU_CLK_UNHALTED.THREAD_P)".
+
+.It Fl L
+This option will list all known PMC's and there abbreviation (%NNN).
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr pmclog 3 ,
+.Xr hwpmc 4 ,
+.Xr pmcstat 8 ,
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Fx 11.0.
+.Sh AUTHORS
+.An Randall Stewart Aq Mt rrs@FreeBSD.org
diff --git a/usr.sbin/pmcstudy/pmcstudy.c b/usr.sbin/pmcstudy/pmcstudy.c
index 6547489..bb577b9 100644
--- a/usr.sbin/pmcstudy/pmcstudy.c
+++ b/usr.sbin/pmcstudy/pmcstudy.c
@@ -2130,7 +2130,11 @@ test_for_a_pmc(const char *pmc, int out_so_far)
 					printf(" ");
 				}
 			}
-			printf("%s", &line[j]);
+			if (len) {
+				printf("%s", &line[j]);
+			} else {
+				printf("\n");
+			}
 			goto out;
 		}
 	}