From f07bcbb4dc419ea6cffde28f1ace57c7c8f19cd8 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 24 Oct 2018 15:34:21 +0200 Subject: 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: Rodrigo Vivi Signed-off-by: Daniel Vetter --- CONTRIBUTING | 101 --------------------------- CONTRIBUTING.md | 101 +++++++++++++++++++++++++++ README | 202 ----------------------------------------------------- README.md | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 311 insertions(+), 303 deletions(-) delete mode 100644 CONTRIBUTING create mode 100644 CONTRIBUTING.md delete mode 100644 README create mode 100644 README.md diff --git a/CONTRIBUTING b/CONTRIBUTING deleted file mode 100644 index 1a68fcf5..00000000 --- a/CONTRIBUTING +++ /dev/null @@ -1,101 +0,0 @@ -Patches to igt-gpu-tools are very much welcome, we really want this to be the -universal set of low-level tools and testcases for the Intel kernel gfx driver -on Linux and similar platforms. So please bring on porting patches, bugfixes, -improvements for documentation and new tools and testcases. - -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 - - 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 - subjectprefix, see below). - - During the transition period, feel free to send patches to both lists if you - 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 - - 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" - - on its first invocation. - -- igt-gpu-tools is MIT licensed and we require contributions to follow the - developer's certificate of origin: http://developercertificate.org/ - -- When submitting new testcases please follow the naming conventions documented - in the generated documentation. Also please make full use of all the helpers - and convenience macros provided by the igt library. The semantic patch - lib/igt.cocci can help with the more automatic conversions. - -- Patches need to be reviewed on the mailing list. Exceptions only apply for - testcases and tooling for drivers with just a single contributor (e.g. vc4). - In this case patches must still be submitted to the mailing list first. - Testcase should preferably be cross-reviewed by the same people who write and - review the kernel feature itself. - -- When patches from new contributors (without commit access) are stuck, for - anything related to the regular releases, issues with packaging and - integrating platform support or any other igt-gpu-tools issues, please - contact one of the maintainers (listed in the MAINTAINERS file) and cc the - igt-dev mailing list. - -- Changes to the testcases are automatically tested. Take the results into - account before merging. - -Commit rights -------------- - -Commit rights will be granted to anyone who requests them and fulfills the -below criteria: - -- Submitted a few (5-10 as a rule of thumb) non-trivial (not just simple - spelling fixes and whitespace adjustment) patches that have been merged - already. - -- Are actively participating on discussions about their work (on the mailing - list or IRC). This should not be interpreted as a requirement to review other - peoples patches but just make sure that patch submission isn't one-way - communication. Cross-review is still highly encouraged. - -- Will be regularly contributing further patches. This includes regular - contributors to other parts of the open source graphics stack who only - do the oddball rare patch within igt itself. - -- Agrees to use their commit rights in accordance with the documented merge - criteria, tools, and processes. - -Create a gitlab account at https://gitlab.freedesktop.org/ and apply -for access to the IGT gitlab project, -http://gitlab.freedesktop.org/drm/igt-gpu-tools and please ping the -maintainers if your request is stuck. - -Committers are encouraged to request their commit rights get removed when they -no longer contribute to the project. Commit rights will be reinstated when they -come back to the project. - -Maintainers and committers should encourage contributors to request commit -rights, especially junior contributors tend to underestimate their skills. - -Code of Conduct ---------------- - -Please be aware the fd.o Code of Conduct also applies to igt: - -https://www.freedesktop.org/wiki/CodeOfConduct/ - -See the MAINTAINERS file for contact details of the igt maintainers. - -Abuse of commit rights, like engaging in commit fights or willfully pushing -patches that violate the documented merge criteria, will also be handled through -the Code of Conduct enforcement process. - -Happy hacking! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..27c8e796 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +Patches to igt-gpu-tools are very much welcome, we really want this to be the +universal set of low-level tools and testcases for the Intel kernel gfx driver +on Linux and similar platforms. So please bring on porting patches, bugfixes, +improvements for documentation and new tools and testcases. + +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 + + 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 + subjectprefix, see below). + + During the transition period, feel free to send patches to both lists if you + 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 + + 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" + + on its first invocation. + +- igt-gpu-tools is MIT licensed and we require contributions to follow the + developer's certificate of origin: http://developercertificate.org/ + +- When submitting new testcases please follow the naming conventions documented + in the generated documentation. Also please make full use of all the helpers + and convenience macros provided by the igt library. The semantic patch + lib/igt.cocci can help with the more automatic conversions. + +- Patches need to be reviewed on the mailing list. Exceptions only apply for + testcases and tooling for drivers with just a single contributor (e.g. vc4). + In this case patches must still be submitted to the mailing list first. + Testcase should preferably be cross-reviewed by the same people who write and + review the kernel feature itself. + +- When patches from new contributors (without commit access) are stuck, for + anything related to the regular releases, issues with packaging and + integrating platform support or any other igt-gpu-tools issues, please + contact one of the maintainers (listed in the MAINTAINERS file) and cc the + igt-dev mailing list. + +- Changes to the testcases are automatically tested. Take the results into + account before merging. + +Commit rights +------------- + +Commit rights will be granted to anyone who requests them and fulfills the +below criteria: + +- Submitted a few (5-10 as a rule of thumb) non-trivial (not just simple + spelling fixes and whitespace adjustment) patches that have been merged + already. + +- Are actively participating on discussions about their work (on the mailing + list or IRC). This should not be interpreted as a requirement to review other + peoples patches but just make sure that patch submission isn't one-way + communication. Cross-review is still highly encouraged. + +- Will be regularly contributing further patches. This includes regular + contributors to other parts of the open source graphics stack who only + do the oddball rare patch within igt itself. + +- Agrees to use their commit rights in accordance with the documented merge + criteria, tools, and processes. + +Create a gitlab account at https://gitlab.freedesktop.org/ and apply +for access to the IGT gitlab project, +http://gitlab.freedesktop.org/drm/igt-gpu-tools and please ping the +maintainers if your request is stuck. + +Committers are encouraged to request their commit rights get removed when they +no longer contribute to the project. Commit rights will be reinstated when they +come back to the project. + +Maintainers and committers should encourage contributors to request commit +rights, especially junior contributors tend to underestimate their skills. + +Code of Conduct +--------------- + +Please be aware the fd.o Code of Conduct also applies to igt: + +https://www.freedesktop.org/wiki/CodeOfConduct/ + +See the MAINTAINERS file for contact details of the igt maintainers. + +Abuse of commit rights, like engaging in commit fights or willfully pushing +patches that violate the documented merge criteria, will also be handled through +the Code of Conduct enforcement process. + +Happy hacking! diff --git a/README b/README deleted file mode 100644 index 78d14060..00000000 --- a/README +++ /dev/null @@ -1,202 +0,0 @@ -IGT GPU Tools -============= - -Description ------------ - -IGT GPU Tools is a collection of tools for development and testing of the DRM -drivers. There are many macro-level test suites that get used against the -drivers, 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, 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 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. - - 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 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 - - 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. - -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 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 ------------- - -This is a non-exhaustive list of package dependencies required for building -the default configuration (package names may vary): - - gtk-doc-tools - libcairo2-dev - libdrm-dev - libkmod-dev - libpixman-1-dev - libpciaccess-dev - libprocps-dev - libunwind-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): - - libasound2-dev - libgsl-dev - -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 - -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 - -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 - -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) - -http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/ diff --git a/README.md b/README.md new file mode 100644 index 00000000..dcff03ef --- /dev/null +++ b/README.md @@ -0,0 +1,210 @@ +IGT GPU Tools +============= + +Description +----------- + +IGT GPU Tools is a collection of tools for development and testing of the DRM +drivers. There are many macro-level test suites that get used against the +drivers, 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, 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 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. + +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 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 + +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. + +**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 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 +------------ + +This is a non-exhaustive list of package dependencies required for building +the default configuration (package names may vary): + + gtk-doc-tools + libcairo2-dev + libdrm-dev + libkmod-dev + libpixman-1-dev + libpciaccess-dev + libprocps-dev + libunwind-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): + + libasound2-dev + libgsl-dev + +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 + +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 + +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 + +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) + +http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/ -- cgit v1.2.3