Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) KUnit - Unit Testing for the Linux Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) .. toctree::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) 	:maxdepth: 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) 	start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) 	usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 	kunit-tool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 	api/index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 	style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 	faq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) What is KUnit?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) KUnit is heavily inspired by JUnit, Python's unittest.mock, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) cases, grouping related test cases into test suites, providing common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) infrastructure for running tests, and much more.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) KUnit consists of a kernel component, which provides a set of macros for easily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) writing unit tests. Tests written against KUnit will run on kernel boot if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) built-in, or when loaded if built as a module. These tests write out results to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) the kernel log in `TAP <https://testanything.org/>`_ format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) To make running these tests (and reading the results) easier, KUnit offers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) :doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) <http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) results. This provides a quick way of running KUnit tests during development,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) without requiring a virtual machine or separate hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Get started now: :doc:`start`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Why KUnit?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) A unit test is supposed to test a single unit of code in isolation, hence the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) name. A unit test should be the finest granularity of testing and as such should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) allow all possible code paths to be tested in the code under test; this is only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) possible if the code under test is very small and does not have any external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) dependencies outside of the test's control like hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) KUnit provides a common framework for unit tests within the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) KUnit tests can be run on most architectures, and most tests are architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) independent. All built-in KUnit tests run on kernel startup.  Alternatively,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) KUnit and KUnit tests can be built as modules and tests will run when the test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) module is loaded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)         KUnit can also run tests without needing a virtual machine or actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)         hardware under User Mode Linux. User Mode Linux is a Linux architecture,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)         like ARM or x86, which compiles the kernel as a Linux executable. KUnit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)         can be used with UML either by building with ``ARCH=um`` (like any other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)         architecture), or by using :doc:`kunit_tool <kunit-tool>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) KUnit is fast. Excluding build time, from invocation to completion KUnit can run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) several dozen tests in only 10 to 20 seconds; this might not sound like a big
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) deal to some people, but having such fast and easy to run tests fundamentally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) changes the way you go about testing and even writing code in the first place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Linus himself said in his `git talk at Google
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) <https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) 	"... a lot of people seem to think that performance is about doing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 	same thing, just doing it faster, and that is not true. That is not what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) 	performance is all about. If you can do something really fast, really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) 	well, people will start using it differently."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) In this context Linus was talking about branching and merging,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) but this point also applies to testing. If your tests are slow, unreliable, are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) difficult to write, and require a special setup or special hardware to run,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) then you wait a lot longer to write tests, and you wait a lot longer to run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) tests; this means that tests are likely to break, unlikely to test a lot of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) things, and are unlikely to be rerun once they pass. If your tests are really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) fast, you run them all the time, every time you make a change, and every time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) someone sends you some code. Why trust that someone ran all their tests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) correctly on every change when you can just run them yourself in less time than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) it takes to read their test log?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) How do I use it?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) *   :doc:`start` - for new users of KUnit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) *   :doc:`usage` - for a more detailed explanation of KUnit features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) *   :doc:`api/index` - for the list of KUnit APIs used for testing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) *   :doc:`kunit-tool` - for more information on the kunit_tool helper script
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) *   :doc:`faq` - for answers to some common questions about KUnit