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/[email protected]/
Changes in v4:
- Dropped RFC tag
- Fixed 'busses' misspelling
- Link to v3: https://lore.kernel.org/all/[email protected]
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/[email protected]
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/[email protected]
---
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 <[email protected]>
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 <[email protected]>
---
.../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
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 <[email protected]>
---
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
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 <[email protected]>
> ---
> .../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
>
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 <[email protected]>
> > ---
> > .../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