From 33deabb3ab269b8ad7b200b10e66e6510ad93e16 Mon Sep 17 00:00:00 2001 From: Omar Chebib Date: Mon, 22 Feb 2021 10:16:56 +0800 Subject: [PATCH] doc: update "Fatal Errors" chapter for ESP32C3 board --- docs/en/api-guides/fatal-errors.rst | 203 ++++++++++++++++++------- docs/zh_CN/api-guides/fatal-errors.rst | 198 +++++++++++++++++------- 2 files changed, 286 insertions(+), 115 deletions(-) diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index af225aed2e..828a8c74b2 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -7,8 +7,7 @@ Overview In certain situations, execution of the program can not be continued in a well defined way. In ESP-IDF, these situations include: -- CPU Exceptions: Illegal Instruction, Load/Store Alignment Error, Load/Store Prohibited error, Double Exception. - +- CPU Exceptions: |CPU_EXCEPTIONS_LIST| - System level checks and safeguards: - :doc:`Interrupt watchdog <../api-reference/system/wdts>` timeout @@ -28,15 +27,19 @@ Panic Handler Every error cause listed in the `Overview`_ will be handled by *panic handler*. -Panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be similar to:: +Panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be similar to - Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was unhandled. +.. parsed-literal:: -For some of the system level checks (interrupt watchdog, cache access error), the message will be similar to:: + Guru Meditation Error: Core 0 panic'ed (|ILLEGAL_INSTR_MSG|). Exception was unhandled. - Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region accessed) +For some of the system level checks (interrupt watchdog, cache access error), the message will be similar to -In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes. +.. parsed-literal:: + + Guru Meditation Error: Core 0 panic'ed (|CACHE_ERR_MSG|). Exception was unhandled. + +In all cases, error cause will be printed in parentheses. See `Guru Meditation Errors`_ for a list of possible error causes. Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are: @@ -114,51 +117,99 @@ The following diagram illustrates panic handler behavior: Register Dump and Backtrace --------------------------- -Unless ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console:: +Unless ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console - Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA - Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + :: + + Core 0 register dump: + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + + Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + :: + + Core 0 register dump: + MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 + TP : 0x3fc8a2ac T0 : 0x40057fa6 T1 : 0x0000000f T2 : 0x00000000 + S0/FP : 0x00000000 S1 : 0x00000000 A0 : 0x00000001 A1 : 0x00000001 + A2 : 0x00000064 A3 : 0x00000004 A4 : 0x00000001 A5 : 0x00000000 + A6 : 0x42001fd6 A7 : 0x00000000 S2 : 0x00000000 S3 : 0x00000000 + S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 : 0x00000000 + S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 : 0x00000000 + T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 : 0x00000000 + MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000 + MHARTID : 0x00000000 Register values printed are the register values in the exception frame, i.e. values at the moment when CPU exception or other fatal error has occured. Register dump is not printed if the panic handler was executed as a result of an ``abort()`` call. -In some cases, such as interrupt watchdog timeout, panic handler may print additional CPU registers (EPC1-EPC4) and the registers/backtrace of the code running on the other CPU. +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA + + In some cases, such as interrupt watchdog timeout, panic handler may print additional CPU registers (EPC1-EPC4) and the registers/backtrace of the code running on the other CPU. -Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task which was interrupted, and from the ISR. + Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task which was interrupted, and from the ISR. -If :doc:`IDF Monitor ` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines:: +If :doc:`IDF Monitor ` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines - Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 + :: - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + Core 0 register dump: + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 - 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 - 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + + Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 + + 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + :: + + Core 0 register dump: + MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 + 0x420048b4: app_main at /Users/user/esp/example/main/hello_world_main.c:20 + + 0x420048b4: app_main at /Users/user/esp/example/main/hello_world_main.c:20 + + TP : 0x3fc8a2ac T0 : 0x40057fa6 T1 : 0x0000000f T2 : 0x00000000 + S0/FP : 0x00000000 S1 : 0x00000000 A0 : 0x00000001 A1 : 0x00000001 + A2 : 0x00000064 A3 : 0x00000004 A4 : 0x00000001 A5 : 0x00000000 + A6 : 0x42001fd6 A7 : 0x00000000 S2 : 0x00000000 S3 : 0x00000000 + 0x42001fd6: uart_write at /Users/user/esp/esp-idf/components/vfs/vfs_uart.c:201 + + S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 : 0x00000000 + S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 : 0x00000000 + T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 : 0x00000000 + MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000 + MHARTID : 0x00000000 To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack. GDB Stub -------- -If ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port. +If ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port. If :doc:`IDF Monitor ` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this:: @@ -198,8 +249,8 @@ This section explains the meaning of different error causes, printed in parens a .. note:: See `Wikipedia article `_ for historical origins of "Guru Meditation". -IllegalInstruction -^^^^^^^^^^^^^^^^^^ +|ILLEGAL_INSTR_MSG| +^^^^^^^^^^^^^^^^^^^ This CPU exception indicates that the instruction which was executed was not a valid instruction. Most common reasons for this error include: @@ -212,54 +263,77 @@ Most common reasons for this error include: - Some external device was accidentally connected to SPI flash pins, and has interfered with communication between {IDF_TARGET_NAME} and SPI flash. +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA -InstrFetchProhibited -^^^^^^^^^^^^^^^^^^^^ + InstrFetchProhibited + ^^^^^^^^^^^^^^^^^^^^ -This CPU exception indicates that CPU could not load an instruction because the the address of the instruction did not belong to a valid region in instruction RAM or ROM. + This CPU exception indicates that CPU could not load an instruction because the the address of the instruction did not belong to a valid region in instruction RAM or ROM. -Usually this means an attempt to call a function pointer, which does not point to valid code. ``PC`` (Program Counter) register can be used as an indicator: it will be zero or will contain garbage value (not ``0x4xxxxxxx``). + Usually this means an attempt to call a function pointer, which does not point to valid code. ``PC`` (Program Counter) register can be used as an indicator: it will be zero or will contain garbage value (not ``0x4xxxxxxx``). -LoadProhibited, StoreProhibited -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + LoadProhibited, StoreProhibited + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This CPU exception happens when application attempts to read from or write to an invalid memory location. The address which was written/read is found in ``EXCVADDR`` register in the register dump. If this address is zero, it usually means that application attempted to dereference a NULL pointer. If this address is close to zero, it usually means that application attempted to access member of a structure, but the pointer to the structure was NULL. If this address is something else (garbage value, not in ``0x3fxxxxxx`` - ``0x6xxxxxxx`` range), it likely means that the pointer used to access the data was either not initialized or was corrupted. + This CPU exception happens when application attempts to read from or write to an invalid memory location. The address which was written/read is found in ``EXCVADDR`` register in the register dump. If this address is zero, it usually means that application attempted to dereference a NULL pointer. If this address is close to zero, it usually means that application attempted to access member of a structure, but the pointer to the structure was NULL. If this address is something else (garbage value, not in ``0x3fxxxxxx`` - ``0x6xxxxxxx`` range), it likely means that the pointer used to access the data was either not initialized or was corrupted. -IntegerDivideByZero -^^^^^^^^^^^^^^^^^^^ + IntegerDivideByZero + ^^^^^^^^^^^^^^^^^^^ -Application has attempted to do integer division by zero. + Application has attempted to do integer division by zero. -LoadStoreAlignment -^^^^^^^^^^^^^^^^^^ + LoadStoreAlignment + ^^^^^^^^^^^^^^^^^^ -Application has attempted to read or write memory location, and address alignment did not match load/store size. For example, 32-bit load can only be done from 4-byte aligned address, and 16-bit load can only be done from a 2-byte aligned address. + Application has attempted to read or write memory location, and address alignment did not match load/store size. For example, 32-bit load can only be done from 4-byte aligned address, and 16-bit load can only be done from a 2-byte aligned address. -LoadStoreError -^^^^^^^^^^^^^^ + LoadStoreError + ^^^^^^^^^^^^^^ -This exception may happen in the following cases: + This exception may happen in the following cases: -- If the application has attempted to do an 8- or 16- bit load/store from a memory region which only supports 32-bit loads/stores. For example, dereferencing a ``char*`` pointer to intruction memory (IRAM, IROM) will result in such an error. + - If the application has attempted to do an 8- or 16- bit load/store from a memory region which only supports 32-bit loads/stores. For example, dereferencing a ``char*`` pointer to intruction memory (IRAM, IROM) will result in such an error. -- If the application has attempted a store to a read-only memory region, such as IROM or DROM. + - If the application has attempted a store to a read-only memory region, such as IROM or DROM. -Unhandled debug exception -^^^^^^^^^^^^^^^^^^^^^^^^^ + Unhandled debug exception + ^^^^^^^^^^^^^^^^^^^^^^^^^ -This will usually be followed by a message like:: + This will usually be followed by a message like:: - Debug exception reason: Stack canary watchpoint triggered (task_name) + Debug exception reason: Stack canary watchpoint triggered (task_name) -This error indicates that application has written past the end of the stack of ``task_name`` task. Note that not every stack overflow is guaranteed to trigger this error. It is possible that the task writes to stack beyond the stack canary location, in which case the watchpoint will not be triggered. + This error indicates that application has written past the end of the stack of ``task_name`` task. Note that not every stack overflow is guaranteed to trigger this error. It is possible that the task writes to stack beyond the stack canary location, in which case the watchpoint will not be triggered. + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + Instruction address misaligned + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This CPU exception indicates that the address of the instruction to execute is not 2-byte aligned. + + Instruction access fault, Load access fault, Store access fault + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This CPU exception happens when application attempts to execute, read from or write to an invalid memory location. The address which was written/read is found in ``MTVAL`` register in the register dump. If this address is zero, it usually means that application attempted to dereference a NULL pointer. If this address is close to zero, it usually means that application attempted to access member of a structure, but the pointer to the structure was NULL. If this address is something else (garbage value, not in ``0x3fxxxxxx`` - ``0x6xxxxxxx`` range), it likely means that the pointer used to access the data was either not initialized or was corrupted. + + Breakpoint + ^^^^^^^^^^ + + This CPU exception happens when the instruction ``EBREAK`` is executed. + + Load address misaligned, Store address misaligned + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Application has attempted to read or write memory location, and address alignment did not match load/store size. For example, 32-bit load can only be done from 4-byte aligned address, and 16-bit load can only be done from a 2-byte aligned address. Interrupt wdt timeout on CPU0 / CPU1 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Indicates that interrupt watchdog timeout has occured. See :doc:`Watchdogs <../api-reference/system/wdts>` for more information. -Cache disabled but cached memory region accessed -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +|CACHE_ERR_MSG| +^^^^^^^^^^^^^^^ In some situations ESP-IDF will temporarily disable access to external SPI Flash and SPI RAM via caches. For example, this happens with spi_flash APIs are used to read/write/erase/mmap regions of SPI Flash. In these situations, tasks are suspended, and interrupt handlers not registered with ``ESP_INTR_FLAG_IRAM`` are disabled. Make sure that any interrupt handlers registered with this flag have all the code and data in IRAM/DRAM. Refer to the :ref:`SPI flash API documentation ` for more details. @@ -304,3 +378,14 @@ Stack smashing protection (based on GCC ``-fstack-protector*`` flags) can be ena The backtrace should point to the function where stack smashing has occured. Check the function code for unbounded access to local arrays. +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA + + .. |CPU_EXCEPTIONS_LIST| replace:: Illegal Instruction, Load/Store Alignment Error, Load/Store Prohibited error, Double Exception. + .. |ILLEGAL_INSTR_MSG| replace:: IllegalInstruction + .. |CACHE_ERR_MSG| replace:: Cache disabled but cached memory region accessed + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + .. |CPU_EXCEPTIONS_LIST| replace:: Illegal Instruction, Load/Store Alignment Error, Load/Store Prohibited error. + .. |ILLEGAL_INSTR_MSG| replace:: Illegal instruction + .. |CACHE_ERR_MSG| replace:: Cache error diff --git a/docs/zh_CN/api-guides/fatal-errors.rst b/docs/zh_CN/api-guides/fatal-errors.rst index beacb684b6..699ed84dcb 100644 --- a/docs/zh_CN/api-guides/fatal-errors.rst +++ b/docs/zh_CN/api-guides/fatal-errors.rst @@ -9,7 +9,7 @@ 在某些情况下，程序并不会按照我们的预期运行，在 ESP-IDF 中，这些情况包括： -- CPU 异常：非法指令，加载/存储时的内存对齐错误，加载/存储时的访问权限错误，双重异常。 +- CPU 异常：|CPU_EXCEPTIONS_LIST| - 系统级检查错误： - :doc:`中断看门狗 <../api-reference/system/wdts>` 超时 @@ -29,13 +29,17 @@ :ref:`Overview` 中列举的所有错误都会由 *紧急处理程序（Panic Handler）* 负责处理。 -紧急处理程序首先会将出错原因打印到控制台，例如 CPU 异常的错误信息通常会类似于:: +紧急处理程序首先会将出错原因打印到控制台，例如 CPU 异常的错误信息通常会类似于 - Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was unhandled. +.. parsed-literal:: -对于一些系统级检查错误（如中断看门狗超时，高速缓存访问错误等），错误信息会类似于:: + Guru Meditation Error: Core 0 panic'ed (|ILLEGAL_INSTR_MSG|). Exception was unhandled. - Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region accessed) +对于一些系统级检查错误（如中断看门狗超时，高速缓存访问错误等），错误信息会类似于 + +.. parsed-literal:: + + Guru Meditation Error: Core 0 panic'ed (|CACHE_ERR_MSG|). Exception was unhandled. 不管哪种情况，错误原因都会被打印在括号中。请参阅 :ref:`Guru-Meditation-Errors` 以查看所有可能的出错原因。 @@ -112,44 +116,92 @@ 寄存器转储与回溯 ---------------- -除非启用了 ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` 否则紧急处理程序会将 CPU 寄存器和回溯打印到控制台:: +除非启用了 ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` 否则紧急处理程序会将 CPU 寄存器和回溯打印到控制台 - Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA - Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + :: + + Core 0 register dump: + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + + Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + :: + + Core 0 register dump: + MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 + TP : 0x3fc8a2ac T0 : 0x40057fa6 T1 : 0x0000000f T2 : 0x00000000 + S0/FP : 0x00000000 S1 : 0x00000000 A0 : 0x00000001 A1 : 0x00000001 + A2 : 0x00000064 A3 : 0x00000004 A4 : 0x00000001 A5 : 0x00000000 + A6 : 0x42001fd6 A7 : 0x00000000 S2 : 0x00000000 S3 : 0x00000000 + S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 : 0x00000000 + S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 : 0x00000000 + T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 : 0x00000000 + MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000 + MHARTID : 0x00000000 仅会打印异常帧中 CPU 寄存器的值，即引发 CPU 异常或者其它严重错误时刻的值。 紧急处理程序如果是因 abort() 而调用，则不会打印寄存器转储。 -在某些情况下，例如中断看门狗超时，紧急处理程序会额外打印 CPU 寄存器（EPC1-EPC4）的值，以及另一个 CPU 的寄存器值和代码回溯。 +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA -回溯行包含了当前任务中每个堆栈帧的 PC:SP 对（PC 是程序计数器，SP 是堆栈指针）。如果在 ISR 中发生了严重错误，回溯会同时包括被中断任务的 PC:SP 对，以及 ISR 中的 PC:SP 对。 + 在某些情况下，例如中断看门狗超时，紧急处理程序会额外打印 CPU 寄存器（EPC1-EPC4）的值，以及另一个 CPU 的寄存器值和代码回溯。 -如果使用了 :doc:`IDF 监视器 `，该工具会将程序计数器的值转换为对应的代码位置（函数名，文件名，行号），并加以注释:: + 回溯行包含了当前任务中每个堆栈帧的 PC:SP 对（PC 是程序计数器，SP 是堆栈指针）。如果在 ISR 中发生了严重错误，回溯会同时包括被中断任务的 PC:SP 对，以及 ISR 中的 PC:SP 对。 - Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 +如果使用了 :doc:`IDF 监视器 `，该工具会将程序计数器的值转换为对应的代码位置（函数名，文件名，行号），并加以注释 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + :: - Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 - 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 + Core 0 register dump: + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 + + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + + Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 + 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 + + 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + :: + + Core 0 register dump: + MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 + 0x420048b4: app_main at /Users/user/esp/example/main/hello_world_main.c:20 + + 0x420048b4: app_main at /Users/user/esp/example/main/hello_world_main.c:20 + + TP : 0x3fc8a2ac T0 : 0x40057fa6 T1 : 0x0000000f T2 : 0x00000000 + S0/FP : 0x00000000 S1 : 0x00000000 A0 : 0x00000001 A1 : 0x00000001 + A2 : 0x00000064 A3 : 0x00000004 A4 : 0x00000001 A5 : 0x00000000 + A6 : 0x42001fd6 A7 : 0x00000000 S2 : 0x00000000 S3 : 0x00000000 + 0x42001fd6: uart_write at /Users/user/esp/esp-idf/components/vfs/vfs_uart.c:201 + + S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 : 0x00000000 + S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 : 0x00000000 + T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 : 0x00000000 + MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000 + MHARTID : 0x00000000 若要查找发生严重错误的代码位置，请查看 "Backtrace" 的后面几行，发生严重错误的代码显示在顶行，后续几行显示的是调用堆栈。 @@ -200,8 +252,8 @@ Guru Meditation 错误 .. note:: 想要了解 "Guru Meditation" 的历史渊源，请参阅 `维基百科 `_ 。 -IllegalInstruction -^^^^^^^^^^^^^^^^^^ +|ILLEGAL_INSTR_MSG| +^^^^^^^^^^^^^^^^^^^ 此 CPU 异常表示当前执行的指令不是有效指令，引起此错误的常见原因包括： @@ -213,53 +265,76 @@ IllegalInstruction - 某些外部设备意外连接到 SPI Flash 的引脚上，干扰了 {IDF_TARGET_NAME} 和 SPI Flash 之间的通信。 +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA -InstrFetchProhibited -^^^^^^^^^^^^^^^^^^^^ + InstrFetchProhibited + ^^^^^^^^^^^^^^^^^^^^ -此 CPU 异常表示 CPU 无法加载指令，因为指令的地址不在 IRAM 或者 IROM 中的有效区域中。 + 此 CPU 异常表示 CPU 无法加载指令，因为指令的地址不在 IRAM 或者 IROM 中的有效区域中。 -通常这意味着代码中调用了并不指向有效代码块的函数指针。这种情况下，可以查看 ``PC`` （程序计数器）寄存器的值并做进一步判断：若为 0 或者其它非法值（即只要不是 ``0x4xxxxxxx`` 的情况），则证实确实是该原因。 + 通常这意味着代码中调用了并不指向有效代码块的函数指针。这种情况下，可以查看 ``PC`` （程序计数器）寄存器的值并做进一步判断：若为 0 或者其它非法值（即只要不是 ``0x4xxxxxxx`` 的情况），则证实确实是该原因。 -LoadProhibited, StoreProhibited -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + LoadProhibited, StoreProhibited + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -当应用程序尝试读取或写入无效的内存位置时，会发生此类 CPU 异常。此类无效内存地址可以在寄存器转储的 ``EXCVADDR`` 中找到。如果该地址为零，通常意味着应用程序正尝试解引用一个 NULL 指针。如果该地址接近于零，则通常意味着应用程序尝试访问某个结构体的成员，但是该结构体的指针为 NULL。如果该地址是其它非法值（不在 ``0x3fxxxxxx`` - ``0x6xxxxxxx`` 的范围内），则可能意味着用于访问数据的指针未初始化或者已经损坏。 + 当应用程序尝试读取或写入无效的内存位置时，会发生此类 CPU 异常。此类无效内存地址可以在寄存器转储的 ``EXCVADDR`` 中找到。如果该地址为零，通常意味着应用程序正尝试解引用一个 NULL 指针。如果该地址接近于零，则通常意味着应用程序尝试访问某个结构体的成员，但是该结构体的指针为 NULL。如果该地址是其它非法值（不在 ``0x3fxxxxxx`` - ``0x6xxxxxxx`` 的范围内），则可能意味着用于访问数据的指针未初始化或者已经损坏。 -IntegerDivideByZero -^^^^^^^^^^^^^^^^^^^ + IntegerDivideByZero + ^^^^^^^^^^^^^^^^^^^ -应用程序尝试将整数除以零。 + 应用程序尝试将整数除以零。 -LoadStoreAlignment -^^^^^^^^^^^^^^^^^^ + LoadStoreAlignment + ^^^^^^^^^^^^^^^^^^ -应用程序尝试读取/写入的内存位置不符合加载/存储指令对字节对齐大小的要求，例如，32 位加载指令只能访问 4 字节对齐的内存地址，而 16 位加载指令只能访问 2 字节对齐的内存地址。 + 应用程序尝试读取/写入的内存位置不符合加载/存储指令对字节对齐大小的要求，例如，32 位加载指令只能访问 4 字节对齐的内存地址，而 16 位加载指令只能访问 2 字节对齐的内存地址。 -LoadStoreError -^^^^^^^^^^^^^^ + LoadStoreError + ^^^^^^^^^^^^^^ -这类异常通常发生于以下几种场合: + 这类异常通常发生于以下几种场合: -应用程序尝试从仅支持 32 位加载/存储的内存区域执行 8 位或 16 位加载/存储操作，例如，解引用一个指向指令内存区域(比如 IRAM 或者 IROM)的 char* 指针就会触发这个错误。 -应用程序尝试保存数据到只读的内存区域（比如 IROM 或者 DROM）也会触发这个错误。 + 应用程序尝试从仅支持 32 位加载/存储的内存区域执行 8 位或 16 位加载/存储操作，例如，解引用一个指向指令内存区域(比如 IRAM 或者 IROM)的 char* 指针就会触发这个错误。 + 应用程序尝试保存数据到只读的内存区域（比如 IROM 或者 DROM）也会触发这个错误。 -Unhandled debug exception -^^^^^^^^^^^^^^^^^^^^^^^^^ + Unhandled debug exception + ^^^^^^^^^^^^^^^^^^^^^^^^^ -这后面通常会再跟一条消息:: + 这后面通常会再跟一条消息:: - Debug exception reason: Stack canary watchpoint triggered (task_name) + Debug exception reason: Stack canary watchpoint triggered (task_name) -此错误表示应用程序写入的位置越过了 ``task_name`` 任务堆栈的末尾，请注意，并非每次堆栈溢出都会触发此错误。任务有可能会绕过堆栈金丝雀（stack canary）的位置访问堆栈，在这种情况下，监视点就不会被触发。 + 此错误表示应用程序写入的位置越过了 ``task_name`` 任务堆栈的末尾，请注意，并非每次堆栈溢出都会触发此错误。任务有可能会绕过堆栈金丝雀（stack canary）的位置访问堆栈，在这种情况下，监视点就不会被触发。 + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + Instruction address misaligned + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 此 CPU 异常表示要执行的指令地址非 2 字节对齐。 + + Instruction access fault, Load access fault, Store access fault + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 当应用程序尝试读取或写入无效的内存位置时，会发生此类 CPU 异常。此类无效内存地址可以在寄存器转储的 ``MTVAL`` 中找到。如果该地址为零，通常意味着应用程序正尝试解引用一个 NULL 指针。如果该地址接近于零，则通常意味着应用程序尝试访问某个结构体的成员，但是该结构体的指针为 NULL。如果该地址是其它非法值（不在 ``0x3fxxxxxx`` - ``0x6xxxxxxx`` 的范围内），则可能意味着用于访问数据的指针未初始化或者已经损坏。 + + Breakpoint + ^^^^^^^^^^ + + 当执行 ``EBREAK`` 指令时，会发生此 CPU 异常。 + + Load address misaligned, Store address misaligned + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 应用程序尝试读取/写入的内存位置不符合加载/存储指令对字节对齐大小的要求，例如，32 位加载指令只能访问 4 字节对齐的内存地址，而 16 位加载指令只能访问 2 字节对齐的内存地址。 Interrupt wdt timeout on CPU0 / CPU1 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 这表示发生了中断看门狗超时，详细信息请查阅 :doc:`看门狗 <../api-reference/system/wdts>` 文档。 -Cache disabled but cached memory region accessed -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +|CACHE_ERR_MSG| +^^^^^^^^^^^^^^^ 在某些情况下，ESP-IDF 会暂时禁止通过高速缓存访问外部 SPI Flash 和 SPI RAM，例如在使用 spi_flash API 读取/写入/擦除/映射 SPI Flash 的时候。在这些情况下，任务会被挂起，并且未使用 ``ESP_INTR_FLAG_IRAM`` 注册的中断处理程序会被禁用。请确保任何使用此标志注册的中断处理程序所访问的代码和数据分别位于 IRAM 和 DRAM 中。更多详细信息请参阅 :ref:`SPI Flash API 文档 `。 @@ -304,3 +379,14 @@ Stack 粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP 回溯信息会指明发生 Stack 粉碎的函数，建议检查函数中是否有代码访问本地数组时发生了越界。 +.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA + + .. |CPU_EXCEPTIONS_LIST| replace:: 非法指令，加载/存储时的内存对齐错误，加载/存储时的访问权限错误，双重异常。 + .. |ILLEGAL_INSTR_MSG| replace:: IllegalInstruction + .. |CACHE_ERR_MSG| replace:: Cache disabled but cached memory region accessed + +.. only:: CONFIG_IDF_TARGET_ARCH_RISCV + + .. |CPU_EXCEPTIONS_LIST| replace:: 非法指令，加载/存储时的内存对齐错误，加载/存储时的访问权限错误。 + .. |ILLEGAL_INSTR_MSG| replace:: Illegal instruction + .. |CACHE_ERR_MSG| replace:: Cache error