Re: [PATCH] spi: docs: improve the SPI userspace API documentation
From: Ralph Siemsen
Date: Fri Nov 19 2021 - 11:03:30 EST
On Thu, Nov 18, 2021 at 10:31:43PM +0100, Javier Martinez Canillas
This doc is fairly outdated and only uses legacy device instantiation
terminology. Let us update it and also mention the OF and ACPI device
tables, to make easier for users to figure out how should be defined.
Thanks for putting this together! Overall it is a definite improvement.
+NOTE: it used to be supported to define an SPI device using the "spidev"
+ name. For example as .modalias = "spidev" or compatible = "spidev".
+ But this is no longer supported by the Linux kernel and instead a
+ real SPI device name as listed in one of the tables should be used.
This note is factually correct, but it might be a little too terse for
folks who are not full-time kernel developers. I'd suggest making it a
bit more prescriptive. As well, the focus can probably be on the case of
device tree, since that is the one that generates the warning (and with
your patch, causes the driver to fail to load).
I've struggled to put it into the right words, so the following is just
an idea. I've intentionally included the exact wording of the warn/err
to improve google-ability. As well, it is interesting to do a google
search for the message, and see what kinds of advice is offered. A few
that came up for me include:
Anyhow, here is a possible addition to the NOTE in your patch.
spidev listed directly in DT is not supported
Spidev devices are typically declared in the device tree, see
compatible = "vendor,device";
reg = <0>;
spi-max-frequency = <10000000>;
In the past, it was common to use compatible = "spidev" rather than
a more descriptive and device-specific name. For some time this has
been deprecated, and as of kernel version X.Y it is no longer allowed.
The preferred way to fix this is to use a device-specific name. This
means picking a name, usually in the format "vendor,device". This name
must then be specified in:
- the device tree for your board (instead of compatible = "spidev")
- the spidev_dt_ids table in drivers/spi/spidev.c