Re: [PATCH] spi: docs: improve the SPI userspace API documentation

From: Ralph Siemsen
Date: Fri Nov 19 2021 - 11:03:30 EST

Hi Javier,

On Thu, Nov 18, 2021 at 10:31:43PM +0100, Javier Martinez Canillas wrote:
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

spi@0 {
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