Commit f07bcbb4 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

README|CONTRIBUTING: Move to .md



Looks so much better in the gitlab UI. Maybe we want to split out some
of these README into subdirectories ...

v2: Polish layout a bit. Changes are only whitespace, but README is so
complicated reworked that git's rename detection doesn't spot the
similarities anymore.
Reviewed-by: default avatarRodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Daniel Vetter's avatarDaniel Vetter <daniel.vetter@intel.com>
parent caedd30d
......@@ -8,7 +8,7 @@ A short list of contribution guidelines:
- Please submit patches formatted with git send-email/git format-patch or
equivalent to:
Development mailing list for IGT GPU Tools <igt-dev@lists.freedesktop.org>
Development mailing list for IGT GPU Tools <igt-dev@lists.freedesktop.org>
For a transition period patches are accepted on both the igt-dev mailing list
and the former intel-gfx mailing list (with the appropriate patch
......@@ -18,13 +18,13 @@ A short list of contribution guidelines:
have a need to do so, as they will get deduplicated so they only appear and
are tested in one Patchwork instance.
Intel GFX discussion <intel-gfx@lists.freedesktop.org>
Intel GFX discussion <intel-gfx@lists.freedesktop.org>
Please use --subject-prefix="PATCH i-g-t" so IGT patches are easily
identified in the massive amount mails on intel-gfx. To ensure this is always
done, meson.sh (and autogen.sh) will run:
git config format.subjectprefix "PATCH i-g-t"
git config format.subjectprefix "PATCH i-g-t"
on its first invocation.
......
......@@ -14,125 +14,133 @@ specifically for development and testing of the DRM Drivers.
IGT 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.
**benchmarks/**
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.
This is a collection of useful microbenchmarks that can be used to tune
DRM code in relevant ways.
Note that a few other microbenchmarks are in tests (like gem_gtt_speed).
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.
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.
Note that a few other microbenchmarks are in tests (like gem_gtt_speed).
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:
**tests/**
./scripts/run-tests.sh -d
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.
run-tests.sh has options for filtering and excluding tests from test
runs:
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:
-t <regex> only include tests that match the regular expression
-x <regex> exclude tests that match the regular expression
./scripts/run-tests.sh -d
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.
run-tests.sh has options for filtering and excluding tests from test
runs:
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.
-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.
If not using the script, piglit can be obtained from:
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.
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.
If not using the script, piglit can be obtained from:
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 igt-gpu-tools root directory.
git://anongit.freedesktop.org/piglit
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):
There is no need to build and install piglit if it is only going to be
used for running i-g-t tests.
piglit-sources # ./piglit run igt <results-file>
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 igt-gpu-tools root directory.
The testlist is built at runtime, so no need to update anything in
piglit when adding new tests. See
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 -h
piglit-sources # ./piglit run igt <results-file>
for some useful options.
The testlist is built at runtime, so no need to update anything in
piglit when adding new tests. See
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.
piglit-sources $ ./piglit run -h
lib/
Common helper functions and headers used by the other tools.
for some useful options.
man/
Manpages, unfortunately rather incomplete.
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.
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.
**lib/**
These tools generally must be run as root, except for the ones that just
decode dumps.
Common helper functions and headers used by the other tools.
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..
**man/**
The debugger must be run as root: "sudo debugger/eudb"
Manpages, unfortunately rather incomplete.
docs/
Contains the automatically generated igt-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.
**tools/**
To regenerate the html files when updating documentation, use:
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.
$ make clean -C docs && make -C docs
These tools generally must be run as root, except for the ones that just
decode dumps.
If you've added/changed/removed a symbol or anything else that changes
the overall structure or indexes, this needs to be reflected in
igt-gpu-tools-sections.txt. Entirely new sections will also need to be
added to igt-gpu-tools-docs.xml in the appropriate place.
**debugger/**
include/drm-uapi
Imported DRM uapi headers from airlied's drm-next branch.
These should be updated all together by executing "make
headers_install" from that branch of the kernel and then
copying the resulting ./usr/include/drm/*.h in and committing
with a note of which commit on airlied's branch was used to
generate them.
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 igt-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
igt-gpu-tools-sections.txt. Entirely new sections will also need to be
added to igt-gpu-tools-docs.xml in the appropriate place.
**include/drm-uapi**
Imported DRM uapi headers from airlied's drm-next branch.
These should be updated all together by executing "make
headers_install" from that branch of the kernel and then
copying the resulting ./usr/include/drm/*.h in and committing
with a note of which commit on airlied's branch was used to
generate them.
Requirements
......@@ -174,25 +182,25 @@ Meson build system support
Currently we support both meson and automake as build systems, but meson is the
recommended choice. Oneliner to get started:
$ mkdir build && meson build && cd build && ninja
$ mkdir build && meson build && cd build && ninja
Note that meson insist on separate build directories from the source tree.
Running selfchecks for lib/tests and tests/ is done with
$ cd build && ninja test
$ cd build && ninja test
Note that this doesn't actually run the testcases in tests/: scripts/run-tests.sh
should continue to be used for that.
Documentation is built using
$ cd build && ninja && ninja igt-gpu-tools-doc
$ cd build && ninja && ninja igt-gpu-tools-doc
Note that there's a setup script similar to ./autogen.sh which creates a
compatibility Makefile with a few useful default targets:
$ ./meson.sh [make-arguments]
$ ./meson.sh [make-arguments]
Releases for maintainers
------------------------
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment