From abe56e2bbeac816533fc9aba6b8356d9219edb75 Mon Sep 17 00:00:00 2001
From: Guillaume Souchere <guillaume.souchere@espressif.com>
Date: Mon, 14 Nov 2022 12:41:04 +0100
Subject: [PATCH] docs: add section in ram-uasge.rst to clarify DRAM
 limitations on esp32.

The sections details that only 160KB of DRAM can be used for statically allocated data.
Reference this new section in mem_alloc.rst and memory-types.rst.
---
 docs/en/api-guides/memory-types.rst        | 4 ++++
 docs/en/api-reference/system/mem_alloc.rst | 4 +++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/en/api-guides/memory-types.rst b/docs/en/api-guides/memory-types.rst
index 8cc3bddb8e..67aeaab5ac 100644
--- a/docs/en/api-guides/memory-types.rst
+++ b/docs/en/api-guides/memory-types.rst
@@ -24,6 +24,10 @@ Non-constant static data (.data) and zero-initialized data (.bss) is placed by t
 
    The available size of the internal DRAM region is reduced by 64 KB (by shifting start address to ``0x3FFC0000``) if Bluetooth stack is used. Length of this region is also reduced by 16 KB or 32 KB if trace memory is used. Due to some memory fragmentation issues caused by ROM, it is also not possible to use all available DRAM for static allocations - however the remaining DRAM is still available as heap at runtime.
 
+   .. note::
+   
+    There is 520KB of available SRAM (320KB of DRAM and 200KB of IRAM) on the esp32. However, due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
+
 .. only:: not esp32
 
    .. note::
diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst
index 86d2c3267b..be5c359e79 100644
--- a/docs/en/api-reference/system/mem_alloc.rst
+++ b/docs/en/api-reference/system/mem_alloc.rst
@@ -40,6 +40,8 @@ the standard ``free()`` function.
 Available Heap
 --------------
 
+.. _dram-definition:
+
 DRAM
 ^^^^
 
@@ -49,7 +51,7 @@ To find the amount of statically allocated memory, use the :ref:`idf.py size <id
 
 .. only:: esp32
 
-    .. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
+    .. note:: See the :ref:`dram` section for more details about the DRAM usage limitations.
 
 .. note:: At runtime, the available heap DRAM may be less than calculated at compile time, because at startup some memory is allocated from the heap before the FreeRTOS scheduler is started (including memory for the stacks of initial FreeRTOS tasks).