docs: dev-tools: Add documentation for the device focused kselftests

Commit Message

Nícolas F. R. A. Prado Oct. 1, 2024, 3:43 p.m. UTC

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 <[e-mail]>
---
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/[e-mail]
---
 Documentation/dev-tools/kselftest.rst       |  9 ++++++
 Documentation/dev-tools/testing-devices.rst | 47 +++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)


---
base-commit: cea5425829f77e476b03702426f6b3701299b925
change-id: 20241001-kselftest-device-docs-6c8a411109b5

Best regards,

Comments

Shuah Khan Oct. 2, 2024, 6 p.m. UTC | #1

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 <[e-mail]>
> ---
> 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/[e-mail]
> ---
>   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

Nícolas F. R. A. Prado Oct. 3, 2024, 2:41 p.m. UTC | #2

On Wed, Oct 02, 2024 at 12:00:10PM -0600, Shuah Khan wrote:
> 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 <[e-mail]>
> > ---
> > 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/[e-mail]
> > ---
> >   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?

There is no warning. I have added this new document in a new toctree in the
kselftest.rst, as you can see in the hunk below.

Since this new page is specific to kselftest, I think listing it on the
kselftest page makes the most sense and will make it easier to find.

Do you want the new file to be listed in both places (ie kselftest.rst and
index.rst)? It will show up in the index.rst next to kselftest rather than
inside it.

Another option would be to do like kunit and create a directory for kselftest
and have an index.rst there to point to both the current kselftest.rst and the
new document. Structure-wise that would probably be the best approach.

> 
> >   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.

Ack.

Thanks,
Nícolas

Shuah Khan Oct. 4, 2024, 5:22 p.m. UTC | #3

On 10/3/24 08:41, Nícolas F. R. A. Prado wrote:
> On Wed, Oct 02, 2024 at 12:00:10PM -0600, Shuah Khan wrote:
>> 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 <[e-mail]>
>>> ---
>>> 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/[e-mail]
>>> ---
>>>    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?
> 
> There is no warning. I have added this new document in a new toctree in the
> kselftest.rst, as you can see in the hunk below.
> 

I missed that.

> Since this new page is specific to kselftest, I think listing it on the
> kselftest page makes the most sense and will make it easier to find.
> 

Yes - including it from kselftest makes sense to me.

Reviewed-by: Shuah Khan <[e-mail]>

Jon, Let me know if you would like me to take this through kselftest
tree.

thanks,
-- Shuah

Jonathan Corbet Oct. 4, 2024, 5:36 p.m. UTC | #4

Shuah Khan <[e-mail]> writes:

> Jon, Let me know if you would like me to take this through kselftest
> tree.

I'm happy either way - go ahead and grab it if you like, just let me
know.

Thanks,

jon

Shuah Khan Oct. 4, 2024, 7:21 p.m. UTC | #5

On 10/4/24 11:36, Jonathan Corbet wrote:
> Shuah Khan <[e-mail]> writes:
> 
>> Jon, Let me know if you would like me to take this through kselftest
>> tree.
> 
> I'm happy either way - go ahead and grab it if you like, just let me

> know.
> 
> Thanks,
> 
> jon

Applied to linux-kselftest next for Linux 6.13-rc1.

thanks,
-- Shuah

Patch

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
+=============================
+
+
+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.