[v4,3/3] drm/doc: Add KUnit documentation

Commit Message

José Expósito June 20, 2022, 4:06 p.m. UTC

Explain how to run the KUnit tests present in the DRM subsystem and
clarify why the UML-only options were not added to the configuration
file present in drivers/gpu/drm/.kunitconfig [1] [2].

[1] https://lore.kernel.org/dri-devel/CABVgOSn8i=[e-mail]/
[2] https://lore.kernel.org/dri-devel/CAGS_qxqpiCim_sy1LDK7PLwVgWf-LKW+uNFTGM=[e-mail]/

Reviewed-by: Maxime Ripard <[e-mail]>
Reviewed-by: Javier Martinez Canillas <[e-mail]>
Acked-by: Thomas Zimmermann <[e-mail]>
Signed-off-by: José Expósito <[e-mail]>
---
 Documentation/gpu/drm-internals.rst | 32 +++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

Comments

David Gow June 21, 2022, 9:38 a.m. UTC | #1

On Tue, Jun 21, 2022 at 12:06 AM José Expósito
<[e-mail]> wrote:
>
> Explain how to run the KUnit tests present in the DRM subsystem and
> clarify why the UML-only options were not added to the configuration
> file present in drivers/gpu/drm/.kunitconfig [1] [2].
>
> [1] https://lore.kernel.org/dri-devel/CABVgOSn8i=[e-mail]/
> [2] https://lore.kernel.org/dri-devel/CAGS_qxqpiCim_sy1LDK7PLwVgWf-LKW+uNFTGM=[e-mail]/
>
> Reviewed-by: Maxime Ripard <[e-mail]>
> Reviewed-by: Javier Martinez Canillas <[e-mail]>
> Acked-by: Thomas Zimmermann <[e-mail]>
> Signed-off-by: José Expósito <[e-mail]>
> ---

This looks good (and doesn't seem to introduce any 'make htmldocs'
build issues on my machine).

You could also mention that using --arch=x86_64 (or similar) instead
of the UML options is another, equally viable option for running the
tests. That'd make it more obvious how to run on different
architectures: UML, while a good default, is quite different to other
architectures in not having any PCI support out-of-the-box.

(Maybe we should make the --arch=um default config include these
options? Or have um-pci as another architecture. We did decide not to
bother with SMP and x86, though...)

Regardless, this is
Reviewed-by: David Gow <[e-mail]>

Cheers,
-- David

José Expósito June 21, 2022, 6:15 p.m. UTC | #2

Hi David,

On Tue, Jun 21, 2022 at 05:38:38PM +0800, David Gow wrote:
> On Tue, Jun 21, 2022 at 12:06 AM José Expósito
> <[e-mail]> wrote:
> >
> > Explain how to run the KUnit tests present in the DRM subsystem and
> > clarify why the UML-only options were not added to the configuration
> > file present in drivers/gpu/drm/.kunitconfig [1] [2].
> >
> > [1] https://lore.kernel.org/dri-devel/CABVgOSn8i=[e-mail]/
> > [2] https://lore.kernel.org/dri-devel/CAGS_qxqpiCim_sy1LDK7PLwVgWf-LKW+uNFTGM=[e-mail]/
> >
> > Reviewed-by: Maxime Ripard <[e-mail]>
> > Reviewed-by: Javier Martinez Canillas <[e-mail]>
> > Acked-by: Thomas Zimmermann <[e-mail]>
> > Signed-off-by: José Expósito <[e-mail]>
> > ---
> 
> This looks good (and doesn't seem to introduce any 'make htmldocs'
> build issues on my machine).
> 
> You could also mention that using --arch=x86_64 (or similar) instead
> of the UML options is another, equally viable option for running the
> tests. That'd make it more obvious how to run on different
> architectures: UML, while a good default, is quite different to other
> architectures in not having any PCI support out-of-the-box.
> 
> (Maybe we should make the --arch=um default config include these
> options? Or have um-pci as another architecture. We did decide not to
> bother with SMP and x86, though...)

Javier suggested the same:
https://lore.kernel.org/dri-devel/20220614180952.GA7067@elementary/

I prefer to keep the docs as simple as possible and link the KUnit
docs for more information. However, you both have way more experience 
than me and agree on the topic, so I'll be happy to include it in v5
if you think it is a good idea.
 
> Regardless, this is
> Reviewed-by: David Gow <[e-mail]>

Thanks for reviewing and building the docs, appreciate it.
Jose

> Cheers,
> -- David

Patch

diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index 38afed24a75c..5fd20a306718 100644
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -207,6 +207,38 @@  Utilities
    :internal:
 
 
+Unit testing
+============
+
+KUnit
+-----
+
+KUnit (Kernel unit testing framework) provides a common framework for unit tests
+within the Linux kernel.
+
+This section covers the specifics for the DRM subsystem. For general information
+about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.
+
+How to run the tests?
+~~~~~~~~~~~~~~~~~~~~~
+
+In order to facilitate running the test suite, a configuration file is present
+in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as
+follows:
+
+.. code-block:: bash
+
+	$ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \
+		--kconfig_add CONFIG_VIRTIO_UML=y \
+		--kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y
+
+.. note::
+	The configuration included in ``.kunitconfig`` should be as generic as
+	possible.
+	``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not
+	included in it because they are only required for User Mode Linux.
+
+
 Legacy Support Code
 ===================