mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: "Stefan Dösinger" <stefandoesinger@gmail.com>
To: "Rob Herring" <robh@kernel.org>,
	"Krzysztof Kozlowski" <krzk+dt@kernel.org>,
	"Conor Dooley" <conor+dt@kernel.org>,
	"Stefan Dösinger" <stefandoesinger@gmail.com>,
	"Philipp Zabel" <p.zabel@pengutronix.de>,
	"Lee Jones" <lee@kernel.org>, "Ulf Hansson" <ulfh@kernel.org>,
	"Vinod Koul" <vkoul@kernel.org>,
	"Neil Armstrong" <neil.armstrong@linaro.org>,
	"Manivannan Sadhasivam" <mani@kernel.org>,
	"Agustin Santiago Isasmendi" <isasmendi.agus@gmail.com>,
	"Navid Ghahremani" <ghahramani.navid@gmail.com>
Cc: devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
	 linux-arm-kernel@lists.infradead.org, mfd@lists.linux.dev,
	 linux-pm@vger.kernel.org, linux-phy@lists.infradead.org
Subject: [PATCH 1/6] dt-bindings: soc: zte: Document zx297520v3 socsys controller
Date: Fri, 20 Nov 2026 22:20:50 +0300	[thread overview]
Message-ID: <20261120-zx29usb-v1-1-b0433258e51b@gmail.com> (raw)
In-Reply-To: <20261120-zx29usb-v1-0-b0433258e51b@gmail.com>

The best way to sum up this controller is probably "misc". ZTE probably
put everything they didn't bother to put in its own mmio area here.
Documentation in ZTE's sources is very sparse and even the blobs only
touch a handful of registers.

The controller contains power controls, resets, DMA multiplexing,
auxiliary USB phy controls, i2s controls, the proprietary DSP boot
address and many others.

For power controls I could confirm that the USB/HSIC and a GSM-related
controls work. There are 5 bits mentioned in ZTE's kernel though and
there is a second register that is used in a very similar fashion by the
LTE blob.

For the Ethernet PHY reset register there are 5 settable bits,
but only one of them produces an understood effect. I am using
reset-cells=1 because it is likely some of the other bits have an actual
meaning.

Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>

---

ZTE uses the name "SOC_SYS" in their downstream kernel. I am not
particularly thrilled by that name, but couldn't come up with a better
one yet. I am open to suggestions

I do not want to commit to exposing the GSM related bits as power
domains just yet, so no handle for them is defined in this binding. They
are inside the RST/ISO/PWR registers just like their USB counterpart,
but the PWR bit does nothing and the client driver will have to assert
and deassert the reset to wake up the hardware. This is easier to do
with a reset controller than a power domain. The ISO bit kinda works
though, so I can't just pretend they are standalone resets.

The hardware behind the GSM bits has a self-arming watchdog. After
2.5ms it puts itself into a broken state and can only be recovered by
asserting and deasserting the reset in socsys. Like almost everything on
this board it is enabled on boot, so the client driver needs to assert
and deassert the reset before touching it.

How much documentation is appropriate in the binding .yaml? I want to
document the identified registers *somewhere*, and since the yaml lives
in Documentation/ I put it there. I do understand though if the Linux
kernel doesn't want to be a backup SoC datasheet.
---
 .../bindings/soc/zte/zte,zx297520v3-socsys.yaml    | 100 +++++++++++++++++++++
 MAINTAINERS                                        |   1 +
 include/dt-bindings/power/zte,zx297520v3-socsys.h  |  11 +++
 include/dt-bindings/reset/zte,zx297520v3-reset.h   |   2 +
 4 files changed, 114 insertions(+)

diff --git a/Documentation/devicetree/bindings/soc/zte/zte,zx297520v3-socsys.yaml b/Documentation/devicetree/bindings/soc/zte/zte,zx297520v3-socsys.yaml
new file mode 100644
index 000000000000..094409c72333
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/zte/zte,zx297520v3-socsys.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/soc/zte/zte,zx297520v3-socsys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ZTE zx297520v3 SoC miscellaneous system controller
+
+maintainers:
+  - Stefan Dösinger <stefandoesinger@gmail.com>
+
+description: |
+  This controller contains registers controlling numerous components of the
+  zx297520v3 board. It is poorly documented by sources available from ZTE.
+  Information about it has mostly been deduced by experimental testing.
+
+  The device contains power controls for USB and at least parts of the GSM/LTE
+  stack, a reset control for the Ethernet PHY, DMA multiplexing, I2S controls
+  and additional (beyond power) USB PHY and controller flags. To round it out it
+  also contains a flag to bring up the SoC's Cortex A53 CPU in arm64 instead of
+  arm32 mode.
+
+  The "include/dt-bindings/reset/zte,zx297520v3-reset.h" header contains reset
+  defines for this device. "dt-bindings/power/zte,zx297520v3-socsys.h" contains
+  the power domain defines.
+
+  The following registers are mentioned in ZTE's kernel and U-Boot code dumps:
+  0x0:
+    Bit 23: Boot ROM and sram2 remap
+  0x20:
+    Bit 13: A USB control "USB PHY COMMONONN", but without noticeable effect
+  0x40:
+    A mailbox system to read DDR mode registers
+  0x60:
+    I2S configuration
+  0x10c, 0x110, 0x114:
+    Power domain controls: RST (Reset), ISO (Bus isolation) and POWERON. ZTE
+    names devices "RAM", "DSP", "EDCP", "USB" and "HSIC".
+  0x120:
+    DMA channel multiplexing
+  0x150:
+    Ethernet PHY reset
+
+  The following registers are used in ZTE's power management and LTE blobs:
+  0x14:
+    Likely the ZSP rproc entrypoint
+  0x180, 0x184, 0x188:
+    Likely more power domain controls for LTE hardware
+
+  The following have been deduced by testing:
+  0x20:
+    USB PHY and DWC2 controller controls:
+      Bit 0: Force PHY into USB 1 mode
+      Bit 1: Unknown
+      Bit 2: DWC2 controller endianness
+      Bit 3: DWC2 DMA endianness
+      Bits 7:4: PHY clock adjustments
+      Bits 9:8: PHY electrical configuration. Setting them both to 1 allows
+                operating in host mode.
+  0x24:
+    More USB controls of unknown nature
+  0x2c:
+    HSIC controls mirroring the USB controls in 0x20
+  0xbc:
+    A53 mode controls. Setting bit 0 enables arm64 mode, others have no observable effect
+
+properties:
+  compatible:
+    items:
+      - const: zte,zx297520v3-socsys
+      - const: syscon
+
+  reg:
+    maxItems: 1
+
+  "#power-domain-cells":
+    const: 1
+
+  "#reset-cells":
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - "#power-domain-cells"
+  - "#reset-cells"
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/power/zte,zx297520v3-socsys.h>
+    #include <dt-bindings/reset/zte,zx297520v3-reset.h>
+
+    syscon@140000 {
+        compatible = "zte,zx297520v3-socsys", "syscon";
+        reg = <0x00140000 0x400>;
+        #power-domain-cells = <1>;
+        #reset-cells = <1>;
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index 9b6a2da28aa5..ab8797b8d0a5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4033,6 +4033,7 @@ F:	Documentation/devicetree/bindings/arm/zte.yaml
 F:	Documentation/devicetree/bindings/clock/zte,zx297520v3-lspcrm.yaml
 F:	Documentation/devicetree/bindings/clock/zte,zx297520v3-matrixcrm.yaml
 F:	Documentation/devicetree/bindings/clock/zte,zx297520v3-topcrm.yaml
+F:	Documentation/devicetree/bindings/soc/zte/zte,zx297520v3-socsys.yaml
 F:	arch/arm/boot/dts/zte/
 F:	arch/arm/mach-zte/
 F:	drivers/clk/zte/
diff --git a/include/dt-bindings/power/zte,zx297520v3-socsys.h b/include/dt-bindings/power/zte,zx297520v3-socsys.h
new file mode 100644
index 000000000000..fb54e5deea2a
--- /dev/null
+++ b/include/dt-bindings/power/zte,zx297520v3-socsys.h
@@ -0,0 +1,11 @@
+/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
+/*
+ * Copyright (C) Stefan Dösinger
+ */
+
+#ifndef __DT_BINDINGS_POWER_ZTE_ZX297520V3_SOCSYS_H
+#define __DT_BINDINGS_POWER_ZTE_ZX297520V3_SOCSYS_H
+
+#define ZX297520V3_PD_USB	0
+
+#endif /* __DT_BINDINGS_POWER_ZTE_ZX297520V3_SOCSYS_H */
diff --git a/include/dt-bindings/reset/zte,zx297520v3-reset.h b/include/dt-bindings/reset/zte,zx297520v3-reset.h
index b21d5901a7b9..7146e479695a 100644
--- a/include/dt-bindings/reset/zte,zx297520v3-reset.h
+++ b/include/dt-bindings/reset/zte,zx297520v3-reset.h
@@ -59,4 +59,6 @@
 #define ZX297520V3_TIMER_L11_RESET		16
 #define ZX297520V3_TDM_RESET			17
 
+#define ZX297520V3_ETH_PHY_RESET		0
+
 #endif /* __DT_BINDINGS_RESET_ZX297520V3_H */

-- 
2.56.1


  reply	other threads:[~2026-11-20 19:21 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
2026-11-20 19:20 ` Stefan Dösinger [this message]
2026-11-20 19:20 ` [PATCH 2/6] mfd: zx297520v3: Add socsys to the mfd host driver Stefan Dösinger
2026-11-20 19:20 ` [PATCH 3/6] pmdomain: zte: Add a zx297520v3 power domain driver Stefan Dösinger
2026-11-20 19:20 ` [PATCH 4/6] phy: zte: Add a zx29 USB PHY driver Stefan Dösinger
2026-11-20 19:20 ` [PATCH 5/6] ARM: dts: zte: Declare nodes to enable the board's dwc2 controller Stefan Dösinger
2026-11-20 19:20 ` [PATCH 6/6] ARM: dts: zte: Declare the HSIC controller node Stefan Dösinger

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261120-zx29usb-v1-1-b0433258e51b@gmail.com \
    --to=stefandoesinger@gmail.com \
    --cc=conor+dt@kernel.org \
    --cc=devicetree@vger.kernel.org \
    --cc=ghahramani.navid@gmail.com \
    --cc=isasmendi.agus@gmail.com \
    --cc=krzk+dt@kernel.org \
    --cc=lee@kernel.org \
    --cc=linux-arm-kernel@lists.infradead.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-phy@lists.infradead.org \
    --cc=linux-pm@vger.kernel.org \
    --cc=mani@kernel.org \
    --cc=mfd@lists.linux.dev \
    --cc=neil.armstrong@linaro.org \
    --cc=p.zabel@pengutronix.de \
    --cc=robh@kernel.org \
    --cc=ulfh@kernel.org \
    --cc=vkoul@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®