1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
.. 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.
|
