From 880c8d3c9831349a269ac6822c8d44e80807089f Mon Sep 17 00:00:00 2001 From: Arkadiusz Hiler Date: Wed, 2 Oct 2019 23:51:58 +0300 Subject: Make README more friendly * reorder sections so we have a more newbie friendly reading flow: requirements -> building -> running * add links to documentation * drop mentions of autotools * drop piglit references * don't list dependencies, just point to Dockerfiles * mention IGT containers v2: typos, articles and better formatting (Rhys Kidd) Cc: Petri Latvala Signed-off-by: Arkadiusz Hiler Reviewed-by: Rhys Kidd Acked-by: Petri Latvala --- README.md | 234 ++++++++++++++++++++++++-------------------------------------- 1 file changed, 89 insertions(+), 145 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b8c4c5a8..a6a821c0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ IGT GPU Tools ============= + Description ----------- @@ -12,200 +13,143 @@ complicated build procedures or specific testing environments to get useful results. Therefore, IGT GPU Tools includes low-level tools and tests specifically for development and testing of the DRM Drivers. -IGT GPU Tools is split into several sections: - -**benchmarks/** +Generated documentation for the latest master is published under +. -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/** +Requirements +------------ -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. +See `Dockerfile.*` for up-to-date list of package names in Fedora and +Debian. -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: +If your distribution packages IGT you can also use your package manager to +install the dependencies, e.g.: - ./scripts/run-tests.sh -d + # dnf builddep igt-gpu-tools -run-tests.sh has options for filtering and excluding tests from test -runs: +But keep in mind that this may be slightly outdated and miss some +recently added dependencies for building the current master. - -t only include tests that match the regular expression - -x 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. +Building +-------- -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. +Oneliner to get started: + $ meson build && ninja -C build -If not using the script, piglit can be obtained from: +Note that meson insist on separate build directories from the source tree. - git://anongit.freedesktop.org/piglit +Running selfchecks for `lib/tests` and `tests/` is done with -There is no need to build and install piglit if it is only going to be -used for running i-g-t tests. + $ ninja -C build test -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. +Documentation is built using -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): + $ ninja -C build igt-gpu-tools-doc - piglit-sources # ./piglit run igt -The testlist is built at runtime, so no need to update anything in -piglit when adding new tests. See +Running Tests +------------- - piglit-sources $ ./piglit run -h +In `tests/` you can find a set of automated tests to run against the DRM +drivers to validate your 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 further options and these are detailed by using +the `--help` option. -for some useful options. +Most of the test must be run as a root and with no X or Wayland compositor +running. -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. + # build/tests/core_auth + IGT-Version: 1.24 (x86_64) (Linux: 5.3.0 x86_64) + Starting subtest: getclient-simple + Subtest getclient-simple: SUCCESS (0.001s) + Starting subtest: getclient-master-drop + Subtest getclient-master-drop: SUCCESS (0.000s) + Starting subtest: basic-auth + Subtest basic-auth: SUCCESS (0.000s) + Starting subtest: many-magics + Subtest many-magics: SUCCESS (0.000s) -**lib/** + # build/tests/core_auth --run-subtest getclient-simple + IGT-Version: 1.24 (x86_64) (Linux: 5.3.0 x86_64) + Starting subtest: getclient-simple + Subtest getclient-simple: SUCCESS (0.000s) -Common helper functions and headers used by the other tools. -**man/** +The test suite can be run using the `run-tests.sh` script available in the +`scripts/` directory. To use it make sure that `igt_runner` is built, e.g.: -Manpages, unfortunately rather incomplete. + meson -Drunner=enabled build && ninja -C build -**tools/** +`run-tests.sh` has options for filtering and excluding tests from test +runs: -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. + -t only include tests that match the regular expression + -x exclude tests that match the regular expression -These tools generally must be run as root, except for the ones that just -decode dumps. +Useful patterns for test filtering are described in the [API +documentation][API] and the full list of tests and subtests can be produced +by passing `-l` to the `run-tests.sh` script. Further options are are +detailed by using the `-h` option. -**docs/** +Results are written to a JSON file. -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. +[API]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html -To regenerate the html files when updating documentation, use: - $ ninja -C build igt-gpu-tools-doc +IGT Containers +-------------- -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. +IGT is packed into nifty docker-compatible containers for ease of execution +and to avoid having to install all the dependencies. You can use +podman/docker to to run it on your system. -**include/drm-uapi** +Oneliner to get you started with the latest master: -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. + # podman run --rm --priviledged registry.freedesktop.org/drm/igt-gpu-tools/igt:master -Requirements +Other Things ------------ -This is a non-exhaustive list of package dependencies required for building -the default configuration (package names may vary): - - bison - gtk-doc-tools - flex - libcairo2-dev - libdrm-dev - libkmod-dev - libpixman-1-dev - libpciaccess-dev - libprocps-dev - libudev-dev - libunwind-dev - liblzma-dev - libdw-dev - python-docutils - x11proto-dri2-dev - xutils-dev - -The following dependencies are required for building chamelium support -(package names may vary): - - libxmlrpc-core-c3-dev - libudev-dev - libglib2.0-dev - libgsl-dev - -The following dependencies are requires for building audio support -(package names may vary): +### `benchmarks/` - libasound2-dev - libgsl-dev +A collection of useful microbenchmarks that can be used to tune DRM code. -See Dockerfiles.* for package names in different distributions. - -Meson build system support --------------------------- - -Currently we support both meson and automake as build systems, but meson is the -recommended choice. Oneliner to get started: +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. - $ mkdir build && meson build && cd build && ninja +Note that a few other microbenchmarks are in tests (e.g. `gem_gtt_speed`). -Note that meson insist on separate build directories from the source tree. +### `tools/` -Running selfchecks for lib/tests and tests/ is done with +A collection of debugging tools. They generally must be run as root, except +for the ones that just decode dumps. - $ ninja -C build test +### `docs/` -Note that this doesn't actually run the testcases in tests/: scripts/run-tests.sh -should continue to be used for that. +Contains the infrastructure to automatically generate igt-gpu-tools libraries +reference documentation. You need to have the gtk-doc tools installed. -Documentation is built using +To regenerate the html files when updating documentation, use: $ ninja -C build igt-gpu-tools-doc -Note that this needs meson v0.47 or later, earlier versions of meson do not -track depencies correctly for the documentation build and need: +If you've added/changed/removed a symbol or anything else that changes the +overall structure or indexes you need to reflect the change in +`igt-gpu-tools-sections.txt`. Entirely new sections also need to be added to +`igt-gpu-tools-docs.xml` in the appropriate place. - $ ninja -C build && ninja -C build igt-gpu-tools-doc +### `include/drm-uapi/` -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] - -Releases for maintainers ------------------------- - -(1.14) +Imported DRM uapi headers from airlied's drm-next branch. -http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/ +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 exact commit +from airlied's branch was used to generate them. -- cgit v1.2.3