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>
---
v5 changes:
* Fix tx/rx typo in stripe mode example.
v4 changes:
* New patch in v4.
---
Documentation/spi/index.rst | 1 +
Documentation/spi/multiple-data-lanes.rst | 217 ++++++++++++++++++++++++++++++
2 files changed, 218 insertions(+)
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
index 824ce42ed4f0..2c89b1ee39e2 100644
--- a/Documentation/spi/index.rst
+++ b/Documentation/spi/index.rst
@@ -9,6 +9,7 @@ Serial Peripheral Interface (SPI)
spi-summary
spidev
+ multiple-data-lanes
butterfly
spi-lm70llp
spi-sc18is602
diff --git a/Documentation/spi/multiple-data-lanes.rst b/Documentation/spi/multiple-data-lanes.rst
new file mode 100644
index 000000000000..96d6997ecf77
--- /dev/null
+++ b/Documentation/spi/multiple-data-lanes.rst
@@ -0,0 +1,217 @@
+====================================
+SPI devices with multiple data lanes
+====================================
+
+Some specialized SPI controllers and peripherals support multiple data lanes
+that allow reading more than one word at a time in parallel. This is different
+from dual/quad/octal SPI where multiple bits of a single word are transferred
+simultaneously.
+
+For example, controllers that support parallel flash memories have this feature
+as do some simultaneous-sampling ADCs where each channel has its own data lane.
+
+---------------------
+Describing the wiring
+---------------------
+
+The ``spi-tx-bus-width`` and ``spi-rx-bus-width`` properties in the devicetree
+are used to describe how many data lanes are connected between the controller
+and how wide each lane is. The number of items in the array indicates how many
+lanes there are, and the value of each item indicates how many bits wide that
+lane is.
+
+For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be
+wired up like this::
+
+ +--------------+ +----------+
+ | SPI | | AD4630 |
+ | Controller | | ADC |
+ | | | |
+ | CS0 |--->| CS |
+ | SCK |--->| SCK |
+ | SDO |--->| SDI |
+ | | | |
+ | SDIA0 |<---| SDOA0 |
+ | SDIA1 |<---| SDOA1 |
+ | SDIA2 |<---| SDOA2 |
+ | SDIA3 |<---| SDOA3 |
+ | | | |
+ | SDIB0 |<---| SDOB0 |
+ | SDIB1 |<---| SDOB1 |
+ | SDIB2 |<---| SDOB2 |
+ | SDIB3 |<---| SDOB3 |
+ | | | |
+ +--------------+ +----------+
+
+It is described in a devicetree like this::
+
+ spi {
+ compatible = "my,spi-controller";
+
+ ...
+
+ adc@0 {
+ compatible = "adi,ad4630";
+ reg = <0>;
+ ...
+ spi-rx-bus-width = <4>, <4>; /* 2 lanes of 4 bits each */
+ ...
+ };
+ };
+
+In most cases, lanes will be wired up symmetrically (A to A, B to B, etc). If
+this isn't the case, extra ``spi-rx-bus-width`` and ``spi-tx-bus-width``
+properties are needed to provide a mapping between controller lanes and the
+physical lane wires.
+
+Here is an example where a multi-lane SPI controller has each lane wired to
+separate single-lane peripherals::
+
+ +--------------+ +----------+
+ | SPI | | Thing 1 |
+ | Controller | | |
+ | | | |
+ | CS0 |--->| CS |
+ | SDO0 |--->| SDI |
+ | SDI0 |<---| SDO |
+ | SCLK0 |--->| SCLK |
+ | | | |
+ | | +----------+
+ | |
+ | | +----------+
+ | | | Thing 2 |
+ | | | |
+ | CS1 |--->| CS |
+ | SDO1 |--->| SDI |
+ | SDI1 |<---| SDO |
+ | SCLK1 |--->| SCLK |
+ | | | |
+ +--------------+ +----------+
+
+This is described in a devicetree like this::
+
+ spi {
+ compatible = "my,spi-controller";
+
+ ...
+
+ thing1@0 {
+ compatible = "my,thing1";
+ reg = <0>;
+ ...
+ };
+
+ thing2@1 {
+ compatible = "my,thing2";
+ reg = <1>;
+ ...
+ spi-tx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for tx wire */
+ spi-rx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for rx wire */
+ ...
+ };
+ };
+
+
+The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``,
+so these properties can still be omitted even when ``spi-rx-lane-map`` and
+``spi-tx-lane-map`` are used.
+
+----------------------------
+Usage in a peripheral driver
+----------------------------
+
+These types of SPI controllers generally do not support arbitrary use of the
+multiple lanes. Instead, they operate in one of a few defined modes. Peripheral
+drivers should set the :c:type:`struct spi_transfer.multi_lane_mode <spi_transfer>`
+field to indicate which mode they want to use for a given transfer.
+
+The possible values for this field have the following semantics:
+
+- :c:macro:`SPI_MULTI_BUS_MODE_SINGLE`: Only use the first lane. Other lanes are
+ ignored. This means that it is operating just like a conventional SPI
+ peripheral. This is the default, so it does not need to be explicitly set.
+
+ Example::
+
+ tx_buf[0] = 0x88;
+
+ struct spi_transfer xfer = {
+ .tx_buf = tx_buf,
+ .len = 1,
+ };
+
+ spi_sync_transfer(spi, &xfer, 1);
+
+ Assuming the controller is sending the MSB first, the sequence of bits
+ sent over the tx wire would be (right-most bit is sent first)::
+
+ controller > data bits > peripheral
+ ---------- ---------------- ----------
+ SDO 0 0-0-0-1-0-0-0-1 SDI 0
+
+- :c:macro:`SPI_MULTI_BUS_MODE_MIRROR`: Send a single data word over all of the
+ lanes at the same time. This only makes sense for writes and not
+ for reads.
+
+ Example::
+
+ tx_buf[0] = 0x88;
+
+ struct spi_transfer xfer = {
+ .tx_buf = tx_buf,
+ .len = 1,
+ .multi_lane_mode = SPI_MULTI_BUS_MODE_MIRROR,
+ };
+
+ spi_sync_transfer(spi, &xfer, 1);
+
+ The data is mirrored on each tx wire::
+
+ controller > data bits > peripheral
+ ---------- ---------------- ----------
+ SDO 0 0-0-0-1-0-0-0-1 SDI 0
+ SDO 1 0-0-0-1-0-0-0-1 SDI 1
+
+- :c:macro:`SPI_MULTI_BUS_MODE_STRIPE`: Send or receive two different data words
+ at the same time, one on each lane. This means that the buffer needs to be
+ sized to hold data for all lanes. Data is interleaved in the buffer, with
+ the first word corresponding to lane 0, the second to lane 1, and so on.
+ Once the last lane is used, the next word in the buffer corresponds to lane
+ 0 again. Accordingly, the buffer size must be a multiple of the number of
+ lanes. This mode works for both reads and writes.
+
+ Example::
+
+ struct spi_transfer xfer = {
+ .rx_buf = rx_buf,
+ .len = 2,
+ .multi_lane_mode = SPI_MULTI_BUS_MODE_STRIPE,
+ };
+
+ spi_sync_transfer(spi, &xfer, 1);
+
+ Each rx wire has a different data word sent simultaneously::
+
+ controller < data bits < peripheral
+ ---------- ---------------- ----------
+ SDI 0 0-0-0-1-0-0-0-1 SDO 0
+ SDI 1 1-0-0-0-1-0-0-0 SDO 1
+
+ After the transfer, ``rx_buf[0] == 0x11`` (word from SDO 0) and
+ ``rx_buf[1] == 0x88`` (word from SDO 1).
+
+
+-----------------------------
+SPI controller driver support
+-----------------------------
+
+To support multiple data lanes, SPI controller drivers need to set
+:c:type:`struct spi_controller.num_data_lanes <spi_controller>` to a value
+greater than 1.
+
+Then the part of the driver that handles SPI transfers needs to check the
+:c:type:`struct spi_transfer.multi_lane_mode <spi_transfer>` field and implement
+the appropriate behavior for each supported mode and return an error for
+unsupported modes.
+
+The core SPI code should handle the rest.
--
2.43.0On Mon, 12 Jan 2026 11:45:23 -0600
David Lechner <dlechner@baylibre.com> wrote:
> 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>
Hi David,
A few things inline.
> diff --git a/Documentation/spi/multiple-data-lanes.rst b/Documentation/spi/multiple-data-lanes.rst
> new file mode 100644
> index 000000000000..96d6997ecf77
> --- /dev/null
> +++ b/Documentation/spi/multiple-data-lanes.rst
...
> +---------------------
> +Describing the wiring
> +---------------------
> +
> +The ``spi-tx-bus-width`` and ``spi-rx-bus-width`` properties in the devicetree
> +are used to describe how many data lanes are connected between the controller
> +and how wide each lane is. The number of items in the array indicates how many
> +lanes there are, and the value of each item indicates how many bits wide that
> +lane is.
> +
> +For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be
> +wired up like this::
> +
> + +--------------+ +----------+
> + | SPI | | AD4630 |
> + | Controller | | ADC |
> + | | | |
> + | CS0 |--->| CS |
> + | SCK |--->| SCK |
> + | SDO |--->| SDI |
> + | | | |
> + | SDIA0 |<---| SDOA0 |
> + | SDIA1 |<---| SDOA1 |
> + | SDIA2 |<---| SDOA2 |
> + | SDIA3 |<---| SDOA3 |
> + | | | |
> + | SDIB0 |<---| SDOB0 |
> + | SDIB1 |<---| SDOB1 |
> + | SDIB2 |<---| SDOB2 |
> + | SDIB3 |<---| SDOB3 |
> + | | | |
> + +--------------+ +----------+
> +
> +It is described in a devicetree like this::
> +
> + spi {
> + compatible = "my,spi-controller";
> +
> + ...
> +
> + adc@0 {
> + compatible = "adi,ad4630";
> + reg = <0>;
> + ...
> + spi-rx-bus-width = <4>, <4>; /* 2 lanes of 4 bits each */
> + ...
> + };
> + };
> +
> +In most cases, lanes will be wired up symmetrically (A to A, B to B, etc). If
> +this isn't the case, extra ``spi-rx-bus-width`` and ``spi-tx-bus-width``
Wrong properties. They are those sizes but spi-tx-lane-map and spi-rx-lane-map
> +properties are needed to provide a mapping between controller lanes and the
> +physical lane wires.
> +
> +Here is an example where a multi-lane SPI controller has each lane wired to
> +separate single-lane peripherals::
> +
> + +--------------+ +----------+
> + | SPI | | Thing 1 |
> + | Controller | | |
> + | | | |
> + | CS0 |--->| CS |
> + | SDO0 |--->| SDI |
> + | SDI0 |<---| SDO |
> + | SCLK0 |--->| SCLK |
> + | | | |
> + | | +----------+
> + | |
> + | | +----------+
> + | | | Thing 2 |
> + | | | |
> + | CS1 |--->| CS |
> + | SDO1 |--->| SDI |
> + | SDI1 |<---| SDO |
> + | SCLK1 |--->| SCLK |
> + | | | |
> + +--------------+ +----------+
> +
> +This is described in a devicetree like this::
> +
> + spi {
> + compatible = "my,spi-controller";
> +
> + ...
> +
> + thing1@0 {
> + compatible = "my,thing1";
> + reg = <0>;
> + ...
> + };
> +
> + thing2@1 {
> + compatible = "my,thing2";
> + reg = <1>;
> + ...
> + spi-tx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for tx wire */
> + spi-rx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for rx wire */
Whilst simple I'd kind of expect a multi lane case as the example, or this and
the multilane one? For me the comment that follows is sufficient for the 1 lane
offset case you have here.
> + ...
> + };
> + };
> +
> +
> +The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``,
> +so these properties can still be omitted even when ``spi-rx-lane-map`` and
> +``spi-tx-lane-map`` are used.
On 1/14/26 3:10 AM, Jonathan Cameron wrote:
> On Mon, 12 Jan 2026 11:45:23 -0600
> David Lechner <dlechner@baylibre.com> wrote:
>
>> 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.
>>
...
>> +
>> +For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be
>> +wired up like this::
>> +
>> + +--------------+ +----------+
>> + | SPI | | AD4630 |
>> + | Controller | | ADC |
>> + | | | |
>> + | CS0 |--->| CS |
>> + | SCK |--->| SCK |
>> + | SDO |--->| SDI |
>> + | | | |
>> + | SDIA0 |<---| SDOA0 |
>> + | SDIA1 |<---| SDOA1 |
>> + | SDIA2 |<---| SDOA2 |
>> + | SDIA3 |<---| SDOA3 |
>> + | | | |
>> + | SDIB0 |<---| SDOB0 |
>> + | SDIB1 |<---| SDOB1 |
>> + | SDIB2 |<---| SDOB2 |
>> + | SDIB3 |<---| SDOB3 |
>> + | | | |
>> + +--------------+ +----------+
>> +
>> +It is described in a devicetree like this::
>> +
>> + spi {
>> + compatible = "my,spi-controller";
>> +
>> + ...
>> +
>> + adc@0 {
>> + compatible = "adi,ad4630";
>> + reg = <0>;
>> + ...
>> + spi-rx-bus-width = <4>, <4>; /* 2 lanes of 4 bits each */
>> + ...
>> + };
>> + };
...
>> +properties are needed to provide a mapping between controller lanes and the
>> +physical lane wires.
>> +
>> +Here is an example where a multi-lane SPI controller has each lane wired to
>> +separate single-lane peripherals::
>> +
>> + +--------------+ +----------+
>> + | SPI | | Thing 1 |
>> + | Controller | | |
>> + | | | |
>> + | CS0 |--->| CS |
>> + | SDO0 |--->| SDI |
>> + | SDI0 |<---| SDO |
>> + | SCLK0 |--->| SCLK |
>> + | | | |
>> + | | +----------+
>> + | |
>> + | | +----------+
>> + | | | Thing 2 |
>> + | | | |
>> + | CS1 |--->| CS |
>> + | SDO1 |--->| SDI |
>> + | SDI1 |<---| SDO |
>> + | SCLK1 |--->| SCLK |
>> + | | | |
>> + +--------------+ +----------+
>> +
>> +This is described in a devicetree like this::
>> +
>> + spi {
>> + compatible = "my,spi-controller";
>> +
>> + ...
>> +
>> + thing1@0 {
>> + compatible = "my,thing1";
>> + reg = <0>;
>> + ...
>> + };
>> +
>> + thing2@1 {
>> + compatible = "my,thing2";
>> + reg = <1>;
>> + ...
>> + spi-tx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for tx wire */
>> + spi-rx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for rx wire */
>
> Whilst simple I'd kind of expect a multi lane case as the example, or this and
> the multilane one? For me the comment that follows is sufficient for the 1 lane
> offset case you have here.
I thought that is what I did. I have one example that shows multiple lanes (ADC)
and one example that shows the map (Thing 1/2).
But I guess you mean that you want a 3rd example that show both the map and
multiple lanes at the same time?
I chose these two examples because they came from real-world use cases that
drove adding this feature. We didn't have a real-world case yet that used
both the map and multiple lanes at the same time so I didn't include that.
>
>> + ...
>> + };
>> + };
>> +
>> +
>> +The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``,
>> +so these properties can still be omitted even when ``spi-rx-lane-map`` and
>> +``spi-tx-lane-map`` are used.
>
>
>
On Fri, 16 Jan 2026 16:35:13 -0600
David Lechner <dlechner@baylibre.com> wrote:
> On 1/14/26 3:10 AM, Jonathan Cameron wrote:
> > On Mon, 12 Jan 2026 11:45:23 -0600
> > David Lechner <dlechner@baylibre.com> wrote:
> >
> >> 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.
> >>
>
> ...
>
> >> +
> >> +For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be
> >> +wired up like this::
> >> +
> >> + +--------------+ +----------+
> >> + | SPI | | AD4630 |
> >> + | Controller | | ADC |
> >> + | | | |
> >> + | CS0 |--->| CS |
> >> + | SCK |--->| SCK |
> >> + | SDO |--->| SDI |
> >> + | | | |
> >> + | SDIA0 |<---| SDOA0 |
> >> + | SDIA1 |<---| SDOA1 |
> >> + | SDIA2 |<---| SDOA2 |
> >> + | SDIA3 |<---| SDOA3 |
> >> + | | | |
> >> + | SDIB0 |<---| SDOB0 |
> >> + | SDIB1 |<---| SDOB1 |
> >> + | SDIB2 |<---| SDOB2 |
> >> + | SDIB3 |<---| SDOB3 |
> >> + | | | |
> >> + +--------------+ +----------+
> >> +
> >> +It is described in a devicetree like this::
> >> +
> >> + spi {
> >> + compatible = "my,spi-controller";
> >> +
> >> + ...
> >> +
> >> + adc@0 {
> >> + compatible = "adi,ad4630";
> >> + reg = <0>;
> >> + ...
> >> + spi-rx-bus-width = <4>, <4>; /* 2 lanes of 4 bits each */
> >> + ...
> >> + };
> >> + };
>
>
> ...
>
> >> +properties are needed to provide a mapping between controller lanes and the
> >> +physical lane wires.
> >> +
> >> +Here is an example where a multi-lane SPI controller has each lane wired to
> >> +separate single-lane peripherals::
> >> +
> >> + +--------------+ +----------+
> >> + | SPI | | Thing 1 |
> >> + | Controller | | |
> >> + | | | |
> >> + | CS0 |--->| CS |
> >> + | SDO0 |--->| SDI |
> >> + | SDI0 |<---| SDO |
> >> + | SCLK0 |--->| SCLK |
> >> + | | | |
> >> + | | +----------+
> >> + | |
> >> + | | +----------+
> >> + | | | Thing 2 |
> >> + | | | |
> >> + | CS1 |--->| CS |
> >> + | SDO1 |--->| SDI |
> >> + | SDI1 |<---| SDO |
> >> + | SCLK1 |--->| SCLK |
> >> + | | | |
> >> + +--------------+ +----------+
> >> +
> >> +This is described in a devicetree like this::
> >> +
> >> + spi {
> >> + compatible = "my,spi-controller";
> >> +
> >> + ...
> >> +
> >> + thing1@0 {
> >> + compatible = "my,thing1";
> >> + reg = <0>;
> >> + ...
> >> + };
> >> +
> >> + thing2@1 {
> >> + compatible = "my,thing2";
> >> + reg = <1>;
> >> + ...
> >> + spi-tx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for tx wire */
> >> + spi-rx-lane-map = <1>; /* lane 0 is not used, lane 1 is used for rx wire */
> >
> > Whilst simple I'd kind of expect a multi lane case as the example, or this and
> > the multilane one? For me the comment that follows is sufficient for the 1 lane
> > offset case you have here.
>
> I thought that is what I did. I have one example that shows multiple lanes (ADC)
> and one example that shows the map (Thing 1/2).
>
> But I guess you mean that you want a 3rd example that show both the map and
> multiple lanes at the same time?
Oops. No. I was arguing....
>
> I chose these two examples because they came from real-world use cases that
> drove adding this feature. We didn't have a real-world case yet that used
> both the map and multiple lanes at the same time so I didn't include that.
>
> >
> >> + ...
> >> + };
> >> + };
> >> +
> >> +
> >> +The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``,
> >> +so these properties can still be omitted even when ``spi-rx-lane-map`` and
> >> +``spi-tx-lane-map`` are used.
This comment is enough to allow you to drop the first example entirely and
just have the 2nd.
Jonathan
> >
> >
> >
>
>
>
On 1/19/26 4:11 AM, Jonathan Cameron wrote: > On Fri, 16 Jan 2026 16:35:13 -0600 > David Lechner <dlechner@baylibre.com> wrote: > >> On 1/14/26 3:10 AM, Jonathan Cameron wrote: >>> On Mon, 12 Jan 2026 11:45:23 -0600 >>> David Lechner <dlechner@baylibre.com> wrote: >>> ... >>> Whilst simple I'd kind of expect a multi lane case as the example, or this and >>> the multilane one? For me the comment that follows is sufficient for the 1 lane >>> offset case you have here. >> >> I thought that is what I did. I have one example that shows multiple lanes (ADC) >> and one example that shows the map (Thing 1/2). >> >> But I guess you mean that you want a 3rd example that show both the map and >> multiple lanes at the same time? > Oops. No. I was arguing.... >> >> I chose these two examples because they came from real-world use cases that >> drove adding this feature. We didn't have a real-world case yet that used >> both the map and multiple lanes at the same time so I didn't include that. >> >>> >>>> + ... >>>> + }; >>>> + }; >>>> + >>>> + >>>> +The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``, >>>> +so these properties can still be omitted even when ``spi-rx-lane-map`` and >>>> +``spi-tx-lane-map`` are used. > > This comment is enough to allow you to drop the first example entirely and > just have the 2nd. > > Jonathan > I still like having two examples of real-world uses cases since they are solving two very different problems. It think combining these into one contrived example would make it more difficult to see that.
© 2016 - 2026 Red Hat, Inc.