[PATCH 4/6] spi: Documentation: multiple-data-lanes: describe rx and tx lane mask

[Jonathan Santos]

Document that when either rx_lane_mask or tx_lane_mask is non-zero, STRIPE
operates only over the active lanes indicated by the mask. The transfer
buffer must be sized as a multiple of the active lane count rather than
the total lane count.

To maintain backwards compatibility, when both masks are zero, the default
behavior is to enable all lanes.

Signed-off-by: Jonathan Santos <Jonathan.Santos@xxxxxxxxxx>
---
 Documentation/spi/multiple-data-lanes.rst | 30 +++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/spi/multiple-data-lanes.rst b/Documentation/spi/multiple-data-lanes.rst
index 69cb532d052f..578a6a8e4380 100644
--- a/Documentation/spi/multiple-data-lanes.rst
+++ b/Documentation/spi/multiple-data-lanes.rst
@@ -200,6 +200,36 @@ The possible values for this field have the following semantics:
     After the transfer, ``rx_buf[0] == 0x11`` (word from SDO 0) and
     ``rx_buf[1] == 0x88`` (word from SDO 1).
 
+    When ``rx_lane_mask`` or ``tx_lane_mask`` is set, STRIPE operates over
+    active lanes only. Buffer size must be sized as a multiple of the number
+    of active lanes, not the total number of lanes. The mask must be a subset
+    of the total lanes, bits that correspond to lanes not defined for the device
+    are ignored. When ``rx_lane_mask`` or ``tx_lane_mask`` is set to zero, all
+    lanes are considered active.
+
+    Example::
+
+        struct spi_transfer xfer = {
+            .rx_buf = rx_buf,
+            .len = 2,
+            .multi_lane_mode = SPI_MULTI_BUS_MODE_STRIPE,
+            .rx_lane_mask = 0x0A, /* only lanes 1 and 3 are active */
+        };
+
+        spi_sync_transfer(spi, &xfer, 1);
+
+    Each rx wire has a different data word sent simultaneously::
+
+        controller    < data bits <     peripheral
+        ----------   ----------------   ----------
+            SDI 0    1-1-0-1-0-1-1-0    SDO 0
+            SDI 1    0-1-1-0-0-1-0-1    SDO 1
+            SDI 2    1-0-1-1-0-0-1-1    SDO 2
+            SDI 3    0-0-1-0-1-1-0-1    SDO 3
+
+    After the transfer, ``rx_buf[0] == 0x65`` (word from SDO 1) and
+    ``rx_buf[1] == 0x2D`` (word from SDO 3).
+
 
 -----------------------------
 SPI controller driver support
-- 
2.34.1