spi: add new_device/delete_device sysfs interface
Subsystems (2)
v7 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.
Patch 1 adds the new_device/delete_device attributes and the supporting infrastructure (userspace_clients list, dead flag).
Patch 2 adds the ABI and user-facing documentation.
Sent as a fresh top-level thread per Mark's feedback on v6.
Changes since v6:
- new_device_store(): reject empty device names (leading-space input like " 0"). Previously produced an empty modalias that could never bind a driver. (Mark)
- Move sysfs userspace group registration out of the automatic ctlr->dev.groups path and into an explicit sysfs_create_group() call at the end of spi_register_controller(), after the queue, boardinfo matching and DT/ACPI enumeration have all completed. Torn down with sysfs_remove_group() at the start of spi_unregister_controller() so kernfs_drain naturally serialises with in-flight sysfs stores. (Mark)
- Drop userspace_clients_lock; reuse the existing add_lock for the userspace_clients list and the dead flag. new_device_store() now calls __spi_add_device() directly under add_lock (add_lock is already the lock the controller uses to serialise device adds), which lets the dead check, __spi_add_device() and list insertion happen atomically. delete_device_store() also takes add_lock. new_device is annotated DEVICE_ATTR_IGNORE_LOCKDEP alongside delete_device to silence the false-positive class-level splat (kernfs_drain has per-node scope, so no real ABBA). (Jon)
- kernel-doc / inline comment updates for the new struct fields (@userspace_clients now protected by @add_lock, new @userspace_registered, updated @dead).
Changes since v5:
- Rebased on next-20260727 (v7.2-rc5); applies cleanly.
- kernel-doc entries for the new struct spi_controller / struct spi_device fields.
- new_device_store(): reject chip_select > U8_MAX to avoid silent
truncation in spi_set_chipselect(); parse with %u instead of %hu.
- new_device_store(): reject mode bits outside SPI_MODE_USER_MASK (mirrors spidev's SPI_IOC_WR_MODE32 filter).
- new_device_store(): drop the unused 'n' / '%n' from sscanf().
Changes since v4:
- Removed spi_unregister_device() call from new_device_store()'s ctlr->dead teardown path; it raced with device_for_each_child(__unregister) in spi_unregister_controller().
Changes since v3:
- Replaced holding add_lock across __spi_add_device() + list insertion by a ctlr->dead flag checked under add_lock, so add_lock is only held while doing list bookkeeping and can be released before device_del().
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 | 270 +++++++++++++++++- include/linux/spi/spi.h | 23 ++ 5 files changed, 410 insertions(+), 6 deletions(-) create mode 100644 Documentation/ABI/testing/sysfs-class-spi-master create mode 100644 Documentation/spi/instantiating-devices.rst
base-commit: 0d33d21e47d9dc66f91e44da3fc9220c74d93df7
Signature · 1 line
2.17.1
PATCH v7 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 | 270 +++++++++++++++++++++++++++++++++++++++- include/linux/spi/spi.h | 23 ++++ 2 files changed, 287 insertions(+), 6 deletions(-)
drivers/spi/spi.c +264 -6
@@ -43,6 +43,7 @@ EXPORT_TRACEPOINT_SYMBOL(spi_transfer_stop);#include "internals.h" static int __spi_setup (struct spi_device *spi,bool initial_setup); +static int __spi_add_device (struct spi_device *spi,struct spi_device *parent);static DEFINE_IDR (spi_controller_idr);
@@ -297,11 +298,214 @@ 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 ]; +unsigned int chip_select; +u32 max_speed_hz =0 ; +u32 mode =0 ; +char *blank; +int res, status; + + blank =strchr (buf,' ' ); +if (!blank) { +dev_err (dev,"%s: Missing parameters\n" ,"new_device" ); +return -EINVAL ; + } + +if (blank == buf || 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,"%u %u %u" , + &chip_select, &max_speed_hz, &mode); +if (res <1 ) { +dev_err (dev,"%s: Can't parse chip select\n" ,"new_device" ); +return -EINVAL ; + } + +/* +* spi_device.chip_select[] is u8, so cap at U8_MAX independently of +* ctlr->num_chipselect (which is u16 and may exceed 255). Without +* this, values in (U8_MAX, num_chipselect) would silently truncate +* inside spi_set_chipselect() and select the wrong CS. +*/ +if (chip_select >U8_MAX || chip_select >= ctlr->num_chipselect) { +dev_err (dev,"%s: Chip select %u out of range (num_chipselect=%u)\n" , +"new_device" , chip_select, ctlr->num_chipselect); +return -EINVAL ; + } + +/* +* Reject kernel-internal mode bits (SPI_NO_TX, SPI_NO_RX, +* SPI_TPM_HW_FLOW, ...). These are set only by in-kernel drivers +* that know they are safe on their controller/device pair and must +* not be settable through a userspace-writable sysfs. Matches +* spidev's SPI_IOC_WR_MODE32 handling (drivers/spi/spidev.c). +*/ +if (mode & ~(u32 )SPI_MODE_USER_MASK ) { +dev_err (dev,"%s: Invalid mode bits 0x%x\n" ,"new_device" , + mode & ~(u32 )SPI_MODE_USER_MASK ); +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; + } + +/* +* Serialise against spi_unregister_controller() via add_lock so +* that the dead check, __spi_add_device() and list insertion are +* atomic with respect to controller teardown. +*/ +mutex_lock (&ctlr->add_lock); + +if (ctlr->dead) { +mutex_unlock (&ctlr->add_lock); +spi_dev_put (spi); +return -ENODEV ; + } + + status =__spi_add_device (spi,NULL ); +if (status) { +mutex_unlock (&ctlr->add_lock); +spi_dev_put (spi); +return status; + } + +list_add_tail (&spi->userspace_node, &ctlr->userspace_clients); +mutex_unlock (&ctlr->add_lock); + +dev_info (dev,"%s: Instantiated device %s at CS%u\n" , +"new_device" , modalias, chip_select); +return count; +} +static DEVICE_ATTR_IGNORE_LOCKDEP(new_device, 0200, NULL, new_device_store); + +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->add_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->add_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, +}; + +/* +* spi_controller_userspace_group is deliberately NOT listed here. Attaching +* it via ctlr->dev.groups would expose new_device/delete_device the moment +* device_add() runs, i.e. before spi_register_controller() has finished +* bringing up the queue, matching boardinfo and registering DT/ACPI +* children. It is instead created manually as the last step of +* spi_register_controller() and torn down as the first step of +* spi_unregister_controller(). +*/ +static const struct attribute_group *spi_controller_groups[] = { + &spi_controller_statistics_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)
@@ -729,10 +933,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) {for (idx =0 ; idx < spi->num_chipselect; idx++) {
@@ -3259,6 +3463,9 @@ 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 ) +INIT_LIST_HEAD (&ctlr->userspace_clients); +#endif ctlr->bus_num =-1 ; ctlr->num_chipselect =1 ; ctlr->num_data_lanes =1 ;
@@ -3552,6 +3759,24 @@ int spi_register_controller(struct spi_controller *ctlr)of_register_spi_devices (ctlr);acpi_register_spi_devices (ctlr); +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +/* +* Register the new_device/delete_device sysfs interface as the +* final step of controller bringup, only after the queue, +* boardinfo matching and DT/ACPI enumeration have all completed. +* If this fails, the controller is otherwise usable, so log and +* carry on rather than tearing everything down. +*/ + status =sysfs_create_group (&ctlr->dev.kobj, + &spi_controller_userspace_group); +if (status) +dev_warn (&ctlr->dev, +"Failed to create userspace client interface: %d\n" , + status); +else + ctlr->userspace_registered = true; +#endif +return 0 ; del_ctrl:
@@ -3616,12 +3841,48 @@ void spi_unregister_controller(struct spi_controller *ctlr)struct spi_controller *found;int id = ctlr->bus_num; +/* +* Drain in-flight new_device/delete_device sysfs stores and +* prevent new ones from starting. Must happen before we take +* add_lock so kernfs_drain doesn't wait on a store that is +* itself blocked on add_lock. +*/ +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +if (ctlr->userspace_registered) { +sysfs_remove_group (&ctlr->dev.kobj, + &spi_controller_userspace_group); + ctlr->userspace_registered = false; + } +#endif +/* Prevent addition of new devices, unregister existing ones */ if (IS_ENABLED (CONFIG_SPI_DYNAMIC ))mutex_lock (&ctlr->add_lock); +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +/* +* Mark dead and drain userspace_clients before __unregister, +* since spi_unregister_device() doesn't do list_del() itself. +* With the userspace sysfs group already removed above, no new +* entries can appear in this list. +*/ + 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); + } +#endif +device_for_each_child (&ctlr->dev,NULL , __unregister); +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);
@@ -3641,9 +3902,6 @@ void spi_unregister_controller(struct spi_controller *ctlr)if (found == ctlr)idr_remove (&spi_controller_idr, id);mutex_unlock (&board_lock); - -if (IS_ENABLED (CONFIG_SPI_DYNAMIC )) -mutex_unlock (&ctlr->add_lock); }EXPORT_SYMBOL_GPL (spi_unregister_controller);
include/linux/spi/spi.h +23 -0
@@ -179,6 +179,8 @@ extern void spi_transfer_cs_change_delay_exec(struct spi_message *msg,* @num_tx_lanes: Number of transmit lanes wired up. * @rx_lane_map: Map of peripheral lanes (index) to controller lanes (value). * @num_rx_lanes: Number of receive lanes wired up. +* @userspace_node: entry on the parent controller's userspace_clients list +* when this device was instantiated via the sysfs new_device interface * * A @spi_device is used to interchange data between an SPI target device * (usually a discrete chip) and CPU memory.
@@ -252,6 +254,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:
@@ -555,6 +561,14 @@ 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; protected by @add_lock +* @userspace_registered: true once the new_device/delete_device sysfs +* group has been added by spi_register_controller(); used by +* spi_unregister_controller() to know whether to remove it +* @dead: set to true under @add_lock when spi_unregister_controller() +* begins teardown; prevents __spi_add_device() from racing new +* device registrations against controller shutdown * * Each SPI controller can communicate with one or more @spi_device * children. These make a small bus, sharing MOSI, MISO and SCK signals
@@ -807,6 +821,15 @@ struct spi_controller {bool queue_empty;bool must_async;bool defer_optimize_message; + +#if IS_ENABLED (CONFIG_SPI_DYNAMIC ) +/* List of userspace-instantiated devices; protected by @add_lock */ +struct list_head userspace_clients; +/* True after new_device/delete_device sysfs group is created */ +bool userspace_registered; +/* Set true under @add_lock once spi_unregister_controller() has begun teardown */ +bool dead; +#endif };static inline void *spi_controller_get_devdata (struct spi_controller *ctlr)
Signature · 1 line
2.17.1
PATCH v7 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