1.. SPDX-License-Identifier: GPL-2.0 2 3============================== 4How to instantiate SPI devices 5============================== 6 7SPI devices are normally declared statically via device-tree, ACPI, or 8board files. When the SPI controller is registered, these devices are 9instantiated automatically by the SPI core. This is the preferred method 10for any device with a proper kernel driver. 11 12Instantiate from user-space 13--------------------------- 14 15In certain cases a SPI device cannot be declared statically: 16 17* The ``spidev`` driver, which provides raw userspace access to SPI 18 buses, explicitly rejects the bare ``"spidev"`` compatible string in 19 device-tree because spidev is a Linux implementation detail, not a 20 hardware description. Vendor-specific compatible strings for spidev 21 (e.g. ``"vendor,board-spidev"``) are also generally not accepted 22 upstream. Device-tree overlays do not help here either, since the 23 spidev driver performs the same compatible check regardless of how 24 the DT node was loaded. 25 26* You are developing or testing a SPI device on a development board 27 where the SPI bus is exposed on expansion headers, and the connected 28 device may change frequently. 29 30For these cases, a sysfs interface is provided on each SPI host controller 31(similar to the I2C ``new_device``/``delete_device`` interface described 32in Documentation/i2c/instantiating-devices.rst). Two write-only 33attribute files are created in every SPI host controller directory: 34``new_device`` and ``delete_device``. 35 36File ``new_device`` takes 2 to 4 parameters: the name of the SPI 37device (a string), the chip select number, and optionally 38``max_speed_hz`` and ``mode``:: 39 40 <modalias> <chip_select> [<max_speed_hz> [<mode>]] 41 42The modalias is set both as the device's ``modalias`` field and as its 43``driver_override``. This ensures that the device binds to the named 44driver directly, bypassing the normal bus matching logic (OF, ACPI, 45and ``id_table``). This is necessary because drivers like ``spidev`` 46deliberately exclude generic names from their ``id_table``. 47 48If ``max_speed_hz`` is omitted or 0, ``spi_setup()`` clamps it to 49the controller's maximum speed. If ``mode`` is omitted, SPI mode 0 50(CPOL=0, CPHA=0) is used. 51 52File ``delete_device`` takes a single parameter: the chip select 53number. As no two devices can share a chip select on a given SPI bus, 54the chip select is sufficient to uniquely identify the device. 55 56Examples:: 57 58 # Create a spidev device on SPI bus 0, chip select 0 59 echo spidev 0 > /sys/class/spi_master/spi0/new_device 60 61 # Create with explicit clock rate and SPI mode 62 echo spidev 0 10000000 3 > /sys/class/spi_master/spi0/new_device 63 64 # Remove the device 65 echo 0 > /sys/class/spi_master/spi0/delete_device 66 67The attributes are added after the host controller and its firmware-described 68devices have been registered. Their addition emits a ``change`` uevent, 69allowing a udev rule to write to ``new_device`` when the interface is ready. 70 71Limitations 72^^^^^^^^^^^ 73 74Devices created through this interface have the following limitations 75compared to devices declared via device-tree: 76 77* No interrupt (IRQ) support. 78* No additional properties such as ``spi-max-frequency`` DT bindings 79 or controller-specific configuration. 80* No platform data or software nodes. 81 82For ``spidev`` usage these limitations are not relevant, since spidev 83provides a raw byte-level interface that does not require any of these 84features. 85 86Only devices created via ``new_device`` can be removed through 87``delete_device``. Devices declared via device-tree, ACPI, or board 88files are not affected by this interface. 89