Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

Documentation: Kunit: Update architecture.rst for minor fixes

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 <sadiyakazi@google.com>
Reviewed-by: David Gow <davidgow@google.com>
Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>

authored by

Sadiya Kazi and committed by
Shuah Khan
f13ecba0 7b1dd2cf

+58 -57
+58 -57
Documentation/dev-tools/kunit/architecture.rst
··· 4 4 KUnit Architecture 5 5 ================== 6 6 7 - The KUnit architecture can be divided into two parts: 7 + The KUnit architecture is divided into two parts: 8 8 9 9 - `In-Kernel Testing Framework`_ 10 - - `kunit_tool (Command Line Test Harness)`_ 10 + - `kunit_tool (Command-line Test Harness)`_ 11 11 12 12 In-Kernel Testing Framework 13 13 =========================== 14 14 15 15 The kernel testing library supports KUnit tests written in C using 16 - KUnit. KUnit tests are kernel code. KUnit does several things: 16 + KUnit. These KUnit tests are kernel code. KUnit performs the following 17 + tasks: 17 18 18 19 - Organizes tests 19 20 - Reports test results ··· 23 22 Test Cases 24 23 ---------- 25 24 26 - The fundamental unit in KUnit is the test case. The KUnit test cases are 27 - grouped into KUnit suites. A KUnit test case is a function with type 28 - signature ``void (*)(struct kunit *test)``. 29 - These test case functions are wrapped in a struct called 30 - struct kunit_case. 25 + The test case is the fundamental unit in KUnit. KUnit test cases are organised 26 + into suites. A KUnit test case is a function with type signature 27 + ``void (*)(struct kunit *test)``. These test case functions are wrapped in a 28 + struct called struct kunit_case. 31 29 32 30 .. note: 33 31 ``generate_params`` is optional for non-parameterized tests. 34 32 35 - Each KUnit test case gets a ``struct kunit`` context 36 - object passed to it that tracks a running test. The KUnit assertion 37 - macros and other KUnit utilities use the ``struct kunit`` context 38 - object. As an exception, there are two fields: 33 + Each KUnit test case receives a ``struct kunit`` context object that tracks a 34 + running test. The KUnit assertion macros and other KUnit utilities use the 35 + ``struct kunit`` context object. As an exception, there are two fields: 39 36 40 37 - ``->priv``: The setup functions can use it to store arbitrary test 41 38 user data. ··· 76 77 77 78 The KUnit executor can list and run built-in KUnit tests on boot. 78 79 The Test suites are stored in a linker section 79 - called ``.kunit_test_suites``. For code, see: 80 - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v5.15#n945. 80 + called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro 81 + definition in 82 + `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>`_. 81 83 The linker section consists of an array of pointers to 82 84 ``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` 83 - macro. To run all tests compiled into the kernel, the KUnit executor 84 - iterates over the linker section array. 85 + macro. The KUnit executor iterates over the linker section array in order to 86 + run all the tests that are compiled into the kernel. 85 87 86 88 .. kernel-figure:: kunit_suitememorydiagram.svg 87 89 :alt: KUnit Suite Memory ··· 90 90 KUnit Suite Memory Diagram 91 91 92 92 On the kernel boot, the KUnit executor uses the start and end addresses 93 - of this section to iterate over and run all tests. For code, see: 94 - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c 95 - 93 + of this section to iterate over and run all tests. For the implementation of the 94 + executor, see 95 + `lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_. 96 96 When built as a module, the ``kunit_test_suites()`` macro defines a 97 97 ``module_init()`` function, which runs all the tests in the compilation 98 98 unit instead of utilizing the executor. 99 99 100 100 In KUnit tests, some error classes do not affect other tests 101 101 or parts of the kernel, each KUnit case executes in a separate thread 102 - context. For code, see: 103 - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58 102 + context. See the ``kunit_try_catch_run()`` function in 103 + `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>`_. 104 104 105 105 Assertion Macros 106 106 ---------------- ··· 111 111 112 112 - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an 113 113 expectation. 114 + In the event of a failure, the testing flow differs as follows: 114 115 115 - - For an expectation, if the check fails, marks the test as failed 116 - and logs the failure. 116 + - For expectations, the test is marked as failed and the failure is logged. 117 117 118 - - An assertion, on failure, causes the test case to terminate 119 - immediately. 118 + - Failing assertions, on the other hand, result in the test case being 119 + terminated immediately. 120 120 121 - - Assertions call function: 121 + - Assertions call the function: 122 122 ``void __noreturn kunit_abort(struct kunit *)``. 123 123 124 - - ``kunit_abort`` calls function: 124 + - ``kunit_abort`` calls the function: 125 125 ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. 126 126 127 - - ``kunit_try_catch_throw`` calls function: 127 + - ``kunit_try_catch_throw`` calls the function: 128 128 ``void kthread_complete_and_exit(struct completion *, long) __noreturn;`` 129 129 and terminates the special thread context. 130 130 131 131 - ``<op>`` denotes a check with options: ``TRUE`` (supplied property 132 - has the boolean value “true”), ``EQ`` (two supplied properties are 132 + has the boolean value "true"), ``EQ`` (two supplied properties are 133 133 equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not 134 - contain an “err” value). 134 + contain an "err" value). 135 135 136 136 - ``[_MSG]`` prints a custom message on failure. 137 137 138 138 Test Result Reporting 139 139 --------------------- 140 - KUnit prints test results in KTAP format. KTAP is based on TAP14, see: 141 - https://github.com/isaacs/testanything.github.io/blob/tap14/tap-version-14-specification.md. 142 - KTAP (yet to be standardized format) works with KUnit and Kselftest. 143 - The KUnit executor prints KTAP results to dmesg, and debugfs 144 - (if configured). 140 + KUnit prints the test results in KTAP format. KTAP is based on TAP14, see 141 + Documentation/dev-tools/ktap.rst. 142 + KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to 143 + dmesg, and debugfs (if configured). 145 144 146 145 Parameterized Tests 147 146 ------------------- ··· 149 150 parameters. The test is invoked multiple times, once for each parameter 150 151 value and the parameter is stored in the ``param_value`` field. 151 152 The test case includes a KUNIT_CASE_PARAM() macro that accepts a 152 - generator function. 153 - The generator function is passed the previous parameter and returns the next 154 - parameter. It also provides a macro to generate common-case generators based on 155 - arrays. 153 + generator function. The generator function is passed the previous parameter 154 + and returns the next parameter. It also includes a macro for generating 155 + array-based common-case generators. 156 156 157 - kunit_tool (Command Line Test Harness) 157 + kunit_tool (Command-line Test Harness) 158 158 ====================================== 159 159 160 - kunit_tool is a Python script ``(tools/testing/kunit/kunit.py)`` 161 - that can be used to configure, build, exec, parse and run (runs other 162 - commands in order) test results. You can either run KUnit tests using 163 - kunit_tool or can include KUnit in kernel and parse manually. 160 + ``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It 161 + is used to configure, build, execute, parse test results and run all of the 162 + previous commands in correct order (i.e., configure, build, execute and parse). 163 + You have two options for running KUnit tests: either build the kernel with KUnit 164 + enabled and manually parse the results (see 165 + Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool`` 166 + (see Documentation/dev-tools/kunit/run_wrapper.rst). 164 167 165 168 - ``configure`` command generates the kernel ``.config`` from a 166 169 ``.kunitconfig`` file (and any architecture-specific options). 167 - For some architectures, additional config options are specified in the 168 - ``qemu_config`` Python script 169 - (For example: ``tools/testing/kunit/qemu_configs/powerpc.py``). 170 + The Python scripts available in ``qemu_configs`` folder 171 + (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains 172 + additional configuration options for specific architectures. 170 173 It parses both the existing ``.config`` and the ``.kunitconfig`` files 171 - and ensures that ``.config`` is a superset of ``.kunitconfig``. 172 - If this is not the case, it will combine the two and run 173 - ``make olddefconfig`` to regenerate the ``.config`` file. It then 174 - verifies that ``.config`` is now a superset. This checks if all 175 - Kconfig dependencies are correctly specified in ``.kunitconfig``. 176 - ``kunit_config.py`` includes the parsing Kconfigs code. The code which 177 - runs ``make olddefconfig`` is a part of ``kunit_kernel.py``. You can 178 - invoke this command via: ``./tools/testing/kunit/kunit.py config`` and 174 + to ensure that ``.config`` is a superset of ``.kunitconfig``. 175 + If not, it will combine the two and run ``make olddefconfig`` to regenerate 176 + the ``.config`` file. It then checks to see if ``.config`` has become a superset. 177 + This verifies that all the Kconfig dependencies are correctly specified in the 178 + file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing 179 + Kconfigs. The code which runs ``make olddefconfig`` is part of the 180 + ``kunit_kernel.py`` script. You can invoke this command through: 181 + ``./tools/testing/kunit/kunit.py config`` and 179 182 generate a ``.config`` file. 180 183 - ``build`` runs ``make`` on the kernel tree with required options 181 184 (depends on the architecture and some options, for example: build_dir) ··· 185 184 To build a KUnit kernel from the current ``.config``, you can use the 186 185 ``build`` argument: ``./tools/testing/kunit/kunit.py build``. 187 186 - ``exec`` command executes kernel results either directly (using 188 - User-mode Linux configuration), or via an emulator such 189 - as QEMU. It reads results from the log via standard 187 + User-mode Linux configuration), or through an emulator such 188 + as QEMU. It reads results from the log using standard 190 189 output (stdout), and passes them to ``parse`` to be parsed. 191 190 If you already have built a kernel with built-in KUnit tests, 192 191 you can run the kernel and display the test results with the ``exec``