Re: [PATCH v5 5/9] spi: Documentation: add page on multi-lane support

[Jonathan Cameron <jonathan.cameron@huawei.com>]

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

> > 
> > 
> >   
> 
> 
>