spi: add new_device/delete_device sysfs interface
Subsystems (2)
v4 cover spi: add new_device/delete_device sysfs interface
Add I2C-style new_device/delete_device sysfs attributes to SPI host controllers, allowing userspace to instantiate and remove SPI devices at runtime without device-tree changes.
Changes since v3:
- Replaced holding add_lock across __spi_add_device() + list insertion (which caused an ABBA deadlock between add_lock and the kernfs active reference during concurrent unbind) with:
* A 'dead' flag on spi_controller, set in spi_unregister_controller() under both add_lock and userspace_clients_lock.
* __spi_add_device() checks ctlr->dead under add_lock to reject new devices after teardown begins.
* new_device_store() checks ctlr->dead under userspace_clients_lock before list insertion, falling back to cleanup + ENODEV.
* add_lock is released before device_del() so in-flight sysfs stores can drain without deadlocking.
* get_device() taken before spi_add_device() prevents use-after-free if __unregister runs concurrently.
- Used #if IS_ENABLED() preprocessor guard (not runtime IS_ENABLED()) for the ctlr->dead check in __spi_add_device(), since the dead field is conditionally compiled.
Changes since v2:
- Gated sysfs attributes and locking on CONFIG_SPI_DYNAMIC.
Changes since v1:
- Added locking to prevent races between new_device_store() and concurrent spi_unregister_controller().
Vishwaroop A (2):
spi: add new_device/delete_device sysfs interface
docs: spi: add documentation for userspace device instantiation
.../ABI/testing/sysfs-class-spi-master | 34 +++ Documentation/spi/index.rst | 1 + Documentation/spi/instantiating-devices.rst | 88 +++++++ drivers/spi/spi.c | 216 +++++++++++++++++- include/linux/spi/spi.h | 13 + 5 files changed, 346 insertions(+), 6 deletions(-) create mode 100644 Documentation/ABI/testing/sysfs-class-spi-master create mode 100644 Documentation/spi/instantiating-devices.rst
Signature · 1 line
2.17.1
PATCH v4 1/2 spi: add new_device/delete_device sysfs interface
Development boards such as the Jetson AGX Orin expose SPI buses on expansion headers (e.g. the 40-pin header) so that users can connect and interact with SPI peripherals from userspace. The standard way to get /dev/spidevB.C character device nodes for this purpose is to register spi_device instances backed by the spidev driver.
Today there is no viable way to do this on upstream kernels:
- The spidev driver rejects the bare "spidev" compatible string in DT, since spidev is a Linux software interface and not a description of real hardware.
- Vendor-specific compatible strings (e.g. "nvidia,tegra-spidev") have been rejected by DT maintainers for the same reason.
The I2C subsystem solved an analogous problem by exposing new_device/delete_device sysfs attributes on each adapter. Add the same interface to SPI host controllers, so that userspace (e.g. a systemd unit at boot) can instantiate SPI devices at runtime without needing anything in device-tree.
The new_device file accepts:
<modalias> <chip_select> [<max_speed_hz> [<mode>]]
where chip_select is required, while max_speed_hz and mode are optional and default to 0 if omitted. max_speed_hz == 0 is clamped to the controller's maximum by spi_setup(); mode == 0 selects SPI mode 0 (CPOL=0, CPHA=0).
The modalias is used both as the device identifier and as a driver_override, so that the device binds to the named driver directly. This is necessary because some drivers like spidev deliberately exclude generic names from their id_table.
Devices created this way are limited compared to those declared via DT or board files:
- No IRQ is assigned (the device gets IRQ 0 / no interrupt).
- No platform_data or device properties are attached.
- No OF node is associated with the device.
These limitations are acceptable for spidev, which only needs a registered spi_device to expose a character device to userspace.
Only devices created via new_device can be removed through delete_device; DT and platform devices are unaffected.
The sysfs attributes are gated behind CONFIG_SPI_DYNAMIC since this feature adds a new way of dynamically instantiating and removing SPI devices, and the add_lock locking in spi_unregister_controller() is already conditional on CONFIG_SPI_DYNAMIC.
A 'dead' flag on spi_controller prevents new device registration and list insertion after spi_unregister_controller() begins tearing down the controller. This avoids:
1. An ABBA deadlock between add_lock and the kernfs active reference held by sysfs store callbacks. add_lock is released before device_del() so that in-flight sysfs operations can drain.
2. Orphaned devices that could slip through after the userspace_clients cleanup but before device_del().
3. Use-after-free if __unregister frees a device that new_device_store() still references. An extra get_device() before spi_add_device() holds the device alive.
--- drivers/spi/spi.c | 216 ++++++++++++++++++++++++++++++++++++++-- include/linux/spi/spi.h | 13 +++ 2 files changed, 223 insertions(+), 6 deletions(-)
drivers/spi/spi.c +210 -6
@@ -296,11 +296,187 @@ static const struct attribute_group spi_controller_statistics_group = { .attrs = spi_controller_statistics_attrs, }; +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) + +/* +* new_device_store - instantiate a new SPI device from userspace +* +* Takes parameters: <modalias> <chip_select> [<max_speed_hz> [<mode>]] +* +* Examples: +* echo spidev 0 > new_device +* echo spidev 0 10000000 > new_device +* echo spidev 0 10000000 3 > new_device +*/ +static ssize_t +new_device_store (struct device *dev,struct device_attribute *attr, +const char *buf,size_t count) +{ + struct spi_controller *ctlr = container_of(dev, struct spi_controller, + dev); +struct spi_device *spi; +char modalias[SPI_NAME_SIZE ]; +u16 chip_select; +u32 max_speed_hz =0 ; +u32 mode =0 ; +char *blank; +int n, res, status; + + blank =strchr (buf,' ' ); +if (!blank) { +dev_err (dev,"%s: Missing parameters\n" ,"new_device" ); +return -EINVAL ; + } + +if (blank - buf >SPI_NAME_SIZE -1 ) { +dev_err (dev,"%s: Invalid device name\n" ,"new_device" ); +return -EINVAL ; + } + +memset (modalias,0 ,sizeof (modalias)); +memcpy (modalias, buf, blank - buf); + +/* +* sscanf fills only the fields it matches; unmatched optional +* fields (max_speed_hz, mode) stay zero from initialisation above. +* max_speed_hz == 0 is clamped to the controller max by spi_setup(). +* mode == 0 selects SPI mode 0 (CPOL=0, CPHA=0). +*/ + res =sscanf (++blank,"%hu %u %u%n" , + &chip_select, &max_speed_hz, &mode, &n); +if (res <1 ) { +dev_err (dev,"%s: Can't parse chip select\n" ,"new_device" ); +return -EINVAL ; + } + +if (chip_select >= ctlr->num_chipselect) { +dev_err (dev,"%s: Chip select %u >= max %u\n" ,"new_device" , + chip_select, ctlr->num_chipselect); +return -EINVAL ; + } + + spi =spi_alloc_device (ctlr); +if (!spi) +return -ENOMEM ; + +spi_set_chipselect (spi,0 , chip_select); + spi->max_speed_hz = max_speed_hz; + spi->mode = mode; + spi->cs_index_mask =BIT (0 ); +strscpy (spi->modalias, modalias,sizeof (spi->modalias)); + +/* +* Set driver_override so that the device binds to the driver +* named by modalias regardless of whether that driver's +* id_table contains a matching entry. This is needed because +* some drivers (e.g. spidev) deliberately omit generic names +* from their id_table. +*/ + status =device_set_driver_override (&spi->dev, modalias); +if (status) { +spi_dev_put (spi); +return status; + } + +/* Extra ref so concurrent __unregister cannot free the device */ +get_device (&spi->dev); + + status =spi_add_device (spi); +if (status) { +put_device (&spi->dev); +spi_dev_put (spi); +return status; + } + +mutex_lock (&ctlr->userspace_clients_lock); +if (!ctlr->dead) { +list_add_tail (&spi->userspace_node, &ctlr->userspace_clients); +mutex_unlock (&ctlr->userspace_clients_lock); +put_device (&spi->dev); +dev_info (dev,"%s: Instantiated device %s at CS%u\n" , +"new_device" , modalias, chip_select); +return count; + } +mutex_unlock (&ctlr->userspace_clients_lock); + +/* Controller is dying; clean up if __unregister hasn't already */ +if (device_is_registered (&spi->dev)) +spi_unregister_device (spi); +put_device (&spi->dev); +return -ENODEV ; +} +static DEVICE_ATTR_WO (new_device); + +static ssize_t +delete_device_store (struct device *dev,struct device_attribute *attr, +const char *buf,size_t count) +{ + struct spi_controller *ctlr = container_of(dev, struct spi_controller, + dev); +struct spi_device *spi, *next; +unsigned short cs; +char end; +int res; + + res =sscanf (buf,"%hu%c" , &cs, &end); +if (res <1 ) { +dev_err (dev,"%s: Can't parse chip select\n" ,"delete_device" ); +return -EINVAL ; + } +if (res >1 && end !='\n' ) { +dev_err (dev,"%s: Extra parameters\n" ,"delete_device" ); +return -EINVAL ; + } + + res = -ENOENT ; +mutex_lock (&ctlr->userspace_clients_lock); +list_for_each_entry_safe (spi, next, &ctlr->userspace_clients, + userspace_node) { +if (spi_get_chipselect (spi,0 ) == cs) { +dev_info (dev,"%s: Deleting device %s at CS%u\n" , +"delete_device" , spi->modalias, cs); + +list_del (&spi->userspace_node); +spi_unregister_device (spi); + res = count; +break ; + } + } +mutex_unlock (&ctlr->userspace_clients_lock); + +if (res <0 ) +dev_err (dev,"%s: Can't find device in list\n" , +"delete_device" ); +return res; +} +static DEVICE_ATTR_IGNORE_LOCKDEP(delete_device, 0200, NULL, + delete_device_store); + +static struct attribute *spi_controller_userspace_attrs[] = { + &dev_attr_new_device.attr, + &dev_attr_delete_device.attr, +NULL , +}; + +static const struct attribute_group spi_controller_userspace_group = { + .attrs = spi_controller_userspace_attrs, +}; +static const struct attribute_group *spi_controller_groups[] = { &spi_controller_statistics_group, + &spi_controller_userspace_group,NULL , }; +#else /* !CONFIG_SPI_DYNAMIC */ + +static const struct attribute_group *spi_controller_groups[] = { + &spi_controller_statistics_group, +NULL , +}; + +#endif /* CONFIG_SPI_DYNAMIC */ +static void spi_statistics_add_transfer_stats (struct spi_statistics __percpu *pcpu_stats,struct spi_transfer *xfer,struct spi_message *msg)
@@ -724,10 +900,10 @@ static int __spi_add_device(struct spi_device *spi, struct spi_device *parent)return status;/* Controller may unregister concurrently */ -if (IS_ENABLED (CONFIG_SPI_DYNAMIC ) && - !device_is_registered (&ctlr->dev)) { +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +if (ctlr->dead)return -ENODEV ; - } +#endif if (ctlr->cs_gpiods) {u8 cs;
@@ -3256,6 +3432,10 @@ struct spi_controller *__spi_alloc_controller(struct device *dev,mutex_init (&ctlr->bus_lock_mutex);mutex_init (&ctlr->io_mutex);mutex_init (&ctlr->add_lock); +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +mutex_init (&ctlr->userspace_clients_lock); +INIT_LIST_HEAD (&ctlr->userspace_clients); +#endif ctlr->bus_num =-1 ; ctlr->num_chipselect =1 ; ctlr->num_data_lanes =1 ;
@@ -3633,8 +3813,35 @@ void spi_unregister_controller(struct spi_controller *ctlr)if (IS_ENABLED (CONFIG_SPI_DYNAMIC ))mutex_lock (&ctlr->add_lock); +/* +* Mark dead and drain userspace_clients before __unregister, +* since spi_unregister_device() doesn't do list_del() itself. +*/ +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +mutex_lock (&ctlr->userspace_clients_lock); + ctlr->dead = true; +while (!list_empty (&ctlr->userspace_clients)) { +struct spi_device *spi; + + spi =list_first_entry (&ctlr->userspace_clients, + struct spi_device, + userspace_node); +list_del (&spi->userspace_node); +spi_unregister_device (spi); + } +mutex_unlock (&ctlr->userspace_clients_lock); +#endif +device_for_each_child (&ctlr->dev,NULL , __unregister); +/* +* Release add_lock before device_del(): holding it would +* deadlock against kernfs_drain waiting for in-flight sysfs +* stores. ctlr->dead prevents new device registration. +*/ +if (IS_ENABLED (CONFIG_SPI_DYNAMIC )) +mutex_unlock (&ctlr->add_lock); +/* First make sure that this controller was ever added */ mutex_lock (&board_lock); found =idr_find (&spi_controller_idr, id);
@@ -3655,9 +3862,6 @@ void spi_unregister_controller(struct spi_controller *ctlr)idr_remove (&spi_controller_idr, id);mutex_unlock (&board_lock); -if (IS_ENABLED (CONFIG_SPI_DYNAMIC )) -mutex_unlock (&ctlr->add_lock); -/* * Release the last reference on the controller if its driver * has not yet been converted to devm_spi_alloc_host/target().
include/linux/spi/spi.h +13 -0
@@ -250,6 +250,10 @@ struct spi_device {u8 rx_lane_map[SPI_DEVICE_DATA_LANE_CNT_MAX ];u8 num_rx_lanes; +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +struct list_head userspace_node; +#endif +/* * Likely need more hooks for more protocol options affecting how * the controller talks to each chip, like:
@@ -554,6 +558,9 @@ extern struct spi_device *devm_spi_new_ancillary_device(struct spi_device *spi,* @defer_optimize_message: set to true if controller cannot pre-optimize messages * and needs to defer the optimization step until the message is actually * being transferred +* @userspace_clients: list of SPI devices instantiated from userspace via +* the sysfs new_device interface +* @userspace_clients_lock: mutex protecting @userspace_clients * * Each SPI controller can communicate with one or more @spi_device * children. These make a small bus, sharing MOSI, MISO and SCK signals
@@ -809,6 +816,12 @@ struct spi_controller {bool queue_empty;bool must_async;bool defer_optimize_message; + +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +struct list_head userspace_clients; +struct mutex userspace_clients_lock; +bool dead; +#endif };static inline void *spi_controller_get_devdata (struct spi_controller *ctlr)
Signature · 1 line
2.17.1
Mark Brown
maintainerdrivers/spi/spi.c static const struct attribute_group spi_controller_statistics_group = {
Quoted 8 lines · Vishwaroop A
drivers/spi/spi.c +7
-0+static ssize_t +new_device_store (struct device *dev,struct device_attribute *attr, +const char *buf,size_t count) +{ +/* Controller is dying; clean up if __unregister hasn't already */ +if (device_is_registered (&spi->dev)) +spi_unregister_device (spi);
This runs outside of userspace_clients_lock so there's a possibility that if the controller is in the middle of unregistering (which is likely since that's the case we're handling!) it might be running
device_for_each_child(&ctlr->dev, NULL, __unregister);
which would result in a double free.
Quoted 11 lines
drivers/spi/spi.c +7
-0@@ -3633,8 +3813,35 @@ void spi_unregister_controller(struct spi_controller *ctlr)if (IS_ENABLED (CONFIG_SPI_DYNAMIC ))mutex_lock (&ctlr->add_lock); +/* +* Mark dead and drain userspace_clients before __unregister, +* since spi_unregister_device() doesn't do list_del() itself. +*/ +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +mutex_lock (&ctlr->userspace_clients_lock); + ctlr->dead = true;
drivers/spi/spi.c void spi_unregister_controller(struct spi_controller *ctlr) · line 3832
Quoted 10 lines
drivers/spi/spi.c +10
-0+while (!list_empty (&ctlr->userspace_clients)) { +struct spi_device *spi; + + spi =list_first_entry (&ctlr->userspace_clients, + struct spi_device, + userspace_node); +list_del (&spi->userspace_node); +spi_unregister_device (spi); + } +mutex_unlock (&ctlr->userspace_clients_lock);
The spi_unregister_controller() side does things with the lock.
PATCH v4 2/2 docs: spi: add documentation for userspace device instantiation
In reply to Vishwaroop ADocument the new_device and delete_device sysfs attributes on SPI controllers:
- Documentation/spi/instantiating-devices.rst: describes when and why this interface is needed, accepted parameters, usage examples, and limitations.
- Documentation/ABI/testing/sysfs-class-spi-master: formal ABI entry for both attributes.
--- .../ABI/testing/sysfs-class-spi-master | 34 +++++++ Documentation/spi/index.rst | 1 + Documentation/spi/instantiating-devices.rst | 88 +++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-spi-master create mode 100644 Documentation/spi/instantiating-devices.rst
Documentation/ABI/testing/sysfs-class-spi-master new file +34 -0
@@ -0,0 +1,34 @@ +What: /sys/class/spi_master/spiB/new_device +Date: April 2026 +KernelVersion: 7.2 +Contact: [email protected] +Description: (WO) Instantiate a new SPI device on bus B, where B + is the bus number (0, 1, 2, ...). Takes parameters + in the format: + + <modalias> <chip_select> [<max_speed_hz> [<mode>]] + + where modalias is the driver name, chip_select is the + CS line number, and max_speed_hz and mode are optional. + + The device can later be removed with delete_device. + + Only devices created via this interface can be removed + with delete_device; platform and DT devices are not + affected. + + Example: + # echo spidev 0 > /sys/class/spi_master/spi0/new_device + # echo spidev 0 10000000 > /sys/class/spi_master/spi0/new_device + # echo spidev 0 10000000 3 > /sys/class/spi_master/spi0/new_device + +What: /sys/class/spi_master/spiB/delete_device +Date: April 2026 +KernelVersion: 7.2 +Contact: [email protected] +Description: (WO) Remove a SPI device previously created via + new_device. Takes a single parameter: the chip select + number of the device to remove. + + Example: + # echo 0 > /sys/class/spi_master/spi0/delete_device
Documentation/spi/index.rst +1 -0
@@ -8,6 +8,7 @@ Serial Peripheral Interface (SPI) :maxdepth: 1 spi-summary + instantiating-devices spidev multiple-data-lanes butterfly
Documentation/spi/instantiating-devices.rst new file +88 -0
88 lines not on this page · raw message
Signature · 1 line
2.17.1