[PATCH 1/9] dt-bindings: bus: Add SpacemiT K3 eSPI controller

From: Wang Yang

Date: Wed Nov 18 2026 - 03:58:08 EST


Describe the K3 eSPI controller and its peripheral memory translation
window, clocks, resets and link configuration. The EC uses this memory
window rather than the ordinary SPI transfer interface.

The controller implementation is carried as a separate prerequisite so
that the hardware vendor can review it independently.

Prepared with Codex assistance from the existing DC-linux EC support.

Signed-off-by: Wang Yang <yang.wang@xxxxxxxxxxxxxxxx>
---
.../bindings/bus/spacemit,k3-espi.yaml | 146 ++++++++++++++++++
1 file changed, 146 insertions(+)
create mode 100644 Documentation/devicetree/bindings/bus/spacemit,k3-espi.yaml

diff --git a/Documentation/devicetree/bindings/bus/spacemit,k3-espi.yaml b/Documentation/devicetree/bindings/bus/spacemit,k3-espi.yaml
new file mode 100644
index 000000000..30985ee0a
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/spacemit,k3-espi.yaml
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/spacemit,k3-espi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SpacemiT K3 eSPI controller
+
+maintainers:
+ - Yixun Lan <dlan@xxxxxxxxxx>
+
+description: |
+ The K3 eSPI controller connects the application processor to an embedded
+ controller. Child registers are accessed through a peripheral shared-memory
+ window, translated by ranges. The controller manages clocks, resets and
+ channel negotiation, including link recovery after an EC reboot.
+
+properties:
+ compatible:
+ const: spacemit,k3-espi
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ ranges:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Serial clock source
+ - description: Serial clock
+ - description: Bus clock
+
+ clock-names:
+ items:
+ - const: sclk_src
+ - const: sclk
+ - const: mclk
+
+ resets:
+ items:
+ - description: Bus reset
+ - description: Serial clock reset
+
+ pr-mem-base0:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: First peripheral memory translation base.
+
+ pr-mem-base1:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Second peripheral memory translation base.
+
+ operating-frequency:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Requested link clock frequency in MHz.
+ enum: [20, 25, 33, 50, 66]
+ default: 20
+
+ io-mode:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Requested number of eSPI data lines.
+ enum: [single, dual, quad]
+ default: single
+
+ alert-mode:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Use the shared IO1 line or the dedicated alert pin.
+ enum: [io1, pin]
+ default: io1
+
+ alert-type:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Electrical mode of the dedicated alert pin.
+ enum: [open-drain, push-pull]
+ default: open-drain
+
+ watchdog-timeout:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Controller watchdog counter value.
+ maximum: 65535
+ default: 65535
+
+ crc-enable:
+ type: boolean
+ description: Enable link CRC checking.
+
+ auto-gating-enable:
+ type: boolean
+ description: Enable automatic controller clock gating.
+
+ peripheral-channel-enable:
+ type: boolean
+ description: Enable the peripheral channel.
+
+ vwire-channel-enable:
+ type: boolean
+ description: Enable the virtual-wire channel.
+
+ oob-channel-enable:
+ type: boolean
+ description: Enable the out-of-band channel.
+
+ flash-channel-enable:
+ type: boolean
+ description: Enable the flash access channel.
+
+patternProperties:
+ '^ec@[0-9a-f]+$':
+ $ref: /schemas/embedded-controller/google,cros-ec.yaml#
+
+required:
+ - compatible
+ - reg
+ - '#address-cells'
+ - '#size-cells'
+ - ranges
+ - clocks
+ - clock-names
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/spacemit,k3-clocks.h>
+ #include <dt-bindings/reset/spacemit,k3-resets.h>
+
+ espi@cac8c000 {
+ compatible = "spacemit,k3-espi";
+ reg = <0xcac8c000 0x1000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0 0x84000000 0x1000>;
+ clocks = <&syscon_apmu CLK_APMU_ESPI_SCLK_SRC>,
+ <&syscon_apmu CLK_APMU_ESPI_SCLK>,
+ <&syscon_apmu CLK_APMU_ESPI_MCLK>;
+ clock-names = "sclk_src", "sclk", "mclk";
+ resets = <&syscon_apmu RESET_APMU_ESPI_MCLK>,
+ <&syscon_apmu RESET_APMU_ESPI_SCLK>;
+ };

base-commit: 749a4de370409464cf8501ec5b2451df45c84eb4
--
2.43.0