From nobody Wed Apr 8 08:01:16 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 01E20C32772 for ; Mon, 22 Aug 2022 18:10:52 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236408AbiHVSKv (ORCPT ); Mon, 22 Aug 2022 14:10:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60986 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236820AbiHVSKh (ORCPT ); Mon, 22 Aug 2022 14:10:37 -0400 Received: from mail-pf1-x44a.google.com (mail-pf1-x44a.google.com [IPv6:2607:f8b0:4864:20::44a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 43A144622B for ; Mon, 22 Aug 2022 11:10:35 -0700 (PDT) Received: by mail-pf1-x44a.google.com with SMTP id by13-20020a056a00400d00b0052ec5a1cd4dso4903725pfb.21 for ; Mon, 22 Aug 2022 11:10:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:mime-version:message-id:date:from:to:cc; bh=qlD6NeLsjzcixDwtOHCxTrg3u7mh8GFZd+CsXJLZniE=; b=Zo9A95i3UccLuWai9d8/rafLsVcTppbLB6LThLylbNiZN8uVtjIWgFt6dmcy7arPza jGvhEJ6Xr8JqHxQl2TNVtqN9D+9jAxTPMdrJC86OwU3dfdtOeNEiM3aUQ6zIFPa/4GKn VcG/k3B6HMrfvvsS1ejioW9mvQYjw9oYM0L+l2pm2xtSQtqkgVmhHUEGSN7a42ZaBMxq tIGmy4fUWQfvoi1UBLd5vLM94l5EoG0t5r8sAxGwBZuGpmuzWScJ04cKJ82TmETH3+hQ qY2p7lmqImUGENosyXeJYGjFN863cksQXaTMb42qh7IzSd8SXo5B/JRxMNLo5WQme4kS dJ7w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:mime-version:message-id:date:x-gm-message-state :from:to:cc; bh=qlD6NeLsjzcixDwtOHCxTrg3u7mh8GFZd+CsXJLZniE=; b=khyt3BsaC6oe5+u86Nruzxn1+Vw5l6Gi4QI6rnHLdt5CPjOEsn1ST8VtKEiYz9Zytf fiVCwZyyMaPyfxXOV5OPPpEaX8uXj65AH5kHOd2tY0/nnHH+3ABqDJu5xJyxTbpC+M6R FBtCvFVnuITw+lnGUKNFTbyjUG20ovMefz+33C+iYu3cZe48UdwGjy+VwNm4T2BlaxuN bGFVhWtwKGK/az5L5QBi2PrmGGwruMVyfyztNud59w0aF/MguNpBzKJ/sLTn2ksdRWrW pK++gaVtCQI0q5Z54JIXEvcykFwtgNcNrEW0tOgw7PhCuMQ/kkrZP4MT7uZisxsDV7Kh KN6w== X-Gm-Message-State: ACgBeo3r6G5cGoFAmqoTNFbQ9uVVH1L9c0gFAUI6IdaG6ovwcFuvuPKk /voxCNLsB+3rXbcZJTNAwL/mvsgTQNPVhEfe X-Google-Smtp-Source: AA6agR5CXQQiS+1zFYsmDhF9Fy+ePsTwFuotO+BWRhclkJ7/SuOGlEcaMFAZ1R/hJk280pakCYkFLYb+hDsf1rwO X-Received: from skazigti.c.googlers.com ([fda3:e722:ac3:cc00:4f:4b78:c0a8:411e]) (user=sadiyakazi job=sendgmr) by 2002:a05:6a00:855:b0:52e:f01d:723a with SMTP id q21-20020a056a00085500b0052ef01d723amr21871779pfk.31.1661191834758; Mon, 22 Aug 2022 11:10:34 -0700 (PDT) Date: Mon, 22 Aug 2022 18:09:56 +0000 Message-Id: <20220822180956.4013497-1-sadiyakazi@google.com> Mime-Version: 1.0 X-Mailer: git-send-email 2.37.1.595.g718a3a8f04-goog Subject: [PATCH] Documentation: KUnit: Reword kunit_tool guide From: Sadiya Kazi To: brendanhiggins@google.com, davidgow@google.com, skhan@linuxfoundation.org, corbet@lwn.net Cc: linux-kselftest@vger.kernel.org, kunit-dev@googlegroups.com, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Sadiya Kazi Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Updated the kunit_tool.rst guide to streamline it. The following changes were made: 1. Updated headings 2. Reworded content across sections 3. Added a cross reference to full list of command-line args Signed-off-by: Sadiya Kazi --- Documentation/dev-tools/kunit/kunit-tool.rst | 82 ++++++++++---------- 1 file changed, 42 insertions(+), 40 deletions(-) diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/d= ev-tools/kunit/kunit-tool.rst index ae52e0f489f9..33186679f5de 100644 --- a/Documentation/dev-tools/kunit/kunit-tool.rst +++ b/Documentation/dev-tools/kunit/kunit-tool.rst @@ -1,8 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 =20 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -kunit_tool How-To -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Understanding kunit_tool +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This page introduces the kunit_tool and covers the concepts and working of= this tool. =20 What is kunit_tool? =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -10,39 +12,37 @@ What is kunit_tool? kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in bui= lding the Linux kernel as UML (`User Mode Linux `_), running KUnit tests, parsing -the test results and displaying them in a user friendly manner. +the test results and displaying them in a user-friendly manner. =20 kunit_tool addresses the problem of being able to run tests without needin= g a virtual machine or actual hardware with User Mode Linux. User Mode Linux i= s a Linux architecture, like ARM or x86; however, unlike other architectures it -compiles the kernel as a standalone Linux executable that can be run like = any +compiles the kernel as a standalone Linux executable. This executable can = be run like any other program directly inside of a host operating system. To be clear, it = does not require any virtualization support: it is just a regular program. =20 -What is a .kunitconfig? -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +What is .kunitconfig? +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -It's just a defconfig that kunit_tool looks for in the build directory -(``.kunit`` by default). kunit_tool uses it to generate a .config as you = might -expect. In addition, it verifies that the generated .config contains the C= ONFIG -options in the .kunitconfig; the reason it does this is so that it is easy= to -be sure that a CONFIG that enables a test actually ends up in the .config. +.kunitconfig is a default configuration file (defconfig) that kunit_tool l= ooks +for in the build directory (``.kunit``). The kunit_tool uses this file to +generate a .config. Additionally, it also verifies that the generated .con= fig contains the CONFIG options in the .kunitconfig file. This is done to m= ake sure that a CONFIG that enables a test is actually part of the .config= file. =20 -It's also possible to pass a separate .kunitconfig fragment to kunit_tool, +It is also possible to pass a separate .kunitconfig fragment to kunit_tool, which is useful if you have several different groups of tests you wish -to run independently, or if you want to use pre-defined test configs for +to run independently, or if you want to use pre-defined test configuration= s for certain subsystems. =20 -Getting Started with kunit_tool +Getting started with kunit_tool =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =20 -If a kunitconfig is present at the root directory, all you have to do is: +If a kunitconfig is present at the root directory, run the following comma= nd: =20 .. code-block:: bash =20 ./tools/testing/kunit/kunit.py run =20 -However, you most likely want to use it with the following options: +However, most likely you may want to use it with the following options: =20 .. code-block:: bash =20 @@ -68,20 +68,20 @@ For a list of all the flags supported by kunit_tool, yo= u can run: =20 ./tools/testing/kunit/kunit.py run --help =20 -Configuring, Building, and Running Tests +Configuring, building, and running tests =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -It's also possible to run just parts of the KUnit build process independen= tly, -which is useful if you want to make manual changes to part of the process. +It is also possible to run specific parts of the KUnit build process indep= endently. +This is useful if you want to make manual changes to part of the process. =20 -A .config can be generated from a .kunitconfig by using the ``config`` arg= ument +If you want to generate a .config from a .kunitconfig, you can use the ``c= onfig`` argument when running kunit_tool: =20 .. code-block:: bash =20 ./tools/testing/kunit/kunit.py config =20 -Similarly, if you just want to build a KUnit kernel from the current .conf= ig, +Similarly, if you want to build a KUnit kernel from the current .config, you can use the ``build`` argument: =20 .. code-block:: bash @@ -95,33 +95,31 @@ run the kernel and display the test results with the ``= exec`` argument: =20 ./tools/testing/kunit/kunit.py exec =20 -The ``run`` command which is discussed above is equivalent to running all = three +The ``run`` command, discussed above is equivalent to running all three of these in sequence. =20 All of these commands accept a number of optional command-line arguments. = The ``--help`` flag will give a complete list of these, or keep reading this p= age for a guide to some of the more useful ones. =20 -Parsing Test Results +Parsing test results =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -KUnit tests output their results in TAP (Test Anything Protocol) format. -kunit_tool will, when running tests, parse this output and print a summary -which is much more pleasant to read. If you wish to look at the raw test -results in TAP format, you can pass the ``--raw_output`` argument. +The output of the KUnit test results are displayed in TAP (Test Anything P= rotocol) format. +When running tests, the kunit_tool parses this output and prints a plainte= xt, human-readable summary. To view the raw test results in TAP format, you= can use the ``--raw_output`` argument. =20 .. code-block:: bash =20 ./tools/testing/kunit/kunit.py run --raw_output =20 The raw output from test runs may contain other, non-KUnit kernel log -lines. You can see just KUnit output with ``--raw_output=3Dkunit``: +lines. To view only the KUnit output, you can use ``--raw_output=3Dkunit``: =20 .. code-block:: bash =20 ./tools/testing/kunit/kunit.py run --raw_output=3Dkunit =20 -If you have KUnit results in their raw TAP format, you can parse them and = print +If you have KUnit results in the raw TAP format, you can parse them and pr= int the human-readable summary with the ``parse`` command for kunit_tool. This accepts a filename for an argument, or will read from standard input. =20 @@ -135,11 +133,11 @@ accepts a filename for an argument, or will read from= standard input. This is very useful if you wish to run tests in a configuration not suppor= ted by kunit_tool (such as on real hardware, or an unsupported architecture). =20 -Filtering Tests +Filtering tests =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -It's possible to run only a subset of the tests built into a kernel by pas= sing -a filter to the ``exec`` or ``run`` commands. For example, if you only wan= ted +It is possible to run only a subset of the tests built into a kernel by pa= ssing +a filter to the ``exec`` or ``run`` commands. For example, if you want to run KUnit resource tests, you could use: =20 .. code-block:: bash @@ -148,15 +146,14 @@ to run KUnit resource tests, you could use: =20 This uses the standard glob format for wildcards. =20 -Running Tests on QEMU +Running tests on QEMU =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -kunit_tool supports running tests on QEMU as well as via UML (as mentioned -elsewhere). The default way of running tests on QEMU requires two flags: +kunit_tool supports running tests on QEMU as well as via UML. The default = way of running tests on QEMU requires two flags: =20 ``--arch`` Selects a collection of configs (Kconfig as well as QEMU configs - options, etc) that allow KUnit tests to be run on the specified + options and so on) that allow KUnit tests to be run on the specified architecture in a minimal way; this is usually not much slower than using UML. The architecture argument is the same as the name of the option passed to the ``ARCH`` variable used by Kbuild. Not all @@ -196,8 +193,8 @@ look something like this: --jobs=3D12 \ --qemu_config=3D./tools/testing/kunit/qemu_configs/x86_64.py =20 -Other Useful Options -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Other useful options +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 kunit_tool has a number of other command-line arguments which can be useful when adapting it to fit your environment or needs. @@ -228,5 +225,10 @@ Some of the more useful ones are: dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=3D1`` to your .kunitconfig is preferable. =20 -There are several other options (and new ones are often added), so do check +There are several other options (and new ones are often added), so do run ``--help`` if you're looking for something not mentioned here. +For more information on these options, see `Command-line-arguments +`__ + + +. --=20 2.37.1.595.g718a3a8f04-goog