├── .buildinfo ├── .nojekyll ├── CNAME ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── _downloads └── 6a3371457528722a734f3c51d9238c13 │ └── CONTRIBUTING.md ├── _sources ├── development │ ├── design.rst.txt │ ├── gerrit-workflow.rst.txt │ ├── index.rst.txt │ ├── prow.rst.txt │ ├── start.rst.txt │ ├── start_internal.rst.txt │ └── useful-commands.rst.txt ├── index.rst.txt ├── mocking.rst.txt ├── press.rst.txt ├── release_notes.rst.txt ├── third_party │ ├── kernel │ │ └── index.rst.txt │ └── stable_kernel │ │ └── index.rst.txt └── usage │ ├── faq.rst.txt │ ├── getting_kunit.rst.txt │ └── index.rst.txt ├── _static ├── _sphinx_javascript_frameworks_compat.js ├── basic.css ├── css │ ├── badge_only.css │ └── theme.css ├── doctools.js ├── documentation_options.js ├── file.png ├── fonts │ ├── Lato-Bold.ttf │ ├── Lato-Bold.woff2 │ ├── Lato-BoldItalic.ttf │ ├── Lato-BoldItalic.woff2 │ ├── Lato-Italic.ttf │ ├── Lato-Italic.woff2 │ ├── Lato-Regular.ttf │ ├── Lato-Regular.woff2 │ ├── RobotoSlab-Bold.woff2 │ ├── RobotoSlab-Regular.woff2 │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ └── fontawesome-webfont.woff2 ├── jquery.js ├── js │ └── theme.js ├── language_data.js ├── minus.png ├── plus.png ├── pygments.css ├── searchtools.js └── sphinx_highlight.js ├── development ├── design.html ├── gerrit-workflow.html ├── index.html ├── prow.html ├── start.html ├── start_internal.html └── useful-commands.html ├── genindex.html ├── index.html ├── mocking.html ├── objects.inv ├── press.html ├── release_notes.html ├── search.html ├── searchindex.js ├── third_party ├── kernel │ ├── LICENSES │ │ ├── deprecated │ │ │ ├── GFDL-1.1 │ │ │ ├── GFDL-1.2 │ │ │ ├── GPL-1.0 │ │ │ ├── ISC │ │ │ ├── Linux-OpenIB │ │ │ ├── X11 │ │ │ └── Zlib │ │ ├── dual │ │ │ ├── Apache-2.0 │ │ │ ├── CC-BY-4.0 │ │ │ ├── CDDL-1.0 │ │ │ ├── MPL-1.1 │ │ │ └── copyleft-next-0.3.1 │ │ ├── exceptions │ │ │ ├── GCC-exception-2.0 │ │ │ └── Linux-syscall-note │ │ └── preferred │ │ │ ├── BSD-2-Clause │ │ │ ├── BSD-3-Clause │ │ │ ├── BSD-3-Clause-Clear │ │ │ ├── GPL-2.0 │ │ │ ├── LGPL-2.0 │ │ │ ├── LGPL-2.1 │ │ │ └── MIT │ ├── docs │ │ ├── _images │ │ │ └── kunit_suitememorydiagram.svg │ │ ├── _sources │ │ │ ├── api │ │ │ │ ├── functionredirection.rst.txt │ │ │ │ ├── index.rst.txt │ │ │ │ ├── resource.rst.txt │ │ │ │ └── test.rst.txt │ │ │ ├── architecture.rst.txt │ │ │ ├── faq.rst.txt │ │ │ ├── index.rst.txt │ │ │ ├── run_manual.rst.txt │ │ │ ├── run_wrapper.rst.txt │ │ │ ├── running_tips.rst.txt │ │ │ ├── start.rst.txt │ │ │ ├── style.rst.txt │ │ │ └── usage.rst.txt │ │ ├── _static │ │ │ ├── alabaster.css │ │ │ ├── basic.css │ │ │ ├── custom.css │ │ │ ├── doctools.js │ │ │ ├── documentation_options.js │ │ │ ├── file.png │ │ │ ├── forkme_right_darkblue_121621.png │ │ │ ├── language_data.js │ │ │ ├── logo.svg │ │ │ ├── minus.png │ │ │ ├── plus.png │ │ │ ├── pygments.css │ │ │ ├── searchtools.js │ │ │ ├── sphinx_highlight.js │ │ │ ├── theme_overrides.css │ │ │ └── theme_rtd_colors.css │ │ ├── api │ │ │ ├── functionredirection.html │ │ │ ├── index.html │ │ │ ├── resource.html │ │ │ └── test.html │ │ ├── architecture.html │ │ ├── faq.html │ │ ├── genindex.html │ │ ├── index.html │ │ ├── objects.inv │ │ ├── run_manual.html │ │ ├── run_wrapper.html │ │ ├── running_tips.html │ │ ├── search.html │ │ ├── searchindex.js │ │ ├── start.html │ │ ├── style.html │ │ └── usage.html │ └── index.html └── stable_kernel │ └── index.html └── usage ├── faq.html ├── getting_kunit.html └── index.html /.buildinfo: -------------------------------------------------------------------------------- 1 | # Sphinx build info version 1 2 | # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. 3 | config: 91171d26fd7d8f40a6044c159a98d94a 4 | tags: 645f666f9bcd5a90fca523b33c5a78b7 5 | -------------------------------------------------------------------------------- /.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/.nojekyll -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | kunit.dev -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution; 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. 24 | 25 | For code on (Gerrit at 26 | ), we use Gerrit. See 27 | for more 28 | information. 29 | 30 | ## Community Guidelines 31 | 32 | This project follows [Google's Open Source Community 33 | Guidelines](https://opensource.google.com/conduct/). 34 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # KUnit Documentation Website 2 | 3 | This documentation is generated from 4 | . To update this website, please 5 | see the instructions listed there. 6 | 7 | Otherwise, visit for more information about the project. 8 | -------------------------------------------------------------------------------- /_downloads/6a3371457528722a734f3c51d9238c13/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution; 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. 24 | 25 | For code on (Gerrit at 26 | ), we use Gerrit. See 27 | for more 28 | information. 29 | 30 | ## Community Guidelines 31 | 32 | This project follows [Google's Open Source Community 33 | Guidelines](https://opensource.google.com/conduct/). 34 | -------------------------------------------------------------------------------- /_sources/development/design.rst.txt: -------------------------------------------------------------------------------- 1 | ============ 2 | KUnit Design 3 | ============ 4 | 5 | High Level Structure 6 | ==================== 7 | 8 | KUnit in practice is divided into two components: the KUnit kernel (more often 9 | referred to as the KUnit kernel, or just the kernel), and kunit.py. Most 10 | of KUnit, including all the test cases, all of the test libraries, and even the 11 | test runner itself are all part of the Linux kernel. 12 | 13 | .. todo: Discuss the non-UML design of KUnit. 14 | 15 | .. _uml: 16 | 17 | User Mode Linux 18 | --------------- 19 | 20 | User Mode Linux, or UML, is a way to compile and run the Linux kernel as a 21 | normal program that can run in userspace without the help of a VM or any 22 | virtualization support. 23 | 24 | UML is an architecture `arch/um/ 25 | `_ that maps all the 26 | architecture specific elements, which would normally map to low level hardware 27 | features, to the POSIX interface allowing the Linux kernel to be compiled and 28 | run as a normal userspace program. 29 | 30 | For more information on UML, see: http://user-mode-linux.sourceforge.net/ 31 | 32 | KUnit Kernel 33 | ------------ 34 | 35 | Most of the complexity of KUnit lies in the Linux kernel itself. Within the 36 | KUnit kernel there are several parts: 37 | 38 | - The :ref:`test-runner` which schedules and runs all the tests, which is 39 | composed of: 40 | 41 | - The Linux initcall subsystem which invokes: 42 | - The :ref:`test-case-runner` which handles sandboxing and running individual 43 | test cases. 44 | 45 | - The :ref:`test-library` which provide wrappers around the API provided by the 46 | Test Case Runner to test cases to communicate with it. 47 | 48 | The Linux kernel itself is **much** more complicated than this, but a full 49 | overview is outside of the scope of this document. 50 | 51 | .. _test-runner: 52 | 53 | Test Runner 54 | ~~~~~~~~~~~ 55 | 56 | The test runner in KUnit is more or less the KUnit kernel itself. Each `kunit 57 | suite <../third_party/kernel/docs/api/test.html#c.kunit_suite>`_, KUnit's name 58 | for a test suite, registers its test case runner as an init call with the Linux 59 | initcall system with |kunit_test_suite|_. When the kernel boots up, it runs 60 | through all the initcalls to initialize all its subsystems; the last initcalls 61 | it executes are the test case runners. 62 | 63 | .. |kunit_test_suite| replace:: ``kunit_test_suite(suite)`` 64 | .. _kunit_test_suite: third_party/kernel/docs/api/test.html#c.kunit_test_suite 65 | 66 | .. _test-case-runner: 67 | 68 | Test Case Runner 69 | ~~~~~~~~~~~~~~~~ 70 | 71 | Each test case runner is associated with a `kunit suite 72 | <../third_party/kernel/docs/api/test.html#c.kunit_suite>`_. When the test case 73 | runner is invoked, it runs through each test case and for each test case, does 74 | the following: 75 | 76 | - Register a failure handler with the UML trap subsytem. 77 | - Run the init function provided by the ``kunit_suite``. 78 | - Run the test case. 79 | - Run the exit function provided by the ``kunit_suite``. 80 | - Deallocate all the test allocated resources. 81 | - Report test results. 82 | 83 | All this happens in `lib/kunit/test.c 84 | `_. 85 | 86 | .. _test-library: 87 | 88 | Test Library 89 | ~~~~~~~~~~~~ 90 | 91 | Currently, the test runner provides the function ``kunit_do_assertion`` for the 92 | test case to communicate a failed assertion: 93 | 94 | .. code-block:: c 95 | 96 | void kunit_do_assertion(struct kunit *test, 97 | struct kunit_assert *assert, 98 | bool pass, 99 | const char *fmt, ...); 100 | 101 | It takes a 102 | 103 | - `kunit (test context object) <../third_party/kernel/docs/api/test.html#c.kunit>`_ 104 | - `assertion object `_ 105 | - whether the expectation/assertion failed or not 106 | - log message to show on failure represented as a C format string. 107 | 108 | The function definition can be found here: 109 | https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/tree/lib/kunit/test.c?h=test&id=741a98d022362c90609ac9dcd8ad56314d8e68b3#n152 110 | 111 | kunit.py 112 | -------- 113 | 114 | Currently the main purpose kunit.py serves is just to make to process of 115 | building the kernel and running tests easier, but it also serves as a place 116 | where workarounds can be added in. For example, there are some bugs (for 117 | example, if the UML kernel crashes, it will corrupt the user's terminal 118 | settings) with the UML user interface that are much easier to work around 119 | outside of the kernel than fix in the kernel itself. One of the function it 120 | serves is to parse the kernel output and print out the summarized results in a 121 | nice, human readable format. 122 | -------------------------------------------------------------------------------- /_sources/development/gerrit-workflow.rst.txt: -------------------------------------------------------------------------------- 1 | =============== 2 | Gerrit Workflow 3 | =============== 4 | 5 | KUnit can refer both to the unit testing code within the Linux kernel and to 6 | the project as a whole, which includes some other supporting code. The meaning 7 | is usually clear when used in context. 8 | 9 | With that said, KUnit, as a project, is made up of several repositories. As 10 | mentioned elsewhere, the actual KUnit unit testing code is in the upstream 11 | Linux kernel. All our other code is in Gerrit. For an introduction to Gerrit 12 | (with a high level overview of git), see 13 | https://gerrit-review.googlesource.com/Documentation/intro-user.html. For 14 | detailed introduction to git, see https://try.github.io. 15 | 16 | Starting from Scratch 17 | ===================== 18 | 19 | This section describes how to start a change from scratch. 20 | 21 | Cloning a repo for the first time 22 | --------------------------------- 23 | 24 | If you have not done so yet, clone the repository you want to make changes to. 25 | For example: 26 | 27 | .. code-block:: bash 28 | 29 | git clone https://kunit.googlesource.com/prow-presubmit 30 | 31 | Checkout the desired branch 32 | --------------------------- 33 | 34 | Checkout the branch on which you want to make changes to. For example: 35 | 36 | .. code-block:: bash 37 | 38 | git checkout master 39 | 40 | Make sure your branch is up to date 41 | ----------------------------------- 42 | 43 | If you have not done so in a while, you will need to update your repo and 44 | branches. Your remote references can be updated with the ``fetch`` command. For 45 | example: 46 | 47 | .. code-block:: bash 48 | 49 | git fetch origin 50 | 51 | where ``origin`` it the name of the KUnit remote, by default ``origin`` is the 52 | name of the repository that was cloned. 53 | 54 | Now that you have updated your remote references, you need to update the local 55 | branch you will be working on. If this branch is only local to your repository, 56 | you may need to rebase it on the remote branch you are trying to get your 57 | changes into (in this case, you would already have changes underway. See 58 | :ref:`updating-changes` for more information.); here we assume that is not the case. 59 | Update your branch with the `pull` command. For example: 60 | 61 | .. code-block:: bash 62 | 63 | git pull origin -ff 64 | 65 | ``-ff`` forces git not to merge upstream changes into your branch. This is 66 | important as we, the KUnit project, do not want merge commits in our git repos. 67 | This command will fail if you have local changes. 68 | 69 | Making a change 70 | --------------- 71 | 72 | Once you have made a change, that you are happy with and would like to send up 73 | for review you first need to ``commit`` the change. For example: 74 | 75 | .. code-block:: bash 76 | 77 | git add path/to/a/file/you/modified 78 | git add path/to/a/different/file/you/changed 79 | git commit 80 | 81 | A git commit should be a logical, bite-size change that is easy for your 82 | reviewer to understand. 83 | 84 | Your commit message should have a: 85 | 86 | - **subject** - line on top that provides a vague idea of what you are doing. 87 | - **body** - which describes in more detail what you are doing. 88 | 89 | The bottome of your commit message should have: 90 | 91 | - ``Change-Id`` - see 92 | https://gerrit-review.googlesource.com/Documentation/user-changeid.html for 93 | more information. 94 | - ``Signed-off-by`` - see 95 | https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin 96 | 97 | Sending changes for review 98 | -------------------------- 99 | 100 | Now that you are happy with your commits, you need to send them for review. 101 | This is done by pushing them to Gerrit with the ``push`` command. For example, 102 | let's say you want your changes to be submitted on ``master`` 103 | branch, and ``origin`` is the prow-presubmit repo: 104 | 105 | .. code-block:: bash 106 | 107 | git push -u origin HEAD:refs/for/master 108 | 109 | If pushing succeeds, Gerrit will respond by printing out the link where you can find the review. 110 | 111 | .. _updating-changes: 112 | 113 | Updating Existing Changes 114 | ========================= 115 | 116 | This section describes how to update your or another user's changes. 117 | 118 | Checking out someone else's changes 119 | ----------------------------------- 120 | 121 | Gerrit allows users to take over changes made by other users. This can be done 122 | by checking out a change that is currently under review (and then pushing 123 | modified versions of those changes). Let's say there is a change at 124 | https://kunit-review.googlesource.com/c/prow-presubmit/+/2569; you can checkout 125 | this change and its dependencies by clicking on the download button; it will 126 | provide you several options, the first option provides a git command that you 127 | can copy to your command line and run, such as: 128 | 129 | .. code-block:: bash 130 | 131 | git fetch "https://kunit.googlesource.com/prow-presubmit" refs/changes/69/2569/1 && git checkout FETCH_HEAD 132 | 133 | .. tip:: 134 | You can also use this to checkout changes that you have misplaced or lost. 135 | 136 | Updating changes 137 | ---------------- 138 | 139 | Once you have checked out the changes that you need to update, you may want to 140 | update them, as the branch you are looking to submit to may have progressed; 141 | this can be accomplished by rebasing against the branch you want to submit to. 142 | For example: 143 | 144 | .. code-block:: bash 145 | 146 | git rebase master 147 | 148 | Now you need to modify the commits to address reviewer's comments, or maybe you 149 | realized that you forgot something that should be in an earlier commit. 150 | Modifying commits may be accomplished with interactive rebase. Interactive 151 | rebase is a very powerful git command and is discussed in some detail here: 152 | https://dev.to/blakedeboer/beginners-guide-to-interactive-rebasing-1ob. 153 | 154 | You might start an interactive rebase with: 155 | 156 | .. code-block:: bash 157 | 158 | git rebase -i master 159 | 160 | .. note:: 161 | Only modify commits that are actually under review; changing commits that 162 | have already been checked in will cause Gerrit to yell at you. 163 | 164 | Sending changes for review (again) 165 | ---------------------------------- 166 | 167 | All you need to do to update your changes on Gerrit under review is to push 168 | your modified commits to the same branch that you would have as if you were 169 | pushing for the first time. 170 | 171 | For example, let's say you want to submit your changes to ``master``; you would 172 | then 173 | 174 | .. code-block:: bash 175 | 176 | git push -u origin HEAD:refs/for/master 177 | 178 | You may wonder how Gerrit knows to replace the old commits at this location 179 | with the ones that you modified; the secret is the ``Change-Id``. **A Change-Id 180 | should almost never be changed when updating a commit**; it tells Gerrit that 181 | the commit is the same commit as before even though everything else may have 182 | changed about the commit (including the commit hash). 183 | -------------------------------------------------------------------------------- /_sources/development/index.rst.txt: -------------------------------------------------------------------------------- 1 | =========== 2 | Development 3 | =========== 4 | 5 | .. toctree:: 6 | :maxdepth: 2 7 | :caption: Contents: 8 | 9 | start 10 | design 11 | useful-commands 12 | prow 13 | start_internal 14 | gerrit-workflow 15 | 16 | This set of pages provides information for developing KUnit itself. These pages 17 | are for you if you plan on making submissions to KUnit, you are using KUnit for 18 | really advanced use cases, or you just want to know more about how KUnit works 19 | under the hood. 20 | 21 | Checkout: 22 | 23 | - :doc:`start` for getting developing for KUnit. 24 | - :doc:`design` to learn about how KUnit is organized and how it got here. 25 | - :doc:`useful-commands` for a collection of tips and tricks while working on 26 | KUnit. 27 | - :doc:`prow` for information on the CI/CD system we use. 28 | -------------------------------------------------------------------------------- /_sources/development/prow.rst.txt: -------------------------------------------------------------------------------- 1 | =============================== 2 | Prow Presubmit for KUnit Gerrit 3 | =============================== 4 | 5 | We, KUnit, use `Prow 6 | `_, a Kubernetes 7 | based CI/CD system, for our Presubmit system. 8 | 9 | Prow has built in support for Gerrit and GitHub integration. The only thing 10 | needed to run KUnit on Prow is a special test runner container, which we 11 | maintain here: https://kunit.googlesource.com/prow-presubmit. 12 | 13 | The Prow config which specifies our container can be found `here 14 | `_ 15 | in the google-oss prow cluster. 16 | 17 | For more information, please refer to our Prow container repo: 18 | https://kunit.googlesource.com/prow-presubmit/ 19 | -------------------------------------------------------------------------------- /_sources/development/start.rst.txt: -------------------------------------------------------------------------------- 1 | ================================ 2 | Getting Started Developing KUnit 3 | ================================ 4 | 5 | Setting Up Your Work Environment 6 | ================================ 7 | 8 | Follow the instructions at :doc:`../usage/index`. 9 | 10 | Familiarize Yourself with KUnit's Design 11 | ======================================== 12 | 13 | KUnit's design is discussed in the :doc:`design` section. 14 | 15 | Contributing to code in the Linux kernel 16 | ======================================== 17 | 18 | Please follow the guide in the Linux kernel: 19 | https://www.kernel.org/doc/html/latest/#introduction-to-kernel-development 20 | 21 | In addition, remember to CC kunit-dev@googlegroups.com and 22 | linux-kselftest@vger.kernel.org. 23 | 24 | Contributing to code outside of the Linux kernel 25 | ================================================ 26 | 27 | This section is for contributing code to repos that live outside of 28 | https://git.kernel.org. 29 | 30 | This only applies to the deprecated ``kunit/alpha/master`` branch and the other 31 | repos (like the one that hosts this site!). 32 | 33 | See :doc:`start_internal` for more details. 34 | -------------------------------------------------------------------------------- /_sources/development/start_internal.rst.txt: -------------------------------------------------------------------------------- 1 | ====================================================== 2 | Getting Started Contributing to non-kernel KUnit repos 3 | ====================================================== 4 | 5 | This page is for contributing code to repos that live outside of 6 | https://git.kernel.org. 7 | 8 | You most likely want to contribute to KUnit in upstream Linux directly, see 9 | :doc:`start`. 10 | 11 | Why is there a difference? 12 | -------------------------- 13 | 14 | The Linux kernel has been around a lot longer than KUnit, and thus has rules 15 | that we have no say on. However, any code that lives outside of the kernel is 16 | managed by Google; it's open source and everyone has equal right to it, but 17 | because it is under the Google umbrella and not the Linux Foundation's umbrella 18 | it means that there are certain rules we have to follow in one place, and 19 | different rules in the other. 20 | 21 | The details are not important, all you have to know is that if you send code to 22 | the Linux kernel you should follow the rules above, and if you are contributing 23 | to any other KUnit repos, you should follow the rules here. 24 | 25 | If you still have confusion, feel free to reach out to us. 26 | 27 | Sign the Contributor License Agreement 28 | -------------------------------------- 29 | 30 | For any contributions not sent directly to the Linux kernel via the Linux 31 | kernel mailing lists, we require contributors to sign our Contributor License 32 | Agreement (CLA). 33 | 34 | You may sign our CLA here: https://cla.developers.google.com/ 35 | 36 | .. note:: 37 | Your company may already have a CLA on file with Google. 38 | 39 | Submitting Changes 40 | ------------------ 41 | 42 | We use `Gerrit `_ for all non-upstream 43 | code reviews. 44 | 45 | In order for Gerrit to accept your change, you must first make sure your commit 46 | messages are formatted correctly. It should have a: 47 | 48 | - ``Change-Id`` - see 49 | https://gerrit-review.googlesource.com/Documentation/user-changeid.html for 50 | more information. 51 | - ``Signed-off-by`` - see 52 | https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin 53 | 54 | Now you are ready to send your change for review: 55 | 56 | .. code-block:: bash 57 | 58 | git push -u origin HEAD:refs/for/master 59 | 60 | For more information on submitting changes through Gerrit, please see the 61 | following section :doc:`gerrit-workflow`. 62 | -------------------------------------------------------------------------------- /_sources/development/useful-commands.rst.txt: -------------------------------------------------------------------------------- 1 | =============== 2 | Useful Commands 3 | =============== 4 | 5 | Building and Running KUnit Manually 6 | =================================== 7 | 8 | Sometimes for debugging kunit.py or the interaction between the KUnit kernel 9 | and kunit.py, it is useful to build and run the tests manually: 10 | 11 | .. code-block:: bash 12 | 13 | cp kunitconfig .config 14 | make ARCH=um -j 12 15 | ./linux mem=1G log_buf_len=2M 16 | 17 | Cleaning the Kernel 18 | =================== 19 | 20 | As typical, cleaning object files can be accomplished with: 21 | 22 | .. code-block:: bash 23 | 24 | make clean 25 | 26 | and the tree can be fully cleaned with: 27 | 28 | .. code-block:: bash 29 | 30 | make mrproper 31 | -------------------------------------------------------------------------------- /_sources/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. KUnit documentation master file, created by 2 | sphinx-quickstart on Mon Aug 26 16:07:42 2019. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | ===== 7 | KUnit 8 | ===== 9 | 10 | .. toctree:: 11 | :maxdepth: 2 12 | :caption: Contents: 13 | 14 | usage/index 15 | development/index 16 | third_party/kernel/index.rst 17 | release_notes 18 | mocking 19 | press 20 | 21 | What is KUnit? 22 | ============== 23 | 24 | KUnit is a lightweight unit testing framework for the Linux kernel. 25 | These tests are able to be run locally on a developer’s workstation without a 26 | VM or special hardware. 27 | 28 | KUnit is heavily inspired by JUnit, Python's unittest.mock, and 29 | Googletest/Googlemock for C++. KUnit provides facilities for defining unit test 30 | cases, grouping related test cases into test suites, providing common 31 | infrastructure for running tests, and more. 32 | 33 | Check out the `Getting Started `__ guide. 34 | 35 | Who is it for? 36 | ============== 37 | 38 | If you work on the Linux kernel, then KUnit is for you. 39 | 40 | Why unit test the kernel? 41 | ========================= 42 | 43 | The first question is, "why write unit tests in the first place?" 44 | 45 | A unit test is a test focused on testing a small "unit" of code. This is 46 | usually on the level of a few functions at most. Unit tests try to avoid 47 | external dependencies like hardware and/or stub them out where possible. 48 | 49 | This ideally makes unit tests more stable, faster, and easier to debug when 50 | they fail. 51 | 52 | In-kernel testing 53 | ----------------- 54 | 55 | .. note:: 56 | In our case, "unit test" implies in-kernel test code. It's not really possible 57 | to be a "unit test" if you're relying on a kernel working enough to have a 58 | functional userspace on top of it. 59 | 60 | For internal libraries (e.g. ``include/linux/list.h``), there's no good way to 61 | test from userspace. It's *far* easier to write in-kernel code to test these. 62 | That are some tests that make this work, but if you're starting from scratch, 63 | just use KUnit. 64 | 65 | For code with a user facing component, you'll want some tests in userspace. 66 | But it can be useful to have unit tests as well. For example, it can be hard to 67 | trigger certain code paths from userspace, particularly error paths. 68 | Furthermore, it's probably much faster and more hermetic to build and run the 69 | tests under KUnit instead of booting a machine and waiting for all the needed 70 | userspace processes to come up. 71 | 72 | Why KUnit? 73 | ========== 74 | 75 | KUnit provides a library to help making writing tests easy: including making 76 | assertions, setting up and cleaning up test resources, and more. 77 | It also provides a `python script `__ 78 | to make building and running tests easy. 79 | 80 | kselftest has a way of writing unit tests as kernel modules via the helpers in 81 | ``tools/testing/selftests/kselftest_module.h``. But this requires more 82 | boilerplate scattered across several files and potentially several directories. 83 | 84 | Check out the `Kernel Testing Guide `__ 85 | for an overview of when to use KUnit. 86 | 87 | kunit.py and UML 88 | ---------------- 89 | 90 | KUnit provides a simple python script, ``kunit.py`` which can automate configuring, 91 | building, and running kernels with KUnit tests. It also parses test results in 92 | `KTAP `__ format, providing a nice 93 | summary. 94 | 95 | To get started, run: 96 | ``./tools/testing/kunit/kunit.py run`` 97 | 98 | KUnit is able to run tests without needing a 99 | virtual machine or actual hardware with User Mode Linux. User Mode Linux is a 100 | Linux architecture, like ARM or x86; however, unlike other architectures it 101 | compiles to a standalone program that can be run like any other program 102 | directly inside of a host operating system; to be clear, it does not require 103 | any virtualization support; it is just a regular program. User Mode Linux is 104 | fast: on my desktop it boots to init process in under a second. 105 | 106 | The provided tooling (``tools/testing/kunit/kunit.py``) uses UML by default, 107 | but also integrates with QEMU to support other architectures. 108 | 109 | How do I use it? 110 | ================ 111 | 112 | - `Getting Started `__ - for new users of KUnit 113 | - `Documentation Index `__ - for an index of all KUnit docs 114 | - `Running tests with kunit.py `__ - how to use the KUnit tooling 115 | - `Running tests without kunit.py `__ - how to run tests manually or in other environment 116 | - `Writing Tests `__ - detailed tips for writing KUnit tests 117 | - `Common Patterns `__ - useful techniques for testing more complex code 118 | - `Style Guide and Nomenclature `__ - what to name your tests, files, and modules 119 | - `API Reference `__ - a reference of all KUnit APIs 120 | - `Kernel Testing Guide `__ - when to use KUnit 121 | - `Testing Rust Code `__ - how to test code written in Rust 122 | 123 | All of these can also be found in the ``Documentation/`` directory in the kernel source tree. 124 | 125 | Where do I get it? 126 | ================== 127 | 128 | - Upstream: https://www.kernel.org/ (version 5.5 or later) 129 | - KUnit can be found in the ``lib/kunit`` directory. 130 | - ``kunit.py`` lives in the ``tools/testing/kunit`` directory. 131 | 132 | Connect with us 133 | =============== 134 | 135 | - Mailing Lists: kunit-dev@googlegroups.com 136 | - Google Groups (web interface for above): https://groups.google.com/forum/#!forum/kunit-dev 137 | - IRC: #kunit on oftc.net 138 | - Riot: `#kunit:matrix.org `_ 139 | 140 | Contributing 141 | ============ 142 | 143 | If you want to contribute to KUnit in the Linux kernel (which is just the same 144 | as contributing to the Linux kernel, please see `the Linux kernel's guide on 145 | contributing 146 | `_. 147 | 148 | For other KUnit repositories (CI/CD, vim plugin, etc), please see 149 | :download:`CONTRIBUTING.md `. 150 | 151 | In all cases, you will also want to take a look at :doc:`development/index`. 152 | -------------------------------------------------------------------------------- /_sources/press.rst.txt: -------------------------------------------------------------------------------- 1 | ===== 2 | Press 3 | ===== 4 | 5 | Talks about KUnit 6 | ================= 7 | 8 | - `Introduction to KUnit - Linux Plumbers Conference 2019 9 | `_ 10 | - `KUnit - Unit Testing for the Linux Kernel - linux.conf.au 2020 11 | `_ 12 | - `KUnit - One Year Later - Linux Plumbers Conference 2020 13 | `_ 14 | - `KUnit: Past, Present, and Future - linux.conf.au 2021 15 | `_ 16 | - `KUnit Testing Stragegies — Linux Foundation Mentorship Series 17 | `_ 18 | - `Kernel Testing with KUnit: Bridging the Gap — linux.conf.au 2022 19 | `_ 20 | - `How to introduce KUnit to Physical Device Drivers - Linux Plumbers Conference 2022 21 | `_ 22 | - `KUnit Function Redirection and More - Linux Plumbers Conference 2022 23 | `_ 24 | - `KUnit sorcery and the uncanny nature of FPU in the DRM - X.Org Developer’s Conference 2022 25 | `_ 26 | - `Uncovering DRM’s KUnit test coverage - X.Org Developer’s Conference 2022 27 | `_ 28 | 29 | Articles about KUnit 30 | ==================== 31 | 32 | - https://lwn.net/Articles/780985/ 33 | - https://www.linuxjournal.com/content/unit-testing-linux-kernel 34 | - https://lwn.net/Articles/790235/ 35 | - https://www.linuxjournal.com/content/kunit-and-assertions 36 | - https://www.phoronix.com/scan.php?page=news_item&px=KUnit-Linux-Kernel-V1 37 | - https://www.phoronix.com/scan.php?page=news_item&px=Linux-Kernel-KUnit-Framework 38 | - https://hub.packtpub.com/kunit-a-new-unit-testing-framework-for-linux-kernel 39 | -------------------------------------------------------------------------------- /_sources/third_party/kernel/index.rst.txt: -------------------------------------------------------------------------------- 1 | ================ 2 | Upstream Version 3 | ================ 4 | 5 | Here we have a copy of the KUnit documentation taken from upstream. 6 | 7 | For convenience: 8 | 9 | Where to get the code 10 | --------------------- 11 | 12 | This documentation is taken from torvalds' master branch: 13 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/ 14 | 15 | Most KUnit upstream development is done against the 'kunit' branch of the linux kselftest repository: 16 | https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=kunit 17 | 18 | Getting Started Guide 19 | --------------------- 20 | 21 | `docs/ `_ 22 | 23 | This documentation is also `mirrored on kernel.org `_. 24 | -------------------------------------------------------------------------------- /_sources/third_party/stable_kernel/index.rst.txt: -------------------------------------------------------------------------------- 1 | ========================================= 2 | Deprecated Version ("kunit/alpha/master") 3 | ========================================= 4 | 5 | Here we have a copy of the documentation taken from the old "alpha" version 6 | KUnit. 7 | 8 | You should really prefer using the upstream version if possible, but the alpha 9 | version has some features that still haven't made their way upstream (class 10 | mocking, feature mocking, death tests, etc.) 11 | 12 | Where to get the code 13 | --------------------- 14 | 15 | https://kunit.googlesource.com/linux/+/kunit/alpha/master 16 | 17 | Getting Started Guide 18 | --------------------- 19 | 20 | `docs/ `_ 21 | -------------------------------------------------------------------------------- /_sources/usage/faq.rst.txt: -------------------------------------------------------------------------------- 1 | ========================== 2 | Frequently Asked Questions 3 | ========================== 4 | 5 | I’m seeing 'Error:root:Kconfig is not contained in validated .config!' 6 | ---------------------------------------------------------------------- 7 | 8 | This means that there are some missing or wrong entries in your ``kunitconfig`` 9 | file. Make sure you’ve spelt all of your config entries correctly, and that 10 | you’ve included all of their dependencies. 11 | 12 | If you’ve not changed the kunitconfig file, make sure you’ve got the correct 13 | version. In particular, some earlier versions used ``CONFIG_TEST=y`` instead 14 | of ``CONFIG_KUNIT=y``. 15 | 16 | .. note:: This error message can be confusing, so we intend to improve it. 17 | See https://bugzilla.kernel.org/show_bug.cgi?id=205235 for more details. 18 | 19 | 20 | I’m seeing a lot of 'makes integer from pointer without a cast' errors in KUNIT_ASSERTION 21 | ----------------------------------------------------------------------------------------- 22 | 23 | If you wish to compare pointers, you’ll need to use the _PTR variants of the 24 | ``KUNIT_EXPECT`` macros. For example, you need to use 25 | ``KUNIT_EXPECT_PTR_EQ(test, ptr1, ptr2)`` instead of 26 | ``KUNIT_EXPECT_EQ(test, ptr1, ptr2)``. 27 | 28 | This is required for KUnit to use the correct format specifier when printing out 29 | expectation failures. 30 | -------------------------------------------------------------------------------- /_sources/usage/getting_kunit.rst.txt: -------------------------------------------------------------------------------- 1 | ============= 2 | Getting KUnit 3 | ============= 4 | 5 | If you're working on Linux 5.5+, you have KUnit. 6 | Otherwise, you'll want to backport the patches, which should all begin with ``"kunit: "``. 7 | 8 | An option of last resort is to use the deprecated and incompatible 9 | ``kunit/alpha/master`` branch. 10 | See :ref:`alpha-master` below for more details. 11 | 12 | .. _download-links: 13 | 14 | Where are these versions? 15 | ========================= 16 | 17 | Upstream 18 | -------- 19 | 20 | KUnit can be found in Linux 5.5 and newer. 21 | 22 | - Code: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/ 23 | - `Usage <../third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features 24 | - `API <../third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing 25 | 26 | The KUnit code itself is primarily found in the `lib/kunit `__ 27 | directory. 28 | 29 | .. _alpha-master: 30 | 31 | Deprecated 32 | ---------- 33 | 34 | This is where KUnit development was done prior to getting upstreamed, but all 35 | development on it has since ceased. 36 | 37 | It has a couple of features that haven't made their way in the upstream version 38 | of KUnit yet, namely: 39 | 40 | - Class mocking 41 | - Function mocking 42 | - Hardware/platform faking 43 | - Error recovery 44 | 45 | .. note:: 46 | Tests written against the ``kunit/alpha/master`` branch will *not* be 47 | directly compatible with the upstream version, however. You can set 48 | ``CONFIG_KUNIT_USE_UPSTREAM_NAMES=y`` to make it act a bit more like the 49 | upstream version, see `this patch series 50 | `_ for details. 51 | 52 | The old, deprecated branch is stored in a Google-hosted gerrit instance. 53 | 54 | - Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master. 55 | - `Usage <../third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features 56 | - `API <../third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing 57 | - kunitconfig file: https://kunit.googlesource.com/kunitconfig/+/refs/heads/kunit/alpha/master/kunitconfig 58 | -------------------------------------------------------------------------------- /_sources/usage/index.rst.txt: -------------------------------------------------------------------------------- 1 | =========== 2 | Using KUnit 3 | =========== 4 | 5 | .. toctree:: 6 | :maxdepth: 2 7 | :caption: Contents: 8 | 9 | getting_kunit 10 | faq 11 | 12 | Where is KUnit? 13 | :doc:`getting_kunit` 14 | 15 | 16 | KUnit is integrated into the Linux kernel, so all you need is a version of the 17 | kernel which contains KUnit, and a config file with which to build it. The 18 | :doc:`getting_kunit` page covers the different versions of KUnit available, and 19 | where to get them. 20 | 21 | 22 | Running tests 23 | ============= 24 | 25 | To run KUnit tests, you'll need to provide a 'kunitconfig' file, which contains 26 | the list of test modules to build, and their dependencies. 27 | 28 | Once you have the ``kunitconfig`` file, just run: 29 | 30 | .. code-block:: bash 31 | 32 | ./tools/testing/kunit/kunit.py run 33 | 34 | .. tip:: 35 | 36 | You may want to run KUnit with flags like: 37 | 38 | .. code-block:: bash 39 | 40 | ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=24 --defconfig 41 | 42 | - ``--timeout`` sets a maximum amount of time to allow tests to run. 43 | - ``--jobs`` sets the number of threads to use to build the kernel. 44 | - ``--defconfig`` uses an default kunitconfig in the kernel source. 45 | 46 | For more information on these and other flags, try running: 47 | 48 | .. code-block:: bash 49 | 50 | ./tools/testing/kunit/kunit.py run --help 51 | 52 | This will build a UML (User Mode Linux) kernel, run the specified tests, and 53 | print the results (nicely formatted) to the screen. 54 | 55 | .. tip:: 56 | 57 | If you get the error message: ``/bin/sh: flex: command not found`` or 58 | similarly ``/bin/sh: bison: command not found``, you are most likely missing 59 | the flex and bison packages. On a system using the apt package manager you 60 | can install them with 61 | 62 | .. code-block:: bash 63 | 64 | sudo apt-get install flex bison 65 | 66 | For more information on building the kernel, see 67 | https://www.kernel.org/doc/html/latest/process/changes.html 68 | 69 | Writing tests 70 | ============= 71 | 72 | Once you have KUnit working, writing tests is easy. Each test is a function 73 | which accepts a ``struct kunit`` argument, and which calls the various 74 | ``KUNIT_EXPECT_*`` macros to verify the state under test. 75 | 76 | More details can be found in the `Getting Started <../third_party/kernel/docs/start.html>`_ 77 | guide. 78 | 79 | 80 | Submitting tests upstream 81 | ========================= 82 | 83 | Ideally, KUnit tests will be submitted upstream alongside the code being tested, 84 | so any user or developer can run the tests and test any changes they make. 85 | Unless they affect KUnit itself, this means that KUnit tests should ideally be 86 | treated as any other change, and submitted via the maintainer of the subsystem 87 | being tested. (Though do feel free to copy in the 88 | ``kunit-dev@googlegroups.com`` list if you want.) 89 | 90 | For changes to KUnit itself, we recommend submitting patches via the 91 | ``linux-kselftest/kunit`` branch, which contains the version of KUnit likely to 92 | head upstream. To do so, please send your patch via the 93 | ``linux-kselftest@vger.kernel.org`` list. You should still get a review from 94 | any relevant the subsystem maintainers, though. 95 | 96 | And, of course, you should follow the general rules and guidelines laid out in 97 | https://www.kernel.org/doc/html/latest/process/submitting-patches.html 98 | -------------------------------------------------------------------------------- /_static/_sphinx_javascript_frameworks_compat.js: -------------------------------------------------------------------------------- 1 | /* Compatability shim for jQuery and underscores.js. 2 | * 3 | * Copyright Sphinx contributors 4 | * Released under the two clause BSD licence 5 | */ 6 | 7 | /** 8 | * small helper function to urldecode strings 9 | * 10 | * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL 11 | */ 12 | jQuery.urldecode = function(x) { 13 | if (!x) { 14 | return x 15 | } 16 | return decodeURIComponent(x.replace(/\+/g, ' ')); 17 | }; 18 | 19 | /** 20 | * small helper function to urlencode strings 21 | */ 22 | jQuery.urlencode = encodeURIComponent; 23 | 24 | /** 25 | * This function returns the parsed url parameters of the 26 | * current request. Multiple values per key are supported, 27 | * it will always return arrays of strings for the value parts. 28 | */ 29 | jQuery.getQueryParameters = function(s) { 30 | if (typeof s === 'undefined') 31 | s = document.location.search; 32 | var parts = s.substr(s.indexOf('?') + 1).split('&'); 33 | var result = {}; 34 | for (var i = 0; i < parts.length; i++) { 35 | var tmp = parts[i].split('=', 2); 36 | var key = jQuery.urldecode(tmp[0]); 37 | var value = jQuery.urldecode(tmp[1]); 38 | if (key in result) 39 | result[key].push(value); 40 | else 41 | result[key] = [value]; 42 | } 43 | return result; 44 | }; 45 | 46 | /** 47 | * highlight a given string on a jquery object by wrapping it in 48 | * span elements with the given class name. 49 | */ 50 | jQuery.fn.highlightText = function(text, className) { 51 | function highlight(node, addItems) { 52 | if (node.nodeType === 3) { 53 | var val = node.nodeValue; 54 | var pos = val.toLowerCase().indexOf(text); 55 | if (pos >= 0 && 56 | !jQuery(node.parentNode).hasClass(className) && 57 | !jQuery(node.parentNode).hasClass("nohighlight")) { 58 | var span; 59 | var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); 60 | if (isInSVG) { 61 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 62 | } else { 63 | span = document.createElement("span"); 64 | span.className = className; 65 | } 66 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 67 | node.parentNode.insertBefore(span, node.parentNode.insertBefore( 68 | document.createTextNode(val.substr(pos + text.length)), 69 | node.nextSibling)); 70 | node.nodeValue = val.substr(0, pos); 71 | if (isInSVG) { 72 | var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); 73 | var bbox = node.parentElement.getBBox(); 74 | rect.x.baseVal.value = bbox.x; 75 | rect.y.baseVal.value = bbox.y; 76 | rect.width.baseVal.value = bbox.width; 77 | rect.height.baseVal.value = bbox.height; 78 | rect.setAttribute('class', className); 79 | addItems.push({ 80 | "parent": node.parentNode, 81 | "target": rect}); 82 | } 83 | } 84 | } 85 | else if (!jQuery(node).is("button, select, textarea")) { 86 | jQuery.each(node.childNodes, function() { 87 | highlight(this, addItems); 88 | }); 89 | } 90 | } 91 | var addItems = []; 92 | var result = this.each(function() { 93 | highlight(this, addItems); 94 | }); 95 | for (var i = 0; i < addItems.length; ++i) { 96 | jQuery(addItems[i].parent).before(addItems[i].target); 97 | } 98 | return result; 99 | }; 100 | 101 | /* 102 | * backward compatibility for jQuery.browser 103 | * This will be supported until firefox bug is fixed. 104 | */ 105 | if (!jQuery.browser) { 106 | jQuery.uaMatch = function(ua) { 107 | ua = ua.toLowerCase(); 108 | 109 | var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || 110 | /(webkit)[ \/]([\w.]+)/.exec(ua) || 111 | /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || 112 | /(msie) ([\w.]+)/.exec(ua) || 113 | ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || 114 | []; 115 | 116 | return { 117 | browser: match[ 1 ] || "", 118 | version: match[ 2 ] || "0" 119 | }; 120 | }; 121 | jQuery.browser = {}; 122 | jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; 123 | } 124 | -------------------------------------------------------------------------------- /_static/css/badge_only.css: -------------------------------------------------------------------------------- 1 | .clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:normal;src:url("../fonts/fontawesome-webfont.eot?#iefix") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff2") format("woff2"),url("../fonts/fontawesome-webfont.woff") format("woff"),url("../fonts/fontawesome-webfont.ttf") format("truetype"),url("../fonts/fontawesome-webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60}.rst-versions .rst-current-version::after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge .fa-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}} 2 | -------------------------------------------------------------------------------- /_static/doctools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * doctools.js 3 | * ~~~~~~~~~~~ 4 | * 5 | * Base JavaScript utilities for all Sphinx HTML documentation. 6 | * 7 | * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | "use strict"; 12 | 13 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ 14 | "TEXTAREA", 15 | "INPUT", 16 | "SELECT", 17 | "BUTTON", 18 | ]); 19 | 20 | const _ready = (callback) => { 21 | if (document.readyState !== "loading") { 22 | callback(); 23 | } else { 24 | document.addEventListener("DOMContentLoaded", callback); 25 | } 26 | }; 27 | 28 | /** 29 | * Small JavaScript module for the documentation. 30 | */ 31 | const Documentation = { 32 | init: () => { 33 | Documentation.initDomainIndexTable(); 34 | Documentation.initOnKeyListeners(); 35 | }, 36 | 37 | /** 38 | * i18n support 39 | */ 40 | TRANSLATIONS: {}, 41 | PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), 42 | LOCALE: "unknown", 43 | 44 | // gettext and ngettext don't access this so that the functions 45 | // can safely bound to a different name (_ = Documentation.gettext) 46 | gettext: (string) => { 47 | const translated = Documentation.TRANSLATIONS[string]; 48 | switch (typeof translated) { 49 | case "undefined": 50 | return string; // no translation 51 | case "string": 52 | return translated; // translation exists 53 | default: 54 | return translated[0]; // (singular, plural) translation tuple exists 55 | } 56 | }, 57 | 58 | ngettext: (singular, plural, n) => { 59 | const translated = Documentation.TRANSLATIONS[singular]; 60 | if (typeof translated !== "undefined") 61 | return translated[Documentation.PLURAL_EXPR(n)]; 62 | return n === 1 ? singular : plural; 63 | }, 64 | 65 | addTranslations: (catalog) => { 66 | Object.assign(Documentation.TRANSLATIONS, catalog.messages); 67 | Documentation.PLURAL_EXPR = new Function( 68 | "n", 69 | `return (${catalog.plural_expr})` 70 | ); 71 | Documentation.LOCALE = catalog.locale; 72 | }, 73 | 74 | /** 75 | * helper function to focus on search bar 76 | */ 77 | focusSearchBar: () => { 78 | document.querySelectorAll("input[name=q]")[0]?.focus(); 79 | }, 80 | 81 | /** 82 | * Initialise the domain index toggle buttons 83 | */ 84 | initDomainIndexTable: () => { 85 | const toggler = (el) => { 86 | const idNumber = el.id.substr(7); 87 | const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); 88 | if (el.src.substr(-9) === "minus.png") { 89 | el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; 90 | toggledRows.forEach((el) => (el.style.display = "none")); 91 | } else { 92 | el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; 93 | toggledRows.forEach((el) => (el.style.display = "")); 94 | } 95 | }; 96 | 97 | const togglerElements = document.querySelectorAll("img.toggler"); 98 | togglerElements.forEach((el) => 99 | el.addEventListener("click", (event) => toggler(event.currentTarget)) 100 | ); 101 | togglerElements.forEach((el) => (el.style.display = "")); 102 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); 103 | }, 104 | 105 | initOnKeyListeners: () => { 106 | // only install a listener if it is really needed 107 | if ( 108 | !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && 109 | !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS 110 | ) 111 | return; 112 | 113 | document.addEventListener("keydown", (event) => { 114 | // bail for input elements 115 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 116 | // bail with special keys 117 | if (event.altKey || event.ctrlKey || event.metaKey) return; 118 | 119 | if (!event.shiftKey) { 120 | switch (event.key) { 121 | case "ArrowLeft": 122 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 123 | 124 | const prevLink = document.querySelector('link[rel="prev"]'); 125 | if (prevLink && prevLink.href) { 126 | window.location.href = prevLink.href; 127 | event.preventDefault(); 128 | } 129 | break; 130 | case "ArrowRight": 131 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 132 | 133 | const nextLink = document.querySelector('link[rel="next"]'); 134 | if (nextLink && nextLink.href) { 135 | window.location.href = nextLink.href; 136 | event.preventDefault(); 137 | } 138 | break; 139 | } 140 | } 141 | 142 | // some keyboard layouts may need Shift to get / 143 | switch (event.key) { 144 | case "/": 145 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; 146 | Documentation.focusSearchBar(); 147 | event.preventDefault(); 148 | } 149 | }); 150 | }, 151 | }; 152 | 153 | // quick alias for translations 154 | const _ = Documentation.gettext; 155 | 156 | _ready(Documentation.init); 157 | -------------------------------------------------------------------------------- /_static/documentation_options.js: -------------------------------------------------------------------------------- 1 | const DOCUMENTATION_OPTIONS = { 2 | VERSION: '', 3 | LANGUAGE: 'en', 4 | COLLAPSE_INDEX: false, 5 | BUILDER: 'html', 6 | FILE_SUFFIX: '.html', 7 | LINK_SUFFIX: '.html', 8 | HAS_SOURCE: true, 9 | SOURCELINK_SUFFIX: '.txt', 10 | NAVIGATION_WITH_KEYS: false, 11 | SHOW_SEARCH_SUMMARY: true, 12 | ENABLE_SEARCH_SHORTCUTS: true, 13 | }; -------------------------------------------------------------------------------- /_static/file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/file.png -------------------------------------------------------------------------------- /_static/fonts/Lato-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Bold.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Bold.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-BoldItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-BoldItalic.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-BoldItalic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-BoldItalic.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-Italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Italic.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Italic.woff2 -------------------------------------------------------------------------------- /_static/fonts/Lato-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Regular.ttf -------------------------------------------------------------------------------- /_static/fonts/Lato-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/Lato-Regular.woff2 -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/RobotoSlab-Bold.woff2 -------------------------------------------------------------------------------- /_static/fonts/RobotoSlab-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/RobotoSlab-Regular.woff2 -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/fontawesome-webfont.eot -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/fontawesome-webfont.ttf -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/fontawesome-webfont.woff -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/fonts/fontawesome-webfont.woff2 -------------------------------------------------------------------------------- /_static/language_data.js: -------------------------------------------------------------------------------- 1 | /* 2 | * language_data.js 3 | * ~~~~~~~~~~~~~~~~ 4 | * 5 | * This script contains the language-specific data used by searchtools.js, 6 | * namely the list of stopwords, stemmer, scorer and splitter. 7 | * 8 | * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. 9 | * :license: BSD, see LICENSE for details. 10 | * 11 | */ 12 | 13 | var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; 14 | 15 | 16 | /* Non-minified version is copied as a separate JS file, is available */ 17 | 18 | /** 19 | * Porter Stemmer 20 | */ 21 | var Stemmer = function() { 22 | 23 | var step2list = { 24 | ational: 'ate', 25 | tional: 'tion', 26 | enci: 'ence', 27 | anci: 'ance', 28 | izer: 'ize', 29 | bli: 'ble', 30 | alli: 'al', 31 | entli: 'ent', 32 | eli: 'e', 33 | ousli: 'ous', 34 | ization: 'ize', 35 | ation: 'ate', 36 | ator: 'ate', 37 | alism: 'al', 38 | iveness: 'ive', 39 | fulness: 'ful', 40 | ousness: 'ous', 41 | aliti: 'al', 42 | iviti: 'ive', 43 | biliti: 'ble', 44 | logi: 'log' 45 | }; 46 | 47 | var step3list = { 48 | icate: 'ic', 49 | ative: '', 50 | alize: 'al', 51 | iciti: 'ic', 52 | ical: 'ic', 53 | ful: '', 54 | ness: '' 55 | }; 56 | 57 | var c = "[^aeiou]"; // consonant 58 | var v = "[aeiouy]"; // vowel 59 | var C = c + "[^aeiouy]*"; // consonant sequence 60 | var V = v + "[aeiou]*"; // vowel sequence 61 | 62 | var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 63 | var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 64 | var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 65 | var s_v = "^(" + C + ")?" + v; // vowel in stem 66 | 67 | this.stemWord = function (w) { 68 | var stem; 69 | var suffix; 70 | var firstch; 71 | var origword = w; 72 | 73 | if (w.length < 3) 74 | return w; 75 | 76 | var re; 77 | var re2; 78 | var re3; 79 | var re4; 80 | 81 | firstch = w.substr(0,1); 82 | if (firstch == "y") 83 | w = firstch.toUpperCase() + w.substr(1); 84 | 85 | // Step 1a 86 | re = /^(.+?)(ss|i)es$/; 87 | re2 = /^(.+?)([^s])s$/; 88 | 89 | if (re.test(w)) 90 | w = w.replace(re,"$1$2"); 91 | else if (re2.test(w)) 92 | w = w.replace(re2,"$1$2"); 93 | 94 | // Step 1b 95 | re = /^(.+?)eed$/; 96 | re2 = /^(.+?)(ed|ing)$/; 97 | if (re.test(w)) { 98 | var fp = re.exec(w); 99 | re = new RegExp(mgr0); 100 | if (re.test(fp[1])) { 101 | re = /.$/; 102 | w = w.replace(re,""); 103 | } 104 | } 105 | else if (re2.test(w)) { 106 | var fp = re2.exec(w); 107 | stem = fp[1]; 108 | re2 = new RegExp(s_v); 109 | if (re2.test(stem)) { 110 | w = stem; 111 | re2 = /(at|bl|iz)$/; 112 | re3 = new RegExp("([^aeiouylsz])\\1$"); 113 | re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 114 | if (re2.test(w)) 115 | w = w + "e"; 116 | else if (re3.test(w)) { 117 | re = /.$/; 118 | w = w.replace(re,""); 119 | } 120 | else if (re4.test(w)) 121 | w = w + "e"; 122 | } 123 | } 124 | 125 | // Step 1c 126 | re = /^(.+?)y$/; 127 | if (re.test(w)) { 128 | var fp = re.exec(w); 129 | stem = fp[1]; 130 | re = new RegExp(s_v); 131 | if (re.test(stem)) 132 | w = stem + "i"; 133 | } 134 | 135 | // Step 2 136 | re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; 137 | if (re.test(w)) { 138 | var fp = re.exec(w); 139 | stem = fp[1]; 140 | suffix = fp[2]; 141 | re = new RegExp(mgr0); 142 | if (re.test(stem)) 143 | w = stem + step2list[suffix]; 144 | } 145 | 146 | // Step 3 147 | re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; 148 | if (re.test(w)) { 149 | var fp = re.exec(w); 150 | stem = fp[1]; 151 | suffix = fp[2]; 152 | re = new RegExp(mgr0); 153 | if (re.test(stem)) 154 | w = stem + step3list[suffix]; 155 | } 156 | 157 | // Step 4 158 | re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; 159 | re2 = /^(.+?)(s|t)(ion)$/; 160 | if (re.test(w)) { 161 | var fp = re.exec(w); 162 | stem = fp[1]; 163 | re = new RegExp(mgr1); 164 | if (re.test(stem)) 165 | w = stem; 166 | } 167 | else if (re2.test(w)) { 168 | var fp = re2.exec(w); 169 | stem = fp[1] + fp[2]; 170 | re2 = new RegExp(mgr1); 171 | if (re2.test(stem)) 172 | w = stem; 173 | } 174 | 175 | // Step 5 176 | re = /^(.+?)e$/; 177 | if (re.test(w)) { 178 | var fp = re.exec(w); 179 | stem = fp[1]; 180 | re = new RegExp(mgr1); 181 | re2 = new RegExp(meq1); 182 | re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 183 | if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) 184 | w = stem; 185 | } 186 | re = /ll$/; 187 | re2 = new RegExp(mgr1); 188 | if (re.test(w) && re2.test(w)) { 189 | re = /.$/; 190 | w = w.replace(re,""); 191 | } 192 | 193 | // and turn initial Y back to y 194 | if (firstch == "y") 195 | w = firstch.toLowerCase() + w.substr(1); 196 | return w; 197 | } 198 | } 199 | 200 | -------------------------------------------------------------------------------- /_static/minus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/minus.png -------------------------------------------------------------------------------- /_static/plus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/_static/plus.png -------------------------------------------------------------------------------- /_static/pygments.css: -------------------------------------------------------------------------------- 1 | pre { line-height: 125%; } 2 | td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } 3 | span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } 4 | td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } 5 | span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } 6 | .highlight .hll { background-color: #ffffcc } 7 | .highlight { background: #eeffcc; } 8 | .highlight .c { color: #408090; font-style: italic } /* Comment */ 9 | .highlight .err { border: 1px solid #FF0000 } /* Error */ 10 | .highlight .k { color: #007020; font-weight: bold } /* Keyword */ 11 | .highlight .o { color: #666666 } /* Operator */ 12 | .highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ 13 | .highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ 14 | .highlight .cp { color: #007020 } /* Comment.Preproc */ 15 | .highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ 16 | .highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ 17 | .highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ 18 | .highlight .gd { color: #A00000 } /* Generic.Deleted */ 19 | .highlight .ge { font-style: italic } /* Generic.Emph */ 20 | .highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ 21 | .highlight .gr { color: #FF0000 } /* Generic.Error */ 22 | .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ 23 | .highlight .gi { color: #00A000 } /* Generic.Inserted */ 24 | .highlight .go { color: #333333 } /* Generic.Output */ 25 | .highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ 26 | .highlight .gs { font-weight: bold } /* Generic.Strong */ 27 | .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 28 | .highlight .gt { color: #0044DD } /* Generic.Traceback */ 29 | .highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ 30 | .highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ 31 | .highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ 32 | .highlight .kp { color: #007020 } /* Keyword.Pseudo */ 33 | .highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ 34 | .highlight .kt { color: #902000 } /* Keyword.Type */ 35 | .highlight .m { color: #208050 } /* Literal.Number */ 36 | .highlight .s { color: #4070a0 } /* Literal.String */ 37 | .highlight .na { color: #4070a0 } /* Name.Attribute */ 38 | .highlight .nb { color: #007020 } /* Name.Builtin */ 39 | .highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ 40 | .highlight .no { color: #60add5 } /* Name.Constant */ 41 | .highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ 42 | .highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ 43 | .highlight .ne { color: #007020 } /* Name.Exception */ 44 | .highlight .nf { color: #06287e } /* Name.Function */ 45 | .highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ 46 | .highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ 47 | .highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ 48 | .highlight .nv { color: #bb60d5 } /* Name.Variable */ 49 | .highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ 50 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */ 51 | .highlight .mb { color: #208050 } /* Literal.Number.Bin */ 52 | .highlight .mf { color: #208050 } /* Literal.Number.Float */ 53 | .highlight .mh { color: #208050 } /* Literal.Number.Hex */ 54 | .highlight .mi { color: #208050 } /* Literal.Number.Integer */ 55 | .highlight .mo { color: #208050 } /* Literal.Number.Oct */ 56 | .highlight .sa { color: #4070a0 } /* Literal.String.Affix */ 57 | .highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ 58 | .highlight .sc { color: #4070a0 } /* Literal.String.Char */ 59 | .highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ 60 | .highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ 61 | .highlight .s2 { color: #4070a0 } /* Literal.String.Double */ 62 | .highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ 63 | .highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ 64 | .highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ 65 | .highlight .sx { color: #c65d09 } /* Literal.String.Other */ 66 | .highlight .sr { color: #235388 } /* Literal.String.Regex */ 67 | .highlight .s1 { color: #4070a0 } /* Literal.String.Single */ 68 | .highlight .ss { color: #517918 } /* Literal.String.Symbol */ 69 | .highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ 70 | .highlight .fm { color: #06287e } /* Name.Function.Magic */ 71 | .highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ 72 | .highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ 73 | .highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ 74 | .highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ 75 | .highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ -------------------------------------------------------------------------------- /_static/sphinx_highlight.js: -------------------------------------------------------------------------------- 1 | /* Highlighting utilities for Sphinx HTML documentation. */ 2 | "use strict"; 3 | 4 | const SPHINX_HIGHLIGHT_ENABLED = true 5 | 6 | /** 7 | * highlight a given string on a node by wrapping it in 8 | * span elements with the given class name. 9 | */ 10 | const _highlight = (node, addItems, text, className) => { 11 | if (node.nodeType === Node.TEXT_NODE) { 12 | const val = node.nodeValue; 13 | const parent = node.parentNode; 14 | const pos = val.toLowerCase().indexOf(text); 15 | if ( 16 | pos >= 0 && 17 | !parent.classList.contains(className) && 18 | !parent.classList.contains("nohighlight") 19 | ) { 20 | let span; 21 | 22 | const closestNode = parent.closest("body, svg, foreignObject"); 23 | const isInSVG = closestNode && closestNode.matches("svg"); 24 | if (isInSVG) { 25 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 26 | } else { 27 | span = document.createElement("span"); 28 | span.classList.add(className); 29 | } 30 | 31 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 32 | const rest = document.createTextNode(val.substr(pos + text.length)); 33 | parent.insertBefore( 34 | span, 35 | parent.insertBefore( 36 | rest, 37 | node.nextSibling 38 | ) 39 | ); 40 | node.nodeValue = val.substr(0, pos); 41 | /* There may be more occurrences of search term in this node. So call this 42 | * function recursively on the remaining fragment. 43 | */ 44 | _highlight(rest, addItems, text, className); 45 | 46 | if (isInSVG) { 47 | const rect = document.createElementNS( 48 | "http://www.w3.org/2000/svg", 49 | "rect" 50 | ); 51 | const bbox = parent.getBBox(); 52 | rect.x.baseVal.value = bbox.x; 53 | rect.y.baseVal.value = bbox.y; 54 | rect.width.baseVal.value = bbox.width; 55 | rect.height.baseVal.value = bbox.height; 56 | rect.setAttribute("class", className); 57 | addItems.push({ parent: parent, target: rect }); 58 | } 59 | } 60 | } else if (node.matches && !node.matches("button, select, textarea")) { 61 | node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); 62 | } 63 | }; 64 | const _highlightText = (thisNode, text, className) => { 65 | let addItems = []; 66 | _highlight(thisNode, addItems, text, className); 67 | addItems.forEach((obj) => 68 | obj.parent.insertAdjacentElement("beforebegin", obj.target) 69 | ); 70 | }; 71 | 72 | /** 73 | * Small JavaScript module for the documentation. 74 | */ 75 | const SphinxHighlight = { 76 | 77 | /** 78 | * highlight the search words provided in localstorage in the text 79 | */ 80 | highlightSearchWords: () => { 81 | if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight 82 | 83 | // get and clear terms from localstorage 84 | const url = new URL(window.location); 85 | const highlight = 86 | localStorage.getItem("sphinx_highlight_terms") 87 | || url.searchParams.get("highlight") 88 | || ""; 89 | localStorage.removeItem("sphinx_highlight_terms") 90 | url.searchParams.delete("highlight"); 91 | window.history.replaceState({}, "", url); 92 | 93 | // get individual terms from highlight string 94 | const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); 95 | if (terms.length === 0) return; // nothing to do 96 | 97 | // There should never be more than one element matching "div.body" 98 | const divBody = document.querySelectorAll("div.body"); 99 | const body = divBody.length ? divBody[0] : document.querySelector("body"); 100 | window.setTimeout(() => { 101 | terms.forEach((term) => _highlightText(body, term, "highlighted")); 102 | }, 10); 103 | 104 | const searchBox = document.getElementById("searchbox"); 105 | if (searchBox === null) return; 106 | searchBox.appendChild( 107 | document 108 | .createRange() 109 | .createContextualFragment( 110 | '

' + 111 | '' + 112 | _("Hide Search Matches") + 113 | "

" 114 | ) 115 | ); 116 | }, 117 | 118 | /** 119 | * helper function to hide the search marks again 120 | */ 121 | hideSearchWords: () => { 122 | document 123 | .querySelectorAll("#searchbox .highlight-link") 124 | .forEach((el) => el.remove()); 125 | document 126 | .querySelectorAll("span.highlighted") 127 | .forEach((el) => el.classList.remove("highlighted")); 128 | localStorage.removeItem("sphinx_highlight_terms") 129 | }, 130 | 131 | initEscapeListener: () => { 132 | // only install a listener if it is really needed 133 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; 134 | 135 | document.addEventListener("keydown", (event) => { 136 | // bail for input elements 137 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 138 | // bail with special keys 139 | if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; 140 | if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { 141 | SphinxHighlight.hideSearchWords(); 142 | event.preventDefault(); 143 | } 144 | }); 145 | }, 146 | }; 147 | 148 | _ready(() => { 149 | /* Do not call highlightSearchWords() when we are on the search page. 150 | * It will highlight words from the *previous* search query. 151 | */ 152 | if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); 153 | SphinxHighlight.initEscapeListener(); 154 | }); 155 | -------------------------------------------------------------------------------- /development/prow.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Prow Presubmit for KUnit Gerrit — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 65 | 66 |
70 | 71 |
72 |
73 |
74 | 82 |
83 |
84 |
85 |
86 | 87 |
88 |

Prow Presubmit for KUnit Gerrit

89 |

We, KUnit, use Prow, a Kubernetes 90 | based CI/CD system, for our Presubmit system.

91 |

Prow has built in support for Gerrit and GitHub integration. The only thing 92 | needed to run KUnit on Prow is a special test runner container, which we 93 | maintain here: https://kunit.googlesource.com/prow-presubmit.

94 |

The Prow config which specifies our container can be found here 95 | in the google-oss prow cluster.

96 |

For more information, please refer to our Prow container repo: 97 | https://kunit.googlesource.com/prow-presubmit/

98 |
99 | 100 | 101 |
102 |
103 |
107 | 108 |
109 | 110 |
111 |

© Copyright 2019 Google LLC.

112 |
113 | 114 | Built with Sphinx using a 115 | theme 116 | provided by Read the Docs. 117 | 118 | 119 |
120 |
121 |
122 |
123 |
124 | 129 | 130 | 131 | -------------------------------------------------------------------------------- /development/useful-commands.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Useful Commands — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 69 | 70 |
74 | 75 |
76 |
77 |
78 | 86 |
87 |
88 |
89 |
90 | 91 |
92 |

Useful Commands

93 |
94 |

Building and Running KUnit Manually

95 |

Sometimes for debugging kunit.py or the interaction between the KUnit kernel 96 | and kunit.py, it is useful to build and run the tests manually:

97 | 
cp kunitconfig .config
 98 | make ARCH=um -j 12
 99 | ./linux mem=1G log_buf_len=2M
100 |
101 |
102 |
103 |
104 |

Cleaning the Kernel

105 |

As typical, cleaning object files can be accomplished with:

106 | 
make clean
107 |
108 |
109 |

and the tree can be fully cleaned with:

110 | 
make mrproper
111 |
112 |
113 |
114 |
115 | 116 | 117 |
118 |
119 |
123 | 124 |
125 | 126 |
127 |

© Copyright 2019 Google LLC.

128 |
129 | 130 | Built with Sphinx using a 131 | theme 132 | provided by Read the Docs. 133 | 134 | 135 |
136 |
137 |
138 |
139 |
140 | 145 | 146 | 147 | -------------------------------------------------------------------------------- /genindex.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Index — KUnit documentation 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
24 | 54 | 55 |
59 | 60 |
61 |
62 |
63 |
    64 |
    • 65 |
  • Index
    • 66 |
  • 67 |
    • 68 |
69 |
70 |
71 |
72 |
73 | 74 | 75 |

Index

76 | 77 |
78 | 79 |
80 | 81 | 82 |
83 |
84 |
85 | 86 |
87 | 88 |
89 |

© Copyright 2019 Google LLC.

90 |
91 | 92 | Built with Sphinx using a 93 | theme 94 | provided by Read the Docs. 95 | 96 | 97 |
98 |
99 |
100 |
101 |
102 | 107 | 108 | 109 | -------------------------------------------------------------------------------- /objects.inv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/objects.inv -------------------------------------------------------------------------------- /press.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Press — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 |
26 | 60 | 61 |
65 | 66 |
67 |
68 |
69 | 76 |
77 |
78 |
79 |
80 | 81 |
82 |

Press

83 |
84 |

Talks about KUnit

85 |
86 |
99 |
100 |
101 |

Articles about KUnit

102 |
103 |
113 |
114 |
115 | 116 | 117 |
118 |
119 |
122 | 123 |
124 | 125 |
126 |

© Copyright 2019 Google LLC.

127 |
128 | 129 | Built with Sphinx using a 130 | theme 131 | provided by Read the Docs. 132 | 133 | 134 |
135 |
136 |
137 |
138 |
139 | 144 | 145 | 146 | -------------------------------------------------------------------------------- /search.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Search — KUnit documentation 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 57 | 58 |
62 | 63 |
64 |
65 |
66 |
    67 |
    • 68 |
  • Search
    • 69 |
  • 70 |
    • 71 |
72 |
73 |
74 |
75 |
76 | 77 | 84 | 85 | 86 |
87 | 88 |
89 | 90 |
91 |
92 |
93 | 94 |
95 | 96 |
97 |

© Copyright 2019 Google LLC.

98 |
99 | 100 | Built with Sphinx using a 101 | theme 102 | provided by Read the Docs. 103 | 104 | 105 |
106 |
107 |
108 |
109 |
110 | 115 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/deprecated/ISC: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: ISC 2 | SPDX-URL: https://spdx.org/licenses/ISC.html 3 | Usage-Guide: 4 | To use the ISC License put the following SPDX tag/value pair into a 5 | comment according to the placement guidelines in the licensing rules 6 | documentation: 7 | SPDX-License-Identifier: ISC 8 | License-Text: 9 | 10 | ISC License 11 | 12 | Copyright (c) 13 | 14 | Permission to use, copy, modify, and/or distribute this software for any 15 | purpose with or without fee is hereby granted, provided that the above 16 | copyright notice and this permission notice appear in all copies. 17 | 18 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 19 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 20 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 21 | SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 22 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 23 | OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 24 | CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 25 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/deprecated/Linux-OpenIB: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: Linux-OpenIB 2 | SPDX-URL: https://spdx.org/licenses/Linux-OpenIB.html 3 | Usage-Guide: 4 | To use the Linux Kernel Variant of OpenIB.org license put the following 5 | SPDX tag/value pair into a comment according to the placement guidelines 6 | in the licensing rules documentation: 7 | SPDX-License-Identifier: Linux-OpenIB 8 | License-Text: 9 | 10 | Redistribution and use in source and binary forms, with or without 11 | modification, are permitted provided that the following conditions are met: 12 | 13 | - Redistributions of source code must retain the above copyright 14 | notice, this list of conditions and the following disclaimer. 15 | 16 | - Redistributions in binary form must reproduce the above copyright 17 | notice, this list of conditions and the following disclaimer in the 18 | documentation and/or other materials provided with the distribution. 19 | 20 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 21 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 22 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 23 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 24 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 25 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 26 | DEALINGS IN THE SOFTWARE. 27 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/deprecated/X11: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: X11 2 | SPDX-URL: https://spdx.org/licenses/X11.html 3 | Usage-Guide: 4 | To use the X11 put the following SPDX tag/value pair into a comment 5 | according to the placement guidelines in the licensing rules 6 | documentation: 7 | SPDX-License-Identifier: X11 8 | License-Text: 9 | 10 | 11 | X11 License 12 | 13 | Copyright (C) 1996 X Consortium 14 | 15 | Permission is hereby granted, free of charge, to any person obtaining a 16 | copy of this software and associated documentation files (the "Software"), 17 | to deal in the Software without restriction, including without limitation 18 | the rights to use, copy, modify, merge, publish, distribute, sublicense, 19 | and/or sell copies of the Software, and to permit persons to whom the 20 | Software is furnished to do so, subject to the following conditions: 21 | 22 | The above copyright notice and this permission notice shall be included in 23 | all copies or substantial portions of the Software. 24 | 25 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 26 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 27 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 28 | X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 29 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 30 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 31 | 32 | Except as contained in this notice, the name of the X Consortium shall not 33 | be used in advertising or otherwise to promote the sale, use or other 34 | dealings in this Software without prior written authorization from the X 35 | Consortium. 36 | 37 | X Window System is a trademark of X Consortium, Inc. 38 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/deprecated/Zlib: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: Zlib 2 | SPDX-URL: https://spdx.org/licenses/Zlib.html 3 | Usage-Guide: 4 | To use the Zlib License put the following SPDX tag/value pair into a 5 | comment according to the placement guidelines in the licensing rules 6 | documentation: 7 | SPDX-License-Identifier: Zlib 8 | License-Text: 9 | 10 | zlib License 11 | 12 | Copyright (c) 13 | 14 | This software is provided 'as-is', without any express or implied warranty. In 15 | no event will the authors be held liable for any damages arising from the use 16 | of this software. 17 | 18 | Permission is granted to anyone to use this software for any purpose, including 19 | commercial applications, and to alter it and redistribute it freely, subject 20 | to the following restrictions: 21 | 1. The origin of this software must not be misrepresented; you must not 22 | claim that you wrote the original software. If you use this software in a 23 | product, an acknowledgment in the product documentation would be appreciated 24 | but is not required. 25 | 2. Altered source versions must be plainly marked as such, and must not be 26 | misrepresented as being the original software. 27 | 3. This notice may not be removed or altered from any source distribution. 28 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/exceptions/GCC-exception-2.0: -------------------------------------------------------------------------------- 1 | SPDX-Exception-Identifier: GCC-exception-2.0 2 | SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html 3 | SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-2.0-only, GPL-2.0-or-later 4 | Usage-Guide: 5 | This exception is used together with one of the above SPDX-Licenses to 6 | allow linking the compiled version of code to non GPL compliant code. 7 | To use this exception add it with the keyword WITH to one of the 8 | identifiers in the SPDX-Licenses tag: 9 | SPDX-License-Identifier: WITH GCC-exception-2.0 10 | License-Text: 11 | 12 | In addition to the permissions in the GNU Library General Public License, 13 | the Free Software Foundation gives you unlimited permission to link the 14 | compiled version of this file into combinations with other programs, and to 15 | distribute those programs without any restriction coming from the use of 16 | this file. (The General Public License restrictions do apply in other 17 | respects; for example, they cover modification of the file, and 18 | distribution when not linked into another program.) 19 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/exceptions/Linux-syscall-note: -------------------------------------------------------------------------------- 1 | SPDX-Exception-Identifier: Linux-syscall-note 2 | SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html 3 | SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+, GPL-2.0-only, GPL-2.0-or-later 4 | Usage-Guide: 5 | This exception is used together with one of the above SPDX-Licenses 6 | to mark user space API (uapi) header files so they can be included 7 | into non GPL compliant user space application code. 8 | To use this exception add it with the keyword WITH to one of the 9 | identifiers in the SPDX-Licenses tag: 10 | SPDX-License-Identifier: WITH Linux-syscall-note 11 | License-Text: 12 | 13 | NOTE! This copyright does *not* cover user programs that use kernel 14 | services by normal system calls - this is merely considered normal use 15 | of the kernel, and does *not* fall under the heading of "derived work". 16 | Also note that the GPL below is copyrighted by the Free Software 17 | Foundation, but the instance of code that it refers to (the Linux 18 | kernel) is copyrighted by me and others who actually wrote it. 19 | 20 | Also note that the only valid version of the GPL as far as the kernel 21 | is concerned is _this_ particular version of the license (ie v2, not 22 | v2.2 or v3.x or whatever), unless explicitly otherwise stated. 23 | 24 | Linus Torvalds 25 | 26 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/preferred/BSD-2-Clause: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: BSD-2-Clause 2 | SPDX-URL: https://spdx.org/licenses/BSD-2-Clause.html 3 | Usage-Guide: 4 | To use the BSD 2-clause "Simplified" License put the following SPDX 5 | tag/value pair into a comment according to the placement guidelines in 6 | the licensing rules documentation: 7 | SPDX-License-Identifier: BSD-2-Clause 8 | License-Text: 9 | 10 | Copyright (c) . All rights reserved. 11 | 12 | Redistribution and use in source and binary forms, with or without 13 | modification, are permitted provided that the following conditions are met: 14 | 15 | 1. Redistributions of source code must retain the above copyright notice, 16 | this list of conditions and the following disclaimer. 17 | 18 | 2. Redistributions in binary form must reproduce the above copyright 19 | notice, this list of conditions and the following disclaimer in the 20 | documentation and/or other materials provided with the distribution. 21 | 22 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 23 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 26 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32 | POSSIBILITY OF SUCH DAMAGE. 33 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/preferred/BSD-3-Clause: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: BSD-3-Clause 2 | SPDX-URL: https://spdx.org/licenses/BSD-3-Clause.html 3 | Usage-Guide: 4 | To use the BSD 3-clause "New" or "Revised" License put the following SPDX 5 | tag/value pair into a comment according to the placement guidelines in 6 | the licensing rules documentation: 7 | SPDX-License-Identifier: BSD-3-Clause 8 | License-Text: 9 | 10 | Copyright (c) . All rights reserved. 11 | 12 | Redistribution and use in source and binary forms, with or without 13 | modification, are permitted provided that the following conditions are met: 14 | 15 | 1. Redistributions of source code must retain the above copyright notice, 16 | this list of conditions and the following disclaimer. 17 | 18 | 2. Redistributions in binary form must reproduce the above copyright 19 | notice, this list of conditions and the following disclaimer in the 20 | documentation and/or other materials provided with the distribution. 21 | 22 | 3. Neither the name of the copyright holder nor the names of its 23 | contributors may be used to endorse or promote products derived from this 24 | software without specific prior written permission. 25 | 26 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 27 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 30 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36 | POSSIBILITY OF SUCH DAMAGE. 37 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/preferred/BSD-3-Clause-Clear: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: BSD-3-Clause-Clear 2 | SPDX-URL: https://spdx.org/licenses/BSD-3-Clause-Clear.html 3 | Usage-Guide: 4 | To use the BSD 3-clause "Clear" License put the following SPDX 5 | tag/value pair into a comment according to the placement guidelines in 6 | the licensing rules documentation: 7 | SPDX-License-Identifier: BSD-3-Clause-Clear 8 | License-Text: 9 | 10 | The Clear BSD License 11 | 12 | Copyright (c) [xxxx]-[xxxx] [Owner Organization] 13 | All rights reserved. 14 | 15 | Redistribution and use in source and binary forms, with or without 16 | modification, are permitted (subject to the limitations in the disclaimer 17 | below) provided that the following conditions are met: 18 | 19 | * Redistributions of source code must retain the above copyright notice, 20 | this list of conditions and the following disclaimer. 21 | 22 | * Redistributions in binary form must reproduce the above copyright 23 | notice, this list of conditions and the following disclaimer in the 24 | documentation and/or other materials provided with the distribution. 25 | 26 | * Neither the name of [Owner Organization] nor the names of its 27 | contributors may be used to endorse or promote products derived from 28 | this software without specific prior written permission. 29 | 30 | NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY 31 | THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 32 | CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 33 | NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 34 | PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 35 | OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 36 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 37 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 38 | OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 39 | WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 40 | OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 41 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 42 | -------------------------------------------------------------------------------- /third_party/kernel/LICENSES/preferred/MIT: -------------------------------------------------------------------------------- 1 | Valid-License-Identifier: MIT 2 | SPDX-URL: https://spdx.org/licenses/MIT.html 3 | Usage-Guide: 4 | To use the MIT License put the following SPDX tag/value pair into a 5 | comment according to the placement guidelines in the licensing rules 6 | documentation: 7 | SPDX-License-Identifier: MIT 8 | License-Text: 9 | 10 | MIT License 11 | 12 | Copyright (c) 13 | 14 | Permission is hereby granted, free of charge, to any person obtaining a 15 | copy of this software and associated documentation files (the "Software"), 16 | to deal in the Software without restriction, including without limitation 17 | the rights to use, copy, modify, merge, publish, distribute, sublicense, 18 | and/or sell copies of the Software, and to permit persons to whom the 19 | Software is furnished to do so, subject to the following conditions: 20 | 21 | The above copyright notice and this permission notice shall be included in 22 | all copies or substantial portions of the Software. 23 | 24 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 25 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 26 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 27 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 28 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 29 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 30 | DEALINGS IN THE SOFTWARE. 31 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_images/kunit_suitememorydiagram.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | kunit_suite 13 | 14 | 15 | 16 | kunit_suite 17 | 18 | 19 | 20 | kunit_suite 21 | 22 | 23 | 24 | kunit_suite 25 | 26 | 27 | 28 | kunit_suite 29 | 30 | 31 | 32 | kunit_suite 33 | 34 | 35 | 36 | _kunit_suites_start 37 | 38 | 39 | 40 | _kunit_suites_end 41 | 42 | 43 | .init.data 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | struct kunit_suite { const char name[256]; int (*init)(struct kunit *); void (*exit)(struct kunit *); struct kunit_case *test_cases; ...}; 80 | 81 | 82 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/api/functionredirection.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ======================== 4 | Function Redirection API 5 | ======================== 6 | 7 | Overview 8 | ======== 9 | 10 | When writing unit tests, it's important to be able to isolate the code being 11 | tested from other parts of the kernel. This ensures the reliability of the test 12 | (it won't be affected by external factors), reduces dependencies on specific 13 | hardware or config options (making the test easier to run), and protects the 14 | stability of the rest of the system (making it less likely for test-specific 15 | state to interfere with the rest of the system). 16 | 17 | While for some code (typically generic data structures, helpers, and other 18 | "pure functions") this is trivial, for others (like device drivers, 19 | filesystems, core subsystems) the code is heavily coupled with other parts of 20 | the kernel. 21 | 22 | This coupling is often due to global state in some way: be it a global list of 23 | devices, the filesystem, or some hardware state. Tests need to either carefully 24 | manage, isolate, and restore state, or they can avoid it altogether by 25 | replacing access to and mutation of this state with a "fake" or "mock" variant. 26 | 27 | By refactoring access to such state, such as by introducing a layer of 28 | indirection which can use or emulate a separate set of test state. However, 29 | such refactoring comes with its own costs (and undertaking significant 30 | refactoring before being able to write tests is suboptimal). 31 | 32 | A simpler way to intercept and replace some of the function calls is to use 33 | function redirection via static stubs. 34 | 35 | 36 | Static Stubs 37 | ============ 38 | 39 | Static stubs are a way of redirecting calls to one function (the "real" 40 | function) to another function (the "replacement" function). 41 | 42 | It works by adding a macro to the "real" function which checks to see if a test 43 | is running, and if a replacement function is available. If so, that function is 44 | called in place of the original. 45 | 46 | Using static stubs is pretty straightforward: 47 | 48 | 1. Add the KUNIT_STATIC_STUB_REDIRECT() macro to the start of the "real" 49 | function. 50 | 51 | This should be the first statement in the function, after any variable 52 | declarations. KUNIT_STATIC_STUB_REDIRECT() takes the name of the 53 | function, followed by all of the arguments passed to the real function. 54 | 55 | For example: 56 | 57 | .. code-block:: c 58 | 59 | void send_data_to_hardware(const char *str) 60 | { 61 | KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str); 62 | /* real implementation */ 63 | } 64 | 65 | 2. Write one or more replacement functions. 66 | 67 | These functions should have the same function signature as the real function. 68 | In the event they need to access or modify test-specific state, they can use 69 | kunit_get_current_test() to get a struct kunit pointer. This can then 70 | be passed to the expectation/assertion macros, or used to look up KUnit 71 | resources. 72 | 73 | For example: 74 | 75 | .. code-block:: c 76 | 77 | void fake_send_data_to_hardware(const char *str) 78 | { 79 | struct kunit *test = kunit_get_current_test(); 80 | KUNIT_EXPECT_STREQ(test, str, "Hello World!"); 81 | } 82 | 83 | 3. Activate the static stub from your test. 84 | 85 | From within a test, the redirection can be enabled with 86 | kunit_activate_static_stub(), which accepts a struct kunit pointer, 87 | the real function, and the replacement function. You can call this several 88 | times with different replacement functions to swap out implementations of the 89 | function. 90 | 91 | In our example, this would be 92 | 93 | .. code-block:: c 94 | 95 | kunit_activate_static_stub(test, 96 | send_data_to_hardware, 97 | fake_send_data_to_hardware); 98 | 99 | 4. Call (perhaps indirectly) the real function. 100 | 101 | Once the redirection is activated, any call to the real function will call 102 | the replacement function instead. Such calls may be buried deep in the 103 | implementation of another function, but must occur from the test's kthread. 104 | 105 | For example: 106 | 107 | .. code-block:: c 108 | 109 | send_data_to_hardware("Hello World!"); /* Succeeds */ 110 | send_data_to_hardware("Something else"); /* Fails the test. */ 111 | 112 | 5. (Optionally) disable the stub. 113 | 114 | When you no longer need it, disable the redirection (and hence resume the 115 | original behaviour of the 'real' function) using 116 | kunit_deactivate_static_stub(). Otherwise, it will be automatically disabled 117 | when the test exits. 118 | 119 | For example: 120 | 121 | .. code-block:: c 122 | 123 | kunit_deactivate_static_stub(test, send_data_to_hardware); 124 | 125 | 126 | It's also possible to use these replacement functions to test to see if a 127 | function is called at all, for example: 128 | 129 | .. code-block:: c 130 | 131 | void send_data_to_hardware(const char *str) 132 | { 133 | KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str); 134 | /* real implementation */ 135 | } 136 | 137 | /* In test file */ 138 | int times_called = 0; 139 | void fake_send_data_to_hardware(const char *str) 140 | { 141 | times_called++; 142 | } 143 | ... 144 | /* In the test case, redirect calls for the duration of the test */ 145 | kunit_activate_static_stub(test, send_data_to_hardware, fake_send_data_to_hardware); 146 | 147 | send_data_to_hardware("hello"); 148 | KUNIT_EXPECT_EQ(test, times_called, 1); 149 | 150 | /* Can also deactivate the stub early, if wanted */ 151 | kunit_deactivate_static_stub(test, send_data_to_hardware); 152 | 153 | send_data_to_hardware("hello again"); 154 | KUNIT_EXPECT_EQ(test, times_called, 1); 155 | 156 | 157 | 158 | API Reference 159 | ============= 160 | 161 | .. kernel-doc:: include/kunit/static_stub.h 162 | :internal: 163 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/api/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ============= 4 | API Reference 5 | ============= 6 | .. toctree:: 7 | :hidden: 8 | 9 | test 10 | resource 11 | functionredirection 12 | 13 | 14 | This page documents the KUnit kernel testing API. It is divided into the 15 | following sections: 16 | 17 | Documentation/dev-tools/kunit/api/test.rst 18 | 19 | - Documents all of the standard testing API 20 | 21 | Documentation/dev-tools/kunit/api/resource.rst 22 | 23 | - Documents the KUnit resource API 24 | 25 | Documentation/dev-tools/kunit/api/functionredirection.rst 26 | 27 | - Documents the KUnit Function Redirection API 28 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/api/resource.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ============ 4 | Resource API 5 | ============ 6 | 7 | This file documents the KUnit resource API. 8 | 9 | Most users won't need to use this API directly, power users can use it to store 10 | state on a per-test basis, register custom cleanup actions, and more. 11 | 12 | .. kernel-doc:: include/kunit/resource.h 13 | :internal: 14 | 15 | Managed Devices 16 | --------------- 17 | 18 | Functions for using KUnit-managed struct device and struct device_driver. 19 | Include ``kunit/device.h`` to use these. 20 | 21 | .. kernel-doc:: include/kunit/device.h 22 | :internal: 23 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/api/test.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ======== 4 | Test API 5 | ======== 6 | 7 | This file documents all of the standard testing API. 8 | 9 | .. kernel-doc:: include/kunit/test.h 10 | :internal: 11 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/architecture.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ================== 4 | KUnit Architecture 5 | ================== 6 | 7 | The KUnit architecture is divided into two parts: 8 | 9 | - `In-Kernel Testing Framework`_ 10 | - `kunit_tool (Command-line Test Harness)`_ 11 | 12 | In-Kernel Testing Framework 13 | =========================== 14 | 15 | The kernel testing library supports KUnit tests written in C using 16 | KUnit. These KUnit tests are kernel code. KUnit performs the following 17 | tasks: 18 | 19 | - Organizes tests 20 | - Reports test results 21 | - Provides test utilities 22 | 23 | Test Cases 24 | ---------- 25 | 26 | The test case is the fundamental unit in KUnit. KUnit test cases are organised 27 | into suites. A KUnit test case is a function with type signature 28 | ``void (*)(struct kunit *test)``. These test case functions are wrapped in a 29 | struct called struct kunit_case. 30 | 31 | .. note: 32 | ``generate_params`` is optional for non-parameterized tests. 33 | 34 | Each KUnit test case receives a ``struct kunit`` context object that tracks a 35 | running test. The KUnit assertion macros and other KUnit utilities use the 36 | ``struct kunit`` context object. As an exception, there are two fields: 37 | 38 | - ``->priv``: The setup functions can use it to store arbitrary test 39 | user data. 40 | 41 | - ``->param_value``: It contains the parameter value which can be 42 | retrieved in the parameterized tests. 43 | 44 | Test Suites 45 | ----------- 46 | 47 | A KUnit suite includes a collection of test cases. The KUnit suites 48 | are represented by the ``struct kunit_suite``. For example: 49 | 50 | .. code-block:: c 51 | 52 | static struct kunit_case example_test_cases[] = { 53 | KUNIT_CASE(example_test_foo), 54 | KUNIT_CASE(example_test_bar), 55 | KUNIT_CASE(example_test_baz), 56 | {} 57 | }; 58 | 59 | static struct kunit_suite example_test_suite = { 60 | .name = "example", 61 | .init = example_test_init, 62 | .exit = example_test_exit, 63 | .test_cases = example_test_cases, 64 | }; 65 | kunit_test_suite(example_test_suite); 66 | 67 | In the above example, the test suite ``example_test_suite``, runs the 68 | test cases ``example_test_foo``, ``example_test_bar``, and 69 | ``example_test_baz``. Before running the test, the ``example_test_init`` 70 | is called and after running the test, ``example_test_exit`` is called. 71 | The ``kunit_test_suite(example_test_suite)`` registers the test suite 72 | with the KUnit test framework. 73 | 74 | Executor 75 | -------- 76 | 77 | The KUnit executor can list and run built-in KUnit tests on boot. 78 | The Test suites are stored in a linker section 79 | called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro 80 | definition in 81 | `include/asm-generic/vmlinux.lds.h `_. 82 | The linker section consists of an array of pointers to 83 | ``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` 84 | macro. The KUnit executor iterates over the linker section array in order to 85 | run all the tests that are compiled into the kernel. 86 | 87 | .. kernel-figure:: kunit_suitememorydiagram.svg 88 | :alt: KUnit Suite Memory 89 | 90 | KUnit Suite Memory Diagram 91 | 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 the implementation of the 94 | executor, see 95 | `lib/kunit/executor.c `_. 96 | When built as a module, the ``kunit_test_suites()`` macro defines a 97 | ``module_init()`` function, which runs all the tests in the compilation 98 | unit instead of utilizing the executor. 99 | 100 | In KUnit tests, some error classes do not affect other tests 101 | or parts of the kernel, each KUnit case executes in a separate thread 102 | context. See the ``kunit_try_catch_run()`` function in 103 | `lib/kunit/try-catch.c `_. 104 | 105 | Assertion Macros 106 | ---------------- 107 | 108 | KUnit tests verify state using expectations/assertions. 109 | All expectations/assertions are formatted as: 110 | ``KUNIT_{EXPECT|ASSERT}_[_MSG](kunit, property[, message])`` 111 | 112 | - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an 113 | expectation. 114 | In the event of a failure, the testing flow differs as follows: 115 | 116 | - For expectations, the test is marked as failed and the failure is logged. 117 | 118 | - Failing assertions, on the other hand, result in the test case being 119 | terminated immediately. 120 | 121 | - Assertions call the function: 122 | ``void __noreturn __kunit_abort(struct kunit *)``. 123 | 124 | - ``__kunit_abort`` calls the function: 125 | ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``. 126 | 127 | - ``kunit_try_catch_throw`` calls the function: 128 | ``void kthread_complete_and_exit(struct completion *, long) __noreturn;`` 129 | and terminates the special thread context. 130 | 131 | - ```` denotes a check with options: ``TRUE`` (supplied property 132 | has the boolean value "true"), ``EQ`` (two supplied properties are 133 | equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not 134 | contain an "err" value). 135 | 136 | - ``[_MSG]`` prints a custom message on failure. 137 | 138 | Test Result Reporting 139 | --------------------- 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). 144 | 145 | Parameterized Tests 146 | ------------------- 147 | 148 | Each KUnit parameterized test is associated with a collection of 149 | parameters. The test is invoked multiple times, once for each parameter 150 | value and the parameter is stored in the ``param_value`` field. 151 | The test case includes a KUNIT_CASE_PARAM() macro that accepts a 152 | generator function. The generator function is passed the previous parameter 153 | and returns the next parameter. It also includes a macro for generating 154 | array-based common-case generators. 155 | 156 | kunit_tool (Command-line Test Harness) 157 | ====================================== 158 | 159 | ``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It 160 | is used to configure, build, execute, parse test results and run all of the 161 | previous commands in correct order (i.e., configure, build, execute and parse). 162 | You have two options for running KUnit tests: either build the kernel with KUnit 163 | enabled and manually parse the results (see 164 | Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool`` 165 | (see Documentation/dev-tools/kunit/run_wrapper.rst). 166 | 167 | - ``configure`` command generates the kernel ``.config`` from a 168 | ``.kunitconfig`` file (and any architecture-specific options). 169 | The Python scripts available in ``qemu_configs`` folder 170 | (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains 171 | additional configuration options for specific architectures. 172 | It parses both the existing ``.config`` and the ``.kunitconfig`` files 173 | to ensure that ``.config`` is a superset of ``.kunitconfig``. 174 | If not, it will combine the two and run ``make olddefconfig`` to regenerate 175 | the ``.config`` file. It then checks to see if ``.config`` has become a superset. 176 | This verifies that all the Kconfig dependencies are correctly specified in the 177 | file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing 178 | Kconfigs. The code which runs ``make olddefconfig`` is part of the 179 | ``kunit_kernel.py`` script. You can invoke this command through: 180 | ``./tools/testing/kunit/kunit.py config`` and 181 | generate a ``.config`` file. 182 | - ``build`` runs ``make`` on the kernel tree with required options 183 | (depends on the architecture and some options, for example: build_dir) 184 | and reports any errors. 185 | To build a KUnit kernel from the current ``.config``, you can use the 186 | ``build`` argument: ``./tools/testing/kunit/kunit.py build``. 187 | - ``exec`` command executes kernel results either directly (using 188 | User-mode Linux configuration), or through an emulator such 189 | as QEMU. It reads results from the log using standard 190 | output (stdout), and passes them to ``parse`` to be parsed. 191 | If you already have built a kernel with built-in KUnit tests, 192 | you can run the kernel and display the test results with the ``exec`` 193 | argument: ``./tools/testing/kunit/kunit.py exec``. 194 | - ``parse`` extracts the KTAP output from a kernel log, parses 195 | the test results, and prints a summary. For failed tests, any 196 | diagnostic output will be included. 197 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/faq.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ========================== 4 | Frequently Asked Questions 5 | ========================== 6 | 7 | How is this different from Autotest, kselftest, and so on? 8 | ========================================================== 9 | KUnit is a unit testing framework. Autotest, kselftest (and some others) are 10 | not. 11 | 12 | A `unit test `_ is supposed to 13 | test a single unit of code in isolation and hence the name *unit test*. A unit 14 | test should be the finest granularity of testing and should allow all possible 15 | code paths to be tested in the code under test. This is only possible if the 16 | code under test is small and does not have any external dependencies outside of 17 | the test's control like hardware. 18 | 19 | There are no testing frameworks currently available for the kernel that do not 20 | require installing the kernel on a test machine or in a virtual machine. All 21 | testing frameworks require tests to be written in userspace and run on the 22 | kernel under test. This is true for Autotest, kselftest, and some others, 23 | disqualifying any of them from being considered unit testing frameworks. 24 | 25 | Does KUnit support running on architectures other than UML? 26 | =========================================================== 27 | 28 | Yes, mostly. 29 | 30 | For the most part, the KUnit core framework (what we use to write the tests) 31 | can compile to any architecture. It compiles like just another part of the 32 | kernel and runs when the kernel boots, or when built as a module, when the 33 | module is loaded. However, there is infrastructure, like the KUnit Wrapper 34 | (``tools/testing/kunit/kunit.py``) that might not support some architectures 35 | (see :ref:`kunit-on-qemu`). 36 | 37 | In short, yes, you can run KUnit on other architectures, but it might require 38 | more work than using KUnit on UML. 39 | 40 | For more information, see :ref:`kunit-on-non-uml`. 41 | 42 | .. _kinds-of-tests: 43 | 44 | What is the difference between a unit test and other kinds of tests? 45 | ==================================================================== 46 | Most existing tests for the Linux kernel would be categorized as an integration 47 | test, or an end-to-end test. 48 | 49 | - A unit test is supposed to test a single unit of code in isolation. A unit 50 | test should be the finest granularity of testing and, as such, allows all 51 | possible code paths to be tested in the code under test. This is only possible 52 | if the code under test is small and does not have any external dependencies 53 | outside of the test's control like hardware. 54 | - An integration test tests the interaction between a minimal set of components, 55 | usually just two or three. For example, someone might write an integration 56 | test to test the interaction between a driver and a piece of hardware, or to 57 | test the interaction between the userspace libraries the kernel provides and 58 | the kernel itself. However, one of these tests would probably not test the 59 | entire kernel along with hardware interactions and interactions with the 60 | userspace. 61 | - An end-to-end test usually tests the entire system from the perspective of the 62 | code under test. For example, someone might write an end-to-end test for the 63 | kernel by installing a production configuration of the kernel on production 64 | hardware with a production userspace and then trying to exercise some behavior 65 | that depends on interactions between the hardware, the kernel, and userspace. 66 | 67 | KUnit is not working, what should I do? 68 | ======================================= 69 | 70 | Unfortunately, there are a number of things which can break, but here are some 71 | things to try. 72 | 73 | 1. Run ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` 74 | parameter. This might show details or error messages hidden by the kunit_tool 75 | parser. 76 | 2. Instead of running ``kunit.py run``, try running ``kunit.py config``, 77 | ``kunit.py build``, and ``kunit.py exec`` independently. This can help track 78 | down where an issue is occurring. (If you think the parser is at fault, you 79 | can run it manually against ``stdin`` or a file with ``kunit.py parse``.) 80 | 3. Running the UML kernel directly can often reveal issues or error messages, 81 | ``kunit_tool`` ignores. This should be as simple as running ``./vmlinux`` 82 | after building the UML kernel (for example, by using ``kunit.py build``). 83 | Note that UML has some unusual requirements (such as the host having a tmpfs 84 | filesystem mounted), and has had issues in the past when built statically and 85 | the host has KASLR enabled. (On older host kernels, you may need to run 86 | ``setarch `uname -m` -R ./vmlinux`` to disable KASLR.) 87 | 4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test 88 | (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config 89 | around, so you can see what config was used after running ``kunit.py run``. 90 | It also preserves any config changes you might make, so you can 91 | enable/disable things with ``make ARCH=um menuconfig`` or similar, and then 92 | re-run kunit_tool. 93 | 5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This 94 | may help clean up any residual config items which could be causing problems. 95 | 6. Finally, try running KUnit outside UML. KUnit and KUnit tests can be 96 | built into any kernel, or can be built as a module and loaded at runtime. 97 | Doing so should allow you to determine if UML is causing the issue you're 98 | seeing. When tests are built-in, they will execute when the kernel boots, and 99 | modules will automatically execute associated tests when loaded. Test results 100 | can be collected from ``/sys/kernel/debug/kunit//results``, and 101 | can be parsed with ``kunit.py parse``. For more details, see :ref:`kunit-on-qemu`. 102 | 103 | If none of the above tricks help, you are always welcome to email any issues to 104 | kunit-dev@googlegroups.com. 105 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ================================= 4 | KUnit - Linux Kernel Unit Testing 5 | ================================= 6 | 7 | .. toctree:: 8 | :maxdepth: 2 9 | :caption: Contents: 10 | 11 | start 12 | architecture 13 | run_wrapper 14 | run_manual 15 | usage 16 | api/index 17 | style 18 | faq 19 | running_tips 20 | 21 | This section details the kernel unit testing framework. 22 | 23 | Introduction 24 | ============ 25 | 26 | KUnit (Kernel unit testing framework) provides a common framework for 27 | unit tests within the Linux kernel. Using KUnit, you can define groups 28 | of test cases called test suites. The tests either run on kernel boot 29 | if built-in, or load as a module. KUnit automatically flags and reports 30 | failed test cases in the kernel log. The test results appear in 31 | :doc:`KTAP (Kernel - Test Anything Protocol) format`. 32 | It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock 33 | (C++ unit testing framework). 34 | 35 | KUnit tests are part of the kernel, written in the C (programming) 36 | language, and test parts of the Kernel implementation (example: a C 37 | language function). Excluding build time, from invocation to 38 | completion, KUnit can run around 100 tests in less than 10 seconds. 39 | KUnit can test any kernel component, for example: file system, system 40 | calls, memory management, device drivers and so on. 41 | 42 | KUnit follows the white-box testing approach. The test has access to 43 | internal system functionality. KUnit runs in kernel space and is not 44 | restricted to things exposed to user-space. 45 | 46 | In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``) 47 | that configures the Linux kernel, runs KUnit tests under QEMU or UML 48 | (:doc:`User Mode Linux `), 49 | parses the test results and 50 | displays them in a user friendly manner. 51 | 52 | Features 53 | -------- 54 | 55 | - Provides a framework for writing unit tests. 56 | - Runs tests on any kernel architecture. 57 | - Runs a test in milliseconds. 58 | 59 | Prerequisites 60 | ------------- 61 | 62 | - Any Linux kernel compatible hardware. 63 | - For Kernel under test, Linux kernel version 5.5 or greater. 64 | 65 | Unit Testing 66 | ============ 67 | 68 | A unit test tests a single unit of code in isolation. A unit test is the finest 69 | granularity of testing and allows all possible code paths to be tested in the 70 | code under test. This is possible if the code under test is small and does not 71 | have any external dependencies outside of the test's control like hardware. 72 | 73 | 74 | Write Unit Tests 75 | ---------------- 76 | 77 | To write good unit tests, there is a simple but powerful pattern: 78 | Arrange-Act-Assert. This is a great way to structure test cases and 79 | defines an order of operations. 80 | 81 | - Arrange inputs and targets: At the start of the test, arrange the data 82 | that allows a function to work. Example: initialize a statement or 83 | object. 84 | - Act on the target behavior: Call your function/code under test. 85 | - Assert expected outcome: Verify that the result (or resulting state) is as 86 | expected. 87 | 88 | Unit Testing Advantages 89 | ----------------------- 90 | 91 | - Increases testing speed and development in the long run. 92 | - Detects bugs at initial stage and therefore decreases bug fix cost 93 | compared to acceptance testing. 94 | - Improves code quality. 95 | - Encourages writing testable code. 96 | 97 | Read also :ref:`kinds-of-tests`. 98 | 99 | How do I use it? 100 | ================ 101 | 102 | You can find a step-by-step guide to writing and running KUnit tests in 103 | Documentation/dev-tools/kunit/start.rst 104 | 105 | Alternatively, feel free to look through the rest of the KUnit documentation, 106 | or to experiment with tools/testing/kunit/kunit.py and the example test under 107 | lib/kunit/kunit-example-test.c 108 | 109 | Happy testing! 110 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_sources/run_manual.rst.txt: -------------------------------------------------------------------------------- 1 | .. SPDX-License-Identifier: GPL-2.0 2 | 3 | ============================ 4 | Run Tests without kunit_tool 5 | ============================ 6 | 7 | If we do not want to use kunit_tool (For example: we want to integrate 8 | with other systems, or run tests on real hardware), we can 9 | include KUnit in any kernel, read out results, and parse manually. 10 | 11 | .. note:: KUnit is not designed for use in a production system. It is 12 | possible that tests may reduce the stability or security of 13 | the system. 14 | 15 | Configure the Kernel 16 | ==================== 17 | 18 | KUnit tests can run without kunit_tool. This can be useful, if: 19 | 20 | - We have an existing kernel configuration to test. 21 | - Need to run on real hardware (or using an emulator/VM kunit_tool 22 | does not support). 23 | - Wish to integrate with some existing testing systems. 24 | 25 | KUnit is configured with the ``CONFIG_KUNIT`` option, and individual 26 | tests can also be built by enabling their config options in our 27 | ``.config``. KUnit tests usually (but don't always) have config options 28 | ending in ``_KUNIT_TEST``. Most tests can either be built as a module, 29 | or be built into the kernel. 30 | 31 | .. note :: 32 | 33 | We can enable the ``KUNIT_ALL_TESTS`` config option to 34 | automatically enable all tests with satisfied dependencies. This is 35 | a good way of quickly testing everything applicable to the current 36 | config. 37 | 38 | Once we have built our kernel (and/or modules), it is simple to run 39 | the tests. If the tests are built-in, they will run automatically on the 40 | kernel boot. The results will be written to the kernel log (``dmesg``) 41 | in TAP format. 42 | 43 | If the tests are built as modules, they will run when the module is 44 | loaded. 45 | 46 | .. code-block :: bash 47 | 48 | # modprobe example-test 49 | 50 | The results will appear in TAP format in ``dmesg``. 51 | 52 | debugfs 53 | ======= 54 | 55 | KUnit can be accessed from userspace via the debugfs filesystem (See more 56 | information about debugfs at Documentation/filesystems/debugfs.rst). 57 | 58 | If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is 59 | mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform 60 | the following actions. 61 | 62 | Retrieve Test Results 63 | ===================== 64 | 65 | You can use debugfs to retrieve KUnit test results. The test results are 66 | accessible from the debugfs filesystem in the following read-only file: 67 | 68 | .. code-block :: bash 69 | 70 | /sys/kernel/debug/kunit//results 71 | 72 | The test results are printed in a KTAP document. Note this document is separate 73 | to the kernel log and thus, may have different test suite numbering. 74 | 75 | Run Tests After Kernel Has Booted 76 | ================================= 77 | 78 | You can use the debugfs filesystem to trigger built-in tests to run after 79 | boot. To run the test suite, you can use the following command to write to 80 | the ``/sys/kernel/debug/kunit//run`` file: 81 | 82 | .. code-block :: bash 83 | 84 | echo "any string" > /sys/kernel/debugfs/kunit//run 85 | 86 | As a result, the test suite runs and the results are printed to the kernel 87 | log. 88 | 89 | However, this feature is not available with KUnit suites that use init data, 90 | because init data may have been discarded after the kernel boots. KUnit 91 | suites that use init data should be defined using the 92 | kunit_test_init_section_suites() macro. 93 | 94 | Also, you cannot use this feature to run tests concurrently. Instead a test 95 | will wait to run until other tests have completed or failed. 96 | 97 | .. note :: 98 | 99 | For test authors, to use this feature, tests will need to correctly initialise 100 | and/or clean up any data, so the test runs correctly a second time. 101 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/custom.css: -------------------------------------------------------------------------------- 1 | /* SPDX-License-Identifier: GPL-2.0 */ 2 | /* 3 | * CSS tweaks for the Alabaster theme 4 | */ 5 | 6 | /* Shrink the headers a bit */ 7 | div.body h1 { font-size: 180%; } 8 | div.body h2 { font-size: 150%; } 9 | div.body h3 { font-size: 130%; } 10 | div.body h4 { font-size: 110%; } 11 | 12 | /* toctree captions are styled like h2 */ 13 | div.toctree-wrapper p.caption[role=heading] { font-size: 150%; } 14 | 15 | /* Tighten up the layout slightly */ 16 | div.body { padding: 0 15px 0 10px; } 17 | div.sphinxsidebarwrapper { padding: 1em 0.4em; } 18 | div.sphinxsidebar { font-size: inherit; 19 | max-height: 100%; 20 | overflow-y: auto; } 21 | /* Tweak document margins and don't force width */ 22 | div.document { 23 | margin: 20px 10px 0 10px; 24 | width: auto; 25 | } 26 | 27 | /* Size the logo appropriately */ 28 | img.logo { 29 | width: 104px; 30 | margin-bottom: 20px; 31 | } 32 | 33 | /* 34 | * Parameters for the display of function prototypes and such included 35 | * from C source files. 36 | */ 37 | dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } 38 | /* indent lines 2+ of multi-line function prototypes */ 39 | dl.function dt { margin-left: 10em; text-indent: -10em; } 40 | dt.sig-object { font-size: larger; } 41 | div.kernelindent { margin-left: 2em; margin-right: 4em; } 42 | 43 | /* 44 | * Tweaks for our local TOC 45 | */ 46 | div.kerneltoc li.toctree-l1 { font-size: smaller; 47 | text-indent: -1em; 48 | margin-left: 1em; } 49 | div.kerneltoc li.current > a {font-weight: bold; } 50 | div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: small; 51 | text-indent: -1em; 52 | margin-left: 1em; 53 | list-style-type: none; 54 | } 55 | div.kerneltoc li.current ul { margin-left: 0; } 56 | div.kerneltoc { background-color: #eeeeee; } 57 | div.kerneltoc li.current ul { background-color: white; } 58 | 59 | /* 60 | * The CSS magic to toggle the contents on small screens. 61 | */ 62 | label.kernel-toc-title { display: none; } 63 | label.kernel-toc-title:after { 64 | content: "[Hide]"; 65 | } 66 | input[type=checkbox]:checked ~ label.kernel-toc-title:after { 67 | content: "[Show]"; 68 | } 69 | /* Hide the toggle on large screens */ 70 | input.kernel-toc-toggle { display: none; } 71 | 72 | /* 73 | * Show and implement the toggle on small screens. 74 | * The 875px width seems to be wired into alabaster. 75 | */ 76 | @media screen and (max-width: 875px) { 77 | label.kernel-toc-title { display: inline; 78 | font-weight: bold; 79 | font-size: larger; } 80 | input[type=checkbox]:checked ~ div.kerneltoc { 81 | display: none; 82 | } 83 | h3.kernel-toc-contents { display: inline; } 84 | div.kerneltoc a { color: black; } 85 | } 86 | 87 | /* Language selection menu */ 88 | 89 | div.admonition { 90 | /* 91 | * Make sure we don't overlap notes and warnings at the top of the 92 | * document. 93 | */ 94 | clear: both; 95 | } 96 | 97 | div.language-selection { 98 | background: #eeeeee; 99 | border: 1px solid #cccccc; 100 | margin-bottom: 1em; 101 | padding: .5em; 102 | 103 | position: relative; 104 | float: right; 105 | } 106 | 107 | div.language-selection a { 108 | display: block; 109 | padding: 0.5em; 110 | color: #333333; 111 | text-decoration: none; 112 | } 113 | 114 | div.language-selection ul { 115 | display: none; 116 | position: absolute; 117 | 118 | /* Align with the parent div */ 119 | top: 100%; 120 | right: 0; 121 | margin: 0; 122 | 123 | list-style: none; 124 | 125 | background: #fafafa; 126 | border: 1px solid #cccccc; 127 | 128 | /* Never break menu item lines */ 129 | white-space: nowrap; 130 | } 131 | 132 | div.language-selection:hover ul { 133 | display: block; 134 | } 135 | 136 | div.language-selection ul li:hover { 137 | background: #dddddd; 138 | } 139 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/doctools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * doctools.js 3 | * ~~~~~~~~~~~ 4 | * 5 | * Base JavaScript utilities for all Sphinx HTML documentation. 6 | * 7 | * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | "use strict"; 12 | 13 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ 14 | "TEXTAREA", 15 | "INPUT", 16 | "SELECT", 17 | "BUTTON", 18 | ]); 19 | 20 | const _ready = (callback) => { 21 | if (document.readyState !== "loading") { 22 | callback(); 23 | } else { 24 | document.addEventListener("DOMContentLoaded", callback); 25 | } 26 | }; 27 | 28 | /** 29 | * Small JavaScript module for the documentation. 30 | */ 31 | const Documentation = { 32 | init: () => { 33 | Documentation.initDomainIndexTable(); 34 | Documentation.initOnKeyListeners(); 35 | }, 36 | 37 | /** 38 | * i18n support 39 | */ 40 | TRANSLATIONS: {}, 41 | PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), 42 | LOCALE: "unknown", 43 | 44 | // gettext and ngettext don't access this so that the functions 45 | // can safely bound to a different name (_ = Documentation.gettext) 46 | gettext: (string) => { 47 | const translated = Documentation.TRANSLATIONS[string]; 48 | switch (typeof translated) { 49 | case "undefined": 50 | return string; // no translation 51 | case "string": 52 | return translated; // translation exists 53 | default: 54 | return translated[0]; // (singular, plural) translation tuple exists 55 | } 56 | }, 57 | 58 | ngettext: (singular, plural, n) => { 59 | const translated = Documentation.TRANSLATIONS[singular]; 60 | if (typeof translated !== "undefined") 61 | return translated[Documentation.PLURAL_EXPR(n)]; 62 | return n === 1 ? singular : plural; 63 | }, 64 | 65 | addTranslations: (catalog) => { 66 | Object.assign(Documentation.TRANSLATIONS, catalog.messages); 67 | Documentation.PLURAL_EXPR = new Function( 68 | "n", 69 | `return (${catalog.plural_expr})` 70 | ); 71 | Documentation.LOCALE = catalog.locale; 72 | }, 73 | 74 | /** 75 | * helper function to focus on search bar 76 | */ 77 | focusSearchBar: () => { 78 | document.querySelectorAll("input[name=q]")[0]?.focus(); 79 | }, 80 | 81 | /** 82 | * Initialise the domain index toggle buttons 83 | */ 84 | initDomainIndexTable: () => { 85 | const toggler = (el) => { 86 | const idNumber = el.id.substr(7); 87 | const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); 88 | if (el.src.substr(-9) === "minus.png") { 89 | el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; 90 | toggledRows.forEach((el) => (el.style.display = "none")); 91 | } else { 92 | el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; 93 | toggledRows.forEach((el) => (el.style.display = "")); 94 | } 95 | }; 96 | 97 | const togglerElements = document.querySelectorAll("img.toggler"); 98 | togglerElements.forEach((el) => 99 | el.addEventListener("click", (event) => toggler(event.currentTarget)) 100 | ); 101 | togglerElements.forEach((el) => (el.style.display = "")); 102 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); 103 | }, 104 | 105 | initOnKeyListeners: () => { 106 | // only install a listener if it is really needed 107 | if ( 108 | !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && 109 | !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS 110 | ) 111 | return; 112 | 113 | document.addEventListener("keydown", (event) => { 114 | // bail for input elements 115 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 116 | // bail with special keys 117 | if (event.altKey || event.ctrlKey || event.metaKey) return; 118 | 119 | if (!event.shiftKey) { 120 | switch (event.key) { 121 | case "ArrowLeft": 122 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 123 | 124 | const prevLink = document.querySelector('link[rel="prev"]'); 125 | if (prevLink && prevLink.href) { 126 | window.location.href = prevLink.href; 127 | event.preventDefault(); 128 | } 129 | break; 130 | case "ArrowRight": 131 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 132 | 133 | const nextLink = document.querySelector('link[rel="next"]'); 134 | if (nextLink && nextLink.href) { 135 | window.location.href = nextLink.href; 136 | event.preventDefault(); 137 | } 138 | break; 139 | } 140 | } 141 | 142 | // some keyboard layouts may need Shift to get / 143 | switch (event.key) { 144 | case "/": 145 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; 146 | Documentation.focusSearchBar(); 147 | event.preventDefault(); 148 | } 149 | }); 150 | }, 151 | }; 152 | 153 | // quick alias for translations 154 | const _ = Documentation.gettext; 155 | 156 | _ready(Documentation.init); 157 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/documentation_options.js: -------------------------------------------------------------------------------- 1 | const DOCUMENTATION_OPTIONS = { 2 | VERSION: '', 3 | LANGUAGE: 'en', 4 | COLLAPSE_INDEX: false, 5 | BUILDER: 'html', 6 | FILE_SUFFIX: '.html', 7 | LINK_SUFFIX: '.html', 8 | HAS_SOURCE: true, 9 | SOURCELINK_SUFFIX: '.txt', 10 | NAVIGATION_WITH_KEYS: false, 11 | SHOW_SEARCH_SUMMARY: true, 12 | ENABLE_SEARCH_SHORTCUTS: true, 13 | }; -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/third_party/kernel/docs/_static/file.png -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/forkme_right_darkblue_121621.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/third_party/kernel/docs/_static/forkme_right_darkblue_121621.png -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/language_data.js: -------------------------------------------------------------------------------- 1 | /* 2 | * language_data.js 3 | * ~~~~~~~~~~~~~~~~ 4 | * 5 | * This script contains the language-specific data used by searchtools.js, 6 | * namely the list of stopwords, stemmer, scorer and splitter. 7 | * 8 | * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. 9 | * :license: BSD, see LICENSE for details. 10 | * 11 | */ 12 | 13 | var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; 14 | 15 | 16 | /* Non-minified version is copied as a separate JS file, is available */ 17 | 18 | /** 19 | * Porter Stemmer 20 | */ 21 | var Stemmer = function() { 22 | 23 | var step2list = { 24 | ational: 'ate', 25 | tional: 'tion', 26 | enci: 'ence', 27 | anci: 'ance', 28 | izer: 'ize', 29 | bli: 'ble', 30 | alli: 'al', 31 | entli: 'ent', 32 | eli: 'e', 33 | ousli: 'ous', 34 | ization: 'ize', 35 | ation: 'ate', 36 | ator: 'ate', 37 | alism: 'al', 38 | iveness: 'ive', 39 | fulness: 'ful', 40 | ousness: 'ous', 41 | aliti: 'al', 42 | iviti: 'ive', 43 | biliti: 'ble', 44 | logi: 'log' 45 | }; 46 | 47 | var step3list = { 48 | icate: 'ic', 49 | ative: '', 50 | alize: 'al', 51 | iciti: 'ic', 52 | ical: 'ic', 53 | ful: '', 54 | ness: '' 55 | }; 56 | 57 | var c = "[^aeiou]"; // consonant 58 | var v = "[aeiouy]"; // vowel 59 | var C = c + "[^aeiouy]*"; // consonant sequence 60 | var V = v + "[aeiou]*"; // vowel sequence 61 | 62 | var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 63 | var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 64 | var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 65 | var s_v = "^(" + C + ")?" + v; // vowel in stem 66 | 67 | this.stemWord = function (w) { 68 | var stem; 69 | var suffix; 70 | var firstch; 71 | var origword = w; 72 | 73 | if (w.length < 3) 74 | return w; 75 | 76 | var re; 77 | var re2; 78 | var re3; 79 | var re4; 80 | 81 | firstch = w.substr(0,1); 82 | if (firstch == "y") 83 | w = firstch.toUpperCase() + w.substr(1); 84 | 85 | // Step 1a 86 | re = /^(.+?)(ss|i)es$/; 87 | re2 = /^(.+?)([^s])s$/; 88 | 89 | if (re.test(w)) 90 | w = w.replace(re,"$1$2"); 91 | else if (re2.test(w)) 92 | w = w.replace(re2,"$1$2"); 93 | 94 | // Step 1b 95 | re = /^(.+?)eed$/; 96 | re2 = /^(.+?)(ed|ing)$/; 97 | if (re.test(w)) { 98 | var fp = re.exec(w); 99 | re = new RegExp(mgr0); 100 | if (re.test(fp[1])) { 101 | re = /.$/; 102 | w = w.replace(re,""); 103 | } 104 | } 105 | else if (re2.test(w)) { 106 | var fp = re2.exec(w); 107 | stem = fp[1]; 108 | re2 = new RegExp(s_v); 109 | if (re2.test(stem)) { 110 | w = stem; 111 | re2 = /(at|bl|iz)$/; 112 | re3 = new RegExp("([^aeiouylsz])\\1$"); 113 | re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 114 | if (re2.test(w)) 115 | w = w + "e"; 116 | else if (re3.test(w)) { 117 | re = /.$/; 118 | w = w.replace(re,""); 119 | } 120 | else if (re4.test(w)) 121 | w = w + "e"; 122 | } 123 | } 124 | 125 | // Step 1c 126 | re = /^(.+?)y$/; 127 | if (re.test(w)) { 128 | var fp = re.exec(w); 129 | stem = fp[1]; 130 | re = new RegExp(s_v); 131 | if (re.test(stem)) 132 | w = stem + "i"; 133 | } 134 | 135 | // Step 2 136 | re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; 137 | if (re.test(w)) { 138 | var fp = re.exec(w); 139 | stem = fp[1]; 140 | suffix = fp[2]; 141 | re = new RegExp(mgr0); 142 | if (re.test(stem)) 143 | w = stem + step2list[suffix]; 144 | } 145 | 146 | // Step 3 147 | re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; 148 | if (re.test(w)) { 149 | var fp = re.exec(w); 150 | stem = fp[1]; 151 | suffix = fp[2]; 152 | re = new RegExp(mgr0); 153 | if (re.test(stem)) 154 | w = stem + step3list[suffix]; 155 | } 156 | 157 | // Step 4 158 | re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; 159 | re2 = /^(.+?)(s|t)(ion)$/; 160 | if (re.test(w)) { 161 | var fp = re.exec(w); 162 | stem = fp[1]; 163 | re = new RegExp(mgr1); 164 | if (re.test(stem)) 165 | w = stem; 166 | } 167 | else if (re2.test(w)) { 168 | var fp = re2.exec(w); 169 | stem = fp[1] + fp[2]; 170 | re2 = new RegExp(mgr1); 171 | if (re2.test(stem)) 172 | w = stem; 173 | } 174 | 175 | // Step 5 176 | re = /^(.+?)e$/; 177 | if (re.test(w)) { 178 | var fp = re.exec(w); 179 | stem = fp[1]; 180 | re = new RegExp(mgr1); 181 | re2 = new RegExp(meq1); 182 | re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 183 | if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) 184 | w = stem; 185 | } 186 | re = /ll$/; 187 | re2 = new RegExp(mgr1); 188 | if (re.test(w) && re2.test(w)) { 189 | re = /.$/; 190 | w = w.replace(re,""); 191 | } 192 | 193 | // and turn initial Y back to y 194 | if (firstch == "y") 195 | w = firstch.toLowerCase() + w.substr(1); 196 | return w; 197 | } 198 | } 199 | 200 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/minus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/third_party/kernel/docs/_static/minus.png -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/plus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/third_party/kernel/docs/_static/plus.png -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/pygments.css: -------------------------------------------------------------------------------- 1 | pre { line-height: 125%; } 2 | td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } 3 | span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } 4 | td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } 5 | span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } 6 | .highlight .hll { background-color: #ffffcc } 7 | .highlight { background: #eeffcc; } 8 | .highlight .c { color: #408090; font-style: italic } /* Comment */ 9 | .highlight .err { border: 1px solid #FF0000 } /* Error */ 10 | .highlight .k { color: #007020; font-weight: bold } /* Keyword */ 11 | .highlight .o { color: #666666 } /* Operator */ 12 | .highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ 13 | .highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ 14 | .highlight .cp { color: #007020 } /* Comment.Preproc */ 15 | .highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ 16 | .highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ 17 | .highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ 18 | .highlight .gd { color: #A00000 } /* Generic.Deleted */ 19 | .highlight .ge { font-style: italic } /* Generic.Emph */ 20 | .highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ 21 | .highlight .gr { color: #FF0000 } /* Generic.Error */ 22 | .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ 23 | .highlight .gi { color: #00A000 } /* Generic.Inserted */ 24 | .highlight .go { color: #333333 } /* Generic.Output */ 25 | .highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ 26 | .highlight .gs { font-weight: bold } /* Generic.Strong */ 27 | .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 28 | .highlight .gt { color: #0044DD } /* Generic.Traceback */ 29 | .highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ 30 | .highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ 31 | .highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ 32 | .highlight .kp { color: #007020 } /* Keyword.Pseudo */ 33 | .highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ 34 | .highlight .kt { color: #902000 } /* Keyword.Type */ 35 | .highlight .m { color: #208050 } /* Literal.Number */ 36 | .highlight .s { color: #4070a0 } /* Literal.String */ 37 | .highlight .na { color: #4070a0 } /* Name.Attribute */ 38 | .highlight .nb { color: #007020 } /* Name.Builtin */ 39 | .highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ 40 | .highlight .no { color: #60add5 } /* Name.Constant */ 41 | .highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ 42 | .highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ 43 | .highlight .ne { color: #007020 } /* Name.Exception */ 44 | .highlight .nf { color: #06287e } /* Name.Function */ 45 | .highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ 46 | .highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ 47 | .highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ 48 | .highlight .nv { color: #bb60d5 } /* Name.Variable */ 49 | .highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ 50 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */ 51 | .highlight .mb { color: #208050 } /* Literal.Number.Bin */ 52 | .highlight .mf { color: #208050 } /* Literal.Number.Float */ 53 | .highlight .mh { color: #208050 } /* Literal.Number.Hex */ 54 | .highlight .mi { color: #208050 } /* Literal.Number.Integer */ 55 | .highlight .mo { color: #208050 } /* Literal.Number.Oct */ 56 | .highlight .sa { color: #4070a0 } /* Literal.String.Affix */ 57 | .highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ 58 | .highlight .sc { color: #4070a0 } /* Literal.String.Char */ 59 | .highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ 60 | .highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ 61 | .highlight .s2 { color: #4070a0 } /* Literal.String.Double */ 62 | .highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ 63 | .highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ 64 | .highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ 65 | .highlight .sx { color: #c65d09 } /* Literal.String.Other */ 66 | .highlight .sr { color: #235388 } /* Literal.String.Regex */ 67 | .highlight .s1 { color: #4070a0 } /* Literal.String.Single */ 68 | .highlight .ss { color: #517918 } /* Literal.String.Symbol */ 69 | .highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ 70 | .highlight .fm { color: #06287e } /* Name.Function.Magic */ 71 | .highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ 72 | .highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ 73 | .highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ 74 | .highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ 75 | .highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/sphinx_highlight.js: -------------------------------------------------------------------------------- 1 | /* Highlighting utilities for Sphinx HTML documentation. */ 2 | "use strict"; 3 | 4 | const SPHINX_HIGHLIGHT_ENABLED = true 5 | 6 | /** 7 | * highlight a given string on a node by wrapping it in 8 | * span elements with the given class name. 9 | */ 10 | const _highlight = (node, addItems, text, className) => { 11 | if (node.nodeType === Node.TEXT_NODE) { 12 | const val = node.nodeValue; 13 | const parent = node.parentNode; 14 | const pos = val.toLowerCase().indexOf(text); 15 | if ( 16 | pos >= 0 && 17 | !parent.classList.contains(className) && 18 | !parent.classList.contains("nohighlight") 19 | ) { 20 | let span; 21 | 22 | const closestNode = parent.closest("body, svg, foreignObject"); 23 | const isInSVG = closestNode && closestNode.matches("svg"); 24 | if (isInSVG) { 25 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 26 | } else { 27 | span = document.createElement("span"); 28 | span.classList.add(className); 29 | } 30 | 31 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 32 | const rest = document.createTextNode(val.substr(pos + text.length)); 33 | parent.insertBefore( 34 | span, 35 | parent.insertBefore( 36 | rest, 37 | node.nextSibling 38 | ) 39 | ); 40 | node.nodeValue = val.substr(0, pos); 41 | /* There may be more occurrences of search term in this node. So call this 42 | * function recursively on the remaining fragment. 43 | */ 44 | _highlight(rest, addItems, text, className); 45 | 46 | if (isInSVG) { 47 | const rect = document.createElementNS( 48 | "http://www.w3.org/2000/svg", 49 | "rect" 50 | ); 51 | const bbox = parent.getBBox(); 52 | rect.x.baseVal.value = bbox.x; 53 | rect.y.baseVal.value = bbox.y; 54 | rect.width.baseVal.value = bbox.width; 55 | rect.height.baseVal.value = bbox.height; 56 | rect.setAttribute("class", className); 57 | addItems.push({ parent: parent, target: rect }); 58 | } 59 | } 60 | } else if (node.matches && !node.matches("button, select, textarea")) { 61 | node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); 62 | } 63 | }; 64 | const _highlightText = (thisNode, text, className) => { 65 | let addItems = []; 66 | _highlight(thisNode, addItems, text, className); 67 | addItems.forEach((obj) => 68 | obj.parent.insertAdjacentElement("beforebegin", obj.target) 69 | ); 70 | }; 71 | 72 | /** 73 | * Small JavaScript module for the documentation. 74 | */ 75 | const SphinxHighlight = { 76 | 77 | /** 78 | * highlight the search words provided in localstorage in the text 79 | */ 80 | highlightSearchWords: () => { 81 | if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight 82 | 83 | // get and clear terms from localstorage 84 | const url = new URL(window.location); 85 | const highlight = 86 | localStorage.getItem("sphinx_highlight_terms") 87 | || url.searchParams.get("highlight") 88 | || ""; 89 | localStorage.removeItem("sphinx_highlight_terms") 90 | url.searchParams.delete("highlight"); 91 | window.history.replaceState({}, "", url); 92 | 93 | // get individual terms from highlight string 94 | const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); 95 | if (terms.length === 0) return; // nothing to do 96 | 97 | // There should never be more than one element matching "div.body" 98 | const divBody = document.querySelectorAll("div.body"); 99 | const body = divBody.length ? divBody[0] : document.querySelector("body"); 100 | window.setTimeout(() => { 101 | terms.forEach((term) => _highlightText(body, term, "highlighted")); 102 | }, 10); 103 | 104 | const searchBox = document.getElementById("searchbox"); 105 | if (searchBox === null) return; 106 | searchBox.appendChild( 107 | document 108 | .createRange() 109 | .createContextualFragment( 110 | '

' + 111 | '' + 112 | _("Hide Search Matches") + 113 | "

" 114 | ) 115 | ); 116 | }, 117 | 118 | /** 119 | * helper function to hide the search marks again 120 | */ 121 | hideSearchWords: () => { 122 | document 123 | .querySelectorAll("#searchbox .highlight-link") 124 | .forEach((el) => el.remove()); 125 | document 126 | .querySelectorAll("span.highlighted") 127 | .forEach((el) => el.classList.remove("highlighted")); 128 | localStorage.removeItem("sphinx_highlight_terms") 129 | }, 130 | 131 | initEscapeListener: () => { 132 | // only install a listener if it is really needed 133 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; 134 | 135 | document.addEventListener("keydown", (event) => { 136 | // bail for input elements 137 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 138 | // bail with special keys 139 | if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; 140 | if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { 141 | SphinxHighlight.hideSearchWords(); 142 | event.preventDefault(); 143 | } 144 | }); 145 | }, 146 | }; 147 | 148 | _ready(() => { 149 | /* Do not call highlightSearchWords() when we are on the search page. 150 | * It will highlight words from the *previous* search query. 151 | */ 152 | if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); 153 | SphinxHighlight.initEscapeListener(); 154 | }); 155 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/theme_overrides.css: -------------------------------------------------------------------------------- 1 | /* -*- coding: utf-8; mode: css -*- 2 | * 3 | * Sphinx HTML theme customization: read the doc 4 | * Please don't add any color definition here, as the theme should 5 | * work for both normal and dark modes. 6 | */ 7 | 8 | /* Improve contrast and increase size for easier reading. */ 9 | 10 | body { 11 | font-family: serif; 12 | font-size: 100%; 13 | } 14 | 15 | h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { 16 | font-family: sans-serif; 17 | } 18 | 19 | div[class^="highlight"] pre { 20 | font-family: monospace; 21 | font-size: 100%; 22 | } 23 | 24 | .wy-menu-vertical { 25 | font-family: sans-serif; 26 | } 27 | 28 | .c { 29 | font-style: normal; 30 | } 31 | 32 | p { 33 | font-size: 100%; 34 | } 35 | 36 | /* Interim: Code-blocks with line nos - lines and line numbers don't line up. 37 | * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 38 | */ 39 | 40 | div[class^="highlight"] pre { 41 | line-height: normal; 42 | } 43 | .rst-content .highlight > pre { 44 | line-height: normal; 45 | } 46 | 47 | /* Keep fields from being strangely far apart due to inheirited table CSS. */ 48 | .rst-content table.field-list th.field-name { 49 | padding-top: 1px; 50 | padding-bottom: 1px; 51 | } 52 | .rst-content table.field-list td.field-body { 53 | padding-top: 1px; 54 | padding-bottom: 1px; 55 | } 56 | 57 | @media screen { 58 | 59 | /* content column 60 | * 61 | * RTD theme's default is 800px as max width for the content, but we have 62 | * tables with tons of columns, which need the full width of the view-port. 63 | */ 64 | 65 | .wy-nav-content{max-width: none; } 66 | 67 | /* table: 68 | * 69 | * - Sequences of whitespace should collapse into a single whitespace. 70 | * - make the overflow auto (scrollbar if needed) 71 | * - align caption "left" ("center" is unsuitable on vast tables) 72 | */ 73 | 74 | .wy-table-responsive table td { white-space: normal; } 75 | .wy-table-responsive { overflow: auto; } 76 | .rst-content table.docutils caption { text-align: left; font-size: 100%; } 77 | 78 | /* captions: 79 | * 80 | * - captions should have 100% (not 85%) font size 81 | * - hide the permalink symbol as long as link is not hovered 82 | */ 83 | 84 | caption, .wy-table caption, .rst-content table.field-list caption { 85 | font-size: 100%; 86 | } 87 | caption a.headerlink { opacity: 0; } 88 | caption a.headerlink:hover { opacity: 1; } 89 | 90 | /* Menu selection and keystrokes */ 91 | 92 | span.menuselection { 93 | font-family: "Courier New", Courier, monospace 94 | } 95 | 96 | code.kbd, code.kbd span { 97 | font-weight: bold; 98 | font-family: "Courier New", Courier, monospace 99 | } 100 | 101 | /* fix bottom margin of lists items */ 102 | 103 | .rst-content .section ul li:last-child, .rst-content .section ul li p:last-child { 104 | margin-bottom: 12px; 105 | } 106 | 107 | /* inline literal: drop the borderbox, padding and red color */ 108 | 109 | code, .rst-content tt, .rst-content code { 110 | color: inherit; 111 | border: none; 112 | padding: unset; 113 | background: inherit; 114 | font-size: 85%; 115 | } 116 | 117 | .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal { 118 | color: inherit; 119 | } 120 | } 121 | -------------------------------------------------------------------------------- /third_party/kernel/docs/_static/theme_rtd_colors.css: -------------------------------------------------------------------------------- 1 | /* -*- coding: utf-8; mode: css -*- 2 | * 3 | * Sphinx HTML theme customization: color settings for RTD (non-dark) theme 4 | * 5 | */ 6 | 7 | /* Improve contrast and increase size for easier reading. */ 8 | 9 | body { 10 | color: black; 11 | } 12 | 13 | .wy-menu-vertical li.current a { 14 | color: #505050; 15 | } 16 | 17 | .wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { 18 | color: #303030; 19 | } 20 | 21 | div[class^="highlight"] pre { 22 | color: black; 23 | } 24 | 25 | @media screen { 26 | 27 | /* Menu selection and keystrokes */ 28 | 29 | span.menuselection { 30 | color: blue; 31 | } 32 | 33 | code.kbd, code.kbd span { 34 | color: white; 35 | background-color: darkblue; 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /third_party/kernel/docs/api/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | API Reference — The Linux Kernel documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 |
26 | 27 | 93 |
94 |
95 | 96 | 97 |
98 | 99 | 100 | 101 | 102 | 103 |
104 |

API Reference

105 |
106 |
107 |

This page documents the KUnit kernel testing API. It is divided into the 108 | following sections:

109 |

Documentation/dev-tools/kunit/api/test.rst

110 |
111 |
    112 |

  • Documents all of the standard testing API

    • 113 |
114 |
115 |

Documentation/dev-tools/kunit/api/resource.rst

116 |
117 |
    118 |

  • Documents the KUnit resource API

    • 119 |
120 |
121 |

Documentation/dev-tools/kunit/api/functionredirection.rst

122 |
123 |
    124 |

  • Documents the KUnit Function Redirection API

    • 125 |
126 |
127 |
128 | 129 | 130 |
131 | 132 |
133 |
134 |
135 |
136 |
137 | ©The kernel development community. 138 | 139 | | 140 | Powered by Sphinx 7.2.6 141 | & Alabaster 0.7.12 142 | 143 | | 144 | Page source 146 |
147 | 148 | 149 | 150 | 151 | 152 | -------------------------------------------------------------------------------- /third_party/kernel/docs/objects.inv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/google/kunit-docs/ef7dfa6bbe077b3755902bd21acee6673769d5c1/third_party/kernel/docs/objects.inv -------------------------------------------------------------------------------- /third_party/kernel/docs/search.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Search — The Linux Kernel documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 79 |
80 |
81 | 82 | 83 |
84 | 85 |

Search

86 | 87 | 95 | 96 | 97 |

98 | Searching for multiple words only shows matches that contain 99 | all words. 100 |

101 | 102 | 103 |
104 | 105 | 106 | 107 |
108 | 109 | 110 | 111 |
112 | 113 |
114 | 115 | 116 |
117 | 118 |
119 |
120 |
121 |
122 |
123 | ©The kernel development community. 124 | 125 | | 126 | Powered by Sphinx 7.2.6 127 | & Alabaster 0.7.12 128 | 129 |
130 | 131 | 132 | 133 | 134 | 135 | -------------------------------------------------------------------------------- /third_party/kernel/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Upstream Version — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 61 | 62 |
66 | 67 |
68 |
69 |
70 | 77 |
78 |
79 |
80 |
81 | 82 |
83 |

Upstream Version

84 |

Here we have a copy of the KUnit documentation taken from upstream.

85 |

For convenience:

86 |
87 |

Where to get the code

88 |

This documentation is taken from torvalds’ master branch: 89 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/

90 |

Most KUnit upstream development is done against the ‘kunit’ branch of the linux kselftest repository: 91 | https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=kunit

92 |
93 |
94 |

Getting Started Guide

95 |

docs/

96 |

This documentation is also mirrored on kernel.org.

97 |
98 |
99 | 100 | 101 |
102 |
103 |
107 | 108 |
109 | 110 |
111 |

© Copyright 2019 Google LLC.

112 |
113 | 114 | Built with Sphinx using a 115 | theme 116 | provided by Read the Docs. 117 | 118 | 119 |
120 |
121 |
122 |
123 |
124 | 129 | 130 | 131 | -------------------------------------------------------------------------------- /third_party/stable_kernel/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Deprecated Version (“kunit/alpha/master”) — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 55 | 56 |
60 | 61 |
62 |
63 |
64 |
    65 |
    • 66 |
  • Deprecated Version (“kunit/alpha/master”)
    • 67 |
  • 68 | View page source 69 |
    • 70 |
71 |
72 |
73 |
74 |
75 | 76 |
77 |

Deprecated Version (“kunit/alpha/master”)

78 |

Here we have a copy of the documentation taken from the old “alpha” version 79 | KUnit.

80 |

You should really prefer using the upstream version if possible, but the alpha 81 | version has some features that still haven’t made their way upstream (class 82 | mocking, feature mocking, death tests, etc.)

83 |
84 |

Where to get the code

85 |

https://kunit.googlesource.com/linux/+/kunit/alpha/master

86 |
87 |
88 |

Getting Started Guide

89 |

docs/

90 |
91 |
92 | 93 | 94 |
95 |
96 |
97 | 98 |
99 | 100 |
101 |

© Copyright 2019 Google LLC.

102 |
103 | 104 | Built with Sphinx using a 105 | theme 106 | provided by Read the Docs. 107 | 108 | 109 |
110 |
111 |
112 |
113 |
114 | 119 | 120 | 121 | -------------------------------------------------------------------------------- /usage/faq.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Frequently Asked Questions — KUnit documentation 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 68 | 69 |
73 | 74 |
75 |
76 |
77 | 85 |
86 |
87 |
88 |
89 | 90 |
91 |

Frequently Asked Questions

92 |
93 |

I’m seeing ‘Error:root:Kconfig is not contained in validated .config!’

94 |

This means that there are some missing or wrong entries in your kunitconfig 95 | file. Make sure you’ve spelt all of your config entries correctly, and that 96 | you’ve included all of their dependencies.

97 |

If you’ve not changed the kunitconfig file, make sure you’ve got the correct 98 | version. In particular, some earlier versions used CONFIG_TEST=y instead 99 | of CONFIG_KUNIT=y.

100 |
101 |

Note

102 |

This error message can be confusing, so we intend to improve it. 103 | See https://bugzilla.kernel.org/show_bug.cgi?id=205235 for more details.

104 |
105 |
106 |
107 |

I’m seeing a lot of ‘makes integer from pointer without a cast’ errors in KUNIT_ASSERTION

108 |

If you wish to compare pointers, you’ll need to use the _PTR variants of the 109 | KUNIT_EXPECT macros. For example, you need to use 110 | KUNIT_EXPECT_PTR_EQ(test, ptr1, ptr2) instead of 111 | KUNIT_EXPECT_EQ(test, ptr1, ptr2).

112 |

This is required for KUnit to use the correct format specifier when printing out 113 | expectation failures.

114 |
115 |
116 | 117 | 118 |
119 |
120 |
124 | 125 |
126 | 127 |
128 |

© Copyright 2019 Google LLC.

129 |
130 | 131 | Built with Sphinx using a 132 | theme 133 | provided by Read the Docs. 134 | 135 | 136 |
137 |
138 |
139 |
140 |
141 | 146 | 147 | 148 | --------------------------------------------------------------------------------