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         Note: The old automake based testrunner had to be scraped due to
  28         upstream changes which broke dynamic creation of the test list. Of
  29         course it is still possible to directly run tests, even when not always
  30         limiting tests to specific subtests (like piglit does).
  31
  32         The more comfortable way to run tests is with piglit. First grab piglit
  33         from:
  34
  35         git://anongit.freedesktop.org/piglit
  36
  37         and build it (no need to install anything). Then we need to link up the
  38         i-g-t sources with piglit
  39
  40         piglit-sources $ cd bin
  41         piglit-sources/bin $ ln $i-g-t-sources igt -s
  42
  43         To avoid some hassles with piglit's use of Waffle just disable it. Run
  44
  45         piglit-sources $ cmake -D PIGLIT_USE_WAFFLE=OFF .
  46
  47         With
  48
  49         piglit-sources $ ccmake .
  50
  51         you can check your configuration with a curses interface, too.
  52
  53         The tests in the i-g-t sources need to have been built already. Then we
  54         can run the testcases with (as usual as root, no other drm clients
  55         running):
  56
  57         piglit-sources # ./piglit-run.py tests/igt.tests <results-file>
  58
  59         The testlist is built at runtime, so no need to update anything in
  60         piglit when adding new tests. See
  61
  62         piglit-sources $ ./piglit-run.py -h
  63
  64         for some useful options.
  65
  66         Piglit only runs a default set of tests and is useful for regression
  67         testing. Other tests not run are:
  68         - tests that might hang the gpu, see HANG in Makefile.am
  69         - gem_stress, a stress test suite. Look at the source for all the
  70           various options.
  71         - testdisplay is only run in the default mode. testdisplay has tons of
  72           options to test different kms functionality, again read the source for
  73           the details.
  74
  75         When creating new tests or subtests please read and follow
  76         tests/NAMING-CONVENTION.
  77
  78 lib/
  79         Common helper functions and headers used by the other tools.
  80
  81 man/
  82         Manpages, unfortunately rather incomplete.
  83
  84 tools/
  85         This is a collection of debugging tools that had previously been
  86         built with the 2D driver but not shipped.  Some distros were hacking
  87         up the 2D build to ship them.  Instead, here's a separate package for
  88         people debugging the driver.
  89
  90         These tools generally must be run as root, safe for the ones that just
  91         decode dumps.
  92
  93 tools/quick_dump
  94         Quick dumper is a python tool built with SWIG bindings to
  95         important libraries exported by the rest of the tool suite. The tool
  96         itself is quite straight forward, and should also be a useful example
  97         for others wishing to write python based i915 tools.
  98
  99         Note to package maintainers: It is not recommended to package
 100         this directory, as the tool is not yet designed for wide usage. If the
 101         package is installed via "make install" the users will have to set
 102         their python library path appropriately. Use --disable-dumper
 103
 104 debugger/
 105         This tool is to be used to do shader debugging. It acts like a
 106         debug server accepting connections from debug clients such as
 107         mesa. The connections is made with unix domain sockets, and at some
 108         point it would be nice if this directory contained a library for
 109         initiating connections with debug clients..
 110
 111         The debugger must be run as root: "sudo debugger/eudb"
 112
 113 DEPENDENCIES
 114         This is a non-exchaustive list of package dependencies required for
 115         building everything:
 116
 117         libpciaccess-dev
 118         libdrm-dev
 119         xutils-dev
 120         libcairo2-dev
 121         swig2.0
 122         libpython3.3-dev
 123         x11proto-dri2-dev