Skip to contentSkip to conversation

Documentation: kunit: Cleanup run_wrapper, fix x-ref

PATCH Superseded David Gow 4 participants 7 messages Jun 26, 2022 – Jul 6, 2022

Subsystems (4)
lore
Share & tools
lore

David Gow

author
#0 lore raw

PATCH 1/1 Documentation: kunit: Cleanup run_wrapper, fix x-ref

The "Run Tests on qemu" section of run_wrapper.rst had a few issues left over from the last big documentation refactor[1]:
- It referenced a run_uml.rst page, which was integrated into the other pages (including run_wrapper.rst).
- It skimmed over the use of --arch= and --cross_compile= in favour of using a custom --qemu_config. Since most users will want to use the former, let's give examples.

Remove the reference to the non-existant page, and add a couple of examples to encourage the use of --arch= and --cross_compile=.

With this change, there should be no more broken references in the KUnit documentation (i.e., the one mentioned in [2] is gone).

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
[2]: https://lore.kernel.org/linux-doc/[email protected]/

---

Thanks, Mauro, for noticing this in [2]: for whatever reason my version of Sphinx wasn't warning on it.

Unless anyone objects, I'll add this to the list of things to be taken in via the kunit/kunit-fixes tree.

Cheers,
-- David

---
 Documentation/dev-tools/kunit/run_wrapper.rst | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)
Documentation/dev-tools/kunit/run_wrapper.rst +14 -3
index 653985ce9cae..a695f58cd64e 100644
@@ -192,6 +192,20 @@ via UML. To run tests on qemu, by default it requires two flags:
     if we have downloaded the microblaze toolchain from the 0-day
     website to a directory in our home directory called toolchains.
 
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run --arch=x86_64
+
+If a special toolchain is required, it can be slightly more complicated:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run \
+		--arch=s390 \
+		--cross_compile=s390x-linux-gnu-
+
 If we want to run KUnit tests on an architecture not supported by
 the ``--arch`` flag, or want to run KUnit tests on qemu using a
 non-default configuration; then we can write our own``QemuConfig``.
@@ -214,9 +228,6 @@ as
 		--jobs=12 \
 		--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
 
-To run existing KUnit tests on non-UML architectures, see:
-Documentation/dev-tools/kunit/non_uml.rst.
-
 Command-Line Arguments
 ======================
 
Signature · 1 line
2.37.0.rc0.161.g10f37bed90-goog
#1 lore raw

Documentation/dev-tools/kunit/run_wrapper.rst via UML. To run tests on qemu, by default it requires two flags: · line 208

Quoted 8 lines · David Gow
Documentation/dev-tools/kunit/run_wrapper.rst +8 -0
+If a special toolchain is required, it can be slightly more complicated:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run \
+		--arch=s390 \
+		--cross_compile=s390x-linux-gnu-
+

This describes cross-compiling usage, so the text should be "For cross-compiling, pass --arch and --cross_compile flags:"

Signature · 1 line
An old man doll... just what I always wanted! - Clara
author
#2 lore raw

PATCH v2 1/1 Documentation: kunit: Cleanup run_wrapper, fix x-ref

In reply to David Gow

The "Run Tests on qemu" section of run_wrapper.rst had a few issues left over from the last big documentation refactor[1]:
- It referenced a non_uml.rst page, which was integrated into the other pages (including run_wrapper.rst).
- It skimmed over the use of --arch= and --cross_compile= in favour of using a custom --qemu_config. Since most users will want to use the former, let's give examples.

Remove the reference to the non-existant page, and add a couple of examples to encourage the use of --arch= and --cross_compile=.

With this change, there should be no more broken references in the KUnit documentation (i.e., the one mentioned in [2] is gone).

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
[2]: https://lore.kernel.org/linux-doc/[email protected]/

---

Changes since v1:
https://lore.kernel.org/linux-kselftest/[email protected]/
- Reword the --cross_compile example (Thanks Bagas Sanjaya)
- Fix the name of run_uml.rst -> non_uml.rst in the commit description.

---
 Documentation/dev-tools/kunit/run_wrapper.rst | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)
Documentation/dev-tools/kunit/run_wrapper.rst +15 -3
index 653985ce9cae..5e560f2c5fca 100644
@@ -192,6 +192,21 @@ via UML. To run tests on qemu, by default it requires two flags:
     if we have downloaded the microblaze toolchain from the 0-day
     website to a directory in our home directory called toolchains.
 
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run --arch=x86_64
+
+When cross-compiling, we'll likely need to specify a different toolchain, for
+example:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run \
+		--arch=s390 \
+		--cross_compile=s390x-linux-gnu-
+
 If we want to run KUnit tests on an architecture not supported by
 the ``--arch`` flag, or want to run KUnit tests on qemu using a
 non-default configuration; then we can write our own``QemuConfig``.
@@ -214,9 +229,6 @@ as
 		--jobs=12 \
 		--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
 
-To run existing KUnit tests on non-UML architectures, see:
-Documentation/dev-tools/kunit/non_uml.rst.
-
 Command-Line Arguments
 ======================
 
Signature · 1 line
2.37.0.rc0.161.g10f37bed90-goog
#3 lore raw
Quoted 5 lines · David Gow
Documentation/dev-tools/kunit/run_wrapper.rst +5 -0
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run --arch=x86_64

Documentation/dev-tools/kunit/run_wrapper.rst via UML. To run tests on qemu, by default it requires two flags: · line 209

Quoted 10 lines
Documentation/dev-tools/kunit/run_wrapper.rst +10 -0
+
+When cross-compiling, we'll likely need to specify a different toolchain, for
+example:
+
+.. code-block:: bash
+
+	./tools/testing/kunit/kunit.py run \
+		--arch=s390 \
+		--cross_compile=s390x-linux-gnu-
+

nit: s/we'll/you'll/

Otherwise looks OK.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
author
#4 lore raw
Quoted 20 lines · Bagas Sanjaya
Quoted 5 lines · David Gow
Documentation/dev-tools/kunit/run_wrapper.rst +5 -0
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+     ./tools/testing/kunit/kunit.py run --arch=x86_64

Documentation/dev-tools/kunit/run_wrapper.rst via UML. To run tests on qemu, by default it requires two flags: · line 209

Quoted 10 lines
Documentation/dev-tools/kunit/run_wrapper.rst +10 -0
+
+When cross-compiling, we'll likely need to specify a different toolchain, for
+example:
+
+.. code-block:: bash
+
+     ./tools/testing/kunit/kunit.py run \
+             --arch=s390 \
+             --cross_compile=s390x-linux-gnu-
+

nit: s/we'll/you'll/

Quoted 1 line

Otherwise looks OK.

Thanks. The rest of this document is using "we" rather than "you", so I used "we'll" for consistency. If "you" is preferred generally, it'd be best to change it throughout the document (probably in a separate patch).

Cheers,
-- David

maintainer
#5 lore raw
Quoted 4 lines · David Gow

Thanks. The rest of this document is using "we" rather than "you", so I used "we'll" for consistency. If "you" is preferred generally, it'd be best to change it throughout the document (probably in a separate patch).

Nobody has ever tried to articulate a wider policy on first or second-person usage for kernel docs, so far as I know, and I think that's just fine. We have far bigger things to worry about before we get concerned about consistency at that level.

Thanks,

jon

Reviewed-by on v2 1/1
#6 lore raw
In reply to David Gow
Quoted 12 lines · David Gow

The "Run Tests on qemu" section of run_wrapper.rst had a few issues left over from the last big documentation refactor[1]:
- It referenced a non_uml.rst page, which was integrated into the other pages (including run_wrapper.rst).
- It skimmed over the use of --arch= and --cross_compile= in favour of using a custom --qemu_config. Since most users will want to use the former, let's give examples.

Remove the reference to the non-existant page, and add a couple of examples to encourage the use of --arch= and --cross_compile=.

Quoted 7 lines

With this change, there should be no more broken references in the KUnit documentation (i.e., the one mentioned in [2] is gone).

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
[2]: https://lore.kernel.org/linux-doc/[email protected]/