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

[Uwe Kleine-König]

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.
> 
> Also, mention that devices bind could be done in user-space now using
> the "driver_override" sysfs entry.
> 
> Suggested-by: Ralph Siemsen <ralph.siemsen@xxxxxxxxxx>
> Signed-off-by: Javier Martinez Canillas <javierm@xxxxxxxxxx>
> ---
> 
>  Documentation/spi/spidev.rst | 34 +++++++++++++++++++++++++++++-----
>  1 file changed, 29 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst
> index f05dbc5ccdbc..ec0986ae6170 100644
> --- a/Documentation/spi/spidev.rst
> +++ b/Documentation/spi/spidev.rst
> @@ -29,15 +29,39 @@ of the driver stack) that are not accessible to userspace.
>  
>  DEVICE CREATION, DRIVER BINDING
>  ===============================
> -The simplest way to arrange to use this driver is to just list it in the
> -spi_board_info for a device as the driver it should use:  the "modalias"
> -entry is "spidev", matching the name of the driver exposing this API.
> +
> +The spidev driver contains lists of SPI devices that are supported for
> +the different hardware topology representations.
> +
> +The following are the SPI device tables supported by the spidev driver:
> +
> +    - struct spi_device_id spidev_spi_ids[]: list of devices that can be
> +      bound when these are defined using a struct spi_board_info with a
> +      .modalias field matching one of the entries in the table.
> +
> +    - struct of_device_id spidev_dt_ids[]: list of devices that can be
> +      bound when these are defined using a Device Tree node that has a
> +      compatible string matching one of the entries in the table.
> +
> +    - struct acpi_device_id spidev_acpi_ids[]: list of devices that can
> +      be bound when these are defined using a ACPI device object with a
> +      _HID matching one of the entries in the table.
> +
> +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.
> +
>  Set up the other device characteristics (bits per word, SPI clocking,
>  chipselect polarity, etc) as usual, so you won't always need to override
>  them later.
>  
> -(Sysfs also supports userspace driven binding/unbinding of drivers to
> -devices.  That mechanism might be supported here in the future.)
> +Sysfs also supports userspace driven binding/unbinding of drivers to
> +devices.  The mechanism works by writing to the device "driver_overrride"
> +entry.  For example:

I'd write here:

	Sysfs also supports userspace driven binding/unbinding of
	drivers to devices that don't bind automatically using one of
	the tables above. To make the spidev driver bind to such a
	device, use:

> +
> +    echo spidev > /sys/bus/spi/devices/spiX.Y/driver_override
> +    echo spiB.C > /sys/bus/spi/drivers/spidev/bind
>  
>  When you do that, the sysfs node for the SPI device will include a child
>  device node with a "dev" attribute that will be understood by udev or mdev.

What is "that" here? (Maybe this refers to "Set up the other device
characteristics [...] as usual"? Is the effect still accurate?

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | https://www.pengutronix.de/ |

Attachment: signature.asc
Description: PGP signature