[igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md
Rodrigo Vivi
rodrigo.vivi at intel.com
Wed Oct 24 17:04:14 UTC 2018
On Wed, Oct 24, 2018 at 03:34:21PM +0200, Daniel Vetter wrote:
> 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.
>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
> Note this needs Petri's earlier patch to apply cleanly.
> -Daniel
> ---
> CONTRIBUTING => CONTRIBUTING.md | 6 +-
> README | 202 ------------------------------
> README.md | 210 ++++++++++++++++++++++++++++++++
> 3 files changed, 213 insertions(+), 205 deletions(-)
> rename CONTRIBUTING => CONTRIBUTING.md (95%)
> delete mode 100644 README
> create mode 100644 README.md
>
> diff --git a/CONTRIBUTING b/CONTRIBUTING.md
> similarity index 95%
> rename from CONTRIBUTING
> rename to CONTRIBUTING.md
> index 1a68fcf5cc9c..27c8e7967b93 100644
> --- a/CONTRIBUTING
> +++ b/CONTRIBUTING.md
> @@ -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 at lists.freedesktop.org>
> + Development mailing list for IGT GPU Tools <igt-dev at 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 at lists.freedesktop.org>
> + Intel GFX discussion <intel-gfx at 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.
>
> diff --git a/README b/README
> deleted file mode 100644
> index 78d14060dccd..000000000000
> --- 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 <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 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.
> -
> -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 000000000000..dcff03efdbac
> --- /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 <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 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
```bash
> +
> + piglit-sources $ ./piglit run -h
> +
```
I believe all blocks with command lines could be in the markdown block
like this ```bash or something like that.
But this can be done in a follow-up since it gets easier to review
I think...
so:
Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
> +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/
> --
> 2.19.1
>
> _______________________________________________
> igt-dev mailing list
> igt-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/igt-dev
More information about the igt-dev
mailing list