1IGT GPU Tools 2============= 3 4Description 5----------- 6 7IGT GPU Tools is a collection of tools for development and testing of the DRM 8drivers. There are many macro-level test suites that get used against the 9drivers, including xtest, rendercheck, piglit, and oglconform, but failures from 10those can be difficult to track down to kernel changes, and many require 11complicated build procedures or specific testing environments to get useful 12results. Therefore, IGT GPU Tools includes low-level tools and tests 13specifically for development and testing of the DRM Drivers. 14 15IGT GPU Tools is split into several sections: 16 17**benchmarks/** 18 19This is a collection of useful microbenchmarks that can be used to tune 20DRM code in relevant ways. 21 22The benchmarks require KMS to be enabled. When run with an X Server 23running, they must be run as root to avoid the authentication 24requirement. 25 26Note that a few other microbenchmarks are in tests (like gem_gtt_speed). 27 28**tests/** 29 30This is a set of automated tests to run against the DRM to validate 31changes. Many of the tests have subtests, which can be listed by using 32the --list-subtests command line option and then run using the 33--run-subtest option. If --run-subtest is not used, all subtests will 34be run. Some tests have futher options and these are detailed by using 35the --help option. 36 37The test suite can be run using the run-tests.sh script available in 38the scripts directory. Piglit is used to run the tests and can either 39be installed from your distribution (if available), or can be 40downloaded locally for use with the script by running: 41 42 ./scripts/run-tests.sh -d 43 44run-tests.sh has options for filtering and excluding tests from test 45runs: 46 47 -t <regex> only include tests that match the regular expression 48 -x <regex> exclude tests that match the regular expression 49 50Useful patterns for test filtering are described in the API 51documentation and the full list of tests and subtests can be produced 52by passing -l to the run-tests.sh script. 53 54Results are written to a JSON file and an HTML summary can also be 55created by passing -s to the run-tests.sh script. Further options are 56are detailed by using the -h option. 57 58 59If not using the script, piglit can be obtained from: 60 61 git://anongit.freedesktop.org/piglit 62 63There is no need to build and install piglit if it is only going to be 64used for running i-g-t tests. 65 66Set the IGT_TEST_ROOT environment variable to point to the tests 67directory, or set the path key in the "igt" section of piglit.conf to 68the igt-gpu-tools root directory. 69 70The tests in the i-g-t sources need to have been built already. Then we 71can run the testcases with (as usual as root, no other drm clients 72running): 73 74 piglit-sources # ./piglit run igt <results-file> 75 76The testlist is built at runtime, so no need to update anything in 77piglit when adding new tests. See 78 79 piglit-sources $ ./piglit run -h 80 81for some useful options. 82 83Piglit only runs a default set of tests and is useful for regression 84testing. Other tests not run are: 85- tests that might hang the gpu, see HANG in Makefile.am 86- gem_stress, a stress test suite. Look at the source for all the 87 various options. 88- testdisplay is only run in the default mode. testdisplay has tons of 89 options to test different kms functionality, again read the source for 90 the details. 91 92**lib/** 93 94Common helper functions and headers used by the other tools. 95 96**man/** 97 98Manpages, unfortunately rather incomplete. 99 100**tools/** 101 102This is a collection of debugging tools that had previously been 103built with the 2D driver but not shipped. Some distros were hacking 104up the 2D build to ship them. Instead, here's a separate package for 105people debugging the driver. 106 107These tools generally must be run as root, except for the ones that just 108decode dumps. 109 110**docs/** 111 112Contains the automatically generated igt-gpu-tools libraries 113reference documentation in docs/reference/. You need to have the 114gtk-doc tools installed and use the "--enable-gtk-doc" configure flag 115to generate this API documentation. 116 117To regenerate the html files when updating documentation, use: 118 119 $ ninja -C build igt-gpu-tools-doc 120 121If you've added/changed/removed a symbol or anything else that changes 122the overall structure or indexes, this needs to be reflected in 123igt-gpu-tools-sections.txt. Entirely new sections will also need to be 124added to igt-gpu-tools-docs.xml in the appropriate place. 125 126**include/drm-uapi** 127 128Imported DRM uapi headers from airlied's drm-next branch. 129These should be updated all together by executing "make 130headers_install" from that branch of the kernel and then 131copying the resulting ./usr/include/drm/*.h in and committing 132with a note of which commit on airlied's branch was used to 133generate them. 134 135 136Requirements 137------------ 138 139This is a non-exhaustive list of package dependencies required for building 140the default configuration (package names may vary): 141 142 bison 143 gtk-doc-tools 144 flex 145 libcairo2-dev 146 libdrm-dev 147 libkmod-dev 148 libpixman-1-dev 149 libpciaccess-dev 150 libprocps-dev 151 libudev-dev 152 libunwind-dev 153 liblzma-dev 154 libdw-dev 155 python-docutils 156 x11proto-dri2-dev 157 xutils-dev 158 159The following dependencies are required for building chamelium support 160(package names may vary): 161 162 libxmlrpc-core-c3-dev 163 libudev-dev 164 libglib2.0-dev 165 libgsl-dev 166 167The following dependencies are requires for building audio support 168(package names may vary): 169 170 libasound2-dev 171 libgsl-dev 172 173See Dockerfiles.* for package names in different distributions. 174 175Meson build system support 176-------------------------- 177 178Currently we support both meson and automake as build systems, but meson is the 179recommended choice. Oneliner to get started: 180 181 $ mkdir build && meson build && cd build && ninja 182 183Note that meson insist on separate build directories from the source tree. 184 185Running selfchecks for lib/tests and tests/ is done with 186 187 $ ninja -C build test 188 189Note that this doesn't actually run the testcases in tests/: scripts/run-tests.sh 190should continue to be used for that. 191 192Documentation is built using 193 194 $ ninja -C build igt-gpu-tools-doc 195 196Note that this needs meson v0.47 or later, earlier versions of meson do not 197track depencies correctly for the documentation build and need: 198 199 $ ninja -C build && ninja -C build igt-gpu-tools-doc 200 201Note that there's a setup script similar to ./autogen.sh which creates a 202compatibility Makefile with a few useful default targets: 203 204 $ ./meson.sh [make-arguments] 205 206Releases for maintainers 207------------------------ 208 209(1.14) 210 211http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/ 212