From 8d55e70ef81a772a72fef6f5e7d6ea0512247c5d Mon Sep 17 00:00:00 2001 From: Neha Malcom Francis Date: Mon, 8 Dec 2025 14:49:57 +0530 Subject: [PATCH 1/2] chore(linux): Make U-Boot DDR documentation generic Current U-Boot documentation only describes one of the many functionalities of the U-Boot DDR driver i.e. Inline ECC. Modify it to become generic and make sure to add the page for missing platforms (J7200 and J721E) where Inline ECC is presently not tested officially (yet). Signed-off-by: Neha Malcom Francis --- configs/J7200/J7200_linux_toc.txt | 1 + configs/J721E/J721E_linux_toc.txt | 1 + .../U-Boot/UG-DDRSS-J7.rst | 71 +++++++++++++------ .../U-Boot/UG-DDRSS.rst | 56 ++++++++++----- 4 files changed, 88 insertions(+), 41 deletions(-) diff --git a/configs/J7200/J7200_linux_toc.txt b/configs/J7200/J7200_linux_toc.txt index 696a4252c..2b4d7200d 100644 --- a/configs/J7200/J7200_linux_toc.txt +++ b/configs/J7200/J7200_linux_toc.txt @@ -37,6 +37,7 @@ linux/Foundational_Components/U-Boot/UG-NOR linux/Foundational_Components/U-Boot/UG-UART linux/Foundational_Components/U-Boot/UG-SATA linux/Foundational_Components/U-Boot/UG-UFS +linux/Foundational_Components/U-Boot/UG-DDRSS-J7 linux/Foundational_Components/U-Boot/UG-HyperBus linux/Foundational_Components/U-Boot/UG-RemoteProc linux/Foundational_Components/U-Boot/UG-AVS diff --git a/configs/J721E/J721E_linux_toc.txt b/configs/J721E/J721E_linux_toc.txt index d2659ce33..ad0db6add 100644 --- a/configs/J721E/J721E_linux_toc.txt +++ b/configs/J721E/J721E_linux_toc.txt @@ -37,6 +37,7 @@ linux/Foundational_Components/U-Boot/UG-NOR linux/Foundational_Components/U-Boot/UG-UART linux/Foundational_Components/U-Boot/UG-SATA linux/Foundational_Components/U-Boot/UG-UFS +linux/Foundational_Components/U-Boot/UG-DDRSS-J7 linux/Foundational_Components/U-Boot/UG-HyperBus linux/Foundational_Components/U-Boot/UG-RemoteProc linux/Foundational_Components/U-Boot/UG-AVS diff --git a/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst b/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst index 460869f10..27afd8f11 100644 --- a/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst +++ b/source/linux/Foundational_Components/U-Boot/UG-DDRSS-J7.rst @@ -1,18 +1,43 @@ -######### -DDRSS ECC -######### +### +DDR +### ******** Overview ******** -The DDR subsystem (DDRSS) comprises DDR controller, DDR PHY and wrapper logic -to integrate these blocks in the device. For SDRAM data integrity, the DDRSS +The DDR subsystem (DDRSS) comprises DDR controller, DDR PHY and wrapper logic to +integrate these blocks in the device. The K3 DDRSS driver +(:file:`drivers/ram/k3-ddrss/k3-ddrss.c`) runs during the R5 SPL stage and is +responsible for initializing and configuring the DDR subsystem. + +****************** +DDR Initialization +****************** + +The driver utilizes an auto-generated configuration file containing the +necessary settings for the DDR. It configures the frequency, timing parameters, +training algorithms etc. for DDR initialization. The configuration DTSI can be +generated using the `Sysconfig tool `_ and +selecting the software product as "DDR Configuration for \*" as well as the +required device. + +********** +Inline ECC +********** + +.. ifconfig:: CONFIG_part_variant in ('J7200', 'J721E') + + .. note:: + + Inline ECC is currently not tested and supported for J721E and J7200 + +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 correction double error detection (SECDED) ECC data is calculated over 64-bit data quanta. For every 256-byte data block -32 bytes of ECC is stored inline. Thus 1/9th of the total SDRAM space is used +32 bytes of ECC is stored inline. Thus, 1/9th of the total SDRAM space is used for ECC storage and the remaining 8/9th of the SDRAM data space are seen as consecutive byte addresses. Even if there are non-ECC protected regions the previously described 1/9th-8/9th rule still applies and consecutive byte @@ -25,8 +50,8 @@ protected by it. 1-bit error is correctable by ECC, but multi-bit and multiple 1-bit errors are not correctable and will be treated as an uncorrectable error. Any uncorrectable error will cause a bus abort. -DDRSS inline ECC handling -========================= +ECC Handling +============ .. note:: @@ -35,22 +60,22 @@ DDRSS inline ECC handling Enabling inline ECC ------------------- -The inline ECC feature of DDRSS can be enabled by adding the -``CONFIG_K3_INLINE_ECC`` config to the R5 defconfig: + The inline ECC feature of DDRSS can be enabled by adding the + ``CONFIG_K3_INLINE_ECC`` config to the R5 defconfig: - .. code-block:: kconfig + .. code-block:: kconfig - # u-boot/configs/*_r5_defconfig + # u-boot/configs/*_r5_defconfig - CONFIG_PINCTRL_SINGLE=y - CONFIG_POWER_DOMAIN=y - CONFIG_TI_POWER_DOMAIN=y - CONFIG_K3_INLINE_ECC=y - CONFIG_K3_SYSTEM_CONTROLLER=y - CONFIG_REMOTEPROC_TI_K3_ARM64=y - CONFIG_RESET_TI_SCI=y + CONFIG_PINCTRL_SINGLE=y + CONFIG_POWER_DOMAIN=y + CONFIG_TI_POWER_DOMAIN=y + CONFIG_K3_INLINE_ECC=y + CONFIG_K3_SYSTEM_CONTROLLER=y + CONFIG_REMOTEPROC_TI_K3_ARM64=y + CONFIG_RESET_TI_SCI=y -This enables inline ECC for the entire region of the DDR. + This enables inline ECC for the entire region of the DDR. Priming with BIST Engine ------------------------ @@ -73,8 +98,8 @@ the absence of which it resorts to enabling for the entire DDR region: .. code-block:: dts inline_ecc: protected@9e780000 { - device_type = "ecc"; - reg = <0x9e780000 0x0080000>; - bootph-all; + device_type = "ecc"; + reg = <0x9e780000 0x0080000>; + bootph-all; }; diff --git a/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst b/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst index 4d2c658c2..9b76ee171 100644 --- a/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst +++ b/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst @@ -1,24 +1,44 @@ -######### -DDRSS ECC -######### +### +DDR +### ******** Overview ******** -The DDR subsystem (DDRSS) comprises DDR controller, DDR PHY and wrapper logic -to integrate these blocks in the device. 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 correction double error detection (SECDED) -ECC data is calculated over 64-bit data quanta. For every 256-byte data block -32 bytes of ECC is stored inline. Thus 1/9th of the total SDRAM space is used -for ECC storage and the remaining 8/9th of the SDRAM data space are seen as -consecutive byte addresses. Even if there are non-ECC protected regions the -previously described 1/9th-8/9th rule still applies and consecutive byte -addresses are seen from system point of view. |__PART_FAMILY_DEVICE_NAMES__| -supports up to 3 ECC protected non-overlapping memory ranges. The current -U-Boot release supports a single region covering the entire SDRAM space. +The DDR subsystem (DDRSS) comprises DDR controller, DDR PHY and wrapper logic to +integrate these blocks in the device. The K3 DDRSS driver +(:file:`drivers/ram/k3-ddrss/k3-ddrss.c`) runs during the R5 SPL stage and is +responsible for initializing and configuring the DDR subsystem. + +****************** +DDR Initialization +****************** + +The driver utilizes an auto-generated configuration file containing the +necessary settings for the DDR. It configures the frequency, timing parameters, +training algorithms etc. for DDR initialization. The configuration DTSI can be +generated using the `Sysconfig tool `_ and +selecting the software product as "DDR Configuration for \*" as well as the +required device. + +************************** +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 +correction double error detection (SECDED) ECC data is calculated over 64-bit +data quanta. For every 256-byte data block 32 bytes of ECC is stored inline. +Thus 1/9th of the total SDRAM space is used for ECC storage and the remaining +8/9th of the SDRAM data space are seen as consecutive byte addresses. Even if +there are non-ECC protected regions the previously described 1/9th-8/9th rule +still applies and consecutive byte addresses are seen from system point of view. + +|__PART_FAMILY_DEVICE_NAMES__| supports up to 3 ECC protected non-overlapping +memory ranges. The current U-Boot release supports a single region covering the +entire SDRAM space. ECC is calculated for all accesses that are within the address ranges protected by it. 1-bit error is correctable by ECC, but multi-bit and @@ -38,8 +58,8 @@ three ways to handle it: Options 1 and 2 doesn't report the reason. So, if there is a need to report the reason behind uncorrectable error handle it the third way. -DDRSS ECC handling -================== +ECC Handling +============ .. note:: From 29ec80b30696ffddf9375dc54bafb26ac529722e Mon Sep 17 00:00:00 2001 From: Neha Malcom Francis Date: Tue, 9 Dec 2025 16:03:31 +0530 Subject: [PATCH 2/2] feat(linux): Add documentation for dynamic DDR refresh rate change Add driver documentation for kernel DDR driver and how to enable DDR temperature monitoring. Signed-off-by: Neha Malcom Francis --- configs/AM62AX/AM62AX_linux_toc.txt | 1 + configs/AM62PX/AM62PX_linux_toc.txt | 1 + configs/AM62X/AM62X_linux_toc.txt | 1 + configs/AM64X/AM64X_linux_toc.txt | 1 + configs/J7200/J7200_linux_toc.txt | 1 + configs/J721E/J721E_linux_toc.txt | 1 + .../Kernel/Kernel_Drivers/DDR.rst | 95 +++++++++++++++++++ .../U-Boot/UG-DDRSS-J7.rst | 18 ++++ .../U-Boot/UG-DDRSS.rst | 18 +++- ...Foundational_Components_Kernel_Drivers.rst | 1 + 10 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 source/linux/Foundational_Components/Kernel/Kernel_Drivers/DDR.rst diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt index 1711340bc..aa0758c15 100644 --- 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 index e875759b6..c981ffd93 100644 --- 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 index 251919bbf..015846561 100644 --- 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 index 664a75fa3..162546a25 100644 --- 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 index 2b4d7200d..b47ca5641 100644 --- 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 index ad0db6add..039c31493 100644 --- 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 new file mode 100644 index 000000000..d18d4434d --- /dev/null +++ b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DDR.rst @@ -0,0 +1,95 @@ +.. _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 LP SK/ AM62Ax / AM62Px + - Yes + +******************************** +Building and Enabling the Driver +******************************** + +.. rubric:: Kernel Configuration + +The following kernel configuration enables the K3 DDR driver: + +.. 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. + +See :ref:`ddr-temperature-monitoring-uboot` 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 index 27afd8f11..9a25ada9c 100644 --- 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 (:file:`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: + ****************** DDR Initialization ****************** @@ -22,6 +24,22 @@ generated using the `Sysconfig tool `_ and selecting the software product as "DDR Configuration for \*" as well as the required device. +.. _ddr-temperature-monitoring-uboot: + +************************** +DDR Temperature Monitoring +************************** + +For enabling temperature polling in the DDR subsystem, the configuration DTSI +(see :ref:`ddr-init`) 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`) + ********** Inline ECC ********** diff --git a/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst b/source/linux/Foundational_Components/U-Boot/UG-DDRSS.rst index 9b76ee171..5a1ccf8de 100644 --- 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 (:file:`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: + ****************** DDR Initialization ****************** @@ -22,10 +24,24 @@ generated using the `Sysconfig tool `_ and selecting the software product as "DDR Configuration for \*" as well as the required device. +.. _ddr-temperature-monitoring-uboot: + ************************** -Error Correction Code (ECC) +DDR Temperature Monitoring ************************** +For enabling temperature polling in the DDR subsystem the configuration DTSI +(see :ref:`ddr-init`) 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 index 11bf6d51e..a742b2c58 100644 --- 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