mirror of
https://github.com/torvalds/linux.git
synced 2026-09-23 22:14:03 +02:00
036d4b059b
Document 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.
Signed-off-by: Vishwaroop A <va@nvidia.com>
Link: https://patch.msgid.link/20260803104614.2548375-3-va@nvidia.com
Signed-off-by: Mark Brown <broonie@kernel.org>
89 lines
3.5 KiB
ReStructuredText
89 lines
3.5 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
==============================
|
|
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 Documentation/i2c/instantiating-devices.rst). 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.
|