README

   1 This is a collection of tools for development and testing of the Intel DRM
   2 driver.  There are many macro-level test suites that get used against our
   3 driver, including xtest, rendercheck, piglit, and oglconform, but failures
   4 from those can be difficult to track down to kernel changes, and many require
   5 complicated build procedures or specific testing environments to get useful
   6 results.
   7
   8 Thus, intel-graphics-tools was a project I started to collect some low-level
   9 tools I intended to build.
  10
  11 benchmarks/
  12         This should be a collection of useful microbenchmarks.  The hope is
  13         that people can use these to tune some pieces of DRM code in relevant
  14         ways.
  15
  16         The benchmarks require KMS to be enabled.  When run with an X Server
  17         running, they must be run as root to avoid the authentication
  18         requirement.
  19
  20         Note that a few other microbenchmarks are in tests (like gem_gtt_speed).
  21
  22 tests/
  23         This is a set of automated tests to run against the DRM to validate
  24         changes.  Hopefully this can cover the relevant cases we need to
  25         worry about, including backwards compatibility.
  26
  27         The test suite can be run using the run-tests.sh script available in
  28         the scripts directory. Piglit is used to run the tests and can either
  29         be installed from your distribution (if available), or can be
  30         downloaded locally for use with the script by running:
  31
  32         ./scripts/run-tests.sh -d
  33
  34         run-tests.sh has options for filtering and excluding tests from test
  35         runs:
  36
  37           -t <regex>      only include tests that match the regular expression
  38           -x <regex>      exclude tests that match the regular expression
  39
  40         Useful patterns for test filtering are described in
  41         tests/NAMING-CONVENTION and the full list of tests and subtests can be
  42         produced by passing -l to the run-tests.sh script.
  43
  44         Results are written to a JSON file and an HTML summary can also be
  45         created by passing -s to the run-tests.sh script. Further options are
  46         are detailed by using the -h option.
  47
  48
  49         If not using the script, piglit can be obtained from:
  50
  51         git://anongit.freedesktop.org/piglit
  52
  53         There is no need to build and install piglit if it is only going to be
  54         used for running i-g-t tests.
  55
  56         Set the IGT_TEST_ROOT environment variable to point to the tests
  57         directory, or set the path key in the "igt" section of piglit.conf to
  58         the intel-gpu-tools root directory.
  59
  60         The tests in the i-g-t sources need to have been built already. Then we
  61         can run the testcases with (as usual as root, no other drm clients
  62         running):
  63
  64         piglit-sources # ./piglit run igt <results-file>
  65
  66         The testlist is built at runtime, so no need to update anything in
  67         piglit when adding new tests. See
  68
  69         piglit-sources $ ./piglit run -h
  70
  71         for some useful options.
  72
  73         Piglit only runs a default set of tests and is useful for regression
  74         testing. Other tests not run are:
  75         - tests that might hang the gpu, see HANG in Makefile.am
  76         - gem_stress, a stress test suite. Look at the source for all the
  77           various options.
  78         - testdisplay is only run in the default mode. testdisplay has tons of
  79           options to test different kms functionality, again read the source for
  80           the details.
  81
  82         When creating new tests or subtests please read and follow
  83         tests/NAMING-CONVENTION.
  84
  85 lib/
  86         Common helper functions and headers used by the other tools.
  87
  88 man/
  89         Manpages, unfortunately rather incomplete.
  90
  91 tools/
  92         This is a collection of debugging tools that had previously been
  93         built with the 2D driver but not shipped.  Some distros were hacking
  94         up the 2D build to ship them.  Instead, here's a separate package for
  95         people debugging the driver.
  96
  97         These tools generally must be run as root, safe for the ones that just
  98         decode dumps.
  99
 100 tools/quick_dump
 101         Quick dumper is a python tool built with SWIG bindings to
 102         important libraries exported by the rest of the tool suite. The tool
 103         itself is quite straight forward, and should also be a useful example
 104         for others wishing to write python based i915 tools.
 105
 106         Note to package maintainers: It is not recommended to package
 107         this directory, as the tool is not yet designed for wide usage. If the
 108         package is installed via "make install" the users will have to set
 109         their python library path appropriately. Use --disable-dumper
 110
 111 debugger/
 112         This tool is to be used to do shader debugging. It acts like a
 113         debug server accepting connections from debug clients such as
 114         mesa. The connections is made with unix domain sockets, and at some
 115         point it would be nice if this directory contained a library for
 116         initiating connections with debug clients..
 117
 118         The debugger must be run as root: "sudo debugger/eudb"
 119
 120 docs/
 121         Thus far just contains the autogenerated intel-gpu-tools libraries
 122         reference documenation in docs/reference/ You need to have the gtk doc
 123         tools installed to generate this API documentation.
 124
 125         To regenerate the html files when updating documentation, use:
 126
 127         $ make clean -C docs && make -C docs
 128
 129         If you've added/changed/removed a symbol or anything else that changes
 130         the overall structure or indexes, this needs to be reflected in
 131         intel-gpu-tools-sections.txt. Entirely new sections will also need to be
 132         added to intel-gpu-tools-docs.xml in the appropriate place.
 133
 134 DEPENDENCIES
 135         This is a non-exchaustive list of package dependencies required for
 136         building everything:
 137
 138         libpciaccess-dev
 139         libdrm-dev
 140         xutils-dev
 141         libcairo2-dev
 142         swig2.0
 143         libpython3.3-dev
 144         x11proto-dri2-dev
 145         gtk-doc-tools