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

[Ralph Siemsen]

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:
https://community.nxp.com/t5/i-MX-Processors/spidev-spidev-listed-directly-in-DT/m-p/426381/highlight/true#M64609
https://yurovsky.github.io/2016/10/07/spidev-linux-devices.html

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
Documentation/devicetree/bindings/spi/spi-controller.yaml

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

Regards,
Ralph