Merge tag 'linux_kselftest-next-6.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest

Pull kselftest update from Shuah Khan:
 "timer test:
   - remove duplicate defines
   - fixes to improve error reporting

  rtc test:
   - check rtc alarm status in alarm test

  resctrl test:
   - add array overrun checks during iMC config parsing code and when
     reading strings
   - fixes and reorganizing code"

* tag 'linux_kselftest-next-6.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest: (23 commits)
  selftests/resctrl: Replace magic constants used as array size
  selftests/resctrl: Keep results from first test run
  selftests/resctrl: Do not compare performance counters and resctrl at low bandwidth
  selftests/resctrl: Use cache size to determine "fill_buf" buffer size
  selftests/resctrl: Ensure measurements skip initialization of default benchmark
  selftests/resctrl: Make benchmark parameter passing robust
  selftests/resctrl: Remove unused measurement code
  selftests/resctrl: Only support measured read operation
  selftests/resctrl: Remove "once" parameter required to be false
  selftests/resctrl: Make wraparound handling obvious
  selftests/resctrl: Protect against array overflow when reading strings
  selftests/resctrl: Protect against array overrun during iMC config parsing
  selftests/resctrl: Fix memory overflow due to unhandled wraparound
  selftests/resctrl: Print accurate buffer size as part of MBM results
  selftests/resctrl: Make functions only used in same file static
  selftests: Add a test mangling with uc_sigmask
  selftests: Rename sigaltstack to generic signal
  selftest: rtc: Add to check rtc alarm status for alarm related test
  selftests:timers: remove local CLOCKID defines
  selftests: timers: Remove unneeded semicolon
  ...

2 files changed, 56 insertions, 0 deletions

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.