Fix documentation issues
cover Fix documentation issues
- fixed typos in the text
- fixed warnings during build
- fixed errors during build
- fixed incorrect struct usage
---
Andrea Cervesato (4):
doc: Fix broken references and outdated content
doc: Fix typos and grammar
include: Fix kernel-doc warnings in header comments
doc: Fix incorrect struct tst_test field references
doc/developers/api_c_tests.rst | 2 +- doc/developers/api_shell_tests.rst | 4 ++-- doc/developers/build_system.rst | 6 ++--- doc/developers/documentation.rst | 6 ++--- doc/developers/ground_rules.rst | 16 ++++++------- doc/developers/setup_mailinglist.rst | 2 +- doc/developers/test_case_tutorial.rst | 23 ++++++++----------- doc/developers/todo.rst | 4 ++-- doc/developers/writing_tests.rst | 38 +++++++++++++++---------------- doc/index.rst | 2 +- doc/maintainers/ltp_release_procedure.rst | 6 ++--- doc/maintainers/patch_review.rst | 12 +++++----- doc/users/quick_start.rst | 10 ++++---- doc/users/setup_tests.rst | 2 +- doc/users/supported_systems.rst | 6 ++--- doc/users/testers_guide.rst | 6 ++--- include/tst_capability.h | 2 +- include/tst_cmd.h | 4 ++-- include/tst_kvercmp.h | 2 +- include/tst_test.h | 16 ++++++------- include/tst_test_macros.h | 8 +++---- 21 files changed, 87 insertions(+), 90 deletions(-)
---
base-commit: 5ccf816f5d0e6c0ec3d808be456dd9ffa2a7736d
change-id: 20260601-doc_update-a31e6a63d27b
Best regards,
Signature · 5 lines
Andrea Cervesato <[email protected]> -- Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 1/4 doc: Fix broken references and outdated content
From: Andrea Cervesato <[email protected]>
Fix kernel-doc reference to renamed tse_numa.h header, correct TST_EXP_POSSITIVE typo and RST formatting in tst_test_macros.h, use :c:struct: instead of :ref: for struct cross-references, fix broken lapi/ :master: links, drop stale lapi/stat.h notes, correct kirk invocation example and use md5sum/sha1sum commands.
--- doc/developers/api_c_tests.rst | 2 +- doc/developers/api_shell_tests.rst | 2 +- doc/developers/test_case_tutorial.rst | 19 ++++++++----------- doc/developers/todo.rst | 2 +- doc/developers/writing_tests.rst | 6 +++--- doc/maintainers/ltp_release_procedure.rst | 4 ++-- doc/maintainers/patch_review.rst | 6 +++--- include/tst_test_macros.h | 8 ++++---- 8 files changed, 23 insertions(+), 26 deletions(-)
doc/developers/api_c_tests.rst +1 -1
@@ -50,7 +50,7 @@ Process state NUMA ---- -.. kernel-doc:: ../../include/tst_numa.h +.. kernel-doc:: ../../include/tse_numa.h Option parsing --------------
doc/developers/api_shell_tests.rst +1 -1
@@ -30,7 +30,7 @@ documentation at https://linux-test-project.readthedocs.io/en/latest/users/test_ The shell loader test library uses the :doc:`../developers/api_c_tests` internally by parsing a special JSON formatted comment and initializing it accordingly. The JSON format is nearly 1:1 serialization of the -:ref:`struct tst_test` into a JSON. The environment must be always preset even +:c:struct:`tst_test` into a JSON. The environment must be always preset even when it's empty. .. code-block:: shell
doc/developers/test_case_tutorial.rst +8 -11
@@ -137,7 +137,7 @@ initialization code. It is important to note that this is a completely ordinary, independent C program, however ``main()`` is missing because it is implemented in :master:`include/tst_test.h`. -We specify what code we want to run as part of the test using :ref:`struct tst_test`. +We specify what code we want to run as part of the test using :c:struct:`tst_test`. Various callbacks can be set by the test writer, including ``test.test_all``, which we have set to ``run()``. The test harness will execute this callback in a separate process (using ``fork()``), forcibly terminating it
@@ -205,8 +205,8 @@ please do: This should build the test and then run it. However, even though the test is in :master:`testcases/kernel/syscalls` directory it won't be automatically ran -as part of the syscalls test group (e.g. not run via ``kirk -r math``. For -this we need to add it to the runtest file. So open :master:`runtest/syscalls` +as part of the syscalls test group (e.g. not run via ``kirk -f syscalls``). +For this we need to add it to the runtest file. So open :master:`runtest/syscalls` and add the lines starting with a ``+``. .. code-block::
@@ -517,15 +517,14 @@ that should be by setting ``.needs_tmpdir = 1``. /*************** statx structure and wrapper goes here ! ***************/ ... -We have added an extra include :master:`lapi/fcntl.h` which wraps the system header by +We have added an extra include :master:`include/lapi/fcntl.h` which wraps the system header by the same name (``#include <fcntl.h>``). This header ensures we have definitions for recently added macros such as ``AT_FDCWD`` by providing fall backs if the -system header does not have them. The :master:`lapi/` directory contains a number of +system header does not have them. The :master:`include/lapi/` directory contains a number of headers like this. -At some point we may wish to add :master:`lapi/stat.h` to provide a fall back for -macros such as ``STATX_BASIC_STATS``. However for the time being we have just -defined it in the test. +The :master:`include/lapi/stat.h` header provides similar fall backs for +macros such as ``STATX_BASIC_STATS`` used by this test. .. code-block:: c
@@ -759,9 +758,7 @@ the next section and come back later. Submitting the test for review ------------------------------ -Ignoring the fact we should probably create :master:`lapi/stat.h` along with a bunch -of fallback logic in the build system. We can now get our test ready for -submission. +We can now get our test ready for submission. The first thing you need to do before considering submitting your test is run ``make check-statx01`` or ``make check`` in the test's directory. Again, we use
doc/developers/todo.rst +1 -1
@@ -61,5 +61,5 @@ LTP root folder: LTP also provides a shell loader implementation for plain-C tests inside :master:`testcases/lib/tst_run_shell.c` and it permits to run shell tests -into plain-C LTP API, featuring :ref:`struct tst_test` initializations and a +into plain-C LTP API, featuring :c:struct:`tst_test` initializations and a direct access to kernel syscalls.
doc/developers/writing_tests.rst +3 -3
@@ -138,7 +138,7 @@ The following linting code can be found when we run ``make check``: * - LTP-005 - Array must terminate with a sentinel value (i.e. ``NULL`` or ``{}``) - - When defining arrays in the :ref:`struct tst_test` structure, we need to + - When defining arrays in the :c:struct:`tst_test` structure, we need to end the array items with a sentinel ``NULL`` value. Shell coding style
@@ -361,7 +361,7 @@ LTP C And Shell Test API Comparison .. list-table:: :header-rows: 1 - * - C API :ref:`struct tst_test` members + * - C API :c:struct:`tst_test` members - Shell API ``$TST_*`` variables * - .all_filesystems
@@ -531,5 +531,5 @@ LTP C And Shell Test API Comparison * - C API other structs - Shell API ``$TST_*`` variables - * - :ref:`struct tst_device` + * - ``struct tst_device`` - TST_DEVICE
doc/maintainers/ltp_release_procedure.rst +2 -2
@@ -112,8 +112,8 @@ metadata documentation: tar -cJf ltp-full-YYYYMMDD.tar.xz ltp-full-YYYYMMDD --exclude .git # Generate checksums - md5 ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.md5 - sha1 ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha1 + md5sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.md5 + sha1sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha1 sha256sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha256 You can use :master:`tools/create-tarballs-metadata.sh` script to have the above
doc/maintainers/patch_review.rst +3 -3
@@ -146,12 +146,12 @@ New test should C tests ~~~~~~~ -* Use :doc:`../developers/api_c_tests`, implementing :ref:`struct tst_test` +* Use :doc:`../developers/api_c_tests`, implementing :c:struct:`tst_test` * Test binaries are added into corresponding ``.gitignore`` files * Check coding style with ``make check`` * Metadata documentation -* If a test is a regression test it should include :ref:`.tags<struct tst_tag>` in the - :ref:`struct tst_test` definition +* If a test is a regression test it should include :c:struct:`.tags <tst_tag>` in the + :c:struct:`tst_test` definition Shell tests ~~~~~~~~~~~
include/tst_test_macros.h +4 -4
@@ -146,7 +146,7 @@ extern int TST_PASS;* @SCALL: Tested syscall. * @...: A printf-like parameters. * -* This is a variant of the TST_EXP_POSSITIVE() for a more specific case that +* This is a variant of the TST_EXP_POSITIVE() for a more specific case that * the returned value is a file descriptor. */ #define TST_EXP_FD (SCALL , ...) \
@@ -200,7 +200,7 @@ extern int TST_PASS;* @SCALL: Tested syscall. * @...: A printf-like parameters. * -* This is a variant of the TST_EXP_POSSITIVE() for a more specific case that +* This is a variant of the TST_EXP_POSITIVE() for a more specific case that * the returned value is a pid. */ #define TST_EXP_PID (SCALL , ...) \
@@ -379,8 +379,8 @@ extern int TST_PASS;* @...: A printf-like parameters. * * This macro works like TST_EXP_PASS_PTR_VOID() but checks the return -* value against NULL instead of (void *)-1. Use this for libc functions -* such as fopen() that return NULL on failure. +* value against NULL instead of ``(void *)-1``. Use this for libc functions +* such as :manpage:`fopen(3)` that return NULL on failure. */ #define TST_EXP_PASS_PTR_NULL (SCALL , ...) \ TST_EXP_PASS_PTR_(SCALL, #SCALL, NULL, ##__VA_ARGS__)
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 1/4] doc: Fix broken references and outdated content
Hi!
Signature · 5 lines
Cyril Hrubis [email protected] -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 1/4] doc: Fix broken references and outdated content
In reply to Andrea CervesatoHi Andrea,
Quoted 5 lines
Fix kernel-doc reference to renamed
tse_numa.hheader, correctTST_EXP_POSSITIVEtypo and RST formatting intst_test_macros.h, use :c:struct: instead of :ref: for struct cross-references, fix broken lapi/ :master: links, drop stalelapi/stat.hnotes, correct kirk invocation example and use md5sum/sha1sum commands.
Maybe add:
(there are more fixes but this one is the most obvious.)
And I'm sorry I touched the docs (you might need to resolve conflict during rebasing), I haven't noticed this patchset otherwise I'd wait.
Quoted 30 lines
Signed-off-by Andrea Cervesato <[email protected]>--- doc/developers/api_c_tests.rst | 2 +- doc/developers/api_shell_tests.rst | 2 +- doc/developers/test_case_tutorial.rst | 19 ++++++++----------- doc/developers/todo.rst | 2 +- doc/developers/writing_tests.rst | 6 +++--- doc/maintainers/ltp_release_procedure.rst | 4 ++-- doc/maintainers/patch_review.rst | 6 +++--- include/tst_test_macros.h | 8 ++++---- 8 files changed, 23 insertions(+), 26 deletions(-)doc/developers/api_c_tests.rst +1
-1@@ -50,7 +50,7 @@ Process state NUMA ---- -.. kernel-doc:: ../../include/tst_numa.h +.. kernel-doc:: ../../include/tse_numa.h Option parsing --------------doc/developers/api_shell_tests.rst +0
-0
doc/developers/api_shell_tests.rst documentation at https://linux-test-project.readthedocs.io/en/latest/users/test_ · line 34
Quoted 6 lines
doc/developers/api_shell_tests.rst +1
-1@@ -30,7 +30,7 @@ documentation at https://linux-test-project.readthedocs.io/en/latest/users/test_ The shell loader test library uses the :doc:`../developers/api_c_tests` internally by parsing a special JSON formatted comment and initializing it accordingly. The JSON format is nearly 1:1 serialization of the -:ref:`struct tst_test` into a JSON. The environment must be always preset even +:c:struct:`tst_test` into a JSON. The environment must be always preset even when it's empty.
OK, *.rst files require to use :c:struct: instead of :ref:. It's probably my error (I haven't noticed the syntax is different from C files).
doc/developers/test_case_tutorial.rst please do:
Quoted 15 lines
doc/developers/api_shell_tests.rst +0
-0.. code-block:: shelldoc/developers/test_case_tutorial.rst +1
-1@@ -137,7 +137,7 @@ initialization code. It is important to note that this is a completely ordinary, independent C program, however ``main()`` is missing because it is implemented in :master:`include/tst_test.h`. -We specify what code we want to run as part of the test using :ref:`struct tst_test`. +We specify what code we want to run as part of the test using :c:struct:`tst_test`. Various callbacks can be set by the test writer, including ``test.test_all``, which we have set to ``run()``. The test harness will execute this callback in a separate process (using ``fork()``), forcibly terminating it@@ -205,8 +205,8 @@ please do:
nit: could you please use :manpage:fork() ?
doc/developers/test_case_tutorial.rst please do: · line 209
Quoted 6 lines
doc/developers/test_case_tutorial.rst +2
-2This should build the test and then run it. However, even though the test is in :master:`testcases/kernel/syscalls` directory it won't be automatically ran -as part of the syscalls test group (e.g. not run via ``kirk -r math``. For -this we need to add it to the runtest file. So open :master:`runtest/syscalls` +as part of the syscalls test group (e.g. not run via ``kirk -f syscalls``). +For this we need to add it to the runtest file. So open :master:`runtest/syscalls`
IMHO math is fast => good as example.
Quoted 4 lines
doc/developers/test_case_tutorial.rst +0
-0and add the lines starting with a ``+``. .. code-block::
doc/developers/test_case_tutorial.rst that should be by setting ``.needs_tmpdir = 1``. · line 524
Quoted 10 lines
doc/developers/test_case_tutorial.rst +2
-2@@ -517,15 +517,14 @@ that should be by setting ``.needs_tmpdir = 1``. /*************** statx structure and wrapper goes here ! ***************/ -We have added an extra include :master:`lapi/fcntl.h` which wraps the system header by +We have added an extra include :master:`include/lapi/fcntl.h` which wraps the system header by the same name (``#include <fcntl.h>``). This header ensures we have definitions for recently added macros such as ``AT_FDCWD`` by providing fall backs if the -system header does not have them. The :master:`lapi/` directory contains a number of +system header does not have them. The :master:`include/lapi/` directory contains a number of headers like this.
+1
doc/developers/test_case_tutorial.rst that should be by setting ``.needs_tmpdir = 1``. · line 527
Quoted 5 lines
doc/developers/test_case_tutorial.rst +2
-3-At some point we may wish to add :master:`lapi/stat.h` to provide a fall back for -macros such as ``STATX_BASIC_STATS``. However for the time being we have just -defined it in the test. +The :master:`include/lapi/stat.h` header provides similar fall backs for +macros such as ``STATX_BASIC_STATS`` used by this test.
+1
...
Quoted 11 lines
Shell coding style
doc/developers/test_case_tutorial.rst +1
-1@@ -361,7 +361,7 @@ LTP C And Shell Test API Comparison .. list-table:: :header-rows: 1 - * - C API :ref:`struct tst_test` members + * - C API :c:struct:`tst_test` members - Shell API ``$TST_*`` variables * - .all_filesystems
doc/developers/test_case_tutorial.rst LTP C And Shell Test API Comparison · line 534
Quoted 5 lines
doc/developers/test_case_tutorial.rst +1
-1@@ -531,5 +531,5 @@ LTP C And Shell Test API Comparison * - C API other structs - Shell API ``$TST_*`` variables - * - :ref:`struct tst_device` + * - ``struct tst_device``
I'd even add
:c:struct:struct tst_device as a preparation for a new commit but you might add it in the following patchset.
doc/maintainers/ltp_release_procedure.rst metadata documentation: · line 116
Quoted 13 lines
doc/developers/test_case_tutorial.rst +0
-0- TST_DEVICEdoc/maintainers/ltp_release_procedure.rst +2
-2@@ -112,8 +112,8 @@ metadata documentation: tar -cJf ltp-full-YYYYMMDD.tar.xz ltp-full-YYYYMMDD --exclude .git # Generate checksums - md5 ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.md5 - sha1 ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha1 + md5sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.md5 + sha1sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha1
+1
doc/maintainers/patch_review.rst New test should · line 149
Quoted 13 lines
doc/maintainers/ltp_release_procedure.rst +0
-0sha256sum ltp-full-YYYYMMDD.tar.xz > ltp-full-YYYYMMDD.tar.xz.sha256 You can use :master:`tools/create-tarballs-metadata.sh` script to have the abovedoc/maintainers/patch_review.rst +1
-1@@ -146,12 +146,12 @@ New test should C tests ~~~~~~~ -* Use :doc:`../developers/api_c_tests`, implementing :ref:`struct tst_test` +* Use :doc:`../developers/api_c_tests`, implementing :c:struct:`tst_test`
+1
Quoted 33 lines
doc/maintainers/patch_review.rst +2
-2* Test binaries are added into corresponding ``.gitignore`` files * Check coding style with ``make check`` * Metadata documentation -* If a test is a regression test it should include :ref:`.tags<struct tst_tag>` in the - :ref:`struct tst_test` definition +* If a test is a regression test it should include :c:struct:`.tags <tst_tag>` in the + :c:struct:`tst_test` definition Shell tests ~~~~~~~~~~~include/tst_test_macros.h +2
-2@@ -146,7 +146,7 @@ extern int TST_PASS;* @SCALL: Tested syscall. * @...: A printf-like parameters. * -* This is a variant of the TST_EXP_POSSITIVE() for a more specific case that +* This is a variant of the TST_EXP_POSITIVE() for a more specific case that * the returned value is a file descriptor. */ #define TST_EXP_FD (SCALL , ...) \@@ -200,7 +200,7 @@ extern int TST_PASS;* @SCALL: Tested syscall. * @...: A printf-like parameters. * -* This is a variant of the TST_EXP_POSSITIVE() for a more specific case that +* This is a variant of the TST_EXP_POSITIVE() for a more specific case that * the returned value is a pid. */ #define TST_EXP_PID (SCALL , ...) \
include/tst_test_macros.h extern int TST_PASS; · line 383
Quoted 7 lines
include/tst_test_macros.h +2
-2@@ -379,8 +379,8 @@ extern int TST_PASS;* @...: A printf-like parameters. * * This macro works like TST_EXP_PASS_PTR_VOID() but checks the return -* value against NULL instead of (void *)-1. Use this for libc functions -* such as fopen() that return NULL on failure. +* value against NULL instead of ``(void *)-1``. Use this for libc functions +* such as :manpage:`fopen(3)` that return NULL on failure.
+1
include/tst_test_macros.h extern int TST_PASS; · line 386
Quoted 3 lines
include/tst_test_macros.h +0
-0*/ #define TST_EXP_PASS_PTR_NULL (SCALL , ...) \ TST_EXP_PASS_PTR_(SCALL, #SCALL, NULL, ##__VA_ARGS__)
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 2/4 doc: Fix typos and grammar
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Fix typos (reStructedText, ignorcing, clonned, likehood, evironment, asses, effected) and grammar (setup -> set up, permits to, it's -> its, be ran -> be run, will works, "be be" -> "be", result to -> resort to, yielded into -> led to, does not exists, has to be -> have to be) across the documentation tree.
--- doc/developers/api_shell_tests.rst | 2 +- doc/developers/build_system.rst | 6 +++--- doc/developers/documentation.rst | 6 +++--- doc/developers/ground_rules.rst | 10 +++++----- doc/developers/setup_mailinglist.rst | 2 +- doc/developers/test_case_tutorial.rst | 4 ++-- doc/developers/todo.rst | 4 ++-- doc/developers/writing_tests.rst | 4 ++-- doc/index.rst | 2 +- doc/maintainers/ltp_release_procedure.rst | 2 +- doc/maintainers/patch_review.rst | 6 +++--- doc/users/quick_start.rst | 10 +++++----- doc/users/setup_tests.rst | 2 +- doc/users/supported_systems.rst | 6 +++--- doc/users/testers_guide.rst | 6 +++--- include/tst_cmd.h | 2 +- 16 files changed, 37 insertions(+), 37 deletions(-)
doc/developers/api_shell_tests.rst +1 -1
@@ -75,7 +75,7 @@ must source the :shell_lib:`tst_run.sh` script. . tst_run.sh -In order to run a test from a LTP tree a few directories has to be added to the +In order to run a test from a LTP tree a few directories have to be added to the `$PATH`. Note that the number of `../` may depend on the depth of the current directory relative to the LTP root.
doc/developers/build_system.rst +3 -3
@@ -16,7 +16,7 @@ and including new targets was more difficult than it should have been impossible due to the fact that the Makefiles didn't support a prefixing system, and the appropriate implicit / static rules hadn't been configured to compile into multiple object directories for out-of-tree build support (ease of -use / functionality). Finally, there wasn't a means to setup dependencies +use / functionality). Finally, there wasn't a means to set up dependencies between components, such that if a component required ``libltp.a`` in order to compile, it would go off and compile ``libltp.a`` first (ease of use).
@@ -97,9 +97,9 @@ The ``REQ_VERSION_MAJOR`` and ``REQ_VERSION_PATCH`` describe minimal kernel version for which the build system tries to build the module. The build system is also forward compatible with changes in Linux kernel -internal API so that, if module fails to build, the failure is ignored both on +internal API so that, if a module fails to build, the failure is ignored both on build and installation. If the userspace counterpart of the test fails to load -the module because the file does not exists, the test is skipped. +the module because the file does not exist, the test is skipped. Note the ``ifneq($(KERNELRELEASE),)``. The reason it exists, it is that the Makefile is executed twice: once by LTP build system and once by kernel kbuild,
doc/developers/documentation.rst +3 -3
@@ -5,7 +5,7 @@ Documentation This section explains how to use and develop the LTP documentation. The current documentation format is written using -`reStructedText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ +`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ and it's built on top of `Sphinx <https://www.sphinx-doc.org/en/master/>`_. Building documentation
@@ -43,8 +43,8 @@ Validating spelling To check documentation words spelling, we provide support for `aspell <http://aspell.net/>`_, so make sure that it's installed. The documentation can be tested via ``make spelling`` command. Output will be -visible in the ``doc/build`` folder and, if any error will be found, a warning -message will be shown. +visible in the ``doc/build`` folder and, if any error is found, a warning +message is shown. C API documentation ~~~~~~~~~~~~~~~~~~~
doc/developers/ground_rules.rst +5 -5
@@ -22,16 +22,16 @@ The first problem is that it will likely introduce very rare test failures, that means somebody has to spend time looking into these, which is a wasted effort. Nobody likes tests that will fail rarely for no good reason. Even more so you cannot run such tests with a background load to ensure that everything -works correctly on a busy system, because that will increase the likehood of a +works correctly on a busy system, because that will increase the likelihood of a failure. The second problem is that this wastes resources and slows down a test run. If -you think that adding a sleep to a test is not a big deal, lets have a look at +you think that adding a sleep to a test is not a big deal, let's have a look at the bigger perspective. There are about 1600 syscall tests in Linux Test Project, if 7.5% of them would sleep just for one second, we would end up with two minutes of wasted time per testrun. In practice most of the tests, that historically misused sleep for synchronization, waited for much longer just to -be sure that things will works even on slower hardware. With sleeps between 2 +be sure that things will work even on slower hardware. With sleeps between 2 and 5 seconds that puts us somewhere between 4 and 10 minutes which is between 13% and 33% of the syscall runtime on an outdated thinkpad, where the run finishes in a bit less than half an hour. It's even worse on newer hardware,
@@ -125,7 +125,7 @@ You can check for common mistakes, not only in portability, with our ``make check`` tooling. -Split changed into well defined chunks +Split changes into well defined chunks -------------------------------------- When submitting patches make sure to split the work into small well-defined
@@ -162,7 +162,7 @@ Kernel features and RCs ----------------------- LTP tests or fixes for kernel changes that have not yet been released may be -posted to the LTP list for a review but they will not be be accepted until +posted to the LTP list for a review but they will not be accepted until respective kernel changes are released. Review of such changes is also considered to be lower priority than rest of the changes. This is because kernel changes especially in the early RC phase are volatile and could be
doc/developers/setup_mailinglist.rst +1 -1
@@ -46,7 +46,7 @@ For any corner case, please take a look at the .. note:: This method still works in most of the cases, but nowadays we often - require to setup a two factor authentication. If this is the case, please + require to set up a two-factor authentication. If this is the case, please consider setting up Git accordingly. Instead of :manpage:`git-send-email(1)` you may want to use
doc/developers/test_case_tutorial.rst +2 -2
@@ -204,7 +204,7 @@ please do: ./statx01 This should build the test and then run it. However, even though the test is -in :master:`testcases/kernel/syscalls` directory it won't be automatically ran +in :master:`testcases/kernel/syscalls` directory it won't be automatically run as part of the syscalls test group (e.g. not run via ``kirk -f syscalls``). For this we need to add it to the runtest file. So open :master:`runtest/syscalls` and add the lines starting with a ``+``.
@@ -569,7 +569,7 @@ this file in the present working directory. We don't need to create a the temporary directory and its contents. The ``run`` function can be called multiple times by the test harness, however -``setup`` and ``cleanup`` callbacks will only be ran once. +``setup`` and ``cleanup`` callbacks will only be run once. .. warning::
doc/developers/todo.rst +2 -2
@@ -60,6 +60,6 @@ LTP root folder: git --no-pager grep -l -e '^\. .*_lib\.sh' -e '^\. .*test.sh' LTP also provides a shell loader implementation for plain-C tests inside -:master:`testcases/lib/tst_run_shell.c` and it permits to run shell tests -into plain-C LTP API, featuring :c:struct:`tst_test` initializations and a +:master:`testcases/lib/tst_run_shell.c` which allows running shell tests +as plain-C LTP API, featuring :c:struct:`tst_test` initializations and a direct access to kernel syscalls.
doc/developers/writing_tests.rst +2 -2
@@ -52,7 +52,7 @@ Do not over-comment Comments can sometimes save your day, but they can easily do more harm than good. There has been several cases where comments and actual implementation -drifted slowly apart which yielded into API misuses and hard to find bugs. +drifted slowly apart which led to API misuses and hard to find bugs. Remember there is only one thing worse than no documentation: wrong documentation.
@@ -285,7 +285,7 @@ Datafiles If your test needs data files, these should be put into a subdirectory named ``datafiles`` and installed into the ``testcases/data/$TCID`` directory. This will require to add ``INSTALL_DIR := testcases/data/TCID`` into -correspondent ``datafiles/Makefile``. +corresponding ``datafiles/Makefile``. You can obtain path to datafiles via ``$TST_DATAROOT`` provided by ``test.sh`` or via C function ``tst_dataroot()`` provided by libltp:
doc/index.rst +1 -1
@@ -51,7 +51,7 @@ For users How to build and use LTP framework in few steps :doc:`users/setup_tests` - How to setup tests execution + How to set up tests execution :doc:`users/supported_systems` A list of supported technologies by the LTP framework
doc/maintainers/ltp_release_procedure.rst +1 -1
@@ -95,7 +95,7 @@ metadata documentation: .. code-block:: bash - # clone already clonned git repository to new folder + # clone already cloned git repository to new folder cd .. git clone ltp ltp-full-YYYYMMDD cd ltp-full-YYYYMMDD
doc/maintainers/patch_review.rst +3 -3
@@ -33,14 +33,14 @@ The following are examples and may not be appropriate for all tests. various distros/architectures * Use ``make check`` -* Run effected tests in a VM +* Run affected tests in a VM * Use single vCPU * Use many vCPUs and enable NUMA * Restrict RAM to < 1GB. -* Run effected tests on an embedded device -* Run effected tests on non-x86 machine in general +* Run affected tests on an embedded device +* Run affected tests on non-x86 machine in general * Run reproducers on a kernel where the bug is present * Run tests with ``-i0`` and ``-i2`` * Compare usage of system calls with man page descriptions
doc/users/quick_start.rst +5 -5
@@ -3,7 +3,7 @@ Installation and tests execution ================================ -Basics requirements to build LTP are the following: +Basic requirements to build LTP are the following: * git * autoconf
@@ -38,8 +38,8 @@ LTP provides the possibility to build and run single tests: $ make $ PATH=$PATH:$PWD ./foo01 -Shell testcases are a bit more complicated, since they need to setup ``PATH`` -as well as to compiled binary helpers: +Shell testcases are a bit more complicated, since they need to set up ``PATH`` +as well as to compile binary helpers: .. code-block:: console
@@ -48,7 +48,7 @@ as well as to compiled binary helpers: $ cd ../commands/foo $ PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh -Open Posix Testsuite has it's own build system which needs Makefiles to be +Open POSIX Testsuite has its own build system which needs Makefiles to be generated first: .. code-block:: console
@@ -96,7 +96,7 @@ To run all the test suites Test suites (e.g. syscalls) are defined in the ``runtest`` directory. Each file contains a list of test cases in a simple format. -Each test case has its own executable or script that can directly executed: +Each test case has its own executable or script that can be executed directly: .. code-block:: console
doc/users/setup_tests.rst +1 -1
@@ -3,7 +3,7 @@ Tests setup =========== -The internal LTP library provides a set of features that permits to customize +The internal LTP library provides a set of features that lets you customize tests behavior by setting environment variables and using specific tests arguments.
doc/users/supported_systems.rst +3 -3
@@ -50,9 +50,9 @@ newly added syscalls, etc. **Trivial fixes/workarounds may be accepted, but users are encouraged to move to a newer distro.** If latest LTP cannot be compiled even with some amount of workarounds, -you may result to older LTP releases, however these are **not** supported +you may resort to older LTP releases, however these are **not** supported in any way. Also if you are trying to run LTP on more than 10 years old -distribution you may as well reconsider you life choices. +distribution you may as well reconsider your life choices. Build tested architectures --------------------------
@@ -91,7 +91,7 @@ Supported C libraries - Targeted libc, tested both compilation and actual test results. * - `uClibc-ng <https://uclibc-ng.org/>`_ - - Although not being tested, it should work as it attempt to maintain a glibc compatible interface. + - Although not being tested, it should work as it attempts to maintain a glibc compatible interface. * - `uClibc <https://www.uclibc.org/>`_ - Older uClibc might have problems.
doc/users/testers_guide.rst +3 -3
@@ -5,7 +5,7 @@ Testers guide to the Linux test project While we try to make LTP work out of the box as much as possible there are still many things that testers need to consider before the actual testing -starts. It's advisable to make a test plan in order to asses and formalize the +starts. It's advisable to make a test plan in order to assess and formalize the expected test coverage or even just sit down for a while and consider different aspects of the problem at hand.
@@ -27,7 +27,7 @@ behavior, even if the upstream kernel is stable. For example, backporting patches without their full dependency chain can lead to unexpected regressions. Therefore, it’s crucial to test your own kernel builds in the environment where they will actually run, using tools like LTP to -catch issues that does not exists or are not triggered in the upstream +catch issues that do not exist or are not triggered in the upstream configuration.
@@ -61,7 +61,7 @@ devices for these testcases, that can be changed with environment variables as well. Lastly but not least a few testcases repeat the test for all supported filesystem, if you are interested in testing on a single filesystem only, you can limit these tests to a single filesystem too. See the tests setup for a -comprehensive list of the `evironment variables +comprehensive list of the `environment variables <setup_tests.html#library-environment-variables>`_. Then you also have to decide if you are going to run tests in virtual machine
include/tst_cmd.h +1 -1
@@ -111,7 +111,7 @@ static inline int tst_cmd(void (cleanup_fn)(void),#endif /** -* tst_system() - Wrapper function for :manpage:`system(3)`, ignorcing ``SIGCHLD`` +* tst_system() - Wrapper function for :manpage:`system(3)`, ignoring ``SIGCHLD`` * signal. * * @command: The command to be run.
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 2/4] doc: Fix typos and grammar
Hi!
Thanks for fixing all typos :-).
Signature · 5 lines
Cyril Hrubis [email protected] -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 2/4] doc: Fix typos and grammar
In reply to Andrea CervesatoHi Andrea,
Quoted 6 lines
Fix typos (reStructedText, ignorcing, clonned, likehood, evironment, asses, effected) and grammar (setup -> set up, permits to, it's -> its, be ran -> be run, will works, "be be" -> "be", result to -> resort to, yielded into -> led to, does not exists, has to be -> have to be) across the documentation tree.
Good catch, thank you!
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 3/4 include: Fix kernel-doc warnings in header comments
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Drop :ref: cross-references to undocumented structs in tst_test.h and tst_kvercmp.h kernel-doc comments, replacing them with plain text. These produced 'undefined label' Sphinx warnings.
Downgrade kernel-doc comments to plain comments for struct tst_cmd and TST_CAP() macro to avoid name collisions with the tst_cmd() function and struct tst_cap respectively. The kernel-doc parser flattens names case-insensitively, causing 'name used several times' errors and duplicate target warnings.
--- include/tst_capability.h | 2 +- include/tst_cmd.h | 2 +- include/tst_kvercmp.h | 2 +- include/tst_test.h | 16 ++++++++-------- 4 files changed, 11 insertions(+), 11 deletions(-)
include/tst_capability.h +1 -1
@@ -67,7 +67,7 @@ struct tst_cap {char *name; }; -/** +/* * TST_CAP() - Create a struct tst_cap entry. * * @action: What should we do, i.e. drop or add capability.
include/tst_cmd.h +1 -1
@@ -19,7 +19,7 @@ enum tst_cmd_flags { TST_CMD_TCONF_ON_MISSING = 2, }; -/** +/* * struct tst_cmd - Provides details about a command struct needed by LTP test. * @cmd: The name of the command. * @optional: A flag indicating if the command is optional.
include/tst_kvercmp.h +1 -1
@@ -93,7 +93,7 @@ struct tst_kern_exv {* @r1: Major kernel version. * @r2: Minor kernel version. * @r3: Kernel patch level. -* @vers: A {} terminated array of :ref:`struct tst_kern_exv`. +* @vers: A {} terminated array of struct tst_kern_exv. * * Attempts to look up a distro specific kernel version from the struct * tst_kern_exv table first and if no match is found falls back to the version
include/tst_test.h +8 -8
@@ -298,7 +298,7 @@ struct tst_fs {* * @tcnt: A number of tests. If set the test() callback is called tcnt times * and each time passed an increasing counter value. -* @options: An NULL optstr terminated array of :ref:`struct tst_option`. +* @options: An NULL optstr terminated array of struct tst_option. * * @min_kver: A minimal kernel version the test can run on. e.g. "3.10". *
@@ -322,7 +322,7 @@ struct tst_fs {* @forks_child: Has to be set if the test intends to fork children. * * @needs_device: If set a block device is prepared for the test, the device -* path and size are set in the :ref:`struct tst_device` variable +* path and size are set in the struct tst_device variable * called tst_device. If $LTP_DEV variable exists in the test * environment the test attempts to use that device first and * only if that fails the test falls back to use loop devices.
@@ -361,7 +361,7 @@ struct tst_fs {* i.e. file system that is supported by the kernel and has * mkfs installed on the system.The file system is mounted at * tst_test.mntpoint and file system details, e.g. type are set -* in the :ref:`struct tst_device`. Each execution is independent, +* in the struct tst_device. Each execution is independent, * that means that for each iteration tst_test.setup() is * called at the test start and tst_test.cleanup() is called * at the end and tst_brk() only exits test for a single
@@ -500,7 +500,7 @@ struct tst_fs {* * @save_restore: A {} terminated array of /proc or /sys files that should * saved at the start of the test and restored at the end. See -* tst_sys_conf_save() and :ref:`struct tst_path_val` for details. +* tst_sys_conf_save() and struct tst_path_val for details. * * @ulimit: A {} terminated array of process limits RLIMIT_* to be adjusted for * the test.
@@ -522,14 +522,14 @@ struct tst_fs {* @bufs: A description of guarded buffers to be allocated for the test. Guarded * buffers are buffers with poisoned page allocated right before the start * of the buffer and canary right after the end of the buffer. See -* :ref:`struct tst_buffers` and tst_buffers_alloc() for details. +* struct tst_buffers and tst_buffers_alloc() for details. * * @caps: A {} terminated array of capabilities to change before the start of -* the test. See :ref:`struct tst_cap` and tst_cap_setup() for details. +* the test. See struct tst_cap and tst_cap_setup() for details. * -* @tags: A {} terminated array of test tags. See :ref:`struct tst_tag` for details. +* @tags: A {} terminated array of test tags. See struct tst_tag for details. * -* @needs_cmds: A NULL terminated array of :ref:`struct tst_cmd` required for the test to run. +* @needs_cmds: A NULL terminated array of struct tst_cmd required for the test to run. * * @needs_cgroup_ver: If set the test will run only if the specified cgroup * version is present on the system.
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 3/4] include: Fix kernel-doc warnings in header comments
Hi Andrea,
Quoted 3 lines
Drop :ref: cross-references to undocumented structs in
tst_test.handtst_kvercmp.hkernel-doc comments, replacing them with plain text. These produced 'undefined label' Sphinx warnings.
+1, that goes under me I guess. I checked that at the time, but I did not get it would work without :ref:.
Quoted 5 lines
Downgrade kernel-doc comments to plain comments for struct
tst_cmdandTST_CAP()macro to avoid name collisions with thetst_cmd()function and structtst_caprespectively. The kernel-doc parser flattens names case-insensitively, causing 'name used several times' errors and duplicate target warnings.
Hm ...
...
include/tst_capability.h struct tst_cap { · line 71
Quoted 8 lines
+++
b/include/tst_capability.hinclude/tst_capability.h +1
-1@@ -67,7 +67,7 @@ struct tst_cap {char *name; }; -/** +/* * TST_CAP() - Create a struct tst_cap entry.
This is the only warning I'd prefer to stay unfixed (i.e. it was kept in the docs). I wonder if we shouldn't jus rename struct or macro. Because TST_CAP() should be documented. Cyril @WDYT?
Quoted 20 lines
include/tst_capability.h +0
-0* * @action: What should we do, i.e. drop or add capability. include/tst_cmd.h +1
-1@@ -19,7 +19,7 @@ enum tst_cmd_flags { TST_CMD_TCONF_ON_MISSING = 2, }; -/** +/* * struct tst_cmd - Provides details about a command struct needed by LTP test. * @cmd: The name of the command. * @optional: A flag indicating if the command is optional. include/tst_kvercmp.h +0
-0
include/tst_kvercmp.h struct tst_kern_exv { · line 96
Quoted 5 lines
include/tst_kvercmp.h +1
-1@@ -93,7 +93,7 @@ struct tst_kern_exv {* @r1: Major kernel version. * @r2: Minor kernel version. * @r3: Kernel patch level. -* @vers: A {} terminated array of :ref:`struct tst_kern_exv`. +* @vers: A {} terminated array of struct tst_kern_exv.
And ok, C sources and headers should not use :ref:, thanks for fixing it.
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 3/4] include: Fix kernel-doc warnings in header comments
Hi!
Quoted 14 lines
Quoted 5 lines
Downgrade kernel-doc comments to plain comments for struct
tst_cmdandTST_CAP()macro to avoid name collisions with thetst_cmd()function and structtst_caprespectively. The kernel-doc parser flattens names case-insensitively, causing 'name used several times' errors and duplicate target warnings.Hm ...
...
Quoted 4 lines
+++
b/include/tst_capability.hinclude/tst_capability.h +0
-0@@ -67,7 +67,7 @@ struct tst_cap {char *name; };
Quoted 7 lines
include/tst_capability.h struct tst_cap { · line 71
Quoted 3 lines
include/tst_capability.h +1
-1-/** +/* * TST_CAP() - Create a struct tst_cap entry. This is the only warning I'd prefer to stay unfixed (i.e. it was kept in the docs). I wonder if we shouldn't jus rename struct or macro. Because
TST_CAP()should be documented. Cyril @WDYT?
Looking at the resulting html pages both the structure and the function is documented properly there. Also as long as we use c:func: and c:type:
in referencies everything should work. So I vote for ignoring this as well.
Signature · 5 lines
Cyril Hrubis [email protected] -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 3/4] include: Fix kernel-doc warnings in header comments
Hi Cyril,
Quoted 23 lines
Hi!
Quoted 14 lines
Quoted 5 lines
Downgrade kernel-doc comments to plain comments for struct
tst_cmdandTST_CAP()macro to avoid name collisions with thetst_cmd()function and structtst_caprespectively. The kernel-doc parser flattens names case-insensitively, causing 'name used several times' errors and duplicate target warnings.Hm ...
...
Quoted 4 lines
+++
b/include/tst_capability.hinclude/tst_capability.h +0
-0@@ -67,7 +67,7 @@ struct tst_cap {char *name; };Quoted 7 lines
include/tst_capability.h struct tst_cap { · line 71
Quoted 3 lines
include/tst_capability.h +1
-1-/** +/* * TST_CAP() - Create a struct tst_cap entry. This is the only warning I'd prefer to stay unfixed (i.e. it was kept in the docs). I wonder if we shouldn't jus rename struct or macro. Because
TST_CAP()should be documented. Cyril @WDYT?
Quoted 8 lines
Looking at the resulting html pages both the structure and the function is documented properly there. Also as long as we use c:func: and c:type:
in referencies everything should work. So I vote for ignoring this as well.Signature · 2 lines
Cyril Hrubis [email protected]
Ok so I will just ignore it as it was in the beginning and merge the patch-set.
Regards,
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
PATCH 4/4 doc: Fix incorrect struct tst_test field references
In reply to Andrea CervesatoFrom: Andrea Cervesato <[email protected]>
Fix several inaccuracies in ground_rules.rst and writing_tests.rst where struct tst_test fields were referenced incorrectly:
- .save_restore and .needs_cgroup_ctrls are not boolean flags, drop the '= 1' assignment examples.
- .supported_archs example had a stray ')' in the type cast.
- .max_runtime renamed to .runtime per commit a6a369c5eeb4 ("lib: redefine the overall timeout logic of test").
- .tst_hugepage -> .hugepages (the actual field name).
- .dev_extra_opts, .dev_fs_opts, .dev_fs_type never existed as C struct fields; move them to the shell-only section of the comparison table.
--- doc/developers/ground_rules.rst | 6 +++--- doc/developers/writing_tests.rst | 28 ++++++++++++++-------------- 2 files changed, 17 insertions(+), 17 deletions(-)
doc/developers/ground_rules.rst +3 -3
@@ -100,10 +100,10 @@ paths too. The test library can simplify cleanup greatly as there are various helpers such as: - :c:type:`.needs_tmpdir = 1 <tst_test>` that creates and deletes a temporary directory for the test -- :c:type:`.save_restore = 1 <tst_test>` that saves and restores /sys/ and /proc/ files +- :c:type:`.save_restore <tst_test>` that saves and restores /sys/ and /proc/ files - :c:type:`.needs_device = 1 <tst_test>` sets up and tears down a block device for the test - :c:type:`.restore_wallclock = 1 <tst_test>` that restores wall clock after the test -- :c:type:`.needs_cgroup_ctrls = 1 <tst_test>` sets up and cleans up cgroups for the test +- :c:type:`.needs_cgroup_ctrls <tst_test>` sets up and cleans up cgroups for the test - And many more.
@@ -115,7 +115,7 @@ Avoid nonstandard libc APIs when a portable equivalent exists; don't assume If the test is specific to a certain architecture, make sure that it at least compiles at the rest of architectures and set the -:c:type:`.supported_archs = const char *const []){"s390x", ..., NULL} <tst_test>`. +:c:type:`.supported_archs = (const char *const []){"s390x", ..., NULL} <tst_test>`. This also applies to shell code where it's easy to use bash features that are not available on other shell implementations, e.g. dash or busybox. Make sure
doc/developers/writing_tests.rst +14 -14
@@ -379,25 +379,16 @@ LTP C And Shell Test API Comparison * - .cleanup - TST_CLEANUP - * - .dev_extra_opts - - TST_DEV_EXTRA_OPTS - - * - .dev_fs_opts - - TST_DEV_FS_OPTS - - * - .dev_fs_type - - TST_FS_TYPE - * - .dev_min_size - TST_DEVICE_SIZE * - .format_device - TST_FORMAT_DEVICE - * - .max_runtime - - TST_TIMEOUT (not exactly the same, a real timeout based on old .timeout - concept. .max_runtime has also an extra 30 sec safety margin for - teardown of the test.) + * - .runtime + - TST_TIMEOUT (not exactly the same, TST_TIMEOUT is a real timeout. + .runtime controls the test execution loop duration and has an extra + 30 sec safety margin for setup and cleanup.) * - .min_cpus - not applicable
@@ -507,7 +498,7 @@ LTP C And Shell Test API Comparison * - .test_variants - \- - * - .tst_hugepage + * - .hugepages - not applicable * - .ulimit
@@ -525,6 +516,15 @@ LTP C And Shell Test API Comparison * - not applicable - TST_USAGE + * - not applicable + - TST_DEV_EXTRA_OPTS + + * - not applicable + - TST_DEV_FS_OPTS + + * - not applicable + - TST_FS_TYPE + .. list-table:: :header-rows: 1
Signature · 5 lines
2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] [PATCH 4/4] doc: Fix incorrect struct tst_test field references
Hi Andrea,
Thanks!
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Andrea Cervesato via ltp
AppliedMerged, Thanks!
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp