How to instantiate SPI devices

SPI devices are normally declared statically via device-tree, ACPI, or board files. When the SPI controller is registered, these devices are instantiated automatically by the SPI core. This is the preferred method for any device with a proper kernel driver.

Instantiate from user-space

In certain cases a SPI device cannot be declared statically:

  • The spidev driver, which provides raw userspace access to SPI buses, explicitly rejects the bare "spidev" compatible string in device-tree because spidev is a Linux implementation detail, not a hardware description. Vendor-specific compatible strings for spidev (e.g. "vendor,board-spidev") are also generally not accepted upstream. Device-tree overlays do not help here either, since the spidev driver performs the same compatible check regardless of how the DT node was loaded.

  • You are developing or testing a SPI device on a development board where the SPI bus is exposed on expansion headers, and the connected device may change frequently.

For these cases, a sysfs interface is provided on each SPI host controller (similar to the I2C new_device/delete_device interface described in How to instantiate I2C devices). Two write-only attribute files are created in every SPI host controller directory: new_device and delete_device.

File new_device takes 2 to 4 parameters: the name of the SPI device (a string), the chip select number, and optionally max_speed_hz and mode:

<modalias> <chip_select> [<max_speed_hz> [<mode>]]

The modalias is set both as the device’s modalias field and as its driver_override. This ensures that the device binds to the named driver directly, bypassing the normal bus matching logic (OF, ACPI, and id_table). This is necessary because drivers like spidev deliberately exclude generic names from their id_table.

If max_speed_hz is omitted or 0, spi_setup() clamps it to the controller’s maximum speed. If mode is omitted, SPI mode 0 (CPOL=0, CPHA=0) is used.

File delete_device takes a single parameter: the chip select number. As no two devices can share a chip select on a given SPI bus, the chip select is sufficient to uniquely identify the device.

Examples:

# Create a spidev device on SPI bus 0, chip select 0
echo spidev 0 > /sys/class/spi_master/spi0/new_device

# Create with explicit clock rate and SPI mode
echo spidev 0 10000000 3 > /sys/class/spi_master/spi0/new_device

# Remove the device
echo 0 > /sys/class/spi_master/spi0/delete_device

The attributes are added after the host controller and its firmware-described devices have been registered. Their addition emits a change uevent, allowing a udev rule to write to new_device when the interface is ready.

Limitations

Devices created through this interface have the following limitations compared to devices declared via device-tree:

  • No interrupt (IRQ) support.

  • No additional properties such as spi-max-frequency DT bindings or controller-specific configuration.

  • No platform data or software nodes.

For spidev usage these limitations are not relevant, since spidev provides a raw byte-level interface that does not require any of these features.

Only devices created via new_device can be removed through delete_device. Devices declared via device-tree, ACPI, or board files are not affected by this interface.