Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
spi: Documentation: add page on multi-lane support
Add a new page to Documentation/spi/ describing how multi-lane SPI
support works. This is uncommon functionality so it deserves its own
documentation page.
Reviewed-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
Signed-off-by: David Lechner <dlechner@baylibre.com>
Link: https://patch.msgid.link/20260123-spi-add-multi-bus-support-v6-5-12af183c06eb@baylibre.com
Signed-off-by: Mark Brown <broonie@kernel.org>
authored by
David Lechner
and committed by
Mark Brown
05c3bd74
5621a7bc
+218
+1
Documentation/spi/index.rst
+1
Documentation/spi/index.rst
+217
Documentation/spi/multiple-data-lanes.rst
+217
Documentation/spi/multiple-data-lanes.rst
···
1
+
====================================
2
+
SPI devices with multiple data lanes
3
+
====================================
4
+
5
+
Some specialized SPI controllers and peripherals support multiple data lanes
6
+
that allow reading more than one word at a time in parallel. This is different
7
+
from dual/quad/octal SPI where multiple bits of a single word are transferred
8
+
simultaneously.
9
+
10
+
For example, controllers that support parallel flash memories have this feature
11
+
as do some simultaneous-sampling ADCs where each channel has its own data lane.
12
+
13
+
---------------------
14
+
Describing the wiring
15
+
---------------------
16
+
17
+
The ``spi-tx-bus-width`` and ``spi-rx-bus-width`` properties in the devicetree
18
+
are used to describe how many data lanes are connected between the controller
19
+
and how wide each lane is. The number of items in the array indicates how many
20
+
lanes there are, and the value of each item indicates how many bits wide that
21
+
lane is.
22
+
23
+
For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be
24
+
wired up like this::
25
+
26
+
+--------------+ +----------+
27
+
| SPI | | AD4630 |
28
+
| Controller | | ADC |
29
+
| | | |
30
+
| CS0 |--->| CS |
31
+
| SCK |--->| SCK |
32
+
| SDO |--->| SDI |
33
+
| | | |
34
+
| SDIA0 |<---| SDOA0 |
35
+
| SDIA1 |<---| SDOA1 |
36
+
| SDIA2 |<---| SDOA2 |
37
+
| SDIA3 |<---| SDOA3 |
38
+
| | | |
39
+
| SDIB0 |<---| SDOB0 |
40
+
| SDIB1 |<---| SDOB1 |
41
+
| SDIB2 |<---| SDOB2 |
42
+
| SDIB3 |<---| SDOB3 |
43
+
| | | |
44
+
+--------------+ +----------+
45
+
46
+
It is described in a devicetree like this::
47
+
48
+
spi {
49
+
compatible = "my,spi-controller";
50
+
51
+
...
52
+
53
+
adc@0 {
54
+
compatible = "adi,ad4630";
55
+
reg = <0>;
56
+
...
57
+
spi-rx-bus-width = <4>, <4>; /* 2 lanes of 4 bits each */
58
+
...
59
+
};
60
+
};
61
+
62
+
In most cases, lanes will be wired up symmetrically (A to A, B to B, etc). If
63
+
this isn't the case, extra ``spi-rx-lane-map`` and ``spi-tx-lane-map``
64
+
properties are needed to provide a mapping between controller lanes and the
65
+
physical lane wires.
66
+
67
+
Here is an example where a multi-lane SPI controller has each lane wired to
68
+
separate single-lane peripherals::
69
+
70
+
+--------------+ +----------+
71
+
| SPI | | Thing 1 |
72
+
| Controller | | |
73
+
| | | |
74
+
| CS0 |--->| CS |
75
+
| SDO0 |--->| SDI |
76
+
| SDI0 |<---| SDO |
77
+
| SCLK0 |--->| SCLK |
78
+
| | | |
79
+
| | +----------+
80
+
| |
81
+
| | +----------+
82
+
| | | Thing 2 |
83
+
| | | |
84
+
| CS1 |--->| CS |
85
+
| SDO1 |--->| SDI |
86
+
| SDI1 |<---| SDO |
87
+
| SCLK1 |--->| SCLK |
88
+
| | | |
89
+
+--------------+ +----------+
90
+
91
+
This is described in a devicetree like this::
92
+
93
+
spi {
94
+
compatible = "my,spi-controller";
95
+
96
+
...
97
+
98
+
thing1@0 {
99
+
compatible = "my,thing1";
100
+
reg = <0>;
101
+
...
102
+
};
103
+
104
+
thing2@1 {
105
+
compatible = "my,thing2";
106
+
reg = <1>;
107
+
...
108
+
spi-tx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for tx wire */
109
+
spi-rx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for rx wire */
110
+
...
111
+
};
112
+
};
113
+
114
+
115
+
The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``,
116
+
so these properties can still be omitted even when ``spi-rx-lane-map`` and
117
+
``spi-tx-lane-map`` are used.
118
+
119
+
----------------------------
120
+
Usage in a peripheral driver
121
+
----------------------------
122
+
123
+
These types of SPI controllers generally do not support arbitrary use of the
124
+
multiple lanes. Instead, they operate in one of a few defined modes. Peripheral
125
+
drivers should set the :c:type:`struct spi_transfer.multi_lane_mode <spi_transfer>`
126
+
field to indicate which mode they want to use for a given transfer.
127
+
128
+
The possible values for this field have the following semantics:
129
+
130
+
- :c:macro:`SPI_MULTI_BUS_MODE_SINGLE`: Only use the first lane. Other lanes are
131
+
ignored. This means that it is operating just like a conventional SPI
132
+
peripheral. This is the default, so it does not need to be explicitly set.
133
+
134
+
Example::
135
+
136
+
tx_buf[0] = 0x88;
137
+
138
+
struct spi_transfer xfer = {
139
+
.tx_buf = tx_buf,
140
+
.len = 1,
141
+
};
142
+
143
+
spi_sync_transfer(spi, &xfer, 1);
144
+
145
+
Assuming the controller is sending the MSB first, the sequence of bits
146
+
sent over the tx wire would be (right-most bit is sent first)::
147
+
148
+
controller > data bits > peripheral
149
+
---------- ---------------- ----------
150
+
SDO 0 0-0-0-1-0-0-0-1 SDI 0
151
+
152
+
- :c:macro:`SPI_MULTI_BUS_MODE_MIRROR`: Send a single data word over all of the
153
+
lanes at the same time. This only makes sense for writes and not
154
+
for reads.
155
+
156
+
Example::
157
+
158
+
tx_buf[0] = 0x88;
159
+
160
+
struct spi_transfer xfer = {
161
+
.tx_buf = tx_buf,
162
+
.len = 1,
163
+
.multi_lane_mode = SPI_MULTI_BUS_MODE_MIRROR,
164
+
};
165
+
166
+
spi_sync_transfer(spi, &xfer, 1);
167
+
168
+
The data is mirrored on each tx wire::
169
+
170
+
controller > data bits > peripheral
171
+
---------- ---------------- ----------
172
+
SDO 0 0-0-0-1-0-0-0-1 SDI 0
173
+
SDO 1 0-0-0-1-0-0-0-1 SDI 1
174
+
175
+
- :c:macro:`SPI_MULTI_BUS_MODE_STRIPE`: Send or receive two different data words
176
+
at the same time, one on each lane. This means that the buffer needs to be
177
+
sized to hold data for all lanes. Data is interleaved in the buffer, with
178
+
the first word corresponding to lane 0, the second to lane 1, and so on.
179
+
Once the last lane is used, the next word in the buffer corresponds to lane
180
+
0 again. Accordingly, the buffer size must be a multiple of the number of
181
+
lanes. This mode works for both reads and writes.
182
+
183
+
Example::
184
+
185
+
struct spi_transfer xfer = {
186
+
.rx_buf = rx_buf,
187
+
.len = 2,
188
+
.multi_lane_mode = SPI_MULTI_BUS_MODE_STRIPE,
189
+
};
190
+
191
+
spi_sync_transfer(spi, &xfer, 1);
192
+
193
+
Each rx wire has a different data word sent simultaneously::
194
+
195
+
controller < data bits < peripheral
196
+
---------- ---------------- ----------
197
+
SDI 0 0-0-0-1-0-0-0-1 SDO 0
198
+
SDI 1 1-0-0-0-1-0-0-0 SDO 1
199
+
200
+
After the transfer, ``rx_buf[0] == 0x11`` (word from SDO 0) and
201
+
``rx_buf[1] == 0x88`` (word from SDO 1).
202
+
203
+
204
+
-----------------------------
205
+
SPI controller driver support
206
+
-----------------------------
207
+
208
+
To support multiple data lanes, SPI controller drivers need to set
209
+
:c:type:`struct spi_controller.num_data_lanes <spi_controller>` to a value
210
+
greater than 1.
211
+
212
+
Then the part of the driver that handles SPI transfers needs to check the
213
+
:c:type:`struct spi_transfer.multi_lane_mode <spi_transfer>` field and implement
214
+
the appropriate behavior for each supported mode and return an error for
215
+
unsupported modes.
216
+
217
+
The core SPI code should handle the rest.