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

[Bagas Sanjaya <bagasdotme@gmail.com>]

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.
```

> -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``

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