mirror of
https://github.com/tiagovignatti/intel-gpu-tools.git
synced 2025-06-07 16:06:25 +00:00
498fb6205e
The tests/NAMING-CONVENTION file has been removed and its contents is now included in the API documentation. Reported-by: Joonas Lahtinen <joonas.lahtinen@linux.intel.com> Signed-off-by: Thomas Wood <thomas.wood@intel.com>
144 lines
5.0 KiB
Plaintext
144 lines
5.0 KiB
Plaintext
Intel GPU Tools
|
|
===============
|
|
|
|
Description
|
|
-----------
|
|
|
|
Intel GPU Tools is a collection of tools for development and testing of the
|
|
Intel DRM driver. There are many macro-level test suites that get used against
|
|
the driver, including xtest, rendercheck, piglit, and oglconform, but failures
|
|
from those can be difficult to track down to kernel changes, and many require
|
|
complicated build procedures or specific testing environments to get useful
|
|
results. Therefore, Intel GPU Tools includes low-level tools and tests
|
|
specifically for development and testing of the Intel DRM Driver.
|
|
|
|
Intel GPU Tools is split into several sections:
|
|
|
|
benchmarks/
|
|
This is a collection of useful microbenchmarks that can be used to tune
|
|
DRM code in relevant ways.
|
|
|
|
The benchmarks require KMS to be enabled. When run with an X Server
|
|
running, they must be run as root to avoid the authentication
|
|
requirement.
|
|
|
|
Note that a few other microbenchmarks are in tests (like gem_gtt_speed).
|
|
|
|
tests/
|
|
This is a set of automated tests to run against the DRM to validate
|
|
changes. Many of the tests have subtests, which can be listed by using
|
|
the --list-subtests command line option and then run using the
|
|
--run-subtest option. If --run-subtest is not used, all subtests will
|
|
be run. Some tests have futher options and these are detailed by using
|
|
the --help option.
|
|
|
|
The test suite can be run using the run-tests.sh script available in
|
|
the scripts directory. Piglit is used to run the tests and can either
|
|
be installed from your distribution (if available), or can be
|
|
downloaded locally for use with the script by running:
|
|
|
|
./scripts/run-tests.sh -d
|
|
|
|
run-tests.sh has options for filtering and excluding tests from test
|
|
runs:
|
|
|
|
-t <regex> only include tests that match the regular expression
|
|
-x <regex> exclude tests that match the regular expression
|
|
|
|
Useful patterns for test filtering are described in the API
|
|
documentation and the full list of tests and subtests can be produced
|
|
by passing -l to the run-tests.sh script.
|
|
|
|
Results are written to a JSON file and an HTML summary can also be
|
|
created by passing -s to the run-tests.sh script. Further options are
|
|
are detailed by using the -h option.
|
|
|
|
|
|
If not using the script, piglit can be obtained from:
|
|
|
|
git://anongit.freedesktop.org/piglit
|
|
|
|
There is no need to build and install piglit if it is only going to be
|
|
used for running i-g-t tests.
|
|
|
|
Set the IGT_TEST_ROOT environment variable to point to the tests
|
|
directory, or set the path key in the "igt" section of piglit.conf to
|
|
the intel-gpu-tools root directory.
|
|
|
|
The tests in the i-g-t sources need to have been built already. Then we
|
|
can run the testcases with (as usual as root, no other drm clients
|
|
running):
|
|
|
|
piglit-sources # ./piglit run igt <results-file>
|
|
|
|
The testlist is built at runtime, so no need to update anything in
|
|
piglit when adding new tests. See
|
|
|
|
piglit-sources $ ./piglit run -h
|
|
|
|
for some useful options.
|
|
|
|
Piglit only runs a default set of tests and is useful for regression
|
|
testing. Other tests not run are:
|
|
- tests that might hang the gpu, see HANG in Makefile.am
|
|
- gem_stress, a stress test suite. Look at the source for all the
|
|
various options.
|
|
- testdisplay is only run in the default mode. testdisplay has tons of
|
|
options to test different kms functionality, again read the source for
|
|
the details.
|
|
|
|
lib/
|
|
Common helper functions and headers used by the other tools.
|
|
|
|
man/
|
|
Manpages, unfortunately rather incomplete.
|
|
|
|
tools/
|
|
This is a collection of debugging tools that had previously been
|
|
built with the 2D driver but not shipped. Some distros were hacking
|
|
up the 2D build to ship them. Instead, here's a separate package for
|
|
people debugging the driver.
|
|
|
|
These tools generally must be run as root, safe for the ones that just
|
|
decode dumps.
|
|
|
|
debugger/
|
|
This tool is to be used to do shader debugging. It acts like a
|
|
debug server accepting connections from debug clients such as
|
|
mesa. The connections is made with unix domain sockets, and at some
|
|
point it would be nice if this directory contained a library for
|
|
initiating connections with debug clients..
|
|
|
|
The debugger must be run as root: "sudo debugger/eudb"
|
|
|
|
docs/
|
|
Contains the automatically generated intel-gpu-tools libraries
|
|
reference documentation in docs/reference/. You need to have the
|
|
gtk-doc tools installed and use the "--enable-gtk-doc" configure flag
|
|
to generate this API documentation.
|
|
|
|
To regenerate the html files when updating documentation, use:
|
|
|
|
$ make clean -C docs && make -C docs
|
|
|
|
If you've added/changed/removed a symbol or anything else that changes
|
|
the overall structure or indexes, this needs to be reflected in
|
|
intel-gpu-tools-sections.txt. Entirely new sections will also need to be
|
|
added to intel-gpu-tools-docs.xml in the appropriate place.
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
This is a non-exhaustive list of package dependencies required for building
|
|
everything (package names may vary):
|
|
|
|
gtk-doc-tools
|
|
libcairo2-dev
|
|
libdrm-dev
|
|
libpciaccess-dev
|
|
libunwind-dev
|
|
python-docutils
|
|
x11proto-dri2-dev
|
|
xutils-dev
|