[PATCH] Documentation: Kunit: Update architecture.rst for minor fixes

[Sadiya Kazi]

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.
-Upate all occurrences of Command Line to Command-line across the document.
-Correct grammatical issues, for example - added _it_wherever missing.
-Update all occurrences of _via_ to either use _through_ or _using_.
-Update the text preceding the external links and pushed the full
link to a new line for better readability.
-Reword content under the config command to make it more clear and concise.

Signed-off-by: Sadiya Kazi <sadiy...@google.com>
---
.../dev-tools/kunit/architecture.rst | 86 ++++++++++---------
1 file changed, 45 insertions(+), 41 deletions(-)

diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
index 8efe792bdcb9..1736c37c33f2 100644
--- a/Documentation/dev-tools/kunit/architecture.rst
+++ b/Documentation/dev-tools/kunit/architecture.rst
@@ -4,16 +4,17 @@
KUnit Architecture
==================

-The KUnit architecture can be divided into two parts:
+The KUnit architecture is divided into two parts:

- `In-Kernel Testing Framework`_
-- `kunit_tool (Command Line Test Harness)`_
+- `kunit_tool (Command-line Test Harness)`_

In-Kernel Testing Framework
===========================

The kernel testing library supports KUnit tests written in C using
-KUnit. KUnit tests are kernel code. KUnit does several things:
+KUnit. KUnit tests are written in the kernel code. KUnit performs the following
+tasks:

- Organizes tests
- Reports test results
@@ -22,8 +23,8 @@ KUnit. KUnit tests are kernel code. KUnit does several things:
Test Cases
----------

-The fundamental unit in KUnit is the test case. The KUnit test cases are
-grouped into KUnit suites. A KUnit test case is a function with type
+The test case is the fundamental unit in KUnit. KUnit test cases are organised
+into suites. A KUnit test case is a function with type
signature ``void (*)(struct kunit *test)``.
These test case functions are wrapped in a struct called
struct kunit_case.
@@ -31,8 +32,8 @@ struct kunit_case.
.. note:
``generate_params`` is optional for non-parameterized tests.

-Each KUnit test case gets a ``struct kunit`` context
-object passed to it that tracks a running test. The KUnit assertion
+Each KUnit test case receives a ``struct kunit`` context object that tracks a
+running test. The KUnit assertion
macros and other KUnit utilities use the ``struct kunit`` context
object. As an exception, there are two fields:

@@ -77,11 +78,12 @@ Executor

The KUnit executor can list and run built-in KUnit tests on boot.
The Test suites are stored in a linker section
-called ``.kunit_test_suites``. For code, see:
+called ``.kunit_test_suites``. For code, see the following link:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.
+
The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
-macro. To run all tests compiled into the kernel, the KUnit executor
+macro. To run all the compiled tests into the kernel, the KUnit executor
iterates over the linker section array.

.. kernel-figure:: kunit_suitememorydiagram.svg
@@ -90,8 +92,8 @@ iterates over the linker section array.
KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses
-of this section to iterate over and run all tests. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
+of this section to iterate over and run all tests. For code, see the following link:
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c.

When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
@@ -99,46 +101,48 @@ unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
-context. For code, see:
+context. For code, see the following link:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58

Assertion Macros
----------------

-KUnit tests verify state using expectations/assertions.
+KUnit tests verify the state using expectations/assertions.
All expectations/assertions are formatted as:
``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``

- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
expectation.

- - For an expectation, if the check fails, marks the test as failed
+ - For an expectation, if the check fails, it marks the test as failed
and logs the failure.

- An assertion, on failure, causes the test case to terminate
immediately.

- - Assertions call function:
+ - Assertion calls the function:
``void __noreturn kunit_abort(struct kunit *)``.

- - ``kunit_abort`` calls function:
+ - ``kunit_abort`` calls the function:
``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.

- - ``kunit_try_catch_throw`` calls function:
+ - ``kunit_try_catch_throw`` calls the function:
``void kthread_complete_and_exit(struct completion *, long) __noreturn;``
and terminates the special thread context.

- ``<op>`` denotes a check with options: ``TRUE`` (supplied property
- has the boolean value “true”), ``EQ`` (two supplied properties are
+ has the boolean value "true"), ``EQ`` (two supplied properties are
equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
- contain an “err” value).
+ contain an "err" value).

- ``[_MSG]`` prints a custom message on failure.

Test Result Reporting
---------------------
-KUnit prints test results in KTAP format. KTAP is based on TAP14, see:
+KUnit prints the test results in KTAP format.
+KTAP is based on TAP14, see:
https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md.
+
KTAP (yet to be standardized format) works with KUnit and Kselftest.
The KUnit executor prints KTAP results to dmesg, and debugfs
(if configured).
@@ -151,32 +155,32 @@ parameters. The test is invoked multiple times, once for each parameter
value and the parameter is stored in the ``param_value`` field.
The test case includes a KUNIT_CASE_PARAM() macro that accepts a
generator function.
-The generator function is passed the previous parameter and returns the next
-parameter. It also provides a macro to generate common-case generators based on
-arrays.
+The previous parameter is passed to the generator function, which returns
+the next parameter. It also includes a macro for generating array-based
+common-case generators.

-kunit_tool (Command Line Test Harness)
+kunit_tool (Command-line Test Harness)
======================================

-kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)``
-that can be used to configure, build, exec, parse and run (runs other
-commands in order) test results. You can either run KUnit tests using
-kunit_tool or can include KUnit in kernel and parse manually.
+``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
+is used to configure, build, execute, parse, and run (other commands in order)
+test results. You have two options for running KUnit tests: either include KUnit
+in the kernel and parse manually, or use the ``kunit_tool``.

- ``configure`` command generates the kernel ``.config`` from a
``.kunitconfig`` file (and any architecture-specific options).
- For some architectures, additional config options are specified in the
- ``qemu_config`` Python script
- (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``).
+ The Python script available in ``qemu_configs`` folder
+ (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
+ additional configuration options for specific architectures.
It parses both the existing ``.config`` and the ``.kunitconfig`` files
- and ensures that ``.config`` is a superset of ``.kunitconfig``.
- If this is not the case, it will combine the two and run
- ``make olddefconfig`` to regenerate the ``.config`` file. It then
- verifies that ``.config`` is now a superset. This checks if all
- Kconfig dependencies are correctly specified in ``.kunitconfig``.
- ``kunit_config.py`` includes the parsing Kconfigs code. The code which
- runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can
- invoke this command via: ``./tools/testing/kunit/kunit.py config`` and
+ to ensure that ``.config`` is a superset of ``.kunitconfig``.
+ If not, it will combine the two and execute ``make olddefconfig`` to regenerate
+ the ``.config`` file. It then checks to see if ``.config`` has become a superset.
+ This verifies that all the Kconfig dependencies are correctly specified in the file
+ ``.kunitconfig``. The
+ ``kunit_config.py`` script contains the code for parsing Kconfigs. The code which
+ runs ``make olddefconfig`` is part of the ``kunit_kernel.py`` script. You can
+ invoke this command through: ``./tools/testing/kunit/kunit.py config`` and
generate a ``.config`` file.
- ``build`` runs ``make`` on the kernel tree with required options
(depends on the architecture and some options, for example: build_dir)
@@ -184,8 +188,8 @@ kunit_tool or can include KUnit in kernel and parse manually.
To build a KUnit kernel from the current ``.config``, you can use the
``build`` argument: ``./tools/testing/kunit/kunit.py build``.
- ``exec`` command executes kernel results either directly (using
- User-mode Linux configuration), or via an emulator such
- as QEMU. It reads results from the log via standard
+ User-mode Linux configuration), or through an emulator such
+ as QEMU. It reads results from the log using standard
output (stdout), and passes them to ``parse`` to be parsed.
If you already have built a kernel with built-in KUnit tests,
you can run the kernel and display the test results with the ``exec``
--
2.38.0.rc1.362.ged0d419d3c-goog

[David Gow]

On Tue, Oct 11, 2022 at 1:14 AM 'Sadiya Kazi' via KUnit Development
<kuni...@googlegroups.com> wrote:
>
> Updated the architecture.rst page with the following changes:
> -Add missing article _the_ across the document.
> -Reword content across for style and standard.
> -Upate all occurrences of Command Line to Command-line across the document.

Nit: spelling of "Update"

> -Correct grammatical issues, for example - added _it_wherever missing.
> -Update all occurrences of _via_ to either use _through_ or _using_.
> -Update the text preceding the external links and pushed the full
> link to a new line for better readability.
> -Reword content under the config command to make it more clear and concise.
>
> Signed-off-by: Sadiya Kazi <sadiy...@google.com>
> ---

Thanks very much for such a thorough cleanup here. On the whole, I
really like this, but have (quite) a few comments on the individual
changes below.

Cheers,
-- David

> .../dev-tools/kunit/architecture.rst | 86 ++++++++++---------
> 1 file changed, 45 insertions(+), 41 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
> index 8efe792bdcb9..1736c37c33f2 100644
> --- a/Documentation/dev-tools/kunit/architecture.rst
> +++ b/Documentation/dev-tools/kunit/architecture.rst
> @@ -4,16 +4,17 @@
> KUnit Architecture
> ==================
>
> -The KUnit architecture can be divided into two parts:
> +The KUnit architecture is divided into two parts:
>
> - `In-Kernel Testing Framework`_
> -- `kunit_tool (Command Line Test Harness)`_
> +- `kunit_tool (Command-line Test Harness)`_
>
> In-Kernel Testing Framework
> ===========================
>
> The kernel testing library supports KUnit tests written in C using
> -KUnit. KUnit tests are kernel code. KUnit does several things:
> +KUnit. KUnit tests are written in the kernel code. KUnit performs the following

I think "KUnit tests are kernel code" is better than "are written in
the kernel code": the distinction we're trying to draw here is between
"kernel" and "userspace" code.

I prefer just "see" to "see the following link".

But maybe the whole thing could be "are stored in a linker section
called ``.kunit_test_suites``, as defined in:"

> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.

If we're updating things, do we update the link to a newer version?

> +
> The linker section consists of an array of pointers to
> ``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
> -macro. To run all tests compiled into the kernel, the KUnit executor
> +macro. To run all the compiled tests into the kernel, the KUnit executor

I think we want "all the tests [which are] compiled into the kernel" here.

> iterates over the linker section array.
>
> .. kernel-figure:: kunit_suitememorydiagram.svg
> @@ -90,8 +92,8 @@ iterates over the linker section array.
> KUnit Suite Memory Diagram
>
> On the kernel boot, the KUnit executor uses the start and end addresses
> -of this section to iterate over and run all tests. For code, see:
> -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
> +of this section to iterate over and run all tests. For code, see the following link:

As above, I prefer this without "the following link".

> +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c.
>
> When built as a module, the ``kunit_test_suites()`` macro defines a
> ``module_init()`` function, which runs all the tests in the compilation
> @@ -99,46 +101,48 @@ unit instead of utilizing the executor.
>
> In KUnit tests, some error classes do not affect other tests
> or parts of the kernel, each KUnit case executes in a separate thread
> -context. For code, see:
> +context. For code, see the following link:

[And again.] Also, this (and the above) links could be updated if we
were updating the lines around them. Since we might drop this part of
the change, though, it's probably not worth it.

> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58
>
> Assertion Macros
> ----------------
>
> -KUnit tests verify state using expectations/assertions.
> +KUnit tests verify the state using expectations/assertions.

This could go either way, I think since these are verifying "some"
state, but each call does not verify "all" of the state, it's better
without the "the" here.

I could be persuaded otherwise.

> All expectations/assertions are formatted as:
> ``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``
>
> - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
> expectation.
>
> - - For an expectation, if the check fails, marks the test as failed
> + - For an expectation, if the check fails, it marks the test as failed

Maybe just "An exception, if the check fails, marks the test as
failed". Or something else less convoluted?

> and logs the failure.
>
> - An assertion, on failure, causes the test case to terminate
> immediately.
>
> - - Assertions call function:
> + - Assertion calls the function:

"Assertions call the function"? There can be many assertions.

> ``void __noreturn kunit_abort(struct kunit *)``.
>
> - - ``kunit_abort`` calls function:
> + - ``kunit_abort`` calls the function:
> ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.
>
> - - ``kunit_try_catch_throw`` calls function:
> + - ``kunit_try_catch_throw`` calls the function:
> ``void kthread_complete_and_exit(struct completion *, long) __noreturn;``
> and terminates the special thread context.
>
> - ``<op>`` denotes a check with options: ``TRUE`` (supplied property
> - has the boolean value “true”), ``EQ`` (two supplied properties are
> + has the boolean value "true"), ``EQ`` (two supplied properties are
> equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
> - contain an “err” value).
> + contain an "err" value).
>
> - ``[_MSG]`` prints a custom message on failure.
>
> Test Result Reporting
> ---------------------
> -KUnit prints test results in KTAP format. KTAP is based on TAP14, see:
> +KUnit prints the test results in KTAP format.
> +KTAP is based on TAP14, see:
> https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md.
> +

Let's take this opportunity to link to the final KTAP spec in
Documentation/dev-tools/ktap.rst

> KTAP (yet to be standardized format) works with KUnit and Kselftest.

Let's update this, as KTAP is standardised.

> The KUnit executor prints KTAP results to dmesg, and debugfs
> (if configured).
> @@ -151,32 +155,32 @@ parameters. The test is invoked multiple times, once for each parameter
> value and the parameter is stored in the ``param_value`` field.
> The test case includes a KUNIT_CASE_PARAM() macro that accepts a
> generator function.
> -The generator function is passed the previous parameter and returns the next
> -parameter. It also provides a macro to generate common-case generators based on
> -arrays.
> +The previous parameter is passed to the generator function, which returns
> +the next parameter. It also includes a macro for generating array-based
> +common-case generators.

In this case, I prefer the first one, as the "generator function" is
what we're describing, so should be the subject of the sentence.

>
> -kunit_tool (Command Line Test Harness)
> +kunit_tool (Command-line Test Harness)
> ======================================
>
> -kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)``
> -that can be used to configure, build, exec, parse and run (runs other
> -commands in order) test results. You can either run KUnit tests using
> -kunit_tool or can include KUnit in kernel and parse manually.
> +``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
> +is used to configure, build, execute, parse, and run (other commands in order)

"run" runs all of the previous commands in order (i.e., configure,
build, execute, and parse), so maybe we can expand the parenthetical
to make that more obvious?

> +test results. You have two options for running KUnit tests: either include KUnit
> +in the kernel and parse manually, or use the ``kunit_tool``.

Maybe we should avoid saying "include KUnit in the kernel" here. This
has always been a bit misleading. KUnit is always included in the
kernel, but can be "configured, built, and run" manually, or via
kunit_tool. kunit_tool can also parse the results.

>
> - ``configure`` command generates the kernel ``.config`` from a
> ``.kunitconfig`` file (and any architecture-specific options).
> - For some architectures, additional config options are specified in the
> - ``qemu_config`` Python script
> - (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``).
> + The Python script available in ``qemu_configs`` folder
> + (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
> + additional configuration options for specific architectures.

I think this should be "the Python scripts", as there's one per architecture.

> It parses both the existing ``.config`` and the ``.kunitconfig`` files
> - and ensures that ``.config`` is a superset of ``.kunitconfig``.
> - If this is not the case, it will combine the two and run
> - ``make olddefconfig`` to regenerate the ``.config`` file. It then
> - verifies that ``.config`` is now a superset. This checks if all
> - Kconfig dependencies are correctly specified in ``.kunitconfig``.
> - ``kunit_config.py`` includes the parsing Kconfigs code. The code which
> - runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can
> - invoke this command via: ``./tools/testing/kunit/kunit.py config`` and
> + to ensure that ``.config`` is a superset of ``.kunitconfig``.
> + If not, it will combine the two and execute ``make olddefconfig`` to regenerate

"run" reads more cleanly than "execute" here, IMO.

> + the ``.config`` file. It then checks to see if ``.config`` has become a superset.
> + This verifies that all the Kconfig dependencies are correctly specified in the file
> + ``.kunitconfig``. The

Word wrapping is a bit odd here?

> + ``kunit_config.py`` script contains the code for parsing Kconfigs. The code which
> + runs ``make olddefconfig`` is part of the ``kunit_kernel.py`` script. You can
> + invoke this command through: ``./tools/testing/kunit/kunit.py config`` and
> generate a ``.config`` file.
> - ``build`` runs ``make`` on the kernel tree with required options
> (depends on the architecture and some options, for example: build_dir)
> @@ -184,8 +188,8 @@ kunit_tool or can include KUnit in kernel and parse manually.
> To build a KUnit kernel from the current ``.config``, you can use the
> ``build`` argument: ``./tools/testing/kunit/kunit.py build``.
> - ``exec`` command executes kernel results either directly (using
> - User-mode Linux configuration), or via an emulator such
> - as QEMU. It reads results from the log via standard
> + User-mode Linux configuration), or through an emulator such
> + as QEMU. It reads results from the log using standard
> output (stdout), and passes them to ``parse`` to be parsed.
> If you already have built a kernel with built-in KUnit tests,
> you can run the kernel and display the test results with the ``exec``
> --
> 2.38.0.rc1.362.ged0d419d3c-goog
>

> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221010171353.1106166-1-sadiyakazi%40google.com.

[Bagas Sanjaya]

On 10/11/22 00:13, Sadiya Kazi wrote:
> The kernel testing library supports KUnit tests written in C using
> -KUnit. KUnit tests are kernel code. KUnit does several things:
> +KUnit. KUnit tests are written in the kernel code. KUnit performs the following
> +tasks:
>

What about "The kernel testing library supports KUnit tests, which are
written in ordinary kernel code."?

> - Organizes tests
> - Reports test results
> @@ -22,8 +23,8 @@ KUnit. KUnit tests are kernel code. KUnit does several things:
> Test Cases
> ----------
>
> -The fundamental unit in KUnit is the test case. The KUnit test cases are
> -grouped into KUnit suites. A KUnit test case is a function with type
> +The test case is the fundamental unit in KUnit. KUnit test cases are organised
> +into suites. A KUnit test case is a function with type

"which is organized into a test suite".

> The KUnit executor can list and run built-in KUnit tests on boot.
> The Test suites are stored in a linker section
> -called ``.kunit_test_suites``. For code, see:
> +called ``.kunit_test_suites``. For code, see the following link:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.

Instead of link to torvalds's tree, just say "See ``include/asm-generic/vmlinux.lds.h``
for the full code".

> On the kernel boot, the KUnit executor uses the start and end addresses
> -of this section to iterate over and run all tests. For code, see:
> -https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
> +of this section to iterate over and run all tests. For code, see the following link:
> +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c.
>

Same reply above.

> In KUnit tests, some error classes do not affect other tests
> or parts of the kernel, each KUnit case executes in a separate thread
> -context. For code, see:
> +context. For code, see the following link:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58
>

Same reply above.

> Assertion Macros
> ----------------
>
> -KUnit tests verify state using expectations/assertions.
> +KUnit tests verify the state using expectations/assertions.
> All expectations/assertions are formatted as:
> ``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``
>
> - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
> expectation.
>
> - - For an expectation, if the check fails, marks the test as failed
> + - For an expectation, if the check fails, it marks the test as failed
> and logs the failure.
>
> - An assertion, on failure, causes the test case to terminate
> immediately.

Better say:

```
In case of failure, there are differences on testing flow:

- For expectations, the test is marked as failed and the failure is logged.
- On the other hand, failing assertions cause the test case to be
immediately terminated.
```

The kunit_tool description above is redundant. Instead, just say "For
the documentation on using kunit_tool, see
Documentation/dev-tools/kunit/run_wrapper.rst".

Thanks.

--
An old man doll... just what I always wanted! - Clara

[Sadiya Kazi]

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.

-Update all occurrences of Command Line to
Command-line across the document.
-Correct grammatical issues, for example, added _it_
wherever missing.
-Update all occurrences of “via" to either
use “through” or “using”.

-Update the text preceding the external links and pushed
the full link to a new line for better readability.
-Reword content under the config command to make it
more clear and concise.

Signed-off-by: Sadiya Kazi <sadiy...@google.com>
---

Thank you David and Bagas for reviewing the doc. I have added the feedback.

Changes since V1:
https://lore.kernel.org/linux-kselftest/20221010171353.11...@google.com/
- Corrected the typo in the commit message.
- Followed the style for links as suggested by Bagas throughout the document.
- Updated the links for latest versions whereever applicable
(Note: Links having no changes between 5.15 and 6.0 have been retained).
- Updated the KTAP spec link to point to Documentation/dev-tools/ktap.rst.
- Reworded content as per David and Bagas's feedback.

---
.../dev-tools/kunit/architecture.rst | 114 +++++++++---------
1 file changed, 57 insertions(+), 57 deletions(-)

diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
index 8efe792bdcb9..b8ee0fa8afc3 100644

--- a/Documentation/dev-tools/kunit/architecture.rst
+++ b/Documentation/dev-tools/kunit/architecture.rst
@@ -4,16 +4,17 @@
KUnit Architecture
==================

-The KUnit architecture can be divided into two parts:
+The KUnit architecture is divided into two parts:

- `In-Kernel Testing Framework`_
-- `kunit_tool (Command Line Test Harness)`_
+- `kunit_tool (Command-line Test Harness)`_

In-Kernel Testing Framework
===========================

The kernel testing library supports KUnit tests written in C using
-KUnit. KUnit tests are kernel code. KUnit does several things:

+KUnit. These KUnit tests are kernel code. KUnit performs the following
+tasks:

- Organizes tests
- Reports test results

@@ -22,19 +23,17 @@ KUnit. KUnit tests are kernel code. KUnit does several things:

Test Cases
----------

-The fundamental unit in KUnit is the test case. The KUnit test cases are
-grouped into KUnit suites. A KUnit test case is a function with type

-signature ``void (*)(struct kunit *test)``.
-These test case functions are wrapped in a struct called
-struct kunit_case.

+The test case is the fundamental unit in KUnit. KUnit test cases are organised

+into suites. A KUnit test case is a function with type signature
+``void (*)(struct kunit *test)``. These test case functions are wrapped in a
+struct called struct kunit_case.

.. note:
``generate_params`` is optional for non-parameterized tests.

-Each KUnit test case gets a ``struct kunit`` context
-object passed to it that tracks a running test. The KUnit assertion

-macros and other KUnit utilities use the ``struct kunit`` context
-object. As an exception, there are two fields:

+Each KUnit test case receives a ``struct kunit`` context object that tracks a
+running test. The KUnit assertion macros and other KUnit utilities use the

+``struct kunit`` context object. As an exception, there are two fields:

- ``->priv``: The setup functions can use it to store arbitrary test
user data.
@@ -77,12 +76,12 @@ Executor

The KUnit executor can list and run built-in KUnit tests on boot.
The Test suites are stored in a linker section
-called ``.kunit_test_suites``. For code, see:

-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.
+called ``.kunit_test_suites``. For the full code, see
+`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_ .

The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
-macro. To run all tests compiled into the kernel, the KUnit executor

-iterates over the linker section array.
+macro. The KUnit executor iterates over the linker section array in order to
+run all the tests that are compiled into the kernel.

.. kernel-figure:: kunit_suitememorydiagram.svg
:alt: KUnit Suite Memory
@@ -90,17 +89,16 @@ iterates over the linker section array.
KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses
-of this section to iterate over and run all tests. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c

-
+of this section to iterate over and run all tests. For the full code, see
+`executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.

When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation

unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
-context. For code, see:

-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58
+context. For the full code, see
+`try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.

Assertion Macros
----------------
@@ -111,37 +109,36 @@ All expectations/assertions are formatted as:

- ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
expectation.

+ In the event of a failure, the testing flow differs as follows:

- - For an expectation, if the check fails, marks the test as failed

- and logs the failure.
+ - For expectations, the test is marked as failed and the failure is logged.

- - An assertion, on failure, causes the test case to terminate
- immediately.
+ - Failing assertions, on the other hand, result in the test case being
+ terminated immediately.

- - Assertions call function:

+ - Assertions call the function:

``void __noreturn kunit_abort(struct kunit *)``.

- - ``kunit_abort`` calls function:
+ - ``kunit_abort`` calls the function:
``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.

- - ``kunit_try_catch_throw`` calls function:
+ - ``kunit_try_catch_throw`` calls the function:
``void kthread_complete_and_exit(struct completion *, long) __noreturn;``
and terminates the special thread context.

- ``<op>`` denotes a check with options: ``TRUE`` (supplied property
- has the boolean value “true”), ``EQ`` (two supplied properties are
+ has the boolean value "true"), ``EQ`` (two supplied properties are
equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
- contain an “err” value).
+ contain an "err" value).

- ``[_MSG]`` prints a custom message on failure.

Test Result Reporting
---------------------
-KUnit prints test results in KTAP format. KTAP is based on TAP14, see:

-https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md.
-KTAP (yet to be standardized format) works with KUnit and Kselftest.
-The KUnit executor prints KTAP results to dmesg, and debugfs
-(if configured).
+KUnit prints the test results in KTAP format. KTAP is based on TAP14, see
+Documentation/dev-tools/ktap.rst.
+KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to
+dmesg, and debugfs (if configured).

Parameterized Tests
-------------------
@@ -150,33 +147,33 @@ Each KUnit parameterized test is associated with a collection of

parameters. The test is invoked multiple times, once for each parameter
value and the parameter is stored in the ``param_value`` field.
The test case includes a KUNIT_CASE_PARAM() macro that accepts a

-generator function.

-The generator function is passed the previous parameter and returns the next
-parameter. It also provides a macro to generate common-case generators based on
-arrays.

+generator function. The generator function is passed the previous parameter
+and returns the next parameter. It also includes a macro for generating
+array-based common-case generators.

-kunit_tool (Command Line Test Harness)
+kunit_tool (Command-line Test Harness)
======================================

-kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)``
-that can be used to configure, build, exec, parse and run (runs other
-commands in order) test results. You can either run KUnit tests using
-kunit_tool or can include KUnit in kernel and parse manually.
+``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It

+is used to configure, build, execute, parse test results and run all of the
+previous commands in correct order (i.e., configure, build, execute and parse).
+You have two options for running KUnit tests: either use KUnit
+directly through the kernel and parse manually, or use the ``kunit_tool``.

- ``configure`` command generates the kernel ``.config`` from a
``.kunitconfig`` file (and any architecture-specific options).
- For some architectures, additional config options are specified in the
- ``qemu_config`` Python script
- (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``).

+ The Python scripts available in ``qemu_configs`` folder

+ (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
+ additional configuration options for specific architectures.
It parses both the existing ``.config`` and the ``.kunitconfig`` files
- and ensures that ``.config`` is a superset of ``.kunitconfig``.
- If this is not the case, it will combine the two and run
- ``make olddefconfig`` to regenerate the ``.config`` file. It then
- verifies that ``.config`` is now a superset. This checks if all
- Kconfig dependencies are correctly specified in ``.kunitconfig``.
- ``kunit_config.py`` includes the parsing Kconfigs code. The code which
- runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can
- invoke this command via: ``./tools/testing/kunit/kunit.py config`` and
+ to ensure that ``.config`` is a superset of ``.kunitconfig``.

+ If not, it will combine the two and run ``make olddefconfig`` to regenerate

+ the ``.config`` file. It then checks to see if ``.config`` has become a superset.
+ This verifies that all the Kconfig dependencies are correctly specified in the file

+ ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing
+ Kconfigs. The code which runs ``make olddefconfig`` is part of the
+ ``kunit_kernel.py`` script. You can invoke this command through:
+ ``./tools/testing/kunit/kunit.py config`` and

generate a ``.config`` file.
- ``build`` runs ``make`` on the kernel tree with required options
(depends on the architecture and some options, for example: build_dir)

@@ -184,8 +181,8 @@ kunit_tool or can include KUnit in kernel and parse manually.

To build a KUnit kernel from the current ``.config``, you can use the
``build`` argument: ``./tools/testing/kunit/kunit.py build``.
- ``exec`` command executes kernel results either directly (using
- User-mode Linux configuration), or via an emulator such
- as QEMU. It reads results from the log via standard
+ User-mode Linux configuration), or through an emulator such
+ as QEMU. It reads results from the log using standard
output (stdout), and passes them to ``parse`` to be parsed.
If you already have built a kernel with built-in KUnit tests,
you can run the kernel and display the test results with the ``exec``

@@ -193,3 +190,6 @@ kunit_tool or can include KUnit in kernel and parse manually.
- ``parse`` extracts the KTAP output from a kernel log, parses
the test results, and prints a summary. For failed tests, any
diagnostic output will be included.
+
+For more information on kunit_tool, see
+Documentation/dev-tools/kunit/run_wrapper.rst.
--
2.38.0.rc1.362.ged0d419d3c-goog

[Bagas Sanjaya]

On Thu, Oct 13, 2022 at 08:05:46AM +0000, Sadiya Kazi wrote:
> Updated the architecture.rst page with the following changes:
> -Add missing article _the_ across the document.
> -Reword content across for style and standard.
> -Update all occurrences of Command Line to
> Command-line across the document.
> -Correct grammatical issues, for example, added _it_
> wherever missing.
> -Update all occurrences of “via" to either
> use “through” or “using”.
> -Update the text preceding the external links and pushed
> the full link to a new line for better readability.
> -Reword content under the config command to make it
> more clear and concise.
>

I think this patch is rewriting the documentation, since you touch most
of the doc.

That's not what I mean in my review to v1 [1], so here are the proper
changes:

---- >8 ----
diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
index b8ee0fa8afc3ea..1f0fd53b66858d 100644
--- a/Documentation/dev-tools/kunit/architecture.rst
+++ b/Documentation/dev-tools/kunit/architecture.rst
@@ -7,7 +7,7 @@ KUnit Architecture

The KUnit architecture is divided into two parts:

- `In-Kernel Testing Framework`_

-- `kunit_tool (Command-line Test Harness)`_
+- `Running Tests Options`_

In-Kernel Testing Framework
===========================
@@ -76,8 +76,8 @@ Executor

The KUnit executor can list and run built-in KUnit tests on boot.
The Test suites are stored in a linker section

-called ``.kunit_test_suites``. For the full code, see
-`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_ .
+called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro
+definition in ``include/asm-generic/vmlinux.lds.h``

The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``

macro. The KUnit executor iterates over the linker section array in order to

@@ -89,16 +89,17 @@ run all the tests that are compiled into the kernel.

KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses

-of this section to iterate over and run all tests. For the full code, see
-`executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.
+of this section to iterate over and run all tests. For the implementation
+of executor, see
+``lib/kunit/executor.c``.

When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread

-context. For the full code, see
-`try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.
+context. See ``kunit_try_catch_run()`` function code in
+``lib/kunit/try-catch.c`` for the implementation details.

Assertion Macros
----------------
@@ -151,45 +152,10 @@ generator function. The generator function is passed the previous parameter

and returns the next parameter. It also includes a macro for generating

array-based common-case generators.

-kunit_tool (Command-line Test Harness)
-======================================
+Running Tests Options
+=====================

-``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
-is used to configure, build, execute, parse test results and run all of the
-previous commands in correct order (i.e., configure, build, execute and parse).
-You have two options for running KUnit tests: either use KUnit
-directly through the kernel and parse manually, or use the ``kunit_tool``.
-
-- ``configure`` command generates the kernel ``.config`` from a
- ``.kunitconfig`` file (and any architecture-specific options).
- The Python scripts available in ``qemu_configs`` folder
- (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
- additional configuration options for specific architectures.
- It parses both the existing ``.config`` and the ``.kunitconfig`` files
- to ensure that ``.config`` is a superset of ``.kunitconfig``.
- If not, it will combine the two and run ``make olddefconfig`` to regenerate
- the ``.config`` file. It then checks to see if ``.config`` has become a superset.
- This verifies that all the Kconfig dependencies are correctly specified in the file
- ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing
- Kconfigs. The code which runs ``make olddefconfig`` is part of the
- ``kunit_kernel.py`` script. You can invoke this command through:
- ``./tools/testing/kunit/kunit.py config`` and
- generate a ``.config`` file.
-- ``build`` runs ``make`` on the kernel tree with required options
- (depends on the architecture and some options, for example: build_dir)
- and reports any errors.
- To build a KUnit kernel from the current ``.config``, you can use the
- ``build`` argument: ``./tools/testing/kunit/kunit.py build``.
-- ``exec`` command executes kernel results either directly (using
- User-mode Linux configuration), or through an emulator such
- as QEMU. It reads results from the log using standard
- output (stdout), and passes them to ``parse`` to be parsed.
- If you already have built a kernel with built-in KUnit tests,
- you can run the kernel and display the test results with the ``exec``
- argument: ``./tools/testing/kunit/kunit.py exec``.
-- ``parse`` extracts the KTAP output from a kernel log, parses
- the test results, and prints a summary. For failed tests, any
- diagnostic output will be included.
-
-For more information on kunit_tool, see
-Documentation/dev-tools/kunit/run_wrapper.rst.
+There are two options to run tests: either build the kernel with KUnit
+enabled and manually parse the results (see
+Documentation/dev-tools/kunit/run_manual.rst) or use kunit_tool script
+(see Documentation/dev-tools/kunit/run_wrapper.rst).

Thanks.

[1]: https://lore.kernel.org/linux-kselftest/2d174fee-bdd1-a304...@gmail.com/

[Sadiya Kazi]

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.
-Update all occurrences of Command Line to Command-line
across the document.
-Correct grammatical issues, for example,

added _it_wherever missing.

-Update all occurrences of “via" to either use
“through” or “using”.
-Update the text preceding the external links and pushed the full
link to a new line for better readability.
-Reword content under the config command to make it more clear and concise.

Signed-off-by: Sadiya Kazi <sadiy...@google.com>
---

Thank you Bagas for your detailed comments.
I think the current commit message does convey the right message as it is not a complete rewrite, hence retained it.
Also since we talk about the two parts of the architecture, I have retained the it as 'kunit_tool (Command-line Test Harness)' instead of 'Running Tests Options'.

Changes since v2:
https://lore.kernel.org/linux-kselftest/20221013080545.15...@google.com/
-Updated the link descriptions as per Bagas’s feedback
-Reworded content talking about options to run tests and added links as per Bagas’s feedback

Best Regards,
Sadiya Kazi
---
.../dev-tools/kunit/architecture.rst | 118 +++++++++---------
1 file changed, 60 insertions(+), 58 deletions(-)

diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
index 8efe792bdcb9..52b1a30c9f89 100644

@@ -75,14 +74,15 @@ with the KUnit test framework.
Executor
--------

-The KUnit executor can list and run built-in KUnit tests on boot.
+The KUnit executor can list and run built-in KUnit tests on boot

The Test suites are stored in a linker section
-called ``.kunit_test_suites``. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.

+called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro
+definition in

+`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_.

The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
-macro. To run all tests compiled into the kernel, the KUnit executor
-iterates over the linker section array.
+macro. The KUnit executor iterates over the linker section array in order to
+run all the tests that are compiled into the kernel.

.. kernel-figure:: kunit_suitememorydiagram.svg
:alt: KUnit Suite Memory

@@ -90,17 +90,18 @@ iterates over the linker section array.

KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses
-of this section to iterate over and run all tests. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
-

+of this section to iterate over and run all tests. For the implementation of the
+executor, see
+`lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.

When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
-context. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58

+context. For the implememtation details, see ``kunit_try_catch_run()`` function
+code in
+`lib/kunit/try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.

Assertion Macros
----------------
@@ -111,37 +112,36 @@ All expectations/assertions are formatted as:

@@ -150,33 +150,35 @@ Each KUnit parameterized test is associated with a collection of

parameters. The test is invoked multiple times, once for each parameter
value and the parameter is stored in the ``param_value`` field.
The test case includes a KUNIT_CASE_PARAM() macro that accepts a
-generator function.
-The generator function is passed the previous parameter and returns the next
-parameter. It also provides a macro to generate common-case generators based on
-arrays.
+generator function. The generator function is passed the previous parameter
+and returns the next parameter. It also includes a macro for generating
+array-based common-case generators.

-kunit_tool (Command Line Test Harness)
+kunit_tool (Command-line Test Harness)
======================================

-kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)``
-that can be used to configure, build, exec, parse and run (runs other
-commands in order) test results. You can either run KUnit tests using
-kunit_tool or can include KUnit in kernel and parse manually.
+``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
+is used to configure, build, execute, parse test results and run all of the
+previous commands in correct order (i.e., configure, build, execute and parse).

+You have two options for running KUnit tests: either build the kernel with KUnit

+enabled and manually parse the results (see

+Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool``
+(see Documentation/dev-tools/kunit/run_wrapper.rst).

- ``configure`` command generates the kernel ``.config`` from a
``.kunitconfig`` file (and any architecture-specific options).
- For some architectures, additional config options are specified in the
- ``qemu_config`` Python script
- (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``).
+ The Python scripts available in ``qemu_configs`` folder
+ (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
+ additional configuration options for specific architectures.
It parses both the existing ``.config`` and the ``.kunitconfig`` files
- and ensures that ``.config`` is a superset of ``.kunitconfig``.
- If this is not the case, it will combine the two and run
- ``make olddefconfig`` to regenerate the ``.config`` file. It then
- verifies that ``.config`` is now a superset. This checks if all
- Kconfig dependencies are correctly specified in ``.kunitconfig``.
- ``kunit_config.py`` includes the parsing Kconfigs code. The code which
- runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can
- invoke this command via: ``./tools/testing/kunit/kunit.py config`` and
+ to ensure that ``.config`` is a superset of ``.kunitconfig``.
+ If not, it will combine the two and run ``make olddefconfig`` to regenerate
+ the ``.config`` file. It then checks to see if ``.config`` has become a superset.
+ This verifies that all the Kconfig dependencies are correctly specified in the

+ file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing

+ Kconfigs. The code which runs ``make olddefconfig`` is part of the
+ ``kunit_kernel.py`` script. You can invoke this command through:
+ ``./tools/testing/kunit/kunit.py config`` and
generate a ``.config`` file.
- ``build`` runs ``make`` on the kernel tree with required options
(depends on the architecture and some options, for example: build_dir)

@@ -184,8 +186,8 @@ kunit_tool or can include KUnit in kernel and parse manually.

To build a KUnit kernel from the current ``.config``, you can use the
``build`` argument: ``./tools/testing/kunit/kunit.py build``.
- ``exec`` command executes kernel results either directly (using
- User-mode Linux configuration), or via an emulator such
- as QEMU. It reads results from the log via standard
+ User-mode Linux configuration), or through an emulator such
+ as QEMU. It reads results from the log using standard
output (stdout), and passes them to ``parse`` to be parsed.
If you already have built a kernel with built-in KUnit tests,
you can run the kernel and display the test results with the ``exec``

--
2.38.0.413.g74048e4d9e-goog

[Sadiya Kazi]

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.
-Update all occurrences of Command Line to Command-line
across the document.
-Correct grammatical issues, for example,
added _it_wherever missing.
-Update all occurrences of “via" to either use
“through” or “using”.
-Update the text preceding the external links and pushed the full
link to a new line for better readability.
-Reword content under the config command to make it more clear and concise.

Signed-off-by: Sadiya Kazi <sadiy...@google.com>
---

Please Note: The link in the change log in my previous email was broken as it got
mixed with the next line. I have resent the email.

[Bagas Sanjaya]

Seems like you're ignoring my review suggestions from both v1 and v2
(code locations and redundant kunit_tool summary), hence NAK until you address
them.

Thanks.

[Bagas Sanjaya]

Seems like you ignore my requested changes from v1 and v2 review (code
location link and redundant kunit_tool summary), hence NAK until you
have addressed them.

[Sadiya Kazi]

Hi Bagas,
The code location link change has been addressed as per your suggestion. If you think this is not what you have suggested then please give more details. Also, IMO, we should retain a high-level kunit_tool summary on this page and as per your feedback, I have already linked it to the kunit_tool documentation page.
If there are any other changes that I have missed out, please let me know.

Best Regards,
Sadiya

--
You received this message because you are subscribed to the Google Groups "KUnit Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/Y00im2gq9/c5NzVt%40debian.me.

[Jonathan Corbet]

Bagas Sanjaya <bagas...@gmail.com> writes:

> Seems like you ignore my requested changes from v1 and v2 review (code
> location link and redundant kunit_tool summary), hence NAK until you
> have addressed them.

Bagas, you are not a maintainer of or contributor to this work; you are
in no position to "NAK" anything. I will ask you, yet again, to please
focus on doing useful work yourself rather than on adding friction for
others.

jon

[David Gow]

On Mon, Oct 17, 2022 at 3:13 PM 'Sadiya Kazi' via KUnit Development
<kuni...@googlegroups.com> wrote:
>
> Updated the architecture.rst page with the following changes:
> -Add missing article _the_ across the document.
> -Reword content across for style and standard.
> -Update all occurrences of Command Line to Command-line
> across the document.
> -Correct grammatical issues, for example,
> added _it_wherever missing.
> -Update all occurrences of “via" to either use
> “through” or “using”.
> -Update the text preceding the external links and pushed the full
> link to a new line for better readability.
> -Reword content under the config command to make it more clear and concise.
>
> Signed-off-by: Sadiya Kazi <sadiy...@google.com>
> ---

Thanks very much: this looks good to me. A few very minor notes below,
otherwise this is good to go.

Reviewed-by: David Gow <davi...@google.com>

Cheers,
-- David

Nit: shouldn't we keep the full stop here?

Nit: spelling of "implementation". Also, it should be "see _the_
``kunit_try_catch_run()`` function". (In fact, I think we could drop
"For the implementation details" here, which seems redundant to me,
but I'm also okay with keeping it, if you prefer.)

> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221017070820.2253501-1-sadiyakazi%40google.com.

[Sadiya Kazi]

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.
-Update all occurrences of Command Line to Command-line
across the document.
-Correct grammatical issues, for example,
added _it_wherever missing.
-Update all occurrences of “via" to either use
“through” or “using”.
-Update the text preceding the external links and pushed the full
link to a new line for better readability.
-Reword content under the config command to make it more clear and concise.

Signed-off-by: Sadiya Kazi <sadiy...@google.com>

Reviewed-by: David Gow <davi...@google.com>
---
Thank you David. I have made the changes as per your feedback.
Changes since V3:
https://lore.kernel.org/linux-kselftest/20221017070820.22...@google.com/

- Added the missing full stop
- Reworded content around the ``kunit_try_catch_run()`` funtion

Regards,
Sadiya

---
.../dev-tools/kunit/architecture.rst | 115 +++++++++---------
1 file changed, 58 insertions(+), 57 deletions(-)

diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst
index 8efe792bdcb9..e95ab05342bb 100644

@@ -77,12 +76,13 @@ Executor

The KUnit executor can list and run built-in KUnit tests on boot.

The Test suites are stored in a linker section
-called ``.kunit_test_suites``. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945.
+called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro
+definition in
+`include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_.
The linker section consists of an array of pointers to
``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
-macro. To run all tests compiled into the kernel, the KUnit executor
-iterates over the linker section array.
+macro. The KUnit executor iterates over the linker section array in order to
+run all the tests that are compiled into the kernel.

.. kernel-figure:: kunit_suitememorydiagram.svg
:alt: KUnit Suite Memory

@@ -90,17 +90,17 @@ iterates over the linker section array.

KUnit Suite Memory Diagram

On the kernel boot, the KUnit executor uses the start and end addresses
-of this section to iterate over and run all tests. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c
-
+of this section to iterate over and run all tests. For the implementation of the
+executor, see
+`lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.
When built as a module, the ``kunit_test_suites()`` macro defines a
``module_init()`` function, which runs all the tests in the compilation
unit instead of utilizing the executor.

In KUnit tests, some error classes do not affect other tests
or parts of the kernel, each KUnit case executes in a separate thread
-context. For code, see:
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58

+context. See the ``kunit_try_catch_run()`` function in

+`lib/kunit/try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.

Assertion Macros
----------------

@@ -111,37 +111,36 @@ All expectations/assertions are formatted as:

@@ -150,33 +149,35 @@ Each KUnit parameterized test is associated with a collection of

@@ -184,8 +185,8 @@ kunit_tool or can include KUnit in kernel and parse manually.

[David Gow]

On Tue, Oct 18, 2022 at 12:04 PM 'Sadiya Kazi' via KUnit Development
<kuni...@googlegroups.com> wrote:
>
> Updated the architecture.rst page with the following changes:
> -Add missing article _the_ across the document.
> -Reword content across for style and standard.
> -Update all occurrences of Command Line to Command-line
> across the document.
> -Correct grammatical issues, for example,
> added _it_wherever missing.
> -Update all occurrences of “via" to either use
> “through” or “using”.
> -Update the text preceding the external links and pushed the full
> link to a new line for better readability.
> -Reword content under the config command to make it more clear and concise.
>
> Signed-off-by: Sadiya Kazi <sadiy...@google.com>
> Reviewed-by: David Gow <davi...@google.com>
> ---

Thanks -- this looks good to me. Assuming nothing goes wrong, it
should be in 6.2.

Cheers,
-- David

> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221018040332.2384436-1-sadiyakazi%40google.com.