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

[Javier Martinez Canillas]

Hello Ralph,

On 11/19/21 17:03, Ralph Siemsen wrote:
> 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 

Instead of adding the messages here, I think what we should do is to point
to https://www.kernel.org/doc/Documentation/spi/spidev.rst in the spidev
driver messages.

That way we could save people a search in the interwebs. That would be a
separate patch for the spidev driver of course.

> 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
> =============================================
>

Agree with including this section. But we could do it as a follow-up.
 
Best regards,
-- 
Javier Martinez Canillas
Linux Engineering
Red Hat