Update documentation

Describe how to improve Exception Decoder results.

Updated build option details.

Author: mhightower83

cores/esp8266/debug.h

@@ -6,6 +6,9 @@
 
 #ifdef DEBUG_ESP_CORE
 #define DEBUGV(fmt, ...) ::printf((PGM_P)PSTR(fmt), ##__VA_ARGS__)
+#define DEBUG_LEAF_FUNCTION(...) __asm__ __volatile__("" ::: "a0", "memory")
+#else
+#define DEBUG_LEAF_FUNCTION(...)
 #endif
 
 #ifndef DEBUGV

doc/Troubleshooting/stack_dump.rst

@@ -12,42 +12,42 @@ Example:
 
     Exception (0): epc1=0x402103f4 epc2=0x00000000 epc3=0x00000000 excvaddr=0x00000000 depc=0x00000000
 
-    ctx: sys 
+    ctx: sys
     sp: 3ffffc10 end: 3fffffb0 offset: 01a0
 
     >>>stack>>>
-    3ffffdb0:  40223e00 3fff6f50 00000010 60000600  
-    3ffffdc0:  00000001 4021f774 3fffc250 4000050c  
-    3ffffdd0:  400043d5 00000030 00000016 ffffffff  
-    3ffffde0:  400044ab 3fffc718 3ffffed0 08000000  
-    3ffffdf0:  60000200 08000000 00000003 00000000  
-    3ffffe00:  0000ffff 00000001 04000002 003fd000  
-    3ffffe10:  3fff7188 000003fd 3fff2564 00000030  
-    3ffffe20:  40101709 00000008 00000008 00000020  
-    3ffffe30:  c1948db3 394c5e70 7f2060f2 c6ba0c87  
-    3ffffe40:  3fff7058 00000001 40238d41 3fff6ff0  
-    3ffffe50:  3fff6f50 00000010 60000600 00000020  
-    3ffffe60:  402301a8 3fff7098 3fff7014 40238c77  
-    3ffffe70:  4022fb6c 40230ebe 3fff1a5b 3fff6f00  
-    3ffffe80:  3ffffec8 00000010 40231061 3fff0f90  
-    3ffffe90:  3fff6848 3ffed0c0 60000600 3fff6ae0  
-    3ffffea0:  3fff0f90 3fff0f90 3fff6848 3fff6d40  
-    3ffffeb0:  3fff28e8 40101233 d634fe1a fffeffff  
-    3ffffec0:  00000001 00000000 4022d5d6 3fff6848  
-    3ffffed0:  00000002 4000410f 3fff2394 3fff6848  
-    3ffffee0:  3fffc718 40004a3c 000003fd 3fff7188  
-    3ffffef0:  3fffc718 40101510 00000378 3fff1a5b  
-    3fffff00:  000003fd 4021d2e7 00000378 000003ff  
-    3fffff10:  00001000 4021d37d 3fff2564 000003ff  
-    3fffff20:  000003fd 60000600 003fd000 3fff2564  
-    3fffff30:  ffffff00 55aa55aa 00000312 0000001c  
-    3fffff40:  0000001c 0000008a 0000006d 000003ff  
-    3fffff50:  4021d224 3ffecf90 00000000 3ffed0c0  
-    3fffff60:  00000001 4021c2e9 00000003 3fff1238  
-    3fffff70:  4021c071 3ffecf84 3ffecf30 0026a2b0  
-    3fffff80:  4021c0b6 3fffdab0 00000000 3fffdcb0  
-    3fffff90:  3ffecf40 3fffdab0 00000000 3fffdcc0  
-    3fffffa0:  40000f49 40000f49 3fffdab0 40000f49  
+    3ffffdb0:  40223e00 3fff6f50 00000010 60000600
+    3ffffdc0:  00000001 4021f774 3fffc250 4000050c
+    3ffffdd0:  400043d5 00000030 00000016 ffffffff
+    3ffffde0:  400044ab 3fffc718 3ffffed0 08000000
+    3ffffdf0:  60000200 08000000 00000003 00000000
+    3ffffe00:  0000ffff 00000001 04000002 003fd000
+    3ffffe10:  3fff7188 000003fd 3fff2564 00000030
+    3ffffe20:  40101709 00000008 00000008 00000020
+    3ffffe30:  c1948db3 394c5e70 7f2060f2 c6ba0c87
+    3ffffe40:  3fff7058 00000001 40238d41 3fff6ff0
+    3ffffe50:  3fff6f50 00000010 60000600 00000020
+    3ffffe60:  402301a8 3fff7098 3fff7014 40238c77
+    3ffffe70:  4022fb6c 40230ebe 3fff1a5b 3fff6f00
+    3ffffe80:  3ffffec8 00000010 40231061 3fff0f90
+    3ffffe90:  3fff6848 3ffed0c0 60000600 3fff6ae0
+    3ffffea0:  3fff0f90 3fff0f90 3fff6848 3fff6d40
+    3ffffeb0:  3fff28e8 40101233 d634fe1a fffeffff
+    3ffffec0:  00000001 00000000 4022d5d6 3fff6848
+    3ffffed0:  00000002 4000410f 3fff2394 3fff6848
+    3ffffee0:  3fffc718 40004a3c 000003fd 3fff7188
+    3ffffef0:  3fffc718 40101510 00000378 3fff1a5b
+    3fffff00:  000003fd 4021d2e7 00000378 000003ff
+    3fffff10:  00001000 4021d37d 3fff2564 000003ff
+    3fffff20:  000003fd 60000600 003fd000 3fff2564
+    3fffff30:  ffffff00 55aa55aa 00000312 0000001c
+    3fffff40:  0000001c 0000008a 0000006d 000003ff
+    3fffff50:  4021d224 3ffecf90 00000000 3ffed0c0
+    3fffff60:  00000001 4021c2e9 00000003 3fff1238
+    3fffff70:  4021c071 3ffecf84 3ffecf30 0026a2b0
+    3fffff80:  4021c0b6 3fffdab0 00000000 3fffdcb0
+    3fffff90:  3ffecf40 3fffdab0 00000000 3fffdcc0
+    3fffffa0:  40000f49 40000f49 3fffdab0 40000f49
     <<<stack<<<
 
 The first number after ``Exception`` gives the cause of the reset. a
@@ -63,3 +63,5 @@ It's possible to decode the Stack to readable information. For more info see the
    :alt: ESP Exception Decoder
 
    ESP Exception Decoder
+
+For more on troubleshooting, read `My ESP Crashes <../faq/a02-my-esp-crashes.rst>`__.

doc/faq/a02-my-esp-crashes.rst

@@ -236,6 +236,7 @@ If you don't have any code for troubleshooting, use the example below:
 
     void loop(){}
 
+
 Enable the Out-Of-Memory (*OOM*) debug option (in the *Tools > Debug Level*
 menu), compile/flash/upload this code to your ESP (Ctrl+U) and start Serial
 Monitor (Ctrl+Shift+M).  You should shortly see ESP restarting every couple
@@ -270,31 +271,50 @@ Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ you can
 track down where the module is crashing whenever you see the stack trace
 dropped. The same procedure applies to crashes caused by exceptions.
 
-    Note: To decode the exact line of code where the application
+    Notes:
+
+    To decode the exact line of code where the application
     crashed, you need to use ESP Exception Decoder in context of sketch
     you have just loaded to the module for diagnosis. Decoder is not
     able to correctly decode the stack trace dropped by some other
     application not compiled and loaded from your Arduino IDE.
 
+    To improve the results of the Exception Decoder, you can add
+    `-fno-optimize-sibling-calls` to your build options. For details on how
+    to do this, review `Global Build Options <a06-global-build-options.rst>`__.
+    Turning off this optimization allows more caller addresses to be written
+    to the stack aiding in crash decoding. Because of the limited stack space,
+    there is the potential that removing this optimization could overflow the
+    stack and cause a crash.
+
+    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>`.
+
 
 Other Causes for Crashes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Interrupt Service Routines
-   By default, all functions are compiled into flash, which means that the 
-   cache may kick in for that code. However, the cache currently can't be used 
-   during hardware interrupts. That means that, if you use a hardware ISR, such as 
-   attachInterrupt(gpio, myISR, CHANGE) for a GPIO change, the ISR must have the 
-   IRAM_ATTR attribute declared. Not only that, but the entire function tree 
+   By default, all functions are compiled into flash, which means that the
+   cache may kick in for that code. However, the cache currently can't be used
+   during hardware interrupts. That means that, if you use a hardware ISR, such as
+   attachInterrupt(gpio, myISR, CHANGE) for a GPIO change, the ISR must have the
+   IRAM_ATTR attribute declared. Not only that, but the entire function tree
    called from the ISR must also have the IRAM_ATTR declared.
    Be aware that every function that has this attribute reduces available memory.
 
-   In addition, it is not possible to execute delay() or yield() from an ISR, 
+   In addition, it is not possible to execute delay() or yield() from an ISR,
    or do blocking operations, or operations that disable the interrupts, e.g.: read
    a DHT.
 
    Finally, an ISR has very high restrictions on timing for the executed code, meaning
-   that executed code should not take longer than a very few microseconds. It is 
+   that executed code should not take longer than a very few microseconds. It is
    considered best practice to set a flag within the ISR, and then from within the loop()
    check and clear that flag, and execute code.
 
@@ -303,16 +323,16 @@ Asynchronous Callbacks
    than ISRs, but some restrictions still apply.
    It is not possible to execute delay() or yield() from an asynchronous callback.
    Timing is not as tight as an ISR, but it should remain below a few milliseconds. This
-   is a guideline. The hard timing requirements depend on the WiFi configuration and 
+   is a guideline. The hard timing requirements depend on the WiFi configuration and
    amount of traffic. In general, the CPU must not be hogged by the user code, as the
    longer it is away from servicing the WiFi stack, the more likely that memory corruption
    can happen.
 
 Memory, memory, memory
    Running out of heap is the **most common cause for crashes**. Because the build process for
    the ESP leaves out exceptions (they use memory), memory allocations that fail will do
-   so silently. A typical example is when setting or concatenating a large String. If 
-   allocation has failed internally, then the internal string copy can corrupt data, and 
+   so silently. A typical example is when setting or concatenating a large String. If
+   allocation has failed internally, then the internal string copy can corrupt data, and
    the ESP will crash.
 
    In addition, doing many String concatenations in sequence, e.g.: using operator+()
@@ -348,9 +368,9 @@ Memory, memory, memory
    * If you use std libs like std::vector, make sure to call its ::reserve() method before filling it. This allows allocating only once, which reduces mem fragmentation, and makes sure that there are no empty unused slots left over in the container at the end.
 
 Stack
-   The amount of stack in the ESP is tiny at only 4KB. For normal development in large systems, it 
+   The amount of stack in the ESP is tiny at only 4KB. For normal development in large systems, it
    is good practice to use and abuse the stack, because it is faster for allocation/deallocation, the scope of the object is well defined, and deallocation automatically happens in reverse order as allocation, which means no mem fragmentation. However, with the tiny amount of stack available in the ESP, that practice is not really viable, at least not for big objects.
-   
+
    * Large objects that have internally managed memory, such as String, std::string, std::vector, etc, are ok on the stack, because they internally allocate their buffers on the heap.
    * Large arrays on the stack, such as uint8_t buffer[2048] should be avoided on the stack and should be dynamically allocated instead (consider smart pointers).
    * Objects that have large data members, such as large arrays, should also be avoided on the stack, and should be dynamically allocated (consider smart pointers).
@@ -392,7 +412,7 @@ or `esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core,
 types and versions of O/S, you need to provide exact information on what
 your application is about. Only then, people willing to look into your
 issue may be able to compare it to a configuration they are familiar with.
-If you are lucky, they may even attempt to reproduce your issue on their 
+If you are lucky, they may even attempt to reproduce your issue on their
 own equipment!
 This will be far more difficult if you provide only vague details,
 so somebody would need to ask you to find out what is really happening.

doc/faq/a06-global-build-options.rst

@@ -1,5 +1,3 @@
-:orphan:
-
 How to specify global build defines and options
 ===============================================
 
@@ -181,10 +179,10 @@ their builds.
 
 There are two solutions to this issue:
 
-1. Turn off the “Aggressively Cache Compiled core” feature, by setting
+1. Do nothing, and rely on aggressive cache workaround built into the
+   script.
+2. Turn off the “Aggressively Cache Compiled core” feature, by setting
    ``compiler.cache_core=false``.
-2. Rely on the not ideal fail-safe, aggressive cache workaround built
-   into the script.
 
 Using “compiler.cache_core=false”
 ---------------------------------
@@ -253,14 +251,10 @@ problem would be cleared after a reboot. Or you can manually cleanup the
 
 **Arduino command-line option overrides**
 
-The script needs to know the working value of ``compiler.cache_core``
-that the Arduino IDE uses when building. This script can learn the state
-through documented locations; however, the Arduino IDE has two
-command-line options that can alter the results the Arduino IDE uses
-internally. And, the Arduino IDE does not provide a means for a script
-to learn the override value.
+If you are building with ``compiler.cache_core=true`` no action is
+needed. If ``false`` the script would benefit by knowing that.
 
-These two command-line options are the problem:
+When using either of these two command-line options:
 
 ::