Merge branch 'docs/cpu_lockup' into 'master'

Docs/cpu lockup

See merge request espressif/esp-idf!33072

components/esp_system/include/esp_system.h

@@ -37,7 +37,7 @@ typedef enum {
     ESP_RST_JTAG,       //!< Reset by JTAG
     ESP_RST_EFUSE,      //!< Reset due to efuse error
     ESP_RST_PWR_GLITCH, //!< Reset due to power glitch detected
-    ESP_RST_CPU_LOCKUP, //!< Reset due to CPU lock up
+    ESP_RST_CPU_LOCKUP, //!< Reset due to CPU lock up (double exception)
 } esp_reset_reason_t;
 
 /**

components/soc/esp32c5/include/soc/Kconfig.soc_caps.in

@@ -395,6 +395,10 @@ config SOC_CPU_PMP_REGION_GRANULARITY
     int
     default 128
 
+config SOC_CPU_HAS_LOCKUP_RESET
+    bool
+    default y
+
 config SOC_DS_SIGNATURE_MAX_BIT_LEN
     int
     default 3072

components/soc/esp32c5/include/soc/soc_caps.h

@@ -164,6 +164,8 @@
 #define SOC_CPU_IDRAM_SPLIT_USING_PMP   1
 #define SOC_CPU_PMP_REGION_GRANULARITY  128
 
+#define SOC_CPU_HAS_LOCKUP_RESET        1
+
 /*-------------------------- DIGITAL SIGNATURE CAPS ----------------------------------------*/
 /** The maximum length of a Digital Signature in bits. */
 #define SOC_DS_SIGNATURE_MAX_BIT_LEN (3072)

components/soc/esp32c61/include/soc/Kconfig.soc_caps.in

@@ -203,6 +203,10 @@ config SOC_CPU_PMP_REGION_GRANULARITY
     int
     default 128
 
+config SOC_CPU_HAS_LOCKUP_RESET
+    bool
+    default y
+
 config SOC_DMA_CAN_ACCESS_FLASH
     bool
     default y

components/soc/esp32c61/include/soc/soc_caps.h

@@ -144,6 +144,8 @@
 #define SOC_CPU_IDRAM_SPLIT_USING_PMP   1
 #define SOC_CPU_PMP_REGION_GRANULARITY  128 // TODO IDF-9580 check when doing PMP bringup
 
+#define SOC_CPU_HAS_LOCKUP_RESET        1
+
 /*-------------------------- DMA Common CAPS ----------------------------------------*/
 #define SOC_DMA_CAN_ACCESS_FLASH 1 /*!< DMA can access Flash memory */
 

components/soc/esp32p4/include/soc/Kconfig.soc_caps.in

@@ -519,6 +519,10 @@ config SOC_CPU_PMP_REGION_GRANULARITY
     int
     default 128
 
+config SOC_CPU_HAS_LOCKUP_RESET
+    bool
+    default y
+
 config SOC_DS_SIGNATURE_MAX_BIT_LEN
     int
     default 4096

components/soc/esp32p4/include/soc/soc_caps.h

@@ -188,6 +188,8 @@
 #define SOC_CPU_IDRAM_SPLIT_USING_PMP   1
 #define SOC_CPU_PMP_REGION_GRANULARITY  128
 
+#define SOC_CPU_HAS_LOCKUP_RESET        1
+
 /*-------------------------- DIGITAL SIGNATURE CAPS ----------------------------------------*/
 /** The maximum length of a Digital Signature in bits. */
 #define SOC_DS_SIGNATURE_MAX_BIT_LEN (4096)

docs/en/api-guides/fatal-errors.rst

@@ -532,6 +532,16 @@ The backtrace should point to the function where stack smashing has occurred. Ch
     .. |CACHE_ERR_MSG| replace:: Cache error
     .. |STACK_OVERFLOW| replace:: Stack overflow
 
+
+.. only:: SOC_CPU_HAS_LOCKUP_RESET
+
+    CPU Lockup
+    ^^^^^^^^^^
+    A CPU lockup reset happens when there is a double exception, i.e. when an exception occurs while the CPU is already in an exception handler. The most common cause for this is when the cache is in such a state that accessing external memory not possible. If this is the case then the panic handler will crash as well due to being unable to fetch instructions or read data.
+
+    If this is the case you can try placing the panic handler code in IRAM, which can be accessed when cache is disabled, to get more information about the cause of the lockup. This can be done with :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM`.
+
+
 Undefined Behavior Sanitizer (UBSAN) Checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^