feat(linux): Add documentation for dynamic DDR refresh rate change

Neha Malcom Francis · Neha Malcom Francis · commit 82d580c8d2a2 · 2025-12-08T16:33:53.000+05:30
Add driver documentation for kernel DDR driver and how to enable DDR
temperature monitoring.

Signed-off-by: Neha Malcom Francis &lt;n-francis@ti.com&gt;
diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt
@@ -55,6 +55,7 @@ linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/Audio
 linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP
diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt
@@ -56,6 +56,7 @@ linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/Audio
 linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP
diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt
@@ -55,6 +55,7 @@ linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/Audio
 linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP
diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt
@@ -48,6 +48,7 @@ linux/Foundational_Components_Kernel
 linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/ADC
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP
 linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO
diff --git a/configs/J7200/J7200_linux_toc.txt b/configs/J7200/J7200_linux_toc.txt
@@ -50,6 +50,7 @@ linux/Foundational_Components_Kernel
 linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/ADC
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/MCAN
 linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO
diff --git a/configs/J721E/J721E_linux_toc.txt b/configs/J721E/J721E_linux_toc.txt
@@ -52,6 +52,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/ADC
 linux/Foundational_Components/Kernel/Kernel_Drivers/Audio
 linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX
 linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto/SA2UL_OMAP
+linux/Foundational_Components/Kernel/Kernel_Drivers/DDR
 linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7
 linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer
 linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO
diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DDR.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DDR.rst
@@ -0,0 +1,160 @@
+.. _K3-DDR-Driver:
+.. _ddr-driver:
+
+#########
+K3 DDR
+#########
+
+************
+Introduction
+************
+
+The K3 DDR driver provides management and monitoring capabilities for DDR memory
+subsystems on Texas Instruments K3 SoCs.
+
+The following is a list of supported K3 DDR driver features by device family:
+
+.. list-table:: K3 DDR Driver Feature Support
+   :header-rows: 1
+
+   * - Device Family
+     - Temperature Monitoring
+
+   * - J721E / J7200
+     - Yes (only on J7200)
+
+   * - AM62X / AM62AX / AM62PX
+     - Yes
+
+   * - AM64X
+     - Yes
+
+**********************************
+Building and Enabling the Driver
+**********************************
+
+.. rubric:: Kernel Configuration
+
+The K3 DDR driver can be enabled in the kernel configuration:
+
+.. code-block:: kconfig
+
+   CONFIG_K3_DDR_TEMP=y
+   CONFIG_HWMON=y
+
+**********************************
+Device Tree Configuration Examples
+**********************************
+
+The K3 DDR driver requires proper device tree configuration with DDR controller
+and interrupt setup. The compatible string determines which DDR controller variant
+and features are supported:
+
+.. ifconfig:: CONFIG_part_variant in ('J721E', 'J7200')
+
+   **J7 Family Device Tree Example:**
+
+   .. code-block:: dts
+
+      ddrss0: ddr@4e00000 {
+          compatible = "ti,j7-ddrss";
+          reg = <0x0 0x4e00000 0x0 0x1000>;
+          interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>;
+          status = "okay";
+
+          ddr: ddr@4e01000 {
+              reg = <0x0 0x4e01000 0x0 0x2000>;
+          };
+      };
+
+.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM64X')
+
+   **AM62X/AM64X Device Tree Example:**
+
+   .. code-block:: dts
+
+      ddrss0: ddr@f300000 {
+          compatible = "ti,am62-ddrss";
+          reg = <0x00 0xf300000 0x00 0x1000>;
+          interrupts = <GIC_SPI 133 IRQ_TYPE_LEVEL_HIGH>;
+          status = "okay";
+
+          ddr: ddr@f301000 {
+              reg = <0x00 0xf301000 0x00 0x2000>;
+          };
+      };
+
+.. ifconfig:: CONFIG_part_variant in ('AM62AX')
+
+   **AM62AX Device Tree Example:**
+
+   .. code-block:: dts
+
+      ddrss0: ddr@f300000 {
+          compatible = "ti,am62a-ddrss";
+          reg = <0x00 0xf300000 0x00 0x1000>;
+          interrupts = <GIC_SPI 133 IRQ_TYPE_LEVEL_HIGH>;
+          status = "okay";
+
+          ddr: ddr@f301000 {
+              reg = <0x00 0xf301000 0x00 0x2000>;
+          };
+      };
+
+.. _ddr-temperature-monitoring-linux:
+
+************************************
+Using the DDR Temperature Monitoring
+************************************
+
+By default, the DDR subsystem keeps temperature polling turned off. For allowing
+the kernel driver to monitor temperature, the user must enable polling during
+DDR configuration and initialization at boot time.
+
+.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62AX', 'AM62PX', 'AM64X', 'AM68A', 'AM68', 'AM69A', 'AM69', 'J722S')
+
+   See :ref:`ddr-temperature-monitoring-uboot-am6x` in U-Boot documentation.
+
+.. ifconfig:: CONFIG_part_variant in ('J721E', 'J7200', 'J721S2', 'J784S4', 'J742S2')
+
+   See :ref:`ddr-temperature-monitoring-uboot-j7` in U-Boot documentation.
+
+The K3 DDR driver creates a hwmon device that provides temperature status
+information through sysfs. The driver registers as ``k3_ddr`` in the hwmon
+subsystem for temperature monitoring functionality.
+
+The driver reports temperature status according to LPDDR4 specification:
+
++-------+------------------------------------------+
+| Value | Temperature Status                       |
++=======+==========================================+
+| 0     | Low temperature                          |
++-------+------------------------------------------+
+| 1     | 4x refresh interval                      |
++-------+------------------------------------------+
+| 2     | 2x refresh interval                      |
++-------+------------------------------------------+
+| 3     | 1x refresh interval (nominal)            |
++-------+------------------------------------------+
+| 4     | 0.5x refresh interval                    |
++-------+------------------------------------------+
+| 5     | 0.25x refresh interval                   |
++-------+------------------------------------------+
+| 6     | 0.25x refresh interval with derating     |
++-------+------------------------------------------+
+| 7     | High temperature                         |
++-------+------------------------------------------+
+
+The hwmon device should now show up in the filesystem.
+
+.. code-block:: console
+
+   root@evm:~# ls -l /sys/class/hwmon/
+   hwmon0
+
+Check the current DDR temperature status:
+
+.. code-block:: console
+
+   root@evm:~# cat /sys/class/hwmon/hwmon0/device/k3_ddr_temp_status
+   1x refresh interval
diff --git a/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst b/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst
@@ -11,6 +11,8 @@ integrate these blocks in the device. The K3 DDRSS driver
 (drivers/ram/k3-ddrss/k3-ddrss.c) runs during the R5 SPL stage and is
 responsible for initializing and configuring the DDR subsystem.
 
+.. _ddr-init-j7:
+
 ******************
 DDR Initialization
 ******************
@@ -22,11 +24,27 @@ generated using the `Sysconfig tool <https://dev.ti.com/sysconfig>`_ and
 selecting the software product as "DDR Configuration for \*" as well as the
 required device.
 
+.. _ddr-temperature-monitoring-uboot-j7:
+
+**************************
+DDR Temperature Monitoring
+**************************
+
+For enabling temperature polling in the DDR subsystem the configuration DTSI
+(see :ref:`ddr-init-j7`) must be regenerated after selecting 'Yes'
+for LPDDR > DDRSS x > Enable DRAM Temperature Polling and also changing the DRAM
+Timing Parameters as prompted by the tool.
+
+.. ifconfig:: CONFIG_part_variant in ('J7200', 'J721E')
+
+   The kernel DDR driver utilizes this polling feature to provide base support for
+   dynamic DDR refresh rate changes (see :ref:`ddr-temperature-monitoring-linux`)
+
 .. ifconfig:: CONFIG_part_variant not in ('J7200', 'J721E')
 
-   ******************
+   **********
    Inline ECC
-   ******************
+   **********
 
    For SDRAM data integrity, the DDRSS
    bridge supports inline ECC on the data written to or read from the SDRAM. ECC
diff --git a/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst b/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst
@@ -11,6 +11,8 @@ integrate these blocks in the device. The K3 DDRSS driver
 (drivers/ram/k3-ddrss/k3-ddrss.c) runs during the R5 SPL stage and is
 responsible for initializing and configuring the DDR subsystem.
 
+.. _ddr-init-am6:
+
 ******************
 DDR Initialization
 ******************
@@ -22,10 +24,24 @@ generated using the `Sysconfig tool <https://dev.ti.com/sysconfig>`_ and
 selecting the software product as "DDR Configuration for \*" as well as the
 required device.
 
+.. _ddr-temperature-monitoring-uboot-am6x:
+
 **************************
-Error Correction Code (ECC)
+DDR Temperature Monitoring
 **************************
 
+For enabling temperature polling in the DDR subsystem the configuration DTSI
+(see :ref:`ddr-init-am6`) must be regenerated after selecting 'Yes'
+for LPDDR > DDRSS x > Enable DRAM Temperature Polling and also changing the DRAM
+Timing Parameters as prompted by the tool.
+
+The kernel DDR driver utilizes this polling feature to provide base support for
+dynamic DDR refresh rate changes (see :ref:`ddr-temperature-monitoring-linux`)
+
+***************************
+Error Correction Code (ECC)
+***************************
+
 For SDRAM data integrity, the DDRSS bridge supports inline ECC on the data
 written to or read from the SDRAM. ECC is stored together with the data so that
 a dedicated SDRAM device for ECC is not required. The 8-bit single error
diff --git a/source/linux/Foundational_Components_Kernel_Drivers.rst b/source/linux/Foundational_Components_Kernel_Drivers.rst
@@ -15,6 +15,7 @@ Kernel Drivers
    Foundational_Components/Kernel/Kernel_Drivers/MCAN
    Foundational_Components/Kernel/Kernel_Drivers/MCRC64
    Foundational_Components/Kernel/Kernel_Drivers/DCAN
+   Foundational_Components/Kernel/Kernel_Drivers/DDR
    Foundational_Components/Kernel/Kernel_Drivers/Display/DSS
    Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7
    Foundational_Components/Kernel/Kernel_Drivers/Display/LCDC
