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

Neha Malcom Francis · Neha Malcom Francis · commit 7e2cdee69caf · 2025-12-09T23:25:05.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,104 @@
+.. _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
+
+   * - J7200
+     - Yes
+
+   * - 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
+
+.. _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:
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - 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,6 +24,22 @@ 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')
 
    **********
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
