* [PATCH 1/6] dt-bindings: soc: zte: Document zx297520v3 socsys controller
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
@ 2026-11-20 19:20 ` Stefan Dösinger
2026-11-20 19:20 ` [PATCH 2/6] mfd: zx297520v3: Add socsys to the mfd host driver Stefan Dösinger
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
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
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 2/6] mfd: zx297520v3: Add socsys to the mfd host driver
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
2026-11-20 19:20 ` [PATCH 1/6] dt-bindings: soc: zte: Document zx297520v3 socsys controller Stefan Dösinger
@ 2026-11-20 19:20 ` Stefan Dösinger
2026-11-20 19:20 ` [PATCH 3/6] pmdomain: zte: Add a zx297520v3 power domain driver Stefan Dösinger
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
This patch adds the parts of the zx297520v3 socsys controller, that can
be exposed via established driver APIs to the MFD host driver, so that
drivers in the respective subsystems can consume them. For now these are
a reset controller for Ethernet and maybe more, and a power domain
controller for USB, GSM and possibly a cryptographic engine.
Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>
---
This series does not contain a driver for the reset child, as
implementing Ethernet is beyond the scope of the series and needs other
prerequisites (namely pincontrol).
---
drivers/mfd/zte-zx297520v3-crm.c | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/drivers/mfd/zte-zx297520v3-crm.c b/drivers/mfd/zte-zx297520v3-crm.c
index 7c29a860be3f..3d542e3dd7b8 100644
--- a/drivers/mfd/zte-zx297520v3-crm.c
+++ b/drivers/mfd/zte-zx297520v3-crm.c
@@ -23,6 +23,7 @@ enum zx_device_type {
TYPE_TOPCRM,
TYPE_MATRIXCRM,
TYPE_LSPCRM,
+ TYPE_SOCSYS,
};
static const struct mfd_cell zx297520v3_topcrm_cells[] = {
@@ -42,6 +43,11 @@ static const struct mfd_cell zx297520v3_lspcrm_cells[] = {
MFD_CELL_NAME("zx297520v3-lspreset"),
};
+static const struct mfd_cell zx297520v3_socsys_cells[] = {
+ MFD_CELL_NAME("zx297520v3-socsys-reset"),
+ MFD_CELL_NAME("zx297520v3-socsys-power"),
+};
+
static int zx297520v3_crm_probe(struct platform_device *pdev)
{
struct device *dev = &pdev->dev;
@@ -77,6 +83,11 @@ static int zx297520v3_crm_probe(struct platform_device *pdev)
"Failed to deassert reset control\n");
break;
+ case TYPE_SOCSYS:
+ cells = zx297520v3_socsys_cells;
+ num_cells = ARRAY_SIZE(zx297520v3_socsys_cells);
+ break;
+
default:
return -ENODEV;
}
@@ -88,6 +99,7 @@ static const struct of_device_id of_match_zx297520v3_crm[] = {
{ .compatible = "zte,zx297520v3-topcrm", .data = (void *)TYPE_TOPCRM },
{ .compatible = "zte,zx297520v3-matrixcrm", .data = (void *)TYPE_MATRIXCRM },
{ .compatible = "zte,zx297520v3-lspcrm", .data = (void *)TYPE_LSPCRM },
+ { .compatible = "zte,zx297520v3-socsys", .data = (void *)TYPE_SOCSYS },
{ }
};
MODULE_DEVICE_TABLE(of, of_match_zx297520v3_crm);
--
2.56.1
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 3/6] pmdomain: zte: Add a zx297520v3 power domain driver
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
2026-11-20 19:20 ` [PATCH 1/6] dt-bindings: soc: zte: Document zx297520v3 socsys controller Stefan Dösinger
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 ` Stefan Dösinger
2026-11-20 19:20 ` [PATCH 4/6] phy: zte: Add a zx29 USB PHY driver Stefan Dösinger
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
This controller has bits for USB, HSIC, EDCP (a cryptographic engine)
and GSM. Not all of them work the way one might expect (see comments in
the code), but they are there and can be set.
Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>
---
For now this driver can only enable and disable the USB controller. I
expect more LTE related power switches will be added later, but I don't
want to commit to how I expose GSM and EDCP in the bindings just yet.
---
MAINTAINERS | 1 +
drivers/pmdomain/Kconfig | 1 +
drivers/pmdomain/Makefile | 1 +
drivers/pmdomain/zte/Kconfig | 15 ++
drivers/pmdomain/zte/Makefile | 2 +
drivers/pmdomain/zte/zx297520v3-pm-domain.c | 286 ++++++++++++++++++++++++++++
6 files changed, 306 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index ab8797b8d0a5..e394e0044f1f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4038,6 +4038,7 @@ F: arch/arm/boot/dts/zte/
F: arch/arm/mach-zte/
F: drivers/clk/zte/
F: drivers/mfd/zte-zx297520v3-crm.c
+F: drivers/pmdomain/zte/
F: include/dt-bindings/clock/zte,zx297520v3-clk.h
F: include/dt-bindings/phy/zte,zx297520v3-topcrm.h
F: include/dt-bindings/reset/zte,zx297520v3-reset.h
diff --git a/drivers/pmdomain/Kconfig b/drivers/pmdomain/Kconfig
index 5341dff669be..d5050c22f064 100644
--- a/drivers/pmdomain/Kconfig
+++ b/drivers/pmdomain/Kconfig
@@ -21,5 +21,6 @@ source "drivers/pmdomain/tegra/Kconfig"
source "drivers/pmdomain/thead/Kconfig"
source "drivers/pmdomain/ti/Kconfig"
source "drivers/pmdomain/xilinx/Kconfig"
+source "drivers/pmdomain/zte/Kconfig"
endmenu
diff --git a/drivers/pmdomain/Makefile b/drivers/pmdomain/Makefile
index d7aee13ae571..cc3cc7b3d1c2 100644
--- a/drivers/pmdomain/Makefile
+++ b/drivers/pmdomain/Makefile
@@ -19,4 +19,5 @@ obj-y += tegra/
obj-y += thead/
obj-y += ti/
obj-y += xilinx/
+obj-y += zte/
obj-y += core.o governor.o
diff --git a/drivers/pmdomain/zte/Kconfig b/drivers/pmdomain/zte/Kconfig
new file mode 100644
index 000000000000..cc329d085e5a
--- /dev/null
+++ b/drivers/pmdomain/zte/Kconfig
@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: GPL-2.0-only
+
+config ZTE_ZX297520V3_PM_DOMAIN
+ tristate "ZTE zx297520v3 pm domain"
+ depends on HAS_IOMEM
+ depends on PM
+ depends on MFD_ZTE_ZX297520V3_CRM || COMPILE_TEST
+ default SOC_ZX297520V3
+ select PM_GENERIC_DOMAINS
+ select MFD_SYSCON
+ help
+ Say y to enable the power domain driver for ZTE zx297520v3 boards.
+ This driver is necessary to enable the USB hardware found on this
+ board. Say y or m if you are building a kernel for a zx297520v3 based
+ device and plan to use its USB capabilities.
diff --git a/drivers/pmdomain/zte/Makefile b/drivers/pmdomain/zte/Makefile
new file mode 100644
index 000000000000..8a4185f48ff3
--- /dev/null
+++ b/drivers/pmdomain/zte/Makefile
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: GPL-2.0-only
+obj-$(CONFIG_ZTE_ZX297520V3_PM_DOMAIN) += zx297520v3-pm-domain.o
diff --git a/drivers/pmdomain/zte/zx297520v3-pm-domain.c b/drivers/pmdomain/zte/zx297520v3-pm-domain.c
new file mode 100644
index 000000000000..3df4cd5f1b22
--- /dev/null
+++ b/drivers/pmdomain/zte/zx297520v3-pm-domain.c
@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (C) 2026 Stefan Dösinger
+ *
+ * This driver controls power domain registers found on the ZTE zx297520v3 board. The USB and GSM
+ * controllers are controlled from here.
+ */
+
+#include <linux/delay.h>
+#include <linux/mfd/syscon.h>
+#include <linux/module.h>
+#include <linux/of.h>
+#include <linux/platform_device.h>
+#include <linux/pm_domain.h>
+#include <linux/regmap.h>
+
+static const struct {
+ const char *name;
+ u32 reg;
+ u32 mask;
+} power_domains[] = {
+ /* ZTE's kernel defines the following power controls in 0x10c-0x114:
+ *
+ * Name Bit
+ * GSM_RAM 0
+ * GSM_DSP 1
+ * EDCP 4
+ * USB_CTRL 8
+ * USB_HSIC 9
+ *
+ * But the names are wrong/misleading.
+ *
+ * For USB, bit 9 appears to control both HSIC and USB, except for the isolation register,
+ * where setting either bit 8 or bit 9 zeroes both of their address space. So we expose
+ * one power domain that controls both bits.
+ *
+ * Bit 1 isolates and resets the mmio area from 0xf4000000-0xf7000000. The device behind it
+ * is an Infineon PMB887x GSM controller derivate. The power bit doesn't appear to turn it
+ * off, and it remains unset by the stock firmware. The reset works and the driver for this
+ * hardware needs to assert and deassert it to wake it up on boot. The isolation bit 1
+ * works, but only once the GSM hardware is properly booted - if the GSM chip doesn't
+ * respond, and isolation is enabled, attempts to access this area nevertheless stall the
+ * bus.
+ *
+ * Bit 0 controls the TeakLite DSP on the PMB887x.
+ *
+ * The functionality of bit 4 is not understood yet. The "EDCP" hardware seems to be a
+ * cryptographic engine implementing PDCP and some hash functions.
+ */
+
+ {"usb", 0x10c, BIT(8) | BIT(9)},
+
+ /* There is a separate set of registers in 0x180 - 0x188 that accepts 4 bits (0, 1, 6, 7)
+ * and is controlled by the cpko.ko blob in the same way as 0x10c-0x114 is controlled by
+ * the USB driver: LTE on: Set *0x188=0xc3 and the others to 0. LTE off: Set 0x188 to 0 and
+ * the others to 0xc3. It is therefore likely that up to 4 more devices can be powered on
+ * and off in these registers.
+ */
+};
+
+struct zx29_pm_domain {
+ struct generic_pm_domain gpd;
+ struct regmap *map;
+ unsigned int domain;
+};
+
+#define REG_RST 0x0
+#define REG_ISO 0x4
+#define REG_PWR 0x8
+
+static inline struct zx29_pm_domain *to_zte_pm_domain(struct generic_pm_domain *domain)
+{
+ return container_of(domain, struct zx29_pm_domain, gpd);
+}
+
+static int zx29_pd_on(struct generic_pm_domain *domain)
+{
+ const struct zx29_pm_domain *zx29_pd = to_zte_pm_domain(domain);
+ u32 mask = power_domains[zx29_pd->domain].mask;
+ u32 reg = power_domains[zx29_pd->domain].reg;
+ int res;
+
+ dev_dbg(&domain->dev, "Power on\n");
+
+ res = regmap_set_bits(zx29_pd->map, reg + REG_PWR, mask);
+ if (res)
+ goto error;
+
+ /* The 10 microsecond delay is from ZTE's dwc2 USB driver integration */
+ udelay(10);
+
+ res = regmap_clear_bits(zx29_pd->map, reg + REG_RST, mask);
+ if (res)
+ goto error;
+
+ udelay(10);
+
+ res = regmap_clear_bits(zx29_pd->map, reg + REG_ISO, mask);
+ if (res)
+ goto error;
+
+ return 0;
+
+error:
+ /* Power the device off and isolate it from the bus (reads from an unpowered, unisolated
+ * device can stall the CPU), but don't forcefully reset it.
+ */
+ dev_err(&domain->dev, "%s: Power on failed: %d\n", domain->name, res);
+ regmap_set_bits(zx29_pd->map, reg + REG_ISO, mask);
+ regmap_clear_bits(zx29_pd->map, reg + REG_PWR, mask);
+ return res;
+}
+
+static int zx29_pd_off(struct generic_pm_domain *domain)
+{
+ const struct zx29_pm_domain *zx29_pd = to_zte_pm_domain(domain);
+ u32 mask = power_domains[zx29_pd->domain].mask;
+ u32 reg = power_domains[zx29_pd->domain].reg;
+ int res;
+
+ dev_dbg(&domain->dev, "Power off\n");
+
+ /* If isolation fails, abort. The device should still be operational as far as the pmdomain
+ * settings are concerned. If isolation failed, asserting reset or powering it down leaves
+ * the mmio space in a dangerous state: Attempting to access it will stall the CPU forever.
+ *
+ * If later steps fail, consider the device off. It won't work without removing isolation.
+ */
+ res = regmap_set_bits(zx29_pd->map, reg + REG_ISO, mask);
+ if (res) {
+ dev_err(&domain->dev, "Bus isolation failed: %d\n", res);
+ return res;
+ }
+
+ res = regmap_set_bits(zx29_pd->map, reg + REG_RST, mask);
+ if (res)
+ dev_err(&domain->dev, "Device reset failed: %d\n", res);
+
+ res = regmap_clear_bits(zx29_pd->map, reg + REG_PWR, mask);
+ if (res)
+ dev_err(&domain->dev, "Power off failed: %d\n", res);
+
+ return 0;
+}
+
+static int zx29_pd_attach_dev(struct generic_pm_domain *domain, struct device *dev)
+{
+ /* The DT link to the consumer targets the (MFD) parent, which doesn't prevent unbinding the
+ * this driver or removing the module. Either would leave the consumer with a dangling
+ * reference.
+ */
+ if (!device_link_add(dev, &domain->dev, DL_FLAG_AUTOREMOVE_CONSUMER))
+ return -ENOMEM;
+
+ return 0;
+}
+
+static int zx29_pd_is_on(const struct zx29_pm_domain *zx29_pd)
+{
+ u32 mask = power_domains[zx29_pd->domain].mask;
+ u32 reg = power_domains[zx29_pd->domain].reg;
+ int res;
+ unsigned int val;
+
+ /* To consider a domain on, PWR must be set and RST and ISO cleared */
+ res = regmap_test_bits(zx29_pd->map, reg + REG_PWR, mask);
+ if (res < 0)
+ return res;
+ if (!res)
+ return 0;
+
+ res = regmap_read(zx29_pd->map, reg + REG_ISO, &val);
+ if (res < 0)
+ return res;
+ if (val & mask)
+ return 0;
+
+ res = regmap_read(zx29_pd->map, reg + REG_RST, &val);
+ if (res < 0)
+ return res;
+ if (val & mask)
+ return 0;
+
+ return 1;
+}
+
+static void zx29_pd_release_provider(void *data)
+{
+ struct device_node *of_node = data;
+
+ of_genpd_del_provider(of_node);
+}
+
+static void zx29_pd_remove_domain(void *data)
+{
+ struct generic_pm_domain *genpd = data;
+
+ pm_genpd_remove(genpd);
+}
+
+static int zx29_pd_probe(struct platform_device *pdev)
+{
+ struct device *dev = &pdev->dev;
+ struct device_node *of_node = dev->parent->of_node;
+ struct genpd_onecell_data *zx29_pd_data;
+ struct generic_pm_domain **domains;
+ struct zx29_pm_domain *zx29_pd;
+ struct regmap *map;
+ unsigned int i;
+ int res;
+
+ map = device_node_to_regmap(of_node);
+ if (IS_ERR(map))
+ return dev_err_probe(dev, PTR_ERR(map), "Cannot get parent syscon regmap\n");
+
+ zx29_pd = devm_kcalloc(dev, ARRAY_SIZE(power_domains), sizeof(*zx29_pd), GFP_KERNEL);
+ if (!zx29_pd)
+ return -ENOMEM;
+
+ domains = devm_kcalloc(dev, ARRAY_SIZE(power_domains), sizeof(*domains), GFP_KERNEL);
+ if (!domains)
+ return -ENOMEM;
+
+ zx29_pd_data = devm_kzalloc(dev, sizeof(*zx29_pd_data), GFP_KERNEL);
+ if (!zx29_pd_data)
+ return -ENOMEM;
+
+ for (i = 0; i < ARRAY_SIZE(power_domains); i++) {
+ zx29_pd[i].gpd.name = power_domains[i].name;
+ zx29_pd[i].gpd.power_off = zx29_pd_off;
+ zx29_pd[i].gpd.power_on = zx29_pd_on;
+ zx29_pd[i].gpd.attach_dev = zx29_pd_attach_dev;
+
+ zx29_pd[i].map = map;
+ zx29_pd[i].domain = i;
+
+ domains[i] = &zx29_pd[i].gpd;
+
+ res = zx29_pd_is_on(&zx29_pd[i]);
+ if (res < 0)
+ return dev_err_probe(dev, res, "failed to read initial pmdomain state\n");
+
+ dev_dbg(dev, "%s: %s\n", power_domains[i].name, res ? "on" : "off");
+
+ res = pm_genpd_init(&zx29_pd[i].gpd, NULL, !res);
+ if (res)
+ return dev_err_probe(dev, res, "failed to init power domain\n");
+ res = devm_add_action_or_reset(dev, zx29_pd_remove_domain, &zx29_pd[i].gpd);
+ if (res)
+ return dev_err_probe(dev, res, "failed to add pm_genpd release callback\n");
+ }
+
+ zx29_pd_data->domains = domains;
+ zx29_pd_data->num_domains = ARRAY_SIZE(power_domains);
+
+ res = of_genpd_add_provider_onecell(of_node, zx29_pd_data);
+ if (res)
+ return dev_err_probe(dev, res, "Cannot register power domains\n");
+
+ device_link_add(dev, dev->parent, DL_FLAG_AUTOREMOVE_CONSUMER);
+
+ dev_dbg(dev, "zx297520v3 power domain initialized.\n");
+
+ return devm_add_action_or_reset(dev, zx29_pd_release_provider, of_node);
+}
+
+static const struct platform_device_id pmdomain_zx297520v3_ids[] = {
+ {
+ .name = "zx297520v3-socsys-power",
+ },
+ { }
+};
+MODULE_DEVICE_TABLE(platform, pmdomain_zx297520v3_ids);
+
+static struct platform_driver zx297520_pd = {
+ .probe = zx29_pd_probe,
+ .driver = {
+ .name = "zx297520v3-power-domain",
+ },
+ .id_table = pmdomain_zx297520v3_ids,
+};
+module_platform_driver(zx297520_pd);
+
+MODULE_AUTHOR("Stefan Dösinger <stefandoesinger@gmail.com>");
+MODULE_DESCRIPTION("ZTE zx297520v3 power domain driver");
+MODULE_LICENSE("GPL");
--
2.56.1
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 4/6] phy: zte: Add a zx29 USB PHY driver.
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
` (2 preceding siblings ...)
2026-11-20 19:20 ` [PATCH 3/6] pmdomain: zte: Add a zx297520v3 power domain driver Stefan Dösinger
@ 2026-11-20 19:20 ` 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
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
This driver's responsibility is the correct reset sequencing of the USB
and HSIC PHYs. Before the ready flag is set in topcrm+0x84, the dwc2
controller mmio space reads zeroes. Waiting for them is therefore
necessary to avoid race conditions on boot.
Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>
---
Possible future features are host mode support and adjusting the USB PHY
to mpll over/underclocking. But both are unlikely to have productive use
on this platform. None of the zx29 boards I have seen so far can provide
power on VBUS.
The PHY driver reuses the topcrm node for the MFD child device because
the PHY subsystem enforces that the device either matches the of_node or
is a parent of the of_node (__of_phy_provider_register). Krzysztof
rejected a PHY child node [0] for the purpose of satisfying the check.
One issue - and that's possibly the reason for the PHY subsystem's
behavior - is that nothing prevents the phy driver from being unbound
because the DT producer-consumer relationship targets the MFD parent. I
have set suppress_bind_attrs = true, but that feels ugly and only solves
half the problem. The module can still be unloaded without first
releasing the USB consumer.
0:
https://lore.kernel.org/linux-arm-kernel/20260717-uncovered-feathered-groundhog-eab16e@quoll/
---
MAINTAINERS | 1 +
drivers/phy/Kconfig | 11 +++
drivers/phy/Makefile | 1 +
drivers/phy/phy-zx29-usb.c | 183 +++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 196 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index e394e0044f1f..1d47080b2290 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4038,6 +4038,7 @@ F: arch/arm/boot/dts/zte/
F: arch/arm/mach-zte/
F: drivers/clk/zte/
F: drivers/mfd/zte-zx297520v3-crm.c
+F: drivers/phy/phy-zx29-usb.c
F: drivers/pmdomain/zte/
F: include/dt-bindings/clock/zte,zx297520v3-clk.h
F: include/dt-bindings/phy/zte,zx297520v3-topcrm.h
diff --git a/drivers/phy/Kconfig b/drivers/phy/Kconfig
index d151c05297d7..c4829038bfeb 100644
--- a/drivers/phy/Kconfig
+++ b/drivers/phy/Kconfig
@@ -169,6 +169,17 @@ config PHY_XGENE
help
This option enables support for APM X-Gene SoC multi-purpose PHY.
+config PHY_ZTE_ZX29_USB
+ tristate "ZTE zx29 USB phy"
+ depends on MFD_SYSCON && OF && (ARCH_ZTE || COMPILE_TEST)
+ select GENERIC_PHY
+ help
+ This option enables support for ZTE zx29 USB PHYs. You will need this
+ if you have a ZTE zx29 board and want to use its external USB
+ connector for data transfer. This driver is not required purely for
+ providing power to the board. If M is selected, the module will be
+ called phy-zx29-usb.
+
source "drivers/phy/allwinner/Kconfig"
source "drivers/phy/amlogic/Kconfig"
source "drivers/phy/apple/Kconfig"
diff --git a/drivers/phy/Makefile b/drivers/phy/Makefile
index c6dd02003bbe..e135e96b4930 100644
--- a/drivers/phy/Makefile
+++ b/drivers/phy/Makefile
@@ -19,6 +19,7 @@ obj-$(CONFIG_PHY_NXP_TJA1145) += phy-nxp-tja1145.o
obj-$(CONFIG_PHY_PISTACHIO_USB) += phy-pistachio-usb.o
obj-$(CONFIG_PHY_SNPS_EUSB2) += phy-snps-eusb2.o
obj-$(CONFIG_PHY_XGENE) += phy-xgene.o
+obj-$(CONFIG_PHY_ZTE_ZX29_USB) += phy-zx29-usb.o
obj-$(CONFIG_GENERIC_PHY) += allwinner/ \
amlogic/ \
diff --git a/drivers/phy/phy-zx29-usb.c b/drivers/phy/phy-zx29-usb.c
new file mode 100644
index 000000000000..8dfbcb468c26
--- /dev/null
+++ b/drivers/phy/phy-zx29-usb.c
@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * ZTE zx29 USB2 PHY driver
+ *
+ * Copyright (C) 2026 Stefan Dösinger <stefandoesinger@gmail.com>
+ */
+
+#include <dt-bindings/phy/zte,zx297520v3-topcrm.h>
+#include <linux/err.h>
+#include <linux/iopoll.h>
+#include <linux/mfd/syscon.h>
+#include <linux/module.h>
+#include <linux/phy/phy.h>
+#include <linux/platform_device.h>
+#include <linux/regmap.h>
+
+/* This driver controls the PHY reset bits found in zx297520v3-topcrm register 0x80 and waits for
+ * the ready bits in 0x84.
+ *
+ * More USB related controls can be found in zx297520v3-socsys+0x20 and 0x24:
+ *
+ * Bit 0: Limits the PHY to USB 1
+ * Bit 1: Unknown
+ * Bit 2: DWC2 controller endianness
+ * Bit 3: DWC2 DMA endianness
+ * Bits 7:4: PHY clock adjustments. Adjusting these is necessary if mpll is changed from its default
+ * 624 MHz.
+ * Bits 9:8: PHY electrical configuration. Setting them both to 1 allows operating in host mode.
+ *
+ * They are a fairly useless curiosity though. So far no zx297520v3 based device has a working 5v
+ * VBUS supply, so host mode only works when injecting power externally. The clock bits are too
+ * coarse to be of much use. The default value is 2 (0b0010). Setting it to 1 allows lowering mpll
+ * from 624 to about 530 MHz. The next higher setting might be around mpll=718 MHz, but the SoC is
+ * not able to operate stably at that frequency anyway.
+ */
+
+struct phy_zx29_drv_priv;
+
+struct phy_zx29_phy_priv {
+ struct phy_zx29_drv_priv *drv;
+ struct phy *phy;
+ u32 resetflag;
+ u32 waitflag;
+};
+
+struct phy_zx29_drv_priv {
+ struct regmap *regmap;
+ struct phy_zx29_phy_priv phy[2];
+};
+
+static const struct {
+ const char *name;
+ u32 resetflag;
+ u32 waitflag;
+} phy_data[] = {
+ {"usb", 0x8, 0x2},
+ {"hsic", 0x1, 0x1},
+};
+
+#define PHY_ADDR_ZX297520V3 0x80
+
+static int phy_zx29_init(struct phy *phy)
+{
+ struct phy_zx29_phy_priv *phypriv = phy_get_drvdata(phy);
+ struct phy_zx29_drv_priv *priv = phypriv->drv;
+ int res;
+ u32 val;
+
+ dev_dbg(&phy->dev, "Initializing, reset 0x%x, wait 0x%x\n",
+ phypriv->resetflag, phypriv->waitflag);
+
+ /* If the bootloader used the USB device it sometimes fails to re-initialize without a
+ * reset.
+ */
+ res = regmap_clear_bits(priv->regmap, PHY_ADDR_ZX297520V3, phypriv->resetflag);
+ if (res)
+ return res;
+
+ fsleep(10);
+
+ res = regmap_set_bits(priv->regmap, PHY_ADDR_ZX297520V3, phypriv->resetflag);
+ if (res)
+ return res;
+
+ /* The wait time is usually in the single digit microsecond range, but it can be
+ * considerably longer in some situations. The upper ceiling isn't clear though - 50 us is
+ * not reliably enough, but every time I add timing, the usb wakeup time goes back below 10
+ * us.
+ */
+ res = regmap_read_poll_timeout(priv->regmap, PHY_ADDR_ZX297520V3 + 0x4, val,
+ val & phypriv->waitflag, 10, 500);
+ if (res) {
+ dev_err(&phy->dev, "PHY reset failed: %d\n", res);
+ regmap_clear_bits(priv->regmap, PHY_ADDR_ZX297520V3, phypriv->resetflag);
+ }
+
+ return res;
+}
+
+static int phy_zx29_exit(struct phy *phy)
+{
+ struct phy_zx29_phy_priv *phypriv = phy_get_drvdata(phy);
+ struct phy_zx29_drv_priv *priv = phypriv->drv;
+
+ return regmap_clear_bits(priv->regmap, PHY_ADDR_ZX297520V3, phypriv->resetflag);
+}
+
+static const struct phy_ops phy_zx29_ops = {
+ .init = phy_zx29_init,
+ .exit = phy_zx29_exit,
+ .owner = THIS_MODULE,
+};
+
+static struct phy *phy_zx29_xlate(struct device *dev,
+ const struct of_phandle_args *args)
+{
+ struct phy_zx29_drv_priv *priv = dev_get_drvdata(dev);
+
+ if (args->args_count != 1)
+ return ERR_PTR(-EINVAL);
+ if (args->args[0] >= ARRAY_SIZE(priv->phy))
+ return ERR_PTR(-EINVAL);
+
+ return priv->phy[args->args[0]].phy;
+}
+
+static int phy_zx29_probe(struct platform_device *pdev)
+{
+ struct phy_provider *phy_provider;
+ struct device *dev = &pdev->dev;
+ struct phy_zx29_drv_priv *priv;
+ unsigned int i;
+
+ device_set_of_node_from_dev(dev, dev->parent);
+ priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
+ if (!priv)
+ return -ENOMEM;
+ platform_set_drvdata(pdev, priv);
+
+ priv->regmap = syscon_node_to_regmap(dev->of_node);
+ if (IS_ERR(priv->regmap)) {
+ return dev_err_probe(dev, PTR_ERR(priv->regmap),
+ "Failed to get regmap\n");
+ }
+
+ for (i = 0; i < ARRAY_SIZE(phy_data); ++i) {
+ priv->phy[i].drv = priv;
+ priv->phy[i].waitflag = phy_data[i].waitflag;
+ priv->phy[i].resetflag = phy_data[i].resetflag;
+
+ priv->phy[i].phy = devm_phy_create(dev, NULL, &phy_zx29_ops);
+ if (IS_ERR(priv->phy[i].phy))
+ return dev_err_probe(dev, PTR_ERR(priv->phy[i].phy),
+ "failed to create %s PHY\n", phy_data[i].name);
+
+ phy_set_drvdata(priv->phy[i].phy, &priv->phy[i]);
+ }
+
+ phy_provider = devm_of_phy_provider_register(dev, phy_zx29_xlate);
+ return PTR_ERR_OR_ZERO(phy_provider);
+}
+
+static const struct platform_device_id phy_zx29_ids[] = {
+ {
+ .name = "zx297520v3-usb-phy",
+ },
+ { }
+};
+MODULE_DEVICE_TABLE(platform, phy_zx29_ids);
+
+static struct platform_driver phy_zx29_driver = {
+ .probe = phy_zx29_probe,
+ .driver = {
+ .name = "zx297520v3-usb-phy",
+ .suppress_bind_attrs = true,
+ },
+ .id_table = phy_zx29_ids,
+};
+module_platform_driver(phy_zx29_driver);
+
+MODULE_AUTHOR("Stefan Dösinger <stefandoesinger@gmail.com>");
+MODULE_DESCRIPTION("ZTE zx29 USB2 PHY driver");
+MODULE_LICENSE("GPL");
--
2.56.1
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 5/6] ARM: dts: zte: Declare nodes to enable the board's dwc2 controller
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
` (3 preceding siblings ...)
2026-11-20 19:20 ` [PATCH 4/6] phy: zte: Add a zx29 USB PHY driver Stefan Dösinger
@ 2026-11-20 19:20 ` Stefan Dösinger
2026-11-20 19:20 ` [PATCH 6/6] ARM: dts: zte: Declare the HSIC controller node Stefan Dösinger
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
This adds the socsys syscon that provides the power control for the
controller and the dwc2 controller itself.
On all boards I have seen so far the USB connector can only operate in
peripheral mode - including one device that actually has a USB A
connector. DWC2 and the PHY can be programmed into host mode, but there
is no VBUS power supply.
Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>
---
arch/arm/boot/dts/zte/zx297520v3.dtsi | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/arch/arm/boot/dts/zte/zx297520v3.dtsi b/arch/arm/boot/dts/zte/zx297520v3.dtsi
index ebac3cd137df..2fc888b10006 100644
--- a/arch/arm/boot/dts/zte/zx297520v3.dtsi
+++ b/arch/arm/boot/dts/zte/zx297520v3.dtsi
@@ -5,6 +5,8 @@
#include <dt-bindings/clock/zte,zx297520v3-clk.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
+#include <dt-bindings/phy/zte,zx297520v3-topcrm.h>
+#include <dt-bindings/power/zte,zx297520v3-socsys.h>
#include <dt-bindings/reset/zte,zx297520v3-reset.h>
/ {
@@ -111,6 +113,13 @@ reboot {
};
};
+ socsys: syscon@140000 {
+ compatible = "zte,zx297520v3-socsys", "syscon";
+ reg = <0x00140000 0x400>;
+ #power-domain-cells = <1>;
+ #reset-cells = <1>;
+ };
+
matrixcrm: clock-controller@1306000 {
compatible = "zte,zx297520v3-matrixcrm";
reg = <0x01306000 0x400>;
@@ -176,5 +185,19 @@ uart2: serial@140d000 {
status = "disabled";
};
+
+ usb@1500000 {
+ compatible = "snps,dwc2";
+ reg = <0x01500000 0x40000>;
+ interrupts = <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&topcrm ZX297520V3_USB_WCLK>, <&topcrm ZX297520V3_USB_PCLK>;
+ clock-names = "otg", "utmi";
+ dr_mode = "peripheral";
+ resets = <&topcrm ZX297520V3_USB_RESET>;
+ reset-names = "dwc2";
+ power-domains = <&socsys ZX297520V3_PD_USB>;
+ phys = <&topcrm ZX297520V3_USB_PHY>;
+ phy-names = "usb2-phy";
+ };
};
};
--
2.56.1
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 6/6] ARM: dts: zte: Declare the HSIC controller node
2026-11-20 19:20 [PATCH 0/6] ZTE zx297520v3 USB support Stefan Dösinger
` (4 preceding siblings ...)
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 ` Stefan Dösinger
5 siblings, 0 replies; 7+ messages in thread
From: Stefan Dösinger @ 2026-11-20 19:20 UTC (permalink / raw)
To: Rob Herring, Krzysztof Kozlowski, Conor Dooley,
Stefan Dösinger, Philipp Zabel, Lee Jones, Ulf Hansson,
Vinod Koul, Neil Armstrong, Manivannan Sadhasivam,
Agustin Santiago Isasmendi, Navid Ghahremani
Cc: devicetree, linux-kernel, linux-arm-kernel, mfd, linux-pm, linux-phy
This is for documentation purposes. I have not seen any board yet that
actually connects anything to it. On newer boards it seems to be removed
entirely.
Signed-off-by: Stefan Dösinger <stefandoesinger@gmail.com>
---
arch/arm/boot/dts/zte/zx297520v3.dtsi | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)
diff --git a/arch/arm/boot/dts/zte/zx297520v3.dtsi b/arch/arm/boot/dts/zte/zx297520v3.dtsi
index 2fc888b10006..56d6b46a8ed1 100644
--- a/arch/arm/boot/dts/zte/zx297520v3.dtsi
+++ b/arch/arm/boot/dts/zte/zx297520v3.dtsi
@@ -199,5 +199,24 @@ usb@1500000 {
phys = <&topcrm ZX297520V3_USB_PHY>;
phy-names = "usb2-phy";
};
+
+ /* The HSIC controller exists primarily on older hardware, but I haven't seen any
+ * device that is actually connected to it on any board.
+ */
+ usb@1600000 {
+ compatible = "snps,dwc2";
+ reg = <0x01600000 0x40000>;
+ interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&topcrm ZX297520V3_HSIC_WCLK>, <&topcrm ZX297520V3_HSIC_PCLK>;
+ clock-names = "otg", "utmi";
+ dr_mode = "host";
+ resets = <&topcrm ZX297520V3_HSIC_RESET>;
+ reset-names = "dwc2";
+ power-domains = <&socsys ZX297520V3_PD_USB>;
+ phys = <&topcrm ZX297520V3_HSIC_PHY>;
+ phy-names = "usb2-phy";
+
+ status = "disabled";
+ };
};
};
--
2.56.1
^ permalink raw reply [flat|nested] 7+ messages in thread