Message-ID: <20221010171353.1106166-1-sadiyakazi@google.com>
Date:   Mon, 10 Oct 2022 17:13:53 +0000
From:   Sadiya Kazi <sadiyakazi@...gle.com>
To:     brendanhiggins@...gle.com, davidgow@...gle.com,
        skhan@...uxfoundation.org, corbet@....net,
        linux-kselftest@...r.kernel.org, kunit-dev@...glegroups.com,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Cc:     Sadiya Kazi <sadiyakazi@...gle.com>
Subject: [PATCH] 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.
-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@...gle.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

Powered by blists - more mailing lists