intel_gpu_frequency: A tool to manipulate Intel GPU frequency

WARNING: very minimally tested

In general you should not need this tool. Its primary purpose is for
benchmarking, and for debugging performance issues.

For many kernel releases now sysfs has supported reading and writing the GPU
frequency. Therefore, this tool provides no new functionality. What it does
provide is an easy to package (for distros) tool that handles the most common
scenarios.

v2:
Get rid of -f from the usage message (Jordan)
Add space before [-s (Jordan)
Add a -c/--custom example (Jordan)
Add a setting for resetting to hardware default (Ken)
Replicate examples in commit message in the source code. (me)

v3:
Its not It's (me)
Add --help/-h to usage
Add Version + man page
Rename tool to intel_gpu_frequency, from intel_frequency
Remove "sudo" from the examples

Signed-off-by: Ben Widawsky <ben@bwidawsk.net>
Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>
Cc: Kenneth Graunke <kenneth@whitecape.org>

Here are some sample usages:
$ intel_gpu_frequency --get=cur,min,max,eff
cur: 200 MHz
min: 200 MHz
RP1: 200 MHz
max: 1200 MHz

$ intel_gpu_frequency -g
cur: 200 MHz
min: 200 MHz
RP1: 200 MHz
max: 1200 MHz

$ intel_gpu_frequency -geff
RP1: 200 MHz

$ intel_gpu_frequency --set min=300
$ intel_gpu_frequency --get min
cur: 300 MHz
min: 300 MHz
RP1: 200 MHz
max: 1200 MHz

$ intel_gpu_frequency --custom max=900
$ intel_gpu_frequency --get max
cur: 300 MHz
min: 300 MHz
RP1: 200 MHz
max: 900 MHz

$ intel_gpu_frequency --max
$ intel_gpu_frequency -g
cur: 1200 MHz
min: 1200 MHz
RP1: 200 MHz
max: 1200 MHz

$ intel_gpu_frequency -e
$ intel_gpu_frequency -g
cur: 200 MHz
min: 200 MHz
RP1: 200 MHz
max: 200 MHz

$ intel_gpu_frequency --max
$ intel_gpu_frequency -g
cur: 1200 MHz
min: 1200 MHz
RP1: 200 MHz
max: 1200 MHz

$ intel_gpu_frequency --min
$ intel_gpu_frequency -g
cur: 200 MHz
min: 200 MHz
RP1: 200 MHz
max: 200 MHz

2 files changed, 59 insertions, 0 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 0d04f934..dcd79528 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -4,6 +4,7 @@ appman_PRE = 				\
 	intel_bios_dumper.man		\
 	intel_bios_reader.man		\
 	intel_error_decode.man		\
+	intel_gpu_frequency.man		\
 	intel_gpu_top.man		\
 	intel_gtt.man			\
 	intel_infoframes.man		\
diff --git a/man/intel_gpu_frequency.man b/man/intel_gpu_frequency.man
new file mode 100644
index 00000000..60e4e0c8
--- /dev/null
+++ b/man/intel_gpu_frequency.man
@@ -0,0 +1,58 @@
+.TH INTEL_FREQUENCY: "1" "January 2015" "intel_gpu_frequency" "User Commands"
+.SH NAME
+intel_gpu_frequency: \- manual page for intel_gpu_frequency
+.SH SYNOPSIS
+.B intel_gpu_frequency
+[\fI\,-e\/\fR] [\fI\,--min | --max\/\fR] [\fI\,-g (min|max|efficient)\/\fR] [\fI\,-s frequency_mhz\/\fR]
+.SH DESCRIPTION
+\&A program to manipulate Intel GPU frequencies. Intel GPUs
+will automatically throttle the frequencies based on system demands, up when
+needed, down when not. This tool should only be used for debugging performance
+problems, or trying to get a stable frequency while benchmarking.
+
+Intel GPUs only accept specific frequencies. The tool may, or may not attempt to
+adjust requests to the proper frequency if they aren't correct. This may lead to
+non-obvious failures when setting frequency. Multiples of 50MHz is usually a
+safe bet.
+.SH OPTIONS
+.TP
+\fB\-e\fR
+Lock frequency to the most efficient frequency
+.TP
+\fB\-g\fR, \fB\-\-get=\fR
+Get the frequency comma separated list of ("cur"|"min"|"max"|"eff")
+.TP
+\fB\-s\fR, \fB\-\-set\fR
+Lock frequency to an absolute value (MHz)
+.TP
+\fB\-c\fR, \fB\-\-custom\fR
+Set a min, or max frequency "min=X | max=Y"
+.TP
+\fB\-m\fR  \fB\-\-max\fR
+Lock frequency to max frequency
+.TP
+\fB\-i\fR  \fB\-\-min\fR
+Lock frequency to min (never a good idea, DEBUG ONLY)
+.TP
+\fB\-d\fR  \fB\-\-defaults\fR
+Return the system to hardware defaults
+.TP
+\fB\-h\fR  \fB\-\-help\fR
+Returns this
+.HP
+\fB\-v\fR  \fB\-\-version\fR Version
+.SH EXAMPLES
+.TP
+\fbintel_gpu_frequency \-gmin,cur\fR
+Get the current and minimum frequency
+.TP
+\fbintel_gpu_frequency \-s 400\fR
+Lock frequency to 400Mhz
+.TP
+\fbintel_gpu_frequency \-c max=750\fR
+Set the max frequency to 750MHz
+.PP
+.SH "REPORTING BUGS"
+Report bugs to https://bugs.freedesktop.org
+.SH COPYRIGHT
+Copyright (C) 2015 Intel Corporation