[PATCH v2 0/2] Add Realtek System Timer driver

[PATCH v2 0/2] Add Realtek System Timer driver

[Hao-Wen Ting]

Changes v2:
PATCH 1/2
- Add full name 'system timer' to description
- Remove redundant commit messages
- Clarify compatible strings for specific verified SoCs
- Remove redundant reg and interrupts description sentences
- Use generic node name in example
PATCH 2/2
- Correct MAINTAINERS to alphabetical order
- Update Kconfig: switch dependency to ARM/ARM64
- Remove redundant pr_info output

This patch series adds support for the Realtek SYSTIMER, a 64-bit timer
that serves as a tick broadcast timer on Realtek SoCs.

On Realtek platforms, CPUs can enter deep idle states (C-states) where
local timers are stopped and powered off. Without a global tick broadcast
timer, one CPU must remain awake to wake up the others, preventing all CPUs
from entering deep idle simultaneously and limiting power savings.

The Realtek SYSTIMER remains active during deep idle states, allowing all
CPUs to enter power-cut idle states simultaneously. This significantly
reduces overall power consumption while maintaining proper tick broadcast
functionality.

The systimer hardware for both RTD1625 and RTD1635 SoCs has identical register
layout and IRQ configuration. The driver therefore matches both compatibles
without special handling and has been tested on both platforms.

Technical details:
- 64-bit timer operating at 1MHz fixed frequency
- Supports oneshot mode for tick broadcast
- Uses standard TIMER_OF framework and Device Tree integration
- Remains active during CPU power-down states

Testing:
- Verify the functionality of tick broadcast timer on both RTD1625 and RTD1635
SoCs.
- Verify the power consumption reduction on RTD1625 Soc in deep idle scenarios

Patch organization:
Patch 1/2: Device Tree binding documentation
Patch 2/2: Clocksource driver implementation

Best regards,
Hao-Wen Ting

Hao-Wen Ting (2):
  dt-bindings: timer: Add Realtek SYSTIMER binding
  clocksource: Add Realtek systimer as tick broadcast driver

 .../bindings/timer/realtek,systimer.yaml      |  48 +++++
 MAINTAINERS                                   |   5 +
 drivers/clocksource/Kconfig                   |  10 +
 drivers/clocksource/Makefile                  |   1 +
 drivers/clocksource/timer-realtek.c           | 172 ++++++++++++++++++
 5 files changed, 236 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/timer/realtek,systimer.yaml
 create mode 100644 drivers/clocksource/timer-realtek.c


base-commit: 948b99877bf5a1cd58bee930e455b7574daba5c3
-- 
2.34.1

[PATCH v2 1/2] dt-bindings: timer: Add Realtek SYSTIMER binding

[Hao-Wen Ting]

Add device tree binding documentation for the Realtek SYSTIMER, a 64-bit
timer that can be used as a tick broadcast timer on multi-core Realtek
SoCs.

The SYSTIMER remains active during deep CPU idle states where local
timers are powered off, allowing all CPUs to enter power-cut idle states
simultaneously for improved power efficiency. The timer operates at a
fixed 1MHz frequency and supports oneshot mode for tick broadcast
functionality.

Signed-off-by: Hao-Wen Ting <haowen.ting@realtek.com>
---
 .../bindings/timer/realtek,systimer.yaml      | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/timer/realtek,systimer.yaml

diff --git a/Documentation/devicetree/bindings/timer/realtek,systimer.yaml b/Documentation/devicetree/bindings/timer/realtek,systimer.yaml
new file mode 100644
index 000000000000..8e68158c68f8
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/realtek,systimer.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/realtek,systimer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek System Timer
+
+maintainers:
+  - Hao-Wen Ting <haowen.ting@realtek.com>
+
+description: |
+  The Realtek SYSTIMER (System Timer) is a 64-bit timer that can be used as
+  a tick broadcast timer on multi-core Realtek SoCs. It remains active during
+  deep CPU idle states where local timers are powered off, allowing all CPUs
+  to enter power-cut idle states simultaneously for better power efficiency.
+
+  The timer operates at a fixed 1MHz frequency and supports oneshot mode
+  for tick broadcast functionality.
+
+properties:
+  compatible:
+    enum:
+      - realtek,rtd1625-systimer
+      - realtek,rtd1635-systimer
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    timer@89420 {
+        compatible = "realtek,rtd1625-systimer";
+        reg = <0x89420 0x18>;
+        interrupts = <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>;
+    };
-- 
2.34.1

[PATCH v2 2/2] clocksource: Add Realtek systimer as tick broadcast driver

[Hao-Wen Ting]

Add a tick broadcast timer driver for Realtek SoCs.

On Realtek platforms, CPUs can enter deep idle states (C-states) where
the local timer is stopped and powered off. Without a global tick
broadcast timer, one CPU must remain awake to wake up the others,
preventing all CPUs from entering deep idle simultaneously.

This driver provides a tick broadcast timer which remains active
during deep idle states. This allows all CPUs to enter power-cut
idle states simultaneously, significantly reducing overall power
consumption.

The timer operates at 1MHz and supports oneshot mode.

Signed-off-by: Hao-Wen Ting <haowen.ting@realtek.com>
---
 MAINTAINERS                         |   5 +
 drivers/clocksource/Kconfig         |  10 ++
 drivers/clocksource/Makefile        |   1 +
 drivers/clocksource/timer-realtek.c | 172 ++++++++++++++++++++++++++++
 4 files changed, 188 insertions(+)
 create mode 100644 drivers/clocksource/timer-realtek.c

diff --git a/MAINTAINERS b/MAINTAINERS
index c7a116b795d5..90f511bb4982 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -21670,6 +21670,11 @@ S:	Maintained
 F:	Documentation/devicetree/bindings/spi/realtek,rtl9301-snand.yaml
 F:	drivers/spi/spi-realtek-rtl-snand.c
 
+REALTEK SYSTIMER DRIVER
+M:	Hao-Wen Ting <haowen.ting@realtek.com>
+S:	Maintained
+F:	drivers/clocksource/timer-realtek.c
+
 REALTEK WIRELESS DRIVER (rtlwifi family)
 M:	Ping-Ke Shih <pkshih@realtek.com>
 L:	linux-wireless@vger.kernel.org
diff --git a/drivers/clocksource/Kconfig b/drivers/clocksource/Kconfig
index ffcd23668763..0c1835b48a18 100644
--- a/drivers/clocksource/Kconfig
+++ b/drivers/clocksource/Kconfig
@@ -782,4 +782,14 @@ config NXP_STM_TIMER
           Enables the support for NXP System Timer Module found in the
           s32g NXP platform series.
 
+config RTK_SYSTIMER
+	bool "Realtek SYSTIMER support"
+	depends on ARM || ARM64
+	select TIMER_OF
+	help
+	  This enables the global tick-broadcast timer on Realtek platforms.
+	  If your Realtek platform supports power-cut level CPU idle states,
+	  enabling this timer allows all CPUs to enter power-cut simultaneously
+	  to achieve lower power consumption.
+
 endmenu
diff --git a/drivers/clocksource/Makefile b/drivers/clocksource/Makefile
index ec4452ee958f..b46376af6b49 100644
--- a/drivers/clocksource/Makefile
+++ b/drivers/clocksource/Makefile
@@ -95,3 +95,4 @@ obj-$(CONFIG_CLKSRC_LOONGSON1_PWM)	+= timer-loongson1-pwm.o
 obj-$(CONFIG_EP93XX_TIMER)		+= timer-ep93xx.o
 obj-$(CONFIG_RALINK_TIMER)		+= timer-ralink.o
 obj-$(CONFIG_NXP_STM_TIMER)		+= timer-nxp-stm.o
+obj-$(CONFIG_RTK_SYSTIMER)		+= timer-realtek.o
diff --git a/drivers/clocksource/timer-realtek.c b/drivers/clocksource/timer-realtek.c
new file mode 100644
index 000000000000..f484fd97e964
--- /dev/null
+++ b/drivers/clocksource/timer-realtek.c
@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (c) 2025 Realtek Semiconductor Corp.
+ */
+
+#define pr_fmt(fmt)	KBUILD_MODNAME ": " fmt
+
+#include <linux/irqflags.h>
+#include <linux/interrupt.h>
+#include "timer-of.h"
+
+#define ENBL 1
+#define DSBL 0
+
+#define SYSTIMER_RATE 1000000
+#define SYSTIMER_MIN_DELTA 0x64
+#define SYSTIMER_MAX_DELTA ULONG_MAX
+
+/* SYSTIMER Register Offset (RTK Internal Use) */
+#define TS_LW_OFST 0x0
+#define TS_HW_OFST 0x4
+#define TS_CMP_VAL_LW_OFST 0x8
+#define TS_CMP_VAL_HW_OFST 0xC
+#define TS_CMP_CTRL_OFST 0x10
+#define TS_CMP_STAT_OFST 0x14
+
+/* SYSTIMER CMP CTRL REG Mask */
+#define TS_CMP_EN_MASK 0x1
+#define TS_WR_EN0_MASK 0x2
+
+static void __iomem *systimer_base;
+
+static u64 rtk_ts64_read(void)
+{
+	u64 ts;
+	u32 low, high;
+
+	/* Caution: Read LSB word (TS_LW_OFST) first then MSB (TS_HW_OFST) */
+	low = readl(systimer_base + TS_LW_OFST);
+	high = readl(systimer_base + TS_HW_OFST);
+
+	pr_debug("64bit-TS:HW=0x%08x,LW=0x%08x\n", high, low);
+	ts = ((u64)high << 32) | low;
+
+	return ts;
+}
+
+static void rtk_cmp_value_write(u64 value)
+{
+	u32 high, low;
+
+	low = value & 0xFFFFFFFF;
+	high = value >> 32;
+	pr_debug("Write 64bit-CMP:HW=0x%08x,LW=0x%08x\n", high, low);
+
+	writel(high, systimer_base + TS_CMP_VAL_HW_OFST);
+	writel(low, systimer_base + TS_CMP_VAL_LW_OFST);
+}
+
+static inline void rtk_cmp_en_write(bool cmp_en)
+{
+	u32 val;
+
+	val = TS_WR_EN0_MASK;
+	if (cmp_en == ENBL)
+		val |= TS_CMP_EN_MASK;
+
+	writel(val, systimer_base + TS_CMP_CTRL_OFST);
+	pr_debug("Write TS CMP CTRL = 0x%08x\n", val);
+}
+
+static int rtk_syst_clkevt_next_ktime(ktime_t expires,
+				      struct clock_event_device *clkevt)
+{
+	u64 cmp_val;
+	unsigned long flags;
+	ktime_t now = ktime_get();
+	s64 delta_ns = ktime_to_ns(ktime_sub(expires, now));
+	u64 delta_us = delta_ns / 1000;
+
+	pr_debug("delta_ns = %lld, clkevt.min_delta_ns = %llu\n",
+		 delta_ns, clkevt->min_delta_ns);
+
+	if (delta_ns <= (s64)clkevt->min_delta_ns) {
+		delta_ns = clkevt->min_delta_ns;
+		delta_us = delta_ns / 1000;
+		pr_debug("Clamping delta_ns to min_delta_ns\n");
+	}
+
+	rtk_cmp_en_write(DSBL);
+	local_irq_save(flags);
+	cmp_val = rtk_ts64_read();
+
+	/* Set CMP value to current timestamp plus delta_us */
+	rtk_cmp_value_write(cmp_val + delta_us);
+	rtk_cmp_en_write(ENBL);
+	local_irq_restore(flags);
+	return 0;
+}
+
+static irqreturn_t rtk_ts_match_intr_handler(int irq, void *dev_id)
+{
+	u32 val;
+	void __iomem *reg_base;
+	struct clock_event_device *clkevt = dev_id;
+
+	/* Disable TS CMP Match */
+	rtk_cmp_en_write(DSBL);
+
+	/* Clear TS CMP INTR */
+	reg_base = systimer_base + TS_CMP_STAT_OFST;
+	val = readl(reg_base) & TS_CMP_EN_MASK;
+	writel(val | TS_CMP_EN_MASK, reg_base);
+
+	clkevt->event_handler(clkevt);
+
+	return IRQ_HANDLED;
+}
+
+static int rtk_syst_shutdown(struct clock_event_device *clkevt)
+{
+	void __iomem *reg_base;
+	u64 cmp_val = 0;
+
+	/* Disable TS CMP Match */
+	rtk_cmp_en_write(DSBL);
+	/* Set compare value to 0 */
+	rtk_cmp_value_write(cmp_val);
+
+	/* Clear TS CMP INTR */
+	reg_base = systimer_base + TS_CMP_STAT_OFST;
+	writel(TS_CMP_EN_MASK, reg_base);
+	return 0;
+}
+
+static struct timer_of _to = {
+	.flags = TIMER_OF_IRQ | TIMER_OF_BASE,
+
+	.clkevt = {
+		.name = "rtk-clkevt",
+		.rating = 300,
+		.cpumask = cpu_possible_mask,
+		.features = CLOCK_EVT_FEAT_DYNIRQ |
+			    CLOCK_EVT_FEAT_ONESHOT |
+			    CLOCK_EVT_FEAT_KTIME,
+		.set_next_ktime = rtk_syst_clkevt_next_ktime,
+		.set_state_oneshot = rtk_syst_shutdown,
+		.set_state_shutdown = rtk_syst_shutdown
+	},
+
+	.of_irq = {
+		.flags = IRQF_TIMER | IRQF_IRQPOLL,
+		.handler = rtk_ts_match_intr_handler
+	},
+};
+
+static int __init rtk_systimer_init(struct device_node *node)
+{
+	int ret;
+
+	ret = timer_of_init(node, &_to);
+	if (ret)
+		return ret;
+
+	systimer_base = timer_of_base(&_to);
+	clockevents_config_and_register(&_to.clkevt, SYSTIMER_RATE,
+					SYSTIMER_MIN_DELTA, SYSTIMER_MAX_DELTA);
+
+	return 0;
+}
+
+TIMER_OF_DECLARE(rtk_systimer, "realtek,rtd1625-systimer", rtk_systimer_init);
-- 
2.34.1

Re: [PATCH v2 1/2] dt-bindings: timer: Add Realtek SYSTIMER binding

[Krzysztof Kozlowski]

On 14/11/2025 10:04, Hao-Wen Ting wrote:
> Add device tree binding documentation for the Realtek SYSTIMER, a 64-bit
> timer that can be used as a tick broadcast timer on multi-core Realtek
> SoCs.
> 
> The SYSTIMER remains active during deep CPU idle states where local
> timers are powered off, allowing all CPUs to enter power-cut idle states
> simultaneously for improved power efficiency. The timer operates at a
> fixed 1MHz frequency and supports oneshot mode for tick broadcast
> functionality.
> 
> Signed-off-by: Hao-Wen Ting <haowen.ting@realtek.com>
> ---
>  .../bindings/timer/realtek,systimer.yaml      | 48 +++++++++++++++++++
>  1 file changed, 48 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/timer/realtek,systimer.yaml
> 
> diff --git a/Documentation/devicetree/bindings/timer/realtek,systimer.yaml b/Documentation/devicetree/bindings/timer/realtek,systimer.yaml
> new file mode 100644
> index 000000000000..8e68158c68f8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/timer/realtek,systimer.yaml

Filename matching compatible, see writing bindings doc. I already asked
to read that doc.

A nit, subject: drop second/last, redundant "binding". The "dt-bindings"
prefix is already stating that these are bindings.
See also:
https://elixir.bootlin.com/linux/v6.17-rc3/source/Documentation/devicetree/bindings/submitting-patches.rst#L18


> @@ -0,0 +1,48 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/timer/realtek,systimer.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Realtek System Timer
> +
> +maintainers:
> +  - Hao-Wen Ting <haowen.ting@realtek.com>
> +
> +description: |
> +  The Realtek SYSTIMER (System Timer) is a 64-bit timer that can be used as
> +  a tick broadcast timer on multi-core Realtek SoCs. It remains active during
> +  deep CPU idle states where local timers are powered off, allowing all CPUs
> +  to enter power-cut idle states simultaneously for better power efficiency.
> +
> +  The timer operates at a fixed 1MHz frequency and supports oneshot mode
> +  for tick broadcast functionality.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - realtek,rtd1625-systimer
> +      - realtek,rtd1635-systimer

You don't use this compatible which raises questions, maybe you wanted
to express compatibility.


Best regards,
Krzysztof

Re: [PATCH v2 2/2] clocksource: Add Realtek systimer as tick broadcast driver

[Krzysztof Kozlowski]

On 14/11/2025 10:04, Hao-Wen Ting wrote:
> Add a tick broadcast timer driver for Realtek SoCs.
> 
> On Realtek platforms, CPUs can enter deep idle states (C-states) where
> the local timer is stopped and powered off. Without a global tick
> broadcast timer, one CPU must remain awake to wake up the others,
> preventing all CPUs from entering deep idle simultaneously.
> 
> This driver provides a tick broadcast timer which remains active
> during deep idle states. This allows all CPUs to enter power-cut
> idle states simultaneously, significantly reducing overall power
> consumption.
> 
> The timer operates at 1MHz and supports oneshot mode.
> 
> Signed-off-by: Hao-Wen Ting <haowen.ting@realtek.com>
> ---
>  MAINTAINERS                         |   5 +
>  drivers/clocksource/Kconfig         |  10 ++
>  drivers/clocksource/Makefile        |   1 +
>  drivers/clocksource/timer-realtek.c | 172 ++++++++++++++++++++++++++++
>  4 files changed, 188 insertions(+)
>  create mode 100644 drivers/clocksource/timer-realtek.c
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c7a116b795d5..90f511bb4982 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -21670,6 +21670,11 @@ S:	Maintained
>  F:	Documentation/devicetree/bindings/spi/realtek,rtl9301-snand.yaml
>  F:	drivers/spi/spi-realtek-rtl-snand.c
>  
> +REALTEK SYSTIMER DRIVER
> +M:	Hao-Wen Ting <haowen.ting@realtek.com>
> +S:	Maintained
> +F:	drivers/clocksource/timer-realtek.c
> +
>  REALTEK WIRELESS DRIVER (rtlwifi family)
>  M:	Ping-Ke Shih <pkshih@realtek.com>
>  L:	linux-wireless@vger.kernel.org
> diff --git a/drivers/clocksource/Kconfig b/drivers/clocksource/Kconfig
> index ffcd23668763..0c1835b48a18 100644
> --- a/drivers/clocksource/Kconfig
> +++ b/drivers/clocksource/Kconfig
> @@ -782,4 +782,14 @@ config NXP_STM_TIMER
>            Enables the support for NXP System Timer Module found in the
>            s32g NXP platform series.
>  
> +config RTK_SYSTIMER
> +	bool "Realtek SYSTIMER support"
> +	depends on ARM || ARM64


No, I asked to depend on specific SoC ARCH. Not top level architecture.
Also, each such dependency must have compile test, just look at other code.

Best regards,
Krzysztof