intel-gpu-top: Rewrite the tool to be safe to use

intel-gpu-top is a dangerous tool which can hang machines due unsafe mmio
register access. This patch rewrites it to use only PMU.

Only overall command streamer busyness and GPU global data such as power
and frequencies are included in this new version.

For access to more GPU functional unit level data, an OA metric based tool
like gpu-top should be used instead.

v2:
 * Sort engines by class and instance.
 * Do not wait for one sampling period to display something on screen.
 * Move code out of the asserts. (Rinat Ibragimov)
 * Continuously adapt to terminal size. (Rinat Ibragimov)

v3:
 * Change layout and precision of some field. (Chris Wilson)
 Eero Tamminen:
 * Use more user friendly engine names.
 * Don't error out if a counter is missing.
 * Add IMC read/write bandwidth.
 * Report minimum required kernel version.

v4:
 * Really support 4.16 by skipping of missing engines.
 * Simpler and less hacky float printing.
 * Preserve copyright header. (Antonio Argenziano)
 * Simplify engines_ptr macro. (Rinat Ibragimov)

v5:
 * Get RAPL unit from sysfs.
 * Consolidate sysfs paths with a macro.
 * Tidy error handling by carrying over and reporting errno.
 * Check against console height on all prints.
 * More readable minimum kernel version message. (Eero Tamminen)
 * Column banner for per engine stats. (Eero Tamminen)

v6:
 * Man page update. (Eero Tamminen)

Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Cc: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
Cc: Petri Latvala <petri.latvala@intel.com>
Cc: Eero Tamminen <eero.t.tamminen@intel.com>
Cc: Rinat Ibragimov <ibragimovrinat@mail.ru>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com> # v1
Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk> # v0.5
Reviewed-by: Matthew Auld <matthew.auld@intel.com>

1 files changed, 12 insertions, 29 deletions

diff --git a/man/intel_gpu_top.rst b/man/intel_gpu_top.rst
index a5f7175b..19c71230 100644
--- a/man/intel_gpu_top.rst
+++ b/man/intel_gpu_top.rst
@@ -7,9 +7,9 @@ Display a top-like summary of Intel GPU usage
 ---------------------------------------------
 .. include:: defs.rst
 :Author: IGT Developers <igt-dev@lists.freedesktop.org>
-:Date: 2016-03-01
+:Date: 2018-04-04
 :Version: |PACKAGE_STRING|
-:Copyright: 2009,2011,2012,2016 Intel Corporation
+:Copyright: 2009,2011,2012,2016,2018 Intel Corporation
 :Manual section: |MANUAL_SECTION|
 :Manual group: |MANUAL_GROUP|
 
@@ -21,42 +21,25 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-**intel_gpu_top** is a tool to display usage information of an Intel GPU. It
-requires root privilege to map the graphics device.
+**intel_gpu_top** is a tool to display usage information on Intel GPU's.
+
+The tool gathers data using perf performance counters (PMU) exposed by i915 and other platform drivers like RAPL (power) and Uncore IMC (memory bandwidth).
 
 OPTIONS
 =======
 
--s SAMPLES
-    Number of samples to acquire per second.
-
--o FILE
-    Collect usage statistics to FILE. If file is "-", run non-interactively
-    and output statistics to stdout.
-
--e COMMAND
-    Execute COMMAND to profile, and leave when it is finished. Note that the
-    entire command with all parameters should be included as one parameter.
+-s <ms>
+    Refresh period in milliseconds.
 
 -h
-    Show usage notes.
+    Show help text.
 
-EXAMPLES
-========
-
-intel_gpu_top -o "cairo-trace-gvim.log" -s 100 -e "cairo-perf-trace /tmp/gvim"
-    Run cairo-perf-trace with /tmp/gvim trace, non-interactively, saving the
-    statistics into cairo-trace-gvim.log file, and collecting 100 samples per
-    second.
-
-Note that idle units are not displayed, so an entirely idle GPU will only
-display the ring status and header.
+LIMITATIONS
+===========
 
-BUGS
-====
+* Not all metrics are supported on all platforms. Where a metric is unsupported it's value will be replaced by a dashed line.
 
-Some GPUs report some units as busy when they aren't, such that even when idle
-and not hung, it will show up as 100% busy.
+* Non-root access to perf counters is controlled by the *perf_event_paranoid* sysctl.
 
 REPORTING BUGS
 ==============