lkml.org 
[lkml]   [2022]   [Oct]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
Subject[PATCH] Documentation: Kunit: Update architecture.rst for minor fixes
From
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 <sadiyakazi@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
\
 
 \ /
  Last update: 2022-10-10 19:15    [W:0.051 / U:1.848 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site