<div dir="ltr"><div dir="ltr"> </div><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, 3 Oct 2019 at 23:07, Arkadiusz Hiler <<a href="mailto:arkadiusz.hiler@intel.com">arkadiusz.hiler@intel.com</a>> wrote: </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">* 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 Cc: Petri Latvala <<a href="mailto:petri.latvala@intel.com" target="_blank">petri.latvala@intel.com</a>> Signed-off-by: Arkadiusz Hiler <<a href="mailto:arkadiusz.hiler@intel.com" target="_blank">arkadiusz.hiler@intel.com</a>> --- README.md | 280 ++++++++++++++++++++++-------------------------------- 1 file changed, 112 insertions(+), 168 deletions(-) diff --git a/README.md b/README.md index b8c4c5a8..b295dc3e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ IGT GPU Tools ============= + Description ----------- @@ -12,173 +13,31 @@ 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/** - -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://<a href="http://anongit.freedesktop.org/piglit" rel="noreferrer" target="_blank">anongit.freedesktop.org/piglit</a> - -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 igt-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, except for the ones that just -decode dumps. - -**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: - - $ ninja -C build igt-gpu-tools-doc - -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. +Generated documentation for the latest master is published under +<<a href="https://drm.pages.freedesktop.org/igt-gpu-tools/" rel="noreferrer" target="_blank">https://drm.pages.freedesktop.org/igt-gpu-tools/</a>>. Requirements ------------ -This is a non-exhaustive list of package dependencies required for building -the default configuration (package names may vary): +See `Dockerfiles.*` for up-to-date list of packages names in Fedora and </blockquote><div> </div><div>s/Dockerfiles/Dockerfile/</div><div>s/packages/package/ </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> +Debian. - 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 +If your distribution packages IGT you can also use your package manager to +install the dependencies, e.g.: -The following dependencies are required for building chamelium support -(package names may vary): + # dnf builddep igt-gpu-tools - libxmlrpc-core-c3-dev - libudev-dev - libglib2.0-dev - libgsl-dev +But keep in mind that this may be slightly outdated and miss some +recently added dependencies for building the current master. -The following dependencies are requires for building audio support -(package names may vary): - libasound2-dev - libgsl-dev +Building +-------- -See Dockerfiles.* for package names in different distributions. +Oneliner to get started: -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 + $ meson build && ninja -C build Note that meson insist on separate build directories from the source tree. @@ -186,26 +45,111 @@ Running selfchecks for lib/tests and tests/ is done with </blockquote><div> </div><div>In v2, whilst you're here, can you also amend the prior line to properly format the two folder</div><div>references to be consistent with the rest of this README:</div><div> </div><div> Running selfchecks for `lib/tests` and `tests/` is done with</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> $ ninja -C build 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 $ 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: - $ ninja -C build && ninja -C build igt-gpu-tools-doc +Running Tests +------------- -Note that there's a setup script similar to ./autogen.sh which creates a -compatibility Makefile with a few useful default targets: +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. - $ ./meson.sh [make-arguments] +Most of the test must be run as a root and with no X or Wayland compositor +running. -Releases for maintainers ------------------------- + # 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) -(1.14) + # 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) -<a href="http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/" rel="noreferrer" target="_blank">http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/</a> + +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.: + + meson -Drunner=enabled build && ninja -C build + +`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][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. + +Results are written to a JSON file. + +[API]: <a href="https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html" rel="noreferrer" target="_blank">https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html</a> + + +IGT Containers +-------------- + +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. + +Oneliner to get you started with the latest master: + + # podman run --rm --priviledged <a href="http://registry.freedesktop.org/drm/igt-gpu-tools/igt:master" rel="noreferrer" target="_blank">registry.freedesktop.org/drm/igt-gpu-tools/igt:master</a> + + +Other Things +------------ + +### `benchmarks/` + +A collection of useful microbenchmarks that can be used to tune DRM code. + +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 (e.g. `gem_gtt_speed`). + +### `tools/` + +A collection of debugging tools. They generally must be run as root, except +for the ones that just decode dumps. + +### `docs/` + +Contains the infrastracture to automatically generate igt-gpu-tools libraries </blockquote><div> </div><div>s/infrastracture/infrastructure/</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> +reference documentation. You need to have the gtk-doc tools installed. + +To regenerate the html files when updating documentation, use: + + $ ninja -C build igt-gpu-tools-doc + +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. + +### `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 exact commit +from the airlied's branch was used to generate them. </blockquote><div> </div><div>s/the// </div><div> </div><div>With these couple of small nits fixed, this gets my:</div><div>Reviewed-by: Rhys Kidd <<a href="mailto:rhyskidd@gmail.com">rhyskidd@gmail.com</a>></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> -- 2.21.0 _______________________________________________ igt-dev mailing list <a href="mailto:igt-dev@lists.freedesktop.org" target="_blank">igt-dev@lists.freedesktop.org</a> <a href="https://lists.freedesktop.org/mailman/listinfo/igt-dev" rel="noreferrer" target="_blank">https://lists.freedesktop.org/mailman/listinfo/igt-dev</a></blockquote></div></div>