1==================================== 2SPI devices with multiple data lanes 3==================================== 4 5Some specialized SPI controllers and peripherals support multiple data lanes 6that allow reading more than one word at a time in parallel. This is different 7from dual/quad/octal SPI where multiple bits of a single word are transferred 8simultaneously. 9 10For example, controllers that support parallel flash memories have this feature 11as do some simultaneous-sampling ADCs where each channel has its own data lane. 12 13--------------------- 14Describing the wiring 15--------------------- 16 17The ``spi-tx-bus-width`` and ``spi-rx-bus-width`` properties in the devicetree 18are used to describe how many data lanes are connected between the controller 19and how wide each lane is. The number of items in the array indicates how many 20lanes there are, and the value of each item indicates how many bits wide that 21lane is. 22 23For example, a dual-simultaneous-sampling ADC with two 4-bit lanes might be 24wired 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 46It 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 62In most cases, lanes will be wired up symmetrically (A to A, B to B, etc). If 63this isn't the case, extra ``spi-rx-lane-map`` and ``spi-tx-lane-map`` 64properties are needed to provide a mapping between controller lanes and the 65physical lane wires. 66 67Here is an example where a multi-lane SPI controller has each lane wired to 68separate 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 91This 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 115The default values of ``spi-rx-bus-width`` and ``spi-tx-bus-width`` are ``<1>``, 116so these properties can still be omitted even when ``spi-rx-lane-map`` and 117``spi-tx-lane-map`` are used. 118 119---------------------------- 120Usage in a peripheral driver 121---------------------------- 122 123These types of SPI controllers generally do not support arbitrary use of the 124multiple lanes. Instead, they operate in one of a few defined modes. Peripheral 125drivers should set the :c:type:`struct spi_transfer.multi_lane_mode <spi_transfer>` 126field to indicate which mode they want to use for a given transfer. 127 128The 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----------------------------- 205SPI controller driver support 206----------------------------- 207 208To support multiple data lanes, SPI controller drivers need to set 209:c:type:`struct spi_controller.num_data_lanes <spi_controller>` to a value 210greater than 1. 211 212Then 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 214the appropriate behavior for each supported mode and return an error for 215unsupported modes. 216 217The core SPI code should handle the rest. 218