Add a "Usage" section to the KUnit webpage.
This basically updates what's there to talk about experimental versions
rather than stable versions, moves most of the discussion of the
different versions to a "Getting KUnit" page, and adds an FAQ.
It also adds to the index page a very basic "how to run tests" bit, an
anaemic "Writing tests" section which tries to link to the Getting
Started page from the upstream kernel, and a "Submitting tests upstream"
section which covers the current state of the upstreaming process and
how that (in theory) works.
Change-Id: I83e3db99e407c77a7b67546e40b67d237bcc4388
Signed-off-by: David Gow <davidgow@google.com>
diff --git a/index.rst b/index.rst
index 55a8eb9..492b34f 100644
--- a/index.rst
+++ b/index.rst
@@ -38,9 +38,8 @@
==========
Aside from KUnit there is no true unit testing framework for the Linux kernel.
-Autotest and kselftest (and within Google, Kokonut) are sometimes cited as unit
-testing frameworks; however, they are not by most reasonable definitions of
-unit tests.
+Autotest and kselftest are sometimes cited as unit testing frameworks; however,
+they are not by most reasonable definitions of unit tests.
A unit test is supposed to test a single unit of code in isolation, hence the
name. A unit test should be the finest granularity of testing and as such
@@ -69,7 +68,7 @@
- For upstream KUnit:
- `Usage <third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
- `API <third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing
-- For stable KUnit:
+- For experimental KUnit:
- `Usage <third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
- `API <third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing
diff --git a/usage/faq.rst b/usage/faq.rst
new file mode 100644
index 0000000..312f22e
--- /dev/null
+++ b/usage/faq.rst
@@ -0,0 +1,29 @@
+==========================
+Frequently Asked Questions
+==========================
+
+I’m seeing 'Error:root:Kconfig is not contained in validated .config!'
+----------------------------------------------------------------------
+
+This means that there are some missing or wrong entries in your ``kunitconfig``
+file. Make sure you’ve spelt all of your config entries correctly, and that
+you’ve included all of their dependencies.
+
+If you’ve not changed the kunitconfig file, make sure you’ve got the correct
+version. In particular, some earlier versions used ``CONFIG_TEST=y`` instead
+of ``CONFIG_KUNIT=y``.
+
+.. note:: This error message can be confusing, so we intend to improve it.
+ See https://bugzilla.kernel.org/show_bug.cgi?id=205235 for more details.
+
+
+I’m seeing a lot of 'makes integer from pointer without a cast' errors in KUNIT_ASSERTION
+-----------------------------------------------------------------------------------------
+
+If you wish to compare pointers, you’ll need to use the _PTR variants of the
+``KUNIT_EXPECT`` macros. For example, you need to use
+``KUNIT_EXPECT_PTR_EQ(test, ptr1, ptr2)`` instead of
+``KUNIT_EXPECT_EQ(test, ptr1, ptr2)``.
+
+This is required for KUnit to use the correct format specifier when printing out
+expectation failures.
diff --git a/usage/getting_kunit.rst b/usage/getting_kunit.rst
new file mode 100644
index 0000000..e70e96e
--- /dev/null
+++ b/usage/getting_kunit.rst
@@ -0,0 +1,104 @@
+=============
+Getting KUnit
+=============
+
+In order to use KUnit, you must first determine which branch you would like to
+use. What do we mean by that? We are in the process of upstreaming KUnit into
+the Linux kernel, so that means we have code under development that is not in
+the upstream repository or otherwise doesn't match what is currently upstream.
+
+For more information on why there are multiple versions of KUnit, see
+:ref:`why-multiple-versions`.
+
+For information on deciding which version you should use see
+:ref:`which-version`.
+
+For the actual URL you need, see
+:ref:`download-links`
+
+.. _why-multiple-versions:
+
+Why are there multiple versions?
+================================
+
+Ideally, upstreaming code to the Linux kernel would be fast, we would be able to
+develop features entirely on LKML, no one would use code that had not yet been
+accepted upstream, and everything would have been done this way from the start.
+Unfortunately, we do not live in a perfect world, and consequently none of these
+are true.
+
+This means that there are some features that we've developed which aren't yet
+going upstream. We've developed these in an *experimental* branch. This is
+basically a staging branch for features we're still actively experimenting with,
+or which depend on code which isn't yet upstream.
+
+
+But wait, I see more than two branches!
+---------------------------------------
+
+For the upstream version, just use torvalds/master. Our *experimental* branch is
+hosted at https://kunit.googlesource.com/linux/+/kunit/alpha/master.
+
+We will be periodically replacing the *experimental* branch with one based on
+newer upstream kernels, in order to minimise the divergence between
+*experimental* and upstream. For more details on how this will work, see:
+https://lore.kernel.org/linux-kselftest/20190924000503.GA97201@google.com/T/#e73eab088e4791c234bf13156cc276ad15c8376de
+
+.. _which-version:
+
+Which version should I use?
+===========================
+
+As for which branch you should use, upstream should be generally preferred (just
+as upstreaming your own code should be generally preferred); nevertheless, there
+are a lot of features that are not upstream yet, and will not be upstream for
+some time (possibly more than a year), if you need these features for your tests
+then you have no choice other than to use the *experimental* branch.
+
+What features are available upstream?
+-------------------------------------
+
+- Basic test structure for defining test cases and test suites
+- Basic expectations and assertions
+- KUnit managed resources
+- Error reporting
+
+What features are not upstream yet?
+-----------------------------------
+
+- Class mocking
+- Function mocking
+- Hardware/platform faking
+- Error recovery
+
+.. _download-links:
+
+Where are these versions?
+=========================
+
+Upstream
+--------
+
+Alas, KUnit is not quite upstream yet. You can find the current to-be-upstreamed
+branch in the kselftest tree, but be warned that, until it's upstreamed, things
+may change at any point!
+
+- Code: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
+- `Usage <third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
+- `API <third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing
+- kunitconfig file: https://kunit.googlesource.com/kunitconfig/+/refs/heads/master/kunitconfig
+
+You can also find KUnit in linux-next.
+
+Experimental
+------------
+
+The *experimental* branch is stored in a Google-hosted gerrit instance. Going
+forward, there will be a set of versioned *experimental* branches, of which only
+the latest will be actively supported. Until this is available, however, there
+is a historic *kunit/alpha/master* branch containing our experimental code.
+
+- Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master.
+- `Usage <third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
+- `API <third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing
+- kunitconfig file: https://kunit.googlesource.com/kunitconfig/+/refs/heads/kunit/alpha/master/kunitconfig
diff --git a/usage/index.rst b/usage/index.rst
index 5ee2dd7..cb3fd38 100644
--- a/usage/index.rst
+++ b/usage/index.rst
@@ -1,90 +1,65 @@
-===============
-Getting Started
-===============
-
-In order to use KUnit, you must first determine which branch you would like to
-use. What do we mean by that? We are in the process of upstreaming KUnit into
-the Linux kernel, so that means we have code under development that is not in
-the upstream repository or otherwise doesn't match what is currently upstream.
-
-For more information on why there are multiple versions of KUnit, see
-:ref:`why-multiple-versions`.
-
-For information on deciding which version you should use see
-:ref:`which-version`.
-
-.. _why-multiple-versions:
-
-Why are there multiple versions?
-================================
-
-Ideally, upstreaming code to the Linux kernel would be fast, we would be able to
-develope features entirely on LKML, no one would use code that had not yet been
-accepted upstream, and everything would have been done this way from the start.
-Unfortunately, we do not live in a perfect world, and consequently none of these
-are true.
-
-In short, we wrote a bunch of stuff to experiment with before we started sending
-things upstream, people started using that stuff, and upstream diverged. We made
-the decision that it is better to have 2 versions of KUnit rather than ``n``
-versions where ``n > 2``, so we decided to maintain a non-upstream branch called
-*stable* which has all the features not yet upstreamed, and would be maintained
-under the assumption that people are actually using it (hence, we don't make API
-breaking changes, or anything like that); this is why it's called *stable*. Our
-other branch is just upstream Linux.
-
-But wait, I see more than two branches!
----------------------------------------
-
-For the upstream version, just use torvalds/master. Our *stable* branch is
-hosted at https://kunit.googlesource.com/linux/+/kunit/alpha/master.
-
-Nevertheless, you may notice that there are other branches hosted at
-https://kunit.googlesource.com/linux. All these branches are either based on
-upstream (and should not be used since they are not upstream yet), or are based
-on stable.
-
-.. _which-version:
-
-Which version should I use?
-===========================
-
-As for which branch you should use, upstream should be generally preferred (just
-as upstreaming your own code should be generally preferred); nevertheless, there
-are a lot of features that are not upstream yet, and will not be upstream for
-some time (possibly more than a year), if you need these features for your tests
-then you have no choice other than to use the stable branch.
-
-What features are available upstream?
--------------------------------------
-
-- Basic test structure for defining test cases and test suites
-- Basic expectations and assertions
-- KUnit managed resources
-- Error reporting
-
-What features are not upstream yet?
------------------------------------
-
-- Class mocking
-- Function mocking
-- Hardware/platform faking
-- Error recovery
-
-Where to go
+===========
+Using KUnit
===========
-Hopefully you now have a good idea whether you want to use the stable version,
-or the upstream version. As for where to go, see the following sections:
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
-Upstream Getting Started
-------------------------
+ getting_kunit
+ faq
-- Code: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
-- Documentation: :doc:`../third_party/kernel/index`
+Where is KUnit?
+:doc:`getting_kunit`
-Stable Getting Started
-----------------------
-- Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master
-- Documentation: :doc:`../third_party/stable_kernel/index`
+KUnit is integrated into the Linux kernel, so all you need is a version of the
+kernel which contains KUnit, and a config file with which to build it. The
+:doc: `getting_kunit` page covers the different versions of KUnit available, and
+where to get them.
+
+
+Running tests
+=============
+
+To run KUnit tests, you'll need to provide a 'kunitconfig' file, which contains
+the list of test modules to build, and their dependencies.
+
+Once you have the ``kunitconfig`` file, just run:
+
+``$ ./tools/testing/kunit/kunit.py run``
+
+This will build a UML (User Mode Linux) kernel, run the specified tests, and
+print the results (nicely formatted) to the screen.
+
+
+Writing tests
+=============
+
+Once you have KUnit working, writing tests is easy. Each test is a function
+which accepts a ``struct kunit`` argument, and which calls the various
+``KUNIT_EXPECT_*`` macros to verify the state under test.
+
+More details can be found in the `Getting Started <../third_party/kernel/docs/start.html>`_
+guide.
+
+
+Submitting tests upstream
+=========================
+
+Ideally, KUnit tests will be submitted upstream alongside the code being tested,
+so any user or developer can run the tests and test any changes they make. Once
+KUnit itself is upstream, this means that KUnit tests should ideally be treated
+as any other change, and submitted via the maintainer of the subsystem being
+tested. (Though do feel free to copy in the ``kunit-dev@googlegroups.com`` list
+if you want.)
+
+For the time being, though, we recommend submitting patches via the
+``linux-kselftest/test`` branch, which contains the version of KUnit likely to
+head upstream. To do so, please send your patch via the
+``linux-kselftest@vger.kernel.org`` list, and include ``linux-kselftest/test``
+in the subject prefix. You should still get a review from the subsystem
+maintainer, though.
+
+And, of course, you should follow the general rules and guidelines laid out in
+https://www.kernel.org/doc/html/latest/process/submitting-patches.html