Skip to content

Commit 05c3bd7

Browse files
dlechbroonie
dlech
authored and
broonie
committed
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>
1 parent 5621a7b commit 05c3bd7

2 files changed

Lines changed: 218 additions & 0 deletions

File tree

‎Documentation/spi/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Serial Peripheral Interface (SPI)
99

1010
spi-summary
1111
spidev
12+
multiple-data-lanes
1213
butterfly
1314
spi-lm70llp
1415
spi-sc18is602

‎Documentation/spi/multiple-data-lanes.rst‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
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.

0 commit comments

Comments
 (0)