[igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md
Daniel Vetter
daniel at ffwll.ch
Thu Oct 25 06:58:22 UTC 2018
On Wed, Oct 24, 2018 at 10:04:14AM -0700, Rodrigo Vivi wrote:
> 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.
I tried to do that (you need 4 spaces of indent at least). Did I miss one?
Or I'm not entirely following ...
-Daniel
>
> 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
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
More information about the igt-dev
mailing list