Re: [PATCH] docs: dev-tools: Add documentation for the device focused kselftests

[Shuah Khan]

On 10/1/24 09:43, Nícolas F. R. A. Prado wrote:
> Add documentation for the kselftests focused on testing devices and
> point to it from the kselftest documentation. There are multiple tests
> in this category so the aim of this page is to make it clear when to run
> each test.
>
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx>
> ---
> This patch depends on patch "kselftest: devices: Add test to detect
> missing devices" [1], since this patch documents that test.
>
> [1] https://lore.kernel.org/all/20240928-kselftest-dev-exist-v2-1-fab07de6b80b@xxxxxxxxxxxxx
> ---
>   Documentation/dev-tools/kselftest.rst       |  9 ++++++
>   Documentation/dev-tools/testing-devices.rst | 47 +++++++++++++++++++++++++++++

The new file needs to be added to Documentation/dev-tools/index.rst

Docs make should have warned about this?

>   2 files changed, 56 insertions(+)
>
> diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
> index f3766e326d1e..fdb1df86783a 100644
> --- a/Documentation/dev-tools/kselftest.rst
> +++ b/Documentation/dev-tools/kselftest.rst
> @@ -31,6 +31,15 @@ kselftest runs as a userspace process.  Tests that can be written/run in
>   userspace may wish to use the `Test Harness`_.  Tests that need to be
>   run in kernel space may wish to use a `Test Module`_.
>   
> +Documentation on the tests
> +==========================
> +
> +For documentation on the kselftests themselves, see:
> +
> +.. toctree::
> +
> +   testing-devices
> +
>   Running the selftests (hotplug tests are run in limited mode)
>   =============================================================
>   
> diff --git a/Documentation/dev-tools/testing-devices.rst b/Documentation/dev-tools/testing-devices.rst
> new file mode 100644
> index 000000000000..ab26adb99051
> --- /dev/null
> +++ b/Documentation/dev-tools/testing-devices.rst
> @@ -0,0 +1,47 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. Copyright (c) 2024 Collabora Ltd
> +
> +=============================
> +Device testing with kselftest
> +=============================
> +

Get rid of the extra blank line.

> +
> +There are a few different kselftests available for testing devices generically,
> +with some overlap in coverage and different requirements. This document aims to
> +give an overview of each one.
> +
> +Note: Paths in this document are relative to the kselftest folder
> +(``tools/testing/selftests``).
> +
> +Device oriented kselftests:
> +
> +* Devicetree (``dt``)
> +
> +  * **Coverage**: Probe status for devices described in Devicetree
> +  * **Requirements**: None
> +
> +* Error logs (``devices/error_logs``)
> +
> +  * **Coverage**: Error (or more critical) log messages presence coming from any
> +    device
> +  * **Requirements**: None
> +
> +* Discoverable bus (``devices/probe``)
> +
> +  * **Coverage**: Presence and probe status of USB or PCI devices that have been
> +    described in the reference file
> +  * **Requirements**: Manually describe the devices that should be tested in a
> +    YAML reference file (see ``devices/probe/boards/google,spherion.yaml`` for
> +    an example)
> +
> +* Exist (``devices/exist``)
> +
> +  * **Coverage**: Presence of all devices
> +  * **Requirements**: Generate the reference (see ``devices/exist/README.rst``
> +    for details) on a known-good kernel
> +
> +Therefore, the suggestion is to enable the error log and devicetree tests on all
> +(DT-based) platforms, since they don't have any requirements. Then to greatly
> +improve coverage, generate the reference for each platform and enable the exist
> +test. The discoverable bus test can be used to verify the probe status of
> +specific USB or PCI devices, but is probably not worth it for most cases.
>
> ---
> base-commit: cea5425829f77e476b03702426f6b3701299b925
> change-id: 20241001-kselftest-device-docs-6c8a411109b5
>
> Best regards,

thanks,
-- Shuah