Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update troubleshooting docs #8901

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update troubleshooting docs #8901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2894ee2
Update troubleshooting docs
mcspr Mar 31, 2023
e1618eb
Merge branch 'master' into troubleshooting
d-a-v Jul 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ Documentation for latest development version: https://arduino-esp8266.readthedoc
If you find the forum useful, please consider supporting it with a donation. <br />
[![Donate](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://www.paypal.com/webscr?cmd=_s-xclick&hosted_button_id=4M56YCWV6PX66)

Feel free to ask questions at our [Gitter channel](https://app.gitter.im/#/room/#esp8266_Arduino:gitter.im).

If you encounter an issue which you think is a bug in the ESP8266 Arduino Core or the associated libraries, or if you want to propose an enhancement, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues.

Please provide as much context as possible, as well as the information requested in the issue template:
Expand Down
5 changes: 3 additions & 2 deletions doc/Troubleshooting/debugging.rst → doc/Troubleshooting/core_debugging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
Debugging
=========
Core Debugging
==============


Introduction
------------
Expand Down
0 ...aq/pictures/a02-decode-stack-tace-1-2.png → ...roubleshooting/decode-stack-trace-1-2.png
View file
Open in desktop
File renamed without changes
0 ...aq/pictures/a02-decode-stack-tace-3-6.png → ...roubleshooting/decode-stack-trace-3-6.png
View file
Open in desktop
File renamed without changes
Binary file added doc/Troubleshooting/exception-cause-decoding.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
96 changes: 96 additions & 0 deletions doc/Troubleshooting/exception_causes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
Exception Causes (EXCCAUSE)
===========================


+----------+--------------------------------+-----------------------------------------+-------------+----------+
| EXCCAUSE | Cause Name | Cause Description | Required | EXCVADDR |
| Code | | | Option | Loaded |
+==========+================================+=========================================+=============+==========+
| 0 | IllegalInstructionCause | Illegal instruction | Exception | No |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 1 | SyscallCause | SYSCALL instruction | Exception | No |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 2 | InstructionFetchErrorCause | Processor internal physical address or | Exception | Yes |
| | | data error during instruction fetch | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 3 | LoadStoreErrorCause | Processor internal physical address or | Exception | Yes |
| | | data error during load or store | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 4 | Level1InterruptCause | Level-1 interrupt as indicated by set | Interrupt | No |
| | | level-1 bits in the INTERRUPT register | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 5 | AllocaCause | MOVSP instruction, if caller’s | Windowed | No |
| | | registers are not in the register file | Register | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 6 | IntegerDivideByZeroCause | QUOS, QUOU, REMS, or REMU divisor | 32-bit | No |
| | | operand is zero | Integer | |
| | | | Divide | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 7 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 8 | PrivilegedCause | Attempt to execute a privileged | MMU | No |
| | | operation when CRING != 0 | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 9 | LoadStoreAlignmentCause | Load or store to an unaligned address | Unaligned | Yes |
| | | | Exception | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 10..11 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 12 | InstrPIFDateErrorCause | PIF data error during instruction fetch | Processor | Yes |
| | | | Interface | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 13 | LoadStorePIFDataErrorCause | Synchronous PIF data error during | Processor | Yes |
| | | LoadStore access | Interface | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 14 | InstrPIFAddrErrorCause | PIF address error during instruction | Processor | Yes |
| | | fetch | Interface | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 15 | LoadStorePIFAddrErrorCause | Synchronous PIF address error during | Processor | Yes |
| | | LoadStore access | Interface | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 16 | InstTLBMissCause | Error during Instruction TLB refill | MMU | Yes |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 17 | InstTLBMultiHitCause | Multiple instruction TLB entries | MMU | Yes |
| | | matched | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 18 | InstFetchPrivilegeCause | An instruction fetch referenced a | MMU | Yes |
| | | virtual address at a ring level less | | |
| | | than CRING | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 19 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 20 | InstFetchProhibitedCause | An instruction fetch referenced a page | Region | Yes |
| | | mapped with an attribute that does not | Protection | |
| | | permit instruction fetch | or MMU | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 21..23 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 24 | LoadStoreTLBMissCause | Error during TLB refill for a load or | MMU | Yes |
| | | store | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 25 | LoadStoreTLBMultiHitCause | Multiple TLB entries matched for a load | MMU | Yes |
| | | or store | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 26 | LoadStorePrivilegeCause | A load or store referenced a virtual | MMU | Yes |
| | | address at a ring level less than CRING | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 27 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 28 | LoadProhibitedCause | A load referenced a page mapped with an | Region | Yes |
| | | attribute that does not permit loads | Protection | |
| | | | or MMU | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 29 | StoreProhibitedCause | A store referenced a page mapped with | Region | Yes |
| | | an attribute that does not permit | Protection | |
| | | | or MMU | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 30..31 | Reserved for Tensilica | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 32..39 | CoprocessornDisabled | Coprocessor n instruction when cpn | Coprocessor | No |
| | | disabled. n varies 0..7 as the cause | | |
| | | varies 32..39 | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+
| 40..63 | Reserved | | | |
+----------+--------------------------------+-----------------------------------------+-------------+----------+

Infos from Xtensa Instruction Set Architecture (ISA) Reference Manual
Binary file added doc/Troubleshooting/hw-watchdog-example.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
60 changes: 60 additions & 0 deletions doc/Troubleshooting/improving_exception_decoder_results.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
Improving Exception Decoder Results
===================================


Due to the limited resources on the device, our default compiler optimizations
focus on creating the smallest code size (``.bin`` file). The GCC compiler's
option ``-Os`` contains the base set of optimizations used. This set is fine for
release but not ideal for debugging.

Our view of a crash is often the `Stack Dump <stack_dump.rst>`__
which gets copy/pasted into an Exception Decoder.
For some situations, the optimizer doesn't write caller return addresses to the
stack. When we crash, the list of functions called is missing. And when the
crash occurs in a leaf function, there is seldom if ever any evidence of who
called.

With the ``-Os`` option, functions called once are inlined into the calling
function. A chain of these functions can optimize down to the calling function.
When the crash occurs in one of these chain functions, the actual location in
the source code is no longer available.

When you select ``Debug Optimization: Lite`` on the Arduino IDE Tools menu, it
turns off ``optimize-sibling-calls``. Turning off this optimization allows more
caller addresses to be written to the stack, improving the results from the
Exception Decoder. Without this option, the callers involved in the crash may be
missing from the Decoder results. Because of the limited stack space, there is
the remote possibility that removing this optimization could lead to more
frequent stack overflows. You only want to do this in a debug setting. This
option does not help the chained function issue.

When you select ``Debug Optimization: Optimum``, you get an even more complete
stack trace. For example, chained function calls may show up. This selection
uses the compiler option ``-Og``. GCC considers this the ideal optimization for
the "edit-compile-debug cycle" ... "producing debuggable code." You can read the
specifics at `GCC's Optimize Options <https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html>`__

When global optimization creates build size issues or stack overflow issues,
select ``Debug Optimization: None``, and use a targeted approach with
``#pragma GCC optimize("Og")`` at the module level. Or, if you want to use a
different set of optimizations, you can set optimizations through build options.
Read more at `Global Build Options <../faq/a06-global-build-options.rst>`__.

For non-Arduino IDE build platforms, you may need to research how to add build
options. Some build platforms already use ``-Og`` for debug builds.

A crash in a leaf function may not leave the caller's address on the stack.
The return address can stay in a register for the duration of the call.
Resulting in a crash report identifying the crashing function without a
trace of who called. You can encourage the compiler to save the caller's
return address by adding an inline assembly trick
``__asm__ __volatile__("" ::: "a0", "memory");`` at the beginning of the
function's body. Or instead, for a debug build conditional option, use the
macro ``DEBUG_LEAF_FUNCTION()`` from ``#include <debug.h>``. For compiler
toolchain 3.2.0 and above, the ``-Og`` option is an alternative solution.

In some cases, adding ``#pragma GCC optimize("Og,no-ipa-pure-const")`` to a
module as well as using ``DEBUG_LEAF_FUNCTION()`` in a leaf function were
needed to display a complete call chain. Or use
``#pragma GCC optimize("Os,no-inline,no-optimize-sibling-calls,no-ipa-pure-const")``
if you require optimization ``-Os``.
Loading