MT-158113: imx8mm-evk-spi-transport devicetree overlay

Documentation/devicetree/bindings/spi/multitracks,spi-transport.yaml

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/multitracks,spi-transport.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MultiTracks SPI transport protocol (Host role)
+
+maintainers:
+  - Michael Loh <michael@multitracks.com>
+
+description: |
+  A framed, multi-channel, ack/retry link between an i.MX SoC (Host) and an
+  STM32-class client MCU (Client) over a raw SPI bus, plus a companion NRDY
+  GPIO handshake line in addition to the physical SPI SCK/MOSI/MISO lines.
+  See the firmware repo's firmware-common/spi-transport/docs/ProtocolSpec.md
+  for the full wire protocol.
+
+  NSS and NRDY are bound here as driver-private properties, not the
+  standard "cs-gpios" -- the protocol holds NSS low continuously across a
+  multi-step request/ack/clock/complete cycle, not just one SPI transfer,
+  so the driver owns and drives it directly rather than letting the SPI
+  core auto-toggle it per-message.
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+  compatible:
+    const: multitracks,spi-transport
+
+  reg:
+    maxItems: 1
+
+  multitracks,nss-gpios:
+    maxItems: 1
+    description:
+      Host-driven NSS (transfer request) line, held low across the whole
+      request/ack/clock/complete cycle. Always GPIO_ACTIVE_HIGH regardless
+      of the physical wire's true active sense, so the driver's logical
+      value always equals the literal pin level (the protocol's own
+      convention is "true = pin HIGH").
+
+  multitracks,nrdy-gpios:
+    maxItems: 1
+    description:
+      Client-driven NRDY (ready/ack) line, read by the Host. Same
+      GPIO_ACTIVE_HIGH convention as multitracks,nss-gpios.
+
+required:
+  - compatible
+  - reg
+  - spi-max-frequency
+  - multitracks,nss-gpios
+  - multitracks,nrdy-gpios
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        spi@0 {
+            compatible = "multitracks,spi-transport";
+            reg = <0>;
+            spi-max-frequency = <500000>;
+
+            multitracks,nss-gpios = <&gpio5 13 GPIO_ACTIVE_HIGH>;
+            multitracks,nrdy-gpios = <&gpio4 29 GPIO_ACTIVE_HIGH>;
+        };
+    };
+
+...

Documentation/devicetree/bindings/vendor-prefixes.yaml

@@ -912,6 +912,8 @@ patternProperties:
     description: Imagination Technologies Ltd. (formerly MIPS Technologies Inc.)
   "^multi-inno,.*":
     description: Multi-Inno Technology Co.,Ltd
+  "^multitracks,.*":
+    description: MultiTracks.com, LLC
   "^mundoreader,.*":
     description: Mundo Reader S.L.
   "^murata,.*":

arch/arm64/boot/dts/freescale/Makefile

@@ -75,6 +75,7 @@ dtb-$(CONFIG_ARCH_MXC) += imx8mm-ab2.dtb imx8mm-ab2-m4.dtb imx8mm-ddr4-ab2.dtb i
 dtb-$(CONFIG_ARCH_MXC) += imx8mm-evk.dtb imx8mm-evk-rpmsg.dtb imx8mm-evk-rm67191.dtb \
 			  imx8mm-evk-root.dtb imx8mm-evk-inmate.dtb imx8mm-evk-revb-qca-wifi.dtb \
 			  imx8mm-evk-ecspi-slave.dtb \
+			  imx8mm-evk-spi-transport.dtb \
 			  imx8mm-evk-pcie-ep.dtb \
 			  imx8mm-evk-usd-wifi.dtb \
 			  imx8mm-evk-qca-wifi.dtb \

arch/arm64/boot/dts/freescale/imx8mm-evk-spi-transport.dts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: GPL-2.0
+//
+// Copyright 2026 MultiTracks.com, LLC.
+//
+// MT-158113: binds the MultiTracks SPI transport driver (Host role) onto
+// ecspi2, mirroring the pins already used for this same purpose on the
+// mt-connect production board (mt-connect.dts) -- see
+// firmware/firmware-common/spi-transport/docs/ProtocolSpec.md for the wire
+// protocol and NSS/NRDY handshake this binds to real hardware.
+//
+// NSS/NRDY are bound here as driver-private "multitracks,nss-gpios"/
+// "multitracks,nrdy-gpios" properties, NOT the standard "cs-gpios" -- the
+// transport protocol holds
+// NSS low continuously across a multi-step request/ack/clock/complete
+// cycle, not just one SPI transfer, so the driver must own and drive it
+// directly rather than let the SPI core auto-toggle it per-message. Both
+// are declared GPIO_ACTIVE_HIGH regardless of the physical wire's true
+// active sense, so the driver's gpiod_get/set_value_cansleep() calls
+// always see the literal pin level, matching the protocol's own
+// "true = pin HIGH" convention (see drivers/spi/spi-mt-transport/
+// spi_transport_hw_linux.c).
+
+#include "imx8mm-evk.dts"
+
+/delete-node/ &spidev0;
+
+&ecspi2 {
+	/delete-property/ cs-gpios;
+	pinctrl-names = "default";
+	pinctrl-0 = <&pinctrl_ecspi2 &pinctrl_ecspi2_cs &pinctrl_ecspi2_nrdy>;
+
+	mt_transport0: spi@0 {
+		compatible = "multitracks,spi-transport";
+		reg = <0>;
+		spi-max-frequency = <500000>; /* matches mt-connect.dts -- back to the soak-tested-clean rate, MT-159369 */
+
+		multitracks,nss-gpios = <&gpio5 13 GPIO_ACTIVE_HIGH>;
+		multitracks,nrdy-gpios = <&gpio4 29 GPIO_ACTIVE_HIGH>;
+	};
+};
+
+&iomuxc {
+	pinctrl_ecspi2_nrdy: ecspi2nrdygrp {
+		fsl,pins = <
+			MX8MM_IOMUXC_SAI3_RXC_GPIO4_IO29		0x82
+		>;
+	};
+};

arch/arm64/boot/dts/freescale/mt-connect.dts

@@ -508,16 +508,33 @@
 	status = "okay";
 };
 
+/* MT-159369: binds the MultiTracks SPI transport driver (Host role),
+ * porting the binding already hardware-validated on imx8mm-evk-spi-transport.dts
+ * (MT-158113) back to this production board -- same NSS/NRDY pins
+ * (GPIO5_IO13 / GPIO4_IO29, this board's own SPI2_NSS / SPI2_INT pin
+ * names, per the gpio5/gpio4 gpio-line-names above), same reasoning for
+ * multitracks,nss-gpios replacing cs-gpios (the transport protocol holds
+ * NSS low across a multi-step request/ack/clock/complete cycle, not just
+ * one SPI transfer, so the driver must own and drive it directly rather
+ * than let the SPI core auto-toggle it per-message) and for declaring
+ * both driver-private GPIOs GPIO_ACTIVE_HIGH regardless of physical wire
+ * polarity (see drivers/spi/spi-mt-transport/spi_transport_hw_linux.c).
+ * pinctrl_ecspi2 below already covers both the NSS and INT pin muxes on
+ * this board (unlike the EVK, which needed separate overlay-added
+ * groups), so no pinctrl changes are needed here.
+ */
 &ecspi2 {
 	status = "okay";
 	pinctrl-names = "default";
 	pinctrl-0 = <&pinctrl_ecspi2>;
-	cs-gpios = <&gpio5 13 GPIO_ACTIVE_LOW>;
 
-	spidev1: spi@0 {
+	mt_transport0: spi@0 {
+		compatible = "multitracks,spi-transport";
 		reg = <0>;
-		compatible = "rohm,dh2228fv";
-		spi-max-frequency = <500000>;
+		spi-max-frequency = <500000>; /* MT-159369: back to the soak-tested-clean rate -- 10MHz and 4MHz both showed the same 100%-failure DMA-arm/CRC pattern with zero improvement, so this is isolating whether the issue is clock-rate-dependent at all before chasing it as a structural/framing bug instead */
+
+		multitracks,nss-gpios = <&gpio5 13 GPIO_ACTIVE_HIGH>;
+		multitracks,nrdy-gpios = <&gpio4 29 GPIO_ACTIVE_HIGH>;
 	};
 };
 

drivers/spi/Kconfig

@@ -1211,6 +1211,27 @@ config SPI_LOOPBACK_TEST
 	  primarily used for development of spi_master drivers
 	  and to detect regressions
 
+config SPI_MT_TRANSPORT
+	tristate "MultiTracks SPI transport protocol driver (Host role)"
+	# No COMPILE_TEST: this module's core/ subdirectory only exists once
+	# Yocto's meta-mt-transport-evk stages it in at build time (see this
+	# directory's Makefile) -- allmodconfig/allyesconfig CI builds outside
+	# that pipeline would hard-error on core/ being missing. Found by
+	# Copilot's PR #46 review.
+	depends on ARCH_MXC
+	depends on GPIOLIB
+	# Driver unconditionally registers dev_groups/DEVICE_ATTR_RO sysfs
+	# attributes and calls sysfs_emit() -- non-functional without SYSFS.
+	# Found by Copilot's PR #46 review.
+	depends on SYSFS
+	help
+	  Kernel Host-role port of the MultiTracks SPI transport protocol
+	  (see firmware repo firmware-common/spi-transport/) -- a framed,
+	  multi-channel, ack/retry link between an i.MX SoC (Host) and an
+	  STM32-class client MCU (Client) over a raw SPI bus, plus a
+	  companion NRDY GPIO handshake line in addition to the physical
+	  SPI SCK/MOSI/MISO/NSS lines.
+
 config SPI_TLE62X0
 	tristate "Infineon TLE62X0 (for power switching)"
 	depends on SYSFS

drivers/spi/Makefile

@@ -140,6 +140,7 @@ obj-$(CONFIG_SPI_TEGRA210_QUAD)		+= spi-tegra210-quad.o
 obj-$(CONFIG_SPI_TEGRA114)		+= spi-tegra114.o
 obj-$(CONFIG_SPI_TEGRA20_SFLASH)	+= spi-tegra20-sflash.o
 obj-$(CONFIG_SPI_TEGRA20_SLINK)		+= spi-tegra20-slink.o
+obj-$(CONFIG_SPI_MT_TRANSPORT)		+= spi-mt-transport/
 obj-$(CONFIG_SPI_TLE62X0)		+= spi-tle62x0.o
 spi-thunderx-objs			:= spi-cavium.o spi-cavium-thunderx.o
 obj-$(CONFIG_SPI_THUNDERX)		+= spi-thunderx.o

drivers/spi/spi-imx.c

@@ -1487,6 +1487,15 @@ static int spi_imx_dma_transfer(struct spi_imx_data *spi_imx,
 	struct scatterlist *last_sg = sg_last(rx->sgl, rx->nents);
 	unsigned int bytes_per_word, i;
 	int ret;
+	/* MT-159369 bring-up instrumentation: neither wait_for_completion below
+	 * verifies the DMA engine actually drained every byte it was asked to
+	 * move -- completion only means the channel's callback fired, not that
+	 * dma_rx_completion corresponds to a full-residue transfer. Capture
+	 * cookies here so residue can be checked against actual transfer->len
+	 * once both completions fire, to test whether short/partial RX DMA
+	 * completions are the source of the CRC-corruption investigation's
+	 * "correct wire data, wrong bytes in memory" symptom. */
+	dma_cookie_t rx_cookie, tx_cookie;
 
 	if ((is_imx51_ecspi(spi_imx) || is_imx53_ecspi(spi_imx)) &&
 	    transfer->len > MX53_MAX_TRANSFER_BYTES && spi_imx->target_mode) {
@@ -1532,7 +1541,17 @@ static int spi_imx_dma_transfer(struct spi_imx_data *spi_imx,
 
 	desc_rx->callback = spi_imx_dma_rx_callback;
 	desc_rx->callback_param = (void *)spi_imx;
-	dmaengine_submit(desc_rx);
+	rx_cookie = dmaengine_submit(desc_rx); /* MT-159369 bring-up instrumentation */
+	/* Nothing has been issued yet at this point (dma_async_issue_pending()
+	 * for either channel is still below) -- a failed submit here means
+	 * neither channel is actually in flight, so the plain no-cleanup
+	 * dma_failure_no_start path (same one desc_rx's own prep failure just
+	 * above already uses) is sufficient. Found by Copilot's PR #46 review.
+	 */
+	if (dma_submit_error(rx_cookie)) {
+		ret = rx_cookie;
+		goto dma_failure_no_start;
+	}
 	reinit_completion(&spi_imx->dma_rx_completion);
 	dma_async_issue_pending(controller->dma_rx);
 
@@ -1547,7 +1566,19 @@ static int spi_imx_dma_transfer(struct spi_imx_data *spi_imx,
 
 	desc_tx->callback = spi_imx_dma_tx_callback;
 	desc_tx->callback_param = (void *)spi_imx;
-	dmaengine_submit(desc_tx);
+	tx_cookie = dmaengine_submit(desc_tx); /* MT-159369 bring-up instrumentation */
+	/* Unlike the rx_cookie check above, RX is already submitted+issued by
+	 * this point -- a failed TX submit here must terminate both channels,
+	 * same as the desc_tx prep-failure case immediately above, not just
+	 * bail via dma_failure_no_start (which performs no channel cleanup and
+	 * would leak the already-in-flight RX DMA). Found by Copilot's PR #46
+	 * review.
+	 */
+	if (dma_submit_error(tx_cookie)) {
+		dmaengine_terminate_all(controller->dma_tx);
+		dmaengine_terminate_all(controller->dma_rx);
+		return tx_cookie;
+	}
 	reinit_completion(&spi_imx->dma_tx_completion);
 	dma_async_issue_pending(controller->dma_tx);
 
@@ -1574,6 +1605,41 @@ static int spi_imx_dma_transfer(struct spi_imx_data *spi_imx,
 			dmaengine_terminate_all(controller->dma_rx);
 			return -ETIMEDOUT;
 		}
+
+		/* MT-159369 bring-up instrumentation: both completions above
+		 * only prove each channel's callback fired -- neither proves
+		 * the engine actually drained transfer->len bytes. Check
+		 * residue directly; a nonzero value here would mean the RX/TX
+		 * buffer genuinely has fewer real bytes than the rest of this
+		 * driver assumes, direct evidence for (or against) the
+		 * CRC-corruption investigation's short-DMA-completion theory. */
+		{
+			struct dma_tx_state rx_state, tx_state;
+			enum dma_status rx_dma_status, tx_dma_status;
+
+			rx_dma_status = dmaengine_tx_status(controller->dma_rx, rx_cookie,
+							     &rx_state);
+			tx_dma_status = dmaengine_tx_status(controller->dma_tx, tx_cookie,
+							     &tx_state);
+
+			/* Ratelimited: this runs on every non-target-mode DMA
+			 * transfer, so during a real link-quality storm it's the
+			 * same unthrottled-hot-path-logging mechanism that
+			 * commit d5d1f5736d2 already fixed for
+			 * mt_transport_event_callback() (the confirmed cause of
+			 * the MT-159369 boot-time hang) -- this dev_err() was
+			 * missed by that pass. Found by Copilot's PR #46 review.
+			 */
+			if (rx_state.residue != 0 || tx_state.residue != 0)
+				dev_err_ratelimited(spi_imx->dev,
+					"[MT-159369] DMA residue nonzero after completion: rx_status=%d rx_residue=%u tx_status=%d tx_residue=%u len=%u\n",
+					rx_dma_status, rx_state.residue,
+					tx_dma_status, tx_state.residue, transfer->len);
+			else
+				dev_dbg(spi_imx->dev,
+					"[MT-159369] DMA residue clean: len=%u\n",
+					transfer->len);
+		}
 	} else {
 		spi_imx->target_aborted = false;
 

drivers/spi/spi-mt-transport/.gitignore

@@ -0,0 +1,5 @@
+# core/ is the portable SPI transport protocol core -- single source of
+# truth lives in the firmware repo (firmware-common/spi-transport/), staged
+# here at Yocto build time (see imx8mmini-bb-evk's meta-mt-transport-evk
+# linux-imx_%.bbappend), never committed into this repo.
+core/

drivers/spi/spi-mt-transport/Makefile

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# IMPORTANT -- this module only builds inside the imx8mmini-bb-evk Yocto BSP
+# pipeline, not from a plain checkout of this kernel tree built directly
+# (e.g. a bare `make -C . M=drivers/spi/spi-mt-transport modules`). The
+# core/ referenced below is deliberately NOT committed to this repo (see
+# core/'s absence and the .gitignore in this directory) -- it's the
+# portable protocol core, whose single source of truth is the firmware
+# repo's firmware-common/spi-transport/{src,inc}/. Yocto's
+# meta-mt-transport-evk/recipes-kernel/linux-imx/linux-imx_%.bbappend
+# fetches it separately and stages it into core/ via a do_patch[postfuncs]
+# hook *before* this Makefile ever runs. This Makefile is only ever
+# evaluated when CONFIG_SPI_MT_TRANSPORT is already enabled (Kbuild only
+# descends here via drivers/spi/Makefile's obj-$(CONFIG_SPI_MT_TRANSPORT)
+# line), so the check below fires exactly when it matters and fails fast
+# with a clear message instead of the opaque "No rule to make target
+# core/spi_transport.o" a missing core/ would otherwise produce deep in
+# the build.
+# $(src) alone resolves against $(objtree) under Yocto's out-of-tree (O=)
+# kernel builds, same reason the ccflags-y line below needs the
+# $(srctree)/ prefix -- this check needs it too, or it always reports
+# core/ missing even when it's genuinely staged (confirmed via a real
+# false-positive build failure without this prefix).
+ifeq ($(wildcard $(srctree)/$(src)/core/spi_transport.c),)
+$(error spi-mt-transport: core/ is not staged. This module only builds inside \
+	the imx8mmini-bb-evk Yocto BSP pipeline, which fetches the portable \
+	protocol core from the firmware repo and stages it into core/ before \
+	this Makefile runs -- build via bitbake, not a plain kernel checkout)
+endif
+
+obj-$(CONFIG_SPI_MT_TRANSPORT) += spi-mt-transport.o
+spi-mt-transport-y := \
+	core/spi_transport.o \
+	core/spi_transport_channel.o \
+	core/spi_transport_frame.o \
+	core/spi_transport_crc16.o \
+	core/spi_transport_hw.o \
+	spi_transport_os_linux.o \
+	spi_transport_hw_linux.o \
+	spi_mt_transport_drv.o
+
+# $(src) alone resolves against $(objtree) under Yocto's out-of-tree (O=)
+# kernel builds; these headers only exist in the source tree, so the
+# $(srctree)/ prefix is required or the compile can't find them.
+ccflags-y += -I$(srctree)/$(src)/kernel-compat -I$(srctree)/$(src)/core/include

drivers/spi/spi-mt-transport/kernel-compat/stdarg.h

@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Compat shim only -- NOT part of the portable core (../../../.. relative to here).
+ *
+ * The portable core targets hosted C11, so it includes the standard
+ * <stdarg.h>. Under the kernel's -nostdinc build this cross-compiler's own
+ * freestanding headers aren't on the search path either, so <stdarg.h>
+ * doesn't resolve at all -- linux/stdarg.h is the kernel's own sanctioned
+ * replacement for exactly this case. Only reached via this module's own
+ * Makefile (ccflags-y += -I$(src)/kernel-compat), so it
+ * cannot shadow <stdarg.h> anywhere else in the kernel tree.
+ */
+#include <linux/stdarg.h>

drivers/spi/spi-mt-transport/kernel-compat/stdbool.h

@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Compat shim only -- NOT part of the portable core (../../../.. relative to here).
+ *
+ * The portable core targets hosted C11, so it includes the standard
+ * <stdbool.h> for bool/true/false. Under the kernel's -nostdinc build this
+ * cross-compiler's own freestanding headers aren't on the search path
+ * either, so <stdbool.h> doesn't resolve at all. linux/types.h (bool) and
+ * linux/stddef.h (true/false) are the kernel's equivalents. Only reached via
+ * this module's own Makefile (ccflags-y += -I$(src)/kernel-compat),
+ * so it cannot shadow <stdbool.h> anywhere else in the kernel tree.
+ */
+#include <linux/stddef.h>
+#include <linux/types.h>