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@xxxxxxxxxxxxx>
> > ---
> >   .../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