[PATCH v4 0/3] Add test to verify probe of devices from discoverable buses

[PATCH v4 0/3] Add test to verify probe of devices from discoverable buses

[Nícolas F. R. A. Prado]

This is part of an effort to improve detection of regressions impacting
device probe on all platforms. The recently merged DT kselftest [3]
detects probe issues for all devices described statically in the DT.
That leaves out devices discovered at run-time from discoverable buses.

This is where this test comes in. All of the devices that are connected
through discoverable buses (ie USB and PCI), and which are internal and
therefore always present, can be described based on their position in
the system topology in a per-platform YAML file so they can be checked
for. The test will check that the device has been instantiated and bound
to a driver.

Patch 1 introduces the test. Patch 2 and 3 add the device definitions
for the google,spherion machine (Acer Chromebook 514) and XPS 13 as
examples.

This is the output from the test running on Spherion:

TAP version 13
Using board file: boards/google,spherion.yaml
1..8
ok 1 /usb2-controller@11200000/1.4.1/camera.device
ok 2 /usb2-controller@11200000/1.4.1/camera.0.driver
ok 3 /usb2-controller@11200000/1.4.1/camera.1.driver
ok 4 /usb2-controller@11200000/1.4.2/bluetooth.device
ok 5 /usb2-controller@11200000/1.4.2/bluetooth.0.driver
ok 6 /usb2-controller@11200000/1.4.2/bluetooth.1.driver
ok 7 /pci-controller@11230000/0.0/0.0/wifi.device
ok 8 /pci-controller@11230000/0.0/0.0/wifi.driver
Totals: pass:8 fail:0 xfail:0 xpass:0 skip:0 error:0

[3] https://lore.kernel.org/all/20230828211424.2964562-1-nfraprado@collabora.com/

Changes in v4:
- Dropped RFC tag
- Fixed 'busses' misspelling
- Link to v3: https://lore.kernel.org/all/20231227123643.52348-1-nfraprado@collabora.com

Changes in v3:
- Reverted approach of encoding stable device reference in test file
from device match fields (from modalias) back to HW topology (from v1)
- Changed board file description to YAML
- Rewrote test script in python to handle YAML and support x86 platforms
- Link to v2: https://lore.kernel.org/all/20231127233558.868365-1-nfraprado@collabora.com

Changes in v2:
- Changed approach of encoding stable device reference in test file from
HW topology to device match fields (the ones from modalias)
- Better documented test format
- Link to v1: https://lore.kernel.org/all/20231024211818.365844-1-nfraprado@collabora.com

---
Nícolas F. R. A. Prado (3):
      kselftest: Add test to verify probe of devices from discoverable buses
      kselftest: devices: Add sample board file for google,spherion
      kselftest: devices: Add sample board file for XPS 13 9300

 tools/testing/selftests/Makefile                   |   1 +
 tools/testing/selftests/devices/Makefile           |   4 +
 .../devices/boards/Dell Inc.,XPS 13 9300.yaml      |  40 +++
 .../selftests/devices/boards/google,spherion.yaml  |  50 ++++
 tools/testing/selftests/devices/ksft.py            |  90 ++++++
 .../selftests/devices/test_discoverable_devices.py | 318 +++++++++++++++++++++
 6 files changed, 503 insertions(+)
---
base-commit: 6613476e225e090cc9aad49be7fa504e290dd33d
change-id: 20240122-discoverable-devs-ksft-9d501e312688

Best regards,
-- 
Nícolas F. R. A. Prado <nfraprado@collabora.com>

[PATCH v4 1/3] kselftest: Add test to verify probe of devices from discoverable buses

[Nícolas F. R. A. Prado]

Add a new test to verify that a list of expected devices from
discoverable buses (ie USB, PCI) have been successfully instantiated and
probed by a driver.

The per-platform list of expected devices is selected from the ones
under the boards/ directory based on the DT compatible or the DMI IDs.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
 tools/testing/selftests/Makefile                   |   1 +
 tools/testing/selftests/devices/Makefile           |   4 +
 tools/testing/selftests/devices/ksft.py            |  90 ++++++
 .../selftests/devices/test_discoverable_devices.py | 318 +++++++++++++++++++++
 4 files changed, 413 insertions(+)

diff --git a/tools/testing/selftests/Makefile b/tools/testing/selftests/Makefile
index 15b6a111c3be..a7858126c7c5 100644
--- a/tools/testing/selftests/Makefile
+++ b/tools/testing/selftests/Makefile
@@ -13,6 +13,7 @@ TARGETS += core
 TARGETS += cpufreq
 TARGETS += cpu-hotplug
 TARGETS += damon
+TARGETS += devices
 TARGETS += dmabuf-heaps
 TARGETS += drivers/dma-buf
 TARGETS += drivers/s390x/uvdevice
diff --git a/tools/testing/selftests/devices/Makefile b/tools/testing/selftests/devices/Makefile
new file mode 100644
index 000000000000..ca29249b30c3
--- /dev/null
+++ b/tools/testing/selftests/devices/Makefile
@@ -0,0 +1,4 @@
+TEST_PROGS := test_discoverable_devices.py
+TEST_FILES := boards ksft.py
+
+include ../lib.mk
diff --git a/tools/testing/selftests/devices/ksft.py b/tools/testing/selftests/devices/ksft.py
new file mode 100644
index 000000000000..cd89fb2bc10e
--- /dev/null
+++ b/tools/testing/selftests/devices/ksft.py
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# Copyright (c) 2023 Collabora Ltd
+#
+# Kselftest helpers for outputting in KTAP format. Based on kselftest.h.
+#
+
+import sys
+
+ksft_cnt = {"pass": 0, "fail": 0, "skip": 0}
+ksft_num_tests = 0
+ksft_test_number = 1
+
+KSFT_PASS = 0
+KSFT_FAIL = 1
+KSFT_SKIP = 4
+
+
+def print_header():
+    print("TAP version 13")
+
+
+def set_plan(num_tests):
+    global ksft_num_tests
+    ksft_num_tests = num_tests
+    print("1..{}".format(num_tests))
+
+
+def print_cnts():
+    print(
+        f"# Totals: pass:{ksft_cnt['pass']} fail:{ksft_cnt['fail']} xfail:0 xpass:0 skip:{ksft_cnt['skip']} error:0"
+    )
+
+
+def print_msg(msg):
+    print(f"# {msg}")
+
+
+def _test_print(result, description, directive=None):
+    if directive:
+        directive_str = f"# {directive}"
+    else:
+        directive_str = ""
+
+    global ksft_test_number
+    print(f"{result} {ksft_test_number} {description} {directive_str}")
+    ksft_test_number += 1
+
+
+def test_result_pass(description):
+    _test_print("ok", description)
+    ksft_cnt["pass"] += 1
+
+
+def test_result_fail(description):
+    _test_print("not ok", description)
+    ksft_cnt["fail"] += 1
+
+
+def test_result_skip(description):
+    _test_print("ok", description, "SKIP")
+    ksft_cnt["skip"] += 1
+
+
+def test_result(condition, description=""):
+    if condition:
+        test_result_pass(description)
+    else:
+        test_result_fail(description)
+
+
+def finished():
+    if ksft_cnt["pass"] == ksft_num_tests:
+        exit_code = KSFT_PASS
+    else:
+        exit_code = KSFT_FAIL
+
+    print_cnts()
+
+    sys.exit(exit_code)
+
+
+def exit_fail():
+    print_cnts()
+    sys.exit(KSFT_FAIL)
+
+
+def exit_pass():
+    print_cnts()
+    sys.exit(KSFT_PASS)
diff --git a/tools/testing/selftests/devices/test_discoverable_devices.py b/tools/testing/selftests/devices/test_discoverable_devices.py
new file mode 100755
index 000000000000..fbae8deb593d
--- /dev/null
+++ b/tools/testing/selftests/devices/test_discoverable_devices.py
@@ -0,0 +1,318 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: GPL-2.0
+#
+# Copyright (c) 2023 Collabora Ltd
+#
+# This script tests for presence and driver binding of devices from discoverable
+# buses (ie USB, PCI).
+#
+# The per-platform YAML file defining the devices to be tested is stored inside
+# the boards/ directory and chosen based on DT compatible or DMI IDs (sys_vendor
+# and product_name).
+#
+# See boards/google,spherion.yaml and boards/'Dell Inc.,XPS 13 9300.yaml' for
+# the description and examples of the file structure and vocabulary.
+#
+
+import glob
+import ksft
+import os
+import re
+import sys
+import yaml
+
+pci_controllers = []
+usb_controllers = []
+
+sysfs_usb_devices = "/sys/bus/usb/devices/"
+
+
+def find_pci_controller_dirs():
+    sysfs_devices = "/sys/devices"
+    pci_controller_sysfs_dir = "pci[0-9a-f]{4}:[0-9a-f]{2}"
+
+    dir_regex = re.compile(pci_controller_sysfs_dir)
+    for path, dirs, _ in os.walk(sysfs_devices):
+        for d in dirs:
+            if dir_regex.match(d):
+                pci_controllers.append(os.path.join(path, d))
+
+
+def find_usb_controller_dirs():
+    usb_controller_sysfs_dir = "usb[\d]+"
+
+    dir_regex = re.compile(usb_controller_sysfs_dir)
+    for d in os.scandir(sysfs_usb_devices):
+        if dir_regex.match(d.name):
+            usb_controllers.append(os.path.realpath(d.path))
+
+
+def get_dt_mmio(sysfs_dev_dir):
+    re_dt_mmio = re.compile("OF_FULLNAME=.*@([0-9a-f]+)")
+    dt_mmio = None
+
+    # PCI controllers' sysfs don't have an of_node, so have to read it from the
+    # parent
+    while not dt_mmio:
+        try:
+            with open(os.path.join(sysfs_dev_dir, "uevent")) as f:
+                dt_mmio = re_dt_mmio.search(f.read()).group(1)
+                return dt_mmio
+        except:
+            pass
+        sysfs_dev_dir = os.path.dirname(sysfs_dev_dir)
+
+
+def get_acpi_uid(sysfs_dev_dir):
+    with open(os.path.join(sysfs_dev_dir, "firmware_node", "uid")) as f:
+        return f.read()
+
+
+def get_usb_version(sysfs_dev_dir):
+    re_usb_version = re.compile("PRODUCT=.*/(\d)/.*")
+    with open(os.path.join(sysfs_dev_dir, "uevent")) as f:
+        return int(re_usb_version.search(f.read()).group(1))
+
+
+def get_usb_busnum(sysfs_dev_dir):
+    re_busnum = re.compile("BUSNUM=(.*)")
+    with open(os.path.join(sysfs_dev_dir, "uevent")) as f:
+        return int(re_busnum.search(f.read()).group(1))
+
+
+def find_controller_in_sysfs(controller, parent_sysfs=None):
+    if controller["type"] == "pci-controller":
+        controllers = pci_controllers
+    elif controller["type"] == "usb-controller":
+        controllers = usb_controllers
+
+    result_controllers = []
+
+    for c in controllers:
+        if parent_sysfs and parent_sysfs not in c:
+            continue
+
+        if controller.get("dt-mmio"):
+            if str(controller["dt-mmio"]) != get_dt_mmio(c):
+                continue
+
+        if controller.get("usb-version"):
+            if controller["usb-version"] != get_usb_version(c):
+                continue
+
+        if controller.get("acpi-uid"):
+            if controller["acpi-uid"] != get_acpi_uid(c):
+                continue
+
+        result_controllers.append(c)
+
+    return result_controllers
+
+
+def is_controller(device):
+    return device.get("type") and "controller" in device.get("type")
+
+
+def path_to_dir(parent_sysfs, dev_type, path):
+    if dev_type == "usb-device":
+        usb_dev_sysfs_fmt = "{}-{}"
+        busnum = get_usb_busnum(parent_sysfs)
+        dirname = os.path.join(
+            sysfs_usb_devices, usb_dev_sysfs_fmt.format(busnum, path)
+        )
+        return [os.path.realpath(dirname)]
+    else:
+        pci_dev_sysfs_fmt = "????:??:{}"
+        path_glob = ""
+        for dev_func in path.split("/"):
+            dev_func = dev_func.zfill(4)
+            path_glob = os.path.join(path_glob, pci_dev_sysfs_fmt.format(dev_func))
+
+        dir_list = glob.glob(os.path.join(parent_sysfs, path_glob))
+
+        return dir_list
+
+
+def find_in_sysfs(device, parent_sysfs=None):
+    if parent_sysfs and device.get("path"):
+        pathdirs = path_to_dir(
+            parent_sysfs, device["meta"]["type"], str(device["path"])
+        )
+        if len(pathdirs) != 1:
+            # Early return to report error
+            return pathdirs
+        pathdir = pathdirs[0]
+        sysfs_path = os.path.join(parent_sysfs, pathdir)
+    else:
+        sysfs_path = parent_sysfs
+
+    if is_controller(device):
+        return find_controller_in_sysfs(device, sysfs_path)
+    else:
+        return [sysfs_path]
+
+
+def check_driver_presence(sysfs_dir, current_node):
+    if current_node["meta"]["type"] == "usb-device":
+        usb_intf_fmt = "*-*:*.{}"
+
+        interfaces = []
+        for i in current_node["interfaces"]:
+            interfaces.append((i, usb_intf_fmt.format(i)))
+
+        for intf_num, intf_dir_fmt in interfaces:
+            test_name = f"{current_node['meta']['pathname']}.{intf_num}.driver"
+
+            intf_dirs = glob.glob(os.path.join(sysfs_dir, intf_dir_fmt))
+            if len(intf_dirs) != 1:
+                ksft.test_result_fail(test_name)
+                continue
+            intf_dir = intf_dirs[0]
+
+            driver_link = os.path.join(sysfs_dir, intf_dir, "driver")
+            ksft.test_result(os.path.isdir(driver_link), test_name)
+    else:
+        driver_link = os.path.join(sysfs_dir, "driver")
+        test_name = current_node["meta"]["pathname"] + ".driver"
+        ksft.test_result(os.path.isdir(driver_link), test_name)
+
+
+def generate_pathname(device):
+    pathname = ""
+
+    if device.get("path"):
+        pathname = str(device["path"])
+
+    if device.get("type"):
+        dev_type = device["type"]
+        if device.get("usb-version"):
+            dev_type = dev_type.replace("usb", "usb" + str(device["usb-version"]))
+        if device.get("acpi-uid") is not None:
+            dev_type = dev_type.replace("pci", "pci" + str(device["acpi-uid"]))
+        pathname = pathname + "/" + dev_type
+
+    if device.get("dt-mmio"):
+        pathname += "@" + str(device["dt-mmio"])
+
+    if device.get("name"):
+        pathname = pathname + "/" + device["name"]
+
+    return pathname
+
+
+def fill_meta_keys(child, parent=None):
+    child["meta"] = {}
+
+    if parent:
+        child["meta"]["type"] = parent["type"].replace("controller", "device")
+
+    pathname = generate_pathname(child)
+    if parent:
+        pathname = parent["meta"]["pathname"] + "/" + pathname
+    child["meta"]["pathname"] = pathname
+
+
+def parse_device_tree_node(current_node, parent_sysfs=None):
+    if not parent_sysfs:
+        fill_meta_keys(current_node)
+
+    sysfs_dirs = find_in_sysfs(current_node, parent_sysfs)
+    if len(sysfs_dirs) != 1:
+        if len(sysfs_dirs) == 0:
+            ksft.test_result_fail(
+                f"Couldn't find in sysfs: {current_node['meta']['pathname']}"
+            )
+        else:
+            ksft.test_result_fail(
+                f"Found multiple sysfs entries for {current_node['meta']['pathname']}: {sysfs_dirs}"
+            )
+        return
+    sysfs_dir = sysfs_dirs[0]
+
+    if not is_controller(current_node):
+        ksft.test_result(
+            os.path.exists(sysfs_dir), current_node["meta"]["pathname"] + ".device"
+        )
+        check_driver_presence(sysfs_dir, current_node)
+    else:
+        for child_device in current_node["devices"]:
+            fill_meta_keys(child_device, current_node)
+            parse_device_tree_node(child_device, sysfs_dir)
+
+
+def count_tests(device_trees):
+    test_count = 0
+
+    def parse_node(device):
+        nonlocal test_count
+        if device.get("devices"):
+            for child in device["devices"]:
+                parse_node(child)
+        else:
+            if device.get("interfaces"):
+                test_count += len(device["interfaces"])
+            else:
+                test_count += 1
+            test_count += 1
+
+    for device_tree in device_trees:
+        parse_node(device_tree)
+
+    return test_count
+
+
+def get_board_filenames():
+    filenames = []
+
+    platform_compatible_file = "/proc/device-tree/compatible"
+    if os.path.exists(platform_compatible_file):
+        with open(platform_compatible_file) as f:
+            for line in f:
+                filenames.extend(line.split("\0"))
+    else:
+        dmi_id_dir = "/sys/devices/virtual/dmi/id"
+        vendor_dmi_file = os.path.join(dmi_id_dir, "sys_vendor")
+        product_dmi_file = os.path.join(dmi_id_dir, "product_name")
+
+        with open(vendor_dmi_file) as f:
+            vendor = f.read().replace("\n", "")
+        with open(product_dmi_file) as f:
+            product = f.read().replace("\n", "")
+
+        filenames = [vendor + "," + product]
+
+    return filenames
+
+
+def run_test(yaml_file):
+    ksft.print_msg(f"Using board file: {yaml_file}")
+
+    with open(yaml_file) as f:
+        device_trees = yaml.safe_load(f)
+
+    ksft.set_plan(count_tests(device_trees))
+
+    for device_tree in device_trees:
+        parse_device_tree_node(device_tree)
+
+
+find_pci_controller_dirs()
+find_usb_controller_dirs()
+
+ksft.print_header()
+
+board_file = ""
+for board_filename in get_board_filenames():
+    full_board_filename = os.path.join("boards", board_filename + ".yaml")
+
+    if os.path.exists(full_board_filename):
+        board_file = full_board_filename
+        break
+
+if not board_file:
+    ksft.print_msg("No matching board file found")
+    ksft.exit_fail()
+
+run_test(board_file)
+
+ksft.finished()

-- 
2.43.0

[PATCH v4 2/3] kselftest: devices: Add sample board file for google,spherion

[Nícolas F. R. A. Prado]

Add a sample board file describing the file's format and with the list
of devices expected to be probed on the google,spherion machine as an
example.

Test output:

TAP version 13
Using board file: boards/google,spherion.yaml
1..8
ok 1 /usb2-controller@11200000/1.4.1/camera.device
ok 2 /usb2-controller@11200000/1.4.1/camera.0.driver
ok 3 /usb2-controller@11200000/1.4.1/camera.1.driver
ok 4 /usb2-controller@11200000/1.4.2/bluetooth.device
ok 5 /usb2-controller@11200000/1.4.2/bluetooth.0.driver
ok 6 /usb2-controller@11200000/1.4.2/bluetooth.1.driver
ok 7 /pci-controller@11230000/0.0/0.0/wifi.device
ok 8 /pci-controller@11230000/0.0/0.0/wifi.driver
Totals: pass:8 fail:0 xfail:0 xpass:0 skip:0 error:0

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
 .../selftests/devices/boards/google,spherion.yaml  | 50 ++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/tools/testing/selftests/devices/boards/google,spherion.yaml b/tools/testing/selftests/devices/boards/google,spherion.yaml
new file mode 100644
index 000000000000..17157ecd8c14
--- /dev/null
+++ b/tools/testing/selftests/devices/boards/google,spherion.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# This is the device definition for the Google Spherion Chromebook.
+# The filename "google,spherion" comes from the Devicetree compatible, so this
+# file will be automatically used when the test is run on that machine.
+#
+# The top-level is a list of controllers, either for USB or PCI(e).
+# Every controller needs to have a 'type' key set to either 'usb-controller' or
+# 'pci-controller'.
+# Every controller needs to be uniquely identified on the platform. To achieve
+# this, several optional keys can be used:
+# - dt-mmio: identify the MMIO address of the controller as defined in the
+#   Devicetree.
+# - usb-version: for USB controllers to differentiate between USB3 and USB2
+#   buses sharing the same controller.
+# - acpi-uid: _UID property of the controller as supplied by the ACPI. Useful to
+#   distinguish between multiple PCI host controllers.
+#
+# The 'devices' key defines a list of devices that are accessible under that
+# controller. A device might be a leaf device or another controller (see
+# 'Dell Inc.,XPS 13 9300.yaml').
+#
+# The 'path' key is needed for every child device (that is, not top-level) to
+# define how to reach this device from the parent controller. For USB devices it
+# follows the format \d(.\d)* and denotes the port in the hub at each level in
+# the USB topology. For PCI devices it follows the format \d.\d(/\d.\d)*
+# denoting the device (identified by device-function pair) at each level in the
+# PCI topology.
+#
+# The 'name' key is used in the leaf devices to name the device for clarity in
+# the test output.
+#
+# For USB leaf devices, the 'interfaces' key should contain a list of the
+# interfaces in that device that should be bound to a driver.
+#
+- type: usb-controller
+  dt-mmio: 11200000
+  usb-version: 2
+  devices:
+    - path: 1.4.1
+      interfaces: [0, 1]
+      name: camera
+    - path: 1.4.2
+      interfaces: [0, 1]
+      name: bluetooth
+- type: pci-controller
+  dt-mmio: 11230000
+  devices:
+    - path: 0.0/0.0
+      name: wifi

-- 
2.43.0

[PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[Nícolas F. R. A. Prado]

Add a sample board file describing the file's format and with the list
of devices expected to be probed on the XPS 13 9300 machine as an
example x86 platform.

Test output:

TAP version 13
Using board file: boards/Dell Inc.,XPS 13 9300.yaml
1..22
ok 1 /pci-controller/14.0/usb2-controller/9/camera.device
ok 2 /pci-controller/14.0/usb2-controller/9/camera.0.driver
ok 3 /pci-controller/14.0/usb2-controller/9/camera.1.driver
ok 4 /pci-controller/14.0/usb2-controller/9/camera.2.driver
ok 5 /pci-controller/14.0/usb2-controller/9/camera.3.driver
ok 6 /pci-controller/14.0/usb2-controller/10/bluetooth.device
ok 7 /pci-controller/14.0/usb2-controller/10/bluetooth.0.driver
ok 8 /pci-controller/14.0/usb2-controller/10/bluetooth.1.driver
ok 9 /pci-controller/2.0/gpu.device
ok 10 /pci-controller/2.0/gpu.driver
ok 11 /pci-controller/4.0/thermal.device
ok 12 /pci-controller/4.0/thermal.driver
ok 13 /pci-controller/12.0/sensors.device
ok 14 /pci-controller/12.0/sensors.driver
ok 15 /pci-controller/14.3/wifi.device
ok 16 /pci-controller/14.3/wifi.driver
ok 17 /pci-controller/1d.0/0.0/ssd.device
ok 18 /pci-controller/1d.0/0.0/ssd.driver
ok 19 /pci-controller/1d.7/0.0/sdcard-reader.device
ok 20 /pci-controller/1d.7/0.0/sdcard-reader.driver
ok 21 /pci-controller/1f.3/audio.device
ok 22 /pci-controller/1f.3/audio.driver
Totals: pass:22 fail:0 xfail:0 xpass:0 skip:0 error:0

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
 .../devices/boards/Dell Inc.,XPS 13 9300.yaml      | 40 ++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml
new file mode 100644
index 000000000000..ff932eb19f0b
--- /dev/null
+++ b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml	
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# This is the device definition for the XPS 13 9300.
+# The filename "Dell Inc.,XPS 13 9300" was chosen following the format
+# "Vendor,Product", where Vendor comes from
+# /sys/devices/virtual/dmi/id/sys_vendor, and Product comes from
+# /sys/devices/virtual/dmi/id/product_name.
+#
+# See google,spherion.yaml for more information.
+#
+- type: pci-controller
+  # This machine has a single PCI host controller so it's valid to not have any
+  # key to identify the controller. If it had more than one controller, the UID
+  # of the controller from ACPI could be used to distinguish as follows:
+  #acpi-uid: 0
+  devices:
+    - path: 14.0
+      type: usb-controller
+      usb-version: 2
+      devices:
+        - path: 9
+          name: camera
+          interfaces: [0, 1, 2, 3]
+        - path: 10
+          name: bluetooth
+          interfaces: [0, 1]
+    - path: 2.0
+      name: gpu
+    - path: 4.0
+      name: thermal
+    - path: 12.0
+      name: sensors
+    - path: 14.3
+      name: wifi
+    - path: 1d.0/0.0
+      name: ssd
+    - path: 1d.7/0.0
+      name: sdcard-reader
+    - path: 1f.3
+      name: audio

-- 
2.43.0

Re: [PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[AngeloGioacchino Del Regno]

Il 22/01/24 19:53, Nícolas F. R. A. Prado ha scritto:
> Add a sample board file describing the file's format and with the list
> of devices expected to be probed on the XPS 13 9300 machine as an
> example x86 platform.
> 
> Test output:
> 
> TAP version 13
> Using board file: boards/Dell Inc.,XPS 13 9300.yaml
> 1..22
> ok 1 /pci-controller/14.0/usb2-controller/9/camera.device
> ok 2 /pci-controller/14.0/usb2-controller/9/camera.0.driver
> ok 3 /pci-controller/14.0/usb2-controller/9/camera.1.driver
> ok 4 /pci-controller/14.0/usb2-controller/9/camera.2.driver
> ok 5 /pci-controller/14.0/usb2-controller/9/camera.3.driver
> ok 6 /pci-controller/14.0/usb2-controller/10/bluetooth.device
> ok 7 /pci-controller/14.0/usb2-controller/10/bluetooth.0.driver
> ok 8 /pci-controller/14.0/usb2-controller/10/bluetooth.1.driver
> ok 9 /pci-controller/2.0/gpu.device
> ok 10 /pci-controller/2.0/gpu.driver
> ok 11 /pci-controller/4.0/thermal.device
> ok 12 /pci-controller/4.0/thermal.driver
> ok 13 /pci-controller/12.0/sensors.device
> ok 14 /pci-controller/12.0/sensors.driver
> ok 15 /pci-controller/14.3/wifi.device
> ok 16 /pci-controller/14.3/wifi.driver
> ok 17 /pci-controller/1d.0/0.0/ssd.device
> ok 18 /pci-controller/1d.0/0.0/ssd.driver
> ok 19 /pci-controller/1d.7/0.0/sdcard-reader.device
> ok 20 /pci-controller/1d.7/0.0/sdcard-reader.driver
> ok 21 /pci-controller/1f.3/audio.device
> ok 22 /pci-controller/1f.3/audio.driver
> Totals: pass:22 fail:0 xfail:0 xpass:0 skip:0 error:0
> 
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> ---
>   .../devices/boards/Dell Inc.,XPS 13 9300.yaml      | 40 ++++++++++++++++++++++
>   1 file changed, 40 insertions(+)
> 
> diff --git a/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml
> new file mode 100644
> index 000000000000..ff932eb19f0b
> --- /dev/null
> +++ b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml	
> @@ -0,0 +1,40 @@
> +# SPDX-License-Identifier: GPL-2.0
> +#
> +# This is the device definition for the XPS 13 9300.
> +# The filename "Dell Inc.,XPS 13 9300" was chosen following the format
> +# "Vendor,Product", where Vendor comes from
> +# /sys/devices/virtual/dmi/id/sys_vendor, and Product comes from
> +# /sys/devices/virtual/dmi/id/product_name.
> +#
> +# See google,spherion.yaml for more information.

What if - instead of taking google,spherion.yaml as an example - you create a new
file named something like

"example,device.yaml"

that would be a fantasy device, bringing examples for all .. or most of .. the
currently supported types/devices?

You would also move the nice documentation that you wrote in spherion.yaml to the
new example,device.yaml and ask to refer to that instead in all of the real device
specific definitions.

# SPDX-License-Identifier: GPL-2.0 <--- (GPL-2.0 OR MIT) like device trees perhaps?
#
# This is the device definition for the Example Device
# The filename "Example Device" was chosen following the format
# "Vendor,Product", where:
#  - Vendor is "Example" and comes from /sys/devices/virtual/dmi/id/sys_vendor
#  - Product is "Device" and comes from /sys/devices/virtual/dmi/id/product_name
#
# ....the rest of the blurb goes here
#

- type : .... this that the other
   devices:
     - the least amount of device descriptions that you can use for documenting how
       to write this stuff :-)

Anything against that?

Cheers,
Angelo

> +#
> +- type: pci-controller
> +  # This machine has a single PCI host controller so it's valid to not have any
> +  # key to identify the controller. If it had more than one controller, the UID
> +  # of the controller from ACPI could be used to distinguish as follows:
> +  #acpi-uid: 0
> +  devices:
> +    - path: 14.0
> +      type: usb-controller
> +      usb-version: 2
> +      devices:
> +        - path: 9
> +          name: camera
> +          interfaces: [0, 1, 2, 3]
> +        - path: 10
> +          name: bluetooth
> +          interfaces: [0, 1]
> +    - path: 2.0
> +      name: gpu
> +    - path: 4.0
> +      name: thermal
> +    - path: 12.0
> +      name: sensors
> +    - path: 14.3
> +      name: wifi
> +    - path: 1d.0/0.0
> +      name: ssd
> +    - path: 1d.7/0.0
> +      name: sdcard-reader
> +    - path: 1f.3
> +      name: audio
> 

Re: [PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[Nícolas F. R. A. Prado]

On Tue, Jan 23, 2024 at 12:08:22PM +0100, AngeloGioacchino Del Regno wrote:
> Il 22/01/24 19:53, Nícolas F. R. A. Prado ha scritto:
> > Add a sample board file describing the file's format and with the list
> > of devices expected to be probed on the XPS 13 9300 machine as an
> > example x86 platform.
> > 
> > Test output:
> > 
> > TAP version 13
> > Using board file: boards/Dell Inc.,XPS 13 9300.yaml
> > 1..22
> > ok 1 /pci-controller/14.0/usb2-controller/9/camera.device
> > ok 2 /pci-controller/14.0/usb2-controller/9/camera.0.driver
> > ok 3 /pci-controller/14.0/usb2-controller/9/camera.1.driver
> > ok 4 /pci-controller/14.0/usb2-controller/9/camera.2.driver
> > ok 5 /pci-controller/14.0/usb2-controller/9/camera.3.driver
> > ok 6 /pci-controller/14.0/usb2-controller/10/bluetooth.device
> > ok 7 /pci-controller/14.0/usb2-controller/10/bluetooth.0.driver
> > ok 8 /pci-controller/14.0/usb2-controller/10/bluetooth.1.driver
> > ok 9 /pci-controller/2.0/gpu.device
> > ok 10 /pci-controller/2.0/gpu.driver
> > ok 11 /pci-controller/4.0/thermal.device
> > ok 12 /pci-controller/4.0/thermal.driver
> > ok 13 /pci-controller/12.0/sensors.device
> > ok 14 /pci-controller/12.0/sensors.driver
> > ok 15 /pci-controller/14.3/wifi.device
> > ok 16 /pci-controller/14.3/wifi.driver
> > ok 17 /pci-controller/1d.0/0.0/ssd.device
> > ok 18 /pci-controller/1d.0/0.0/ssd.driver
> > ok 19 /pci-controller/1d.7/0.0/sdcard-reader.device
> > ok 20 /pci-controller/1d.7/0.0/sdcard-reader.driver
> > ok 21 /pci-controller/1f.3/audio.device
> > ok 22 /pci-controller/1f.3/audio.driver
> > Totals: pass:22 fail:0 xfail:0 xpass:0 skip:0 error:0
> > 
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> > ---
> >   .../devices/boards/Dell Inc.,XPS 13 9300.yaml      | 40 ++++++++++++++++++++++
> >   1 file changed, 40 insertions(+)
> > 
> > diff --git a/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml
> > new file mode 100644
> > index 000000000000..ff932eb19f0b
> > --- /dev/null
> > +++ b/tools/testing/selftests/devices/boards/Dell Inc.,XPS 13 9300.yaml	
> > @@ -0,0 +1,40 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +#
> > +# This is the device definition for the XPS 13 9300.
> > +# The filename "Dell Inc.,XPS 13 9300" was chosen following the format
> > +# "Vendor,Product", where Vendor comes from
> > +# /sys/devices/virtual/dmi/id/sys_vendor, and Product comes from
> > +# /sys/devices/virtual/dmi/id/product_name.
> > +#
> > +# See google,spherion.yaml for more information.
> 
> What if - instead of taking google,spherion.yaml as an example - you create a new
> file named something like
> 
> "example,device.yaml"
> 
> that would be a fantasy device, bringing examples for all .. or most of .. the
> currently supported types/devices?
> 
> You would also move the nice documentation that you wrote in spherion.yaml to the
> new example,device.yaml and ask to refer to that instead in all of the real device
> specific definitions.
> 
> # SPDX-License-Identifier: GPL-2.0 <--- (GPL-2.0 OR MIT) like device trees perhaps?
> #
> # This is the device definition for the Example Device
> # The filename "Example Device" was chosen following the format
> # "Vendor,Product", where:
> #  - Vendor is "Example" and comes from /sys/devices/virtual/dmi/id/sys_vendor
> #  - Product is "Device" and comes from /sys/devices/virtual/dmi/id/product_name
> #
> # ....the rest of the blurb goes here
> #
> 
> - type : .... this that the other
>   devices:
>     - the least amount of device descriptions that you can use for documenting how
>       to write this stuff :-)
> 
> Anything against that?

That'd also work. Though I feel like a single example file for both a DT-based
and an ACPI-based platform might get unnecessarily confusing (given the
different way for identifying the machine - DMI vs DT compatible - and for
identifying the root level controller - ACPI UID vs DT MMIO).

I also feel like a real machine example is helpful to have.

In my opinion, your suggestion would make much more sense - and be needed even -
if we had several machine files in this directory, so that the documentation
stands out among them. However the feedback that I got from Shuah during
Plumbers was that maintaining per-machine files in-tree wasn't going to happen.
So these two files serve as the documentation, with real-life examples, that
other machines could build upon in a separate repository.

Thanks,
Nícolas

Re: [PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[Askar Safin]

"Nícolas F. R. A. Prado" <nfraprado@collabora.com>:
> Add a sample board file describing the file's format and with the list
> of devices expected to be probed on the XPS 13 9300 machine as an
> example x86 platform.

And now "Dell Inc.,XPS 13 9300.yaml" became the only file in the repository,
which has space in its name:

$ find . -name '* *'
./tools/testing/selftests/devices/probe/boards/Dell Inc.,XPS 13 9300.yaml

I kindly ask you to rename file. New name should not contain space or comma
in it.

The file name in its current form breaks tools. For example, it breaks
"xargs".

For example, the following will work in "fs" directory:

stable/fs$ find . | xargs chmod -w

But it will not work in root of source tree because of this
"Dell Inc.,XPS 13 9300.yaml" file:

stable$ find . | xargs chmod -w
chmod: cannot access './tools/testing/selftests/devices/probe/boards/Dell': No such file or directory
chmod: cannot access 'Inc.,XPS': No such file or directory
chmod: cannot access '13': No such file or directory
chmod: cannot access '9300.yaml': No such file or directory

-- 
Askar Safin

Re: [PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[Nícolas F. R. A. Prado]

On Sun, 2025-12-28 at 08:47 +0300, Askar Safin wrote:
> "Nícolas F. R. A. Prado" <nfraprado@collabora.com>:
> > Add a sample board file describing the file's format and with the
> > list
> > of devices expected to be probed on the XPS 13 9300 machine as an
> > example x86 platform.
> 
> And now "Dell Inc.,XPS 13 9300.yaml" became the only file in the
> repository,
> which has space in its name:
> 
> $ find . -name '* *'
> ./tools/testing/selftests/devices/probe/boards/Dell Inc.,XPS 13
> 9300.yaml
> 
> I kindly ask you to rename file. New name should not contain space or
> comma
> in it.

While I understand it might be inconvenient that this is the only file
with a space in its name, that is exactly the string that is reported
by DMI, so it is natural that it would be used for the filename.

Besides, I'm not aware of there being a style guide rule that prohibits
space in filenames in the kernel tree, or that could have easily be
detected by checkpatch during submission.

Furthermore, not containing a comma is not even feasible, there are
tons of dt-binding filenames containing commas in the tree.

> 
> The file name in its current form breaks tools. For example, it
> breaks
> "xargs".
> 
> For example, the following will work in "fs" directory:
> 
> stable/fs$ find . | xargs chmod -w
> 
> But it will not work in root of source tree because of this
> "Dell Inc.,XPS 13 9300.yaml" file:
> 
> stable$ find . | xargs chmod -w
> chmod: cannot access
> './tools/testing/selftests/devices/probe/boards/Dell': No such file
> or directory
> chmod: cannot access 'Inc.,XPS': No such file or directory
> chmod: cannot access '13': No such file or directory
> chmod: cannot access '9300.yaml': No such file or directory

You can use 'find -print0' and 'xargs -0' instead so the space in the
filename is not an issue.

-- 
Thanks,

Nícolas

Re: [PATCH v4 1/3] kselftest: Add test to verify probe of devices from discoverable buses

[Thomas Weißschuh]

On Mon, Jan 22, 2024 at 03:53:21PM -0300, Nícolas F. R. A. Prado wrote:
> Add a new test to verify that a list of expected devices from
> discoverable buses (ie USB, PCI) have been successfully instantiated and
> probed by a driver.
> 
> The per-platform list of expected devices is selected from the ones
> under the boards/ directory based on the DT compatible or the DMI IDs.
> 
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> ---
>  tools/testing/selftests/Makefile                   |   1 +
>  tools/testing/selftests/devices/Makefile           |   4 +

>  tools/testing/selftests/devices/ksft.py            |  90 ++++++

This seems to be a copy of tools/testing/selftests/kselftest/ksft.py.
Instead of copying the file, try to use it from the standard location.

>  .../selftests/devices/test_discoverable_devices.py | 318 +++++++++++++++++++++
>  4 files changed, 413 insertions(+)

(...)

Re: [PATCH v4 1/3] kselftest: Add test to verify probe of devices from discoverable buses

[Nícolas F. R. A. Prado]

On Mon, 2025-12-29 at 14:57 +0100, Thomas Weißschuh wrote:
> On Mon, Jan 22, 2024 at 03:53:21PM -0300, Nícolas F. R. A. Prado
> wrote:
> > Add a new test to verify that a list of expected devices from
> > discoverable buses (ie USB, PCI) have been successfully
> > instantiated and
> > probed by a driver.
> > 
> > The per-platform list of expected devices is selected from the ones
> > under the boards/ directory based on the DT compatible or the DMI
> > IDs.
> > 
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> > ---
> >  tools/testing/selftests/Makefile                   |   1 +
> >  tools/testing/selftests/devices/Makefile           |   4 +
> 
> >  tools/testing/selftests/devices/ksft.py            |  90 ++++++
> 
> This seems to be a copy of tools/testing/selftests/kselftest/ksft.py.
> Instead of copying the file, try to use it from the standard
> location.

This series is almost 1 year old and has long ago been merged :)

-- 
Thanks,

Nícolas

Re: [PATCH v4 3/3] kselftest: devices: Add sample board file for XPS 13 9300

[Askar Safin]

"Nícolas F. R. A. Prado" <nfraprado@collabora.com>:
> While I understand it might be inconvenient that this is the only file

As well as I understand, it is intended that more files will be added
to tools/testing/selftests/devices/boards with various vendor names and
product names.

So I did some further research. I grepped Linux source and found some
vendor names and product names with undesirable chars.

Let's go.

/rbt/linux/arch/x86/kernel/apm_32.c:2097:                       DMI_MATCH(DMI_PRODUCT_NAME, "PC-PJ/AX"),
/rbt/linux/arch/x86/kernel/reboot.c:396:                        DMI_MATCH(DMI_PRODUCT_NAME, "PowerEdge 300/"),
/rbt/linux/drivers/platform/x86/samsung-laptop.c:1633:          DMI_MATCH(DMI_PRODUCT_NAME, "R40/R41"),

Here we see / chars, which are simply forbidden in Linux filesystems.

I also found a lot of others undesirable chars, such as "(" ")" "'" "&" "#" "*",
which surely will break a lot of tools. In particular, "'" is used in bash
to quote something verbatim.

Here is extended result of my research:
https://zerobin.net/?d1f2655a979acd3f#oBhwIedQvBL/iB9Src65aRYuyjaye2GQBNL3+6yfvGg=

Unfortunately, I'm not sure which of these names refer to whole "board",
and which of them refer to merely some particular device, such as USB device.

BUT for 3 instances of / chars given in the top of this email I'm totally
sure that they refer to whole "boards", so we have at least 3 totally
legitime cases, where we have / in product name, which simply cannot appear
in UNIX filesystem at all.

So, conclusion: if it is indeed intended that further examples of boards
will be added to tools/testing/selftests/devices/boards, then they
will contain all sorts of undesirable chars and notably "/", which cannot
appear in filename at all.

For all these reasons I ask you to change name convention for this directory.
For example, use some kind of sanitized vendor/product names.

> there are
> tons of dt-binding filenames containing commas in the tree.

Okay, I agree with this point. There already are a lot of files with commas.
But I still don't like spaces and all sorts of characters, which are present
in DMI vendor names and product names ( "(" ")" "'" "&" "#" "*" "/" ).

-- 
Askar Safin