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

From: Javier Martinez Canillas
Date: Fri Nov 19 2021 - 13:01:19 EST

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