Update doc

Updated platform.txt - positioned -Os such that it can be overridden by `build.opt`. Add suggestion of using `-Og` which may improve the Decoder's line number correlation with the problem in the source code. Untested adjustments to platformio-build.py
esp8266 · d-a-v · Mar 29, 2023 · Jan 29, 2023 · Jan 30, 2023 · Jan 30, 2023
commit 679038d9772cacaca0aab46f977be72c816f8bd7
diff --git a/doc/Troubleshooting/stack_dump.rst b/doc/Troubleshooting/stack_dump.rst
@@ -64,4 +64,4 @@ It's possible to decode the Stack to readable information. For more info see the
 
    ESP Exception Decoder
 
-For more on troubleshooting, read `My ESP Crashes <../faq/a02-my-esp-crashes.rst>`__.
+For more on troubleshooting, read `FAQ: My ESP Crashes <../faq/a02-my-esp-crashes.rst>`__.
diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst
@@ -271,38 +271,44 @@ 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.
 
-    Notes:
-
-    To decode the exact line of code where the application
+    Note, 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.
 
-    When you select a ``Debug port:`` 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 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.
-
-    If you are not using the "Debug port" and need 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>`__.
-
-    For non-Arduino IDE build platforms, you may need to research how to add
-    build options.
-
-    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>``.
+
+Improving Exception Decoder Results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you select a ``Debug port`` 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 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.
+
+If you are not using the ``Debug port`` and need to improve the results of the
+Exception Decoder, you can add ``-Og`` or ``-fno-optimize-sibling-calls``
+to your build options. For details on how to do this, review
+`Global Build Options <a06-global-build-options.rst>`__.
+
+For non-Arduino IDE build platforms, you may need to research how to add
+build options.
+
+For projects that become too large to flash with a global debug build option,
+you could target the optimization to specific modules of interest by adding
+`#pragma GCC optimize("Og")`.
+
+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

diff --git a/platform.txt b/platform.txt
@@ -70,24 +70,24 @@ compiler.path={runtime.tools.xtensa-lx106-elf-gcc.path}/bin/
 compiler.sdk.path={runtime.platform.path}/tools/sdk
 
 compiler.libc.path={runtime.platform.path}/tools/sdk/libc/xtensa-lx106-elf
-compiler.cpreprocessor.flags=-D__ets__ -DICACHE_FLASH -U__STRICT_ANSI__ -D_GNU_SOURCE -DESP8266 {build.opt.flags} "-I{compiler.sdk.path}/include" "-I{compiler.sdk.path}/{build.lwip_include}" "-I{compiler.libc.path}/include" "-I{build.path}/core"
+compiler.cpreprocessor.flags=-D__ets__ -DICACHE_FLASH -U__STRICT_ANSI__ -D_GNU_SOURCE -DESP8266 -Os {build.opt.flags} "-I{compiler.sdk.path}/include" "-I{compiler.sdk.path}/{build.lwip_include}" "-I{compiler.libc.path}/include" "-I{build.path}/core"
 
 # support precompiled libraries in IDE v1.8.6+
 compiler.libraries.ldflags=
 
 compiler.c.cmd=xtensa-lx106-elf-gcc
-compiler.c.flags=-c "{compiler.warning_flags}-cflags" -std=gnu17 {build.stacksmash_flags} -Os -g -free -fipa-pta -Werror=return-type -Wpointer-arith -Wno-implicit-function-declaration -Wl,-EL -fno-inline-functions -nostdlib -mlongcalls -mtext-section-literals -falign-functions=4 -MMD -ffunction-sections -fdata-sections {build.exception_flags} {build.sslflags} {build.mmuflags} {build.non32xferflags}
+compiler.c.flags=-c "{compiler.warning_flags}-cflags" -std=gnu17 {build.stacksmash_flags} -g -free -fipa-pta -Werror=return-type -Wpointer-arith -Wno-implicit-function-declaration -Wl,-EL -fno-inline-functions -nostdlib -mlongcalls -mtext-section-literals -falign-functions=4 -MMD -ffunction-sections -fdata-sections {build.exception_flags} {build.sslflags} {build.mmuflags} {build.non32xferflags}
 
 compiler.S.cmd=xtensa-lx106-elf-gcc
 compiler.S.flags=-c -g -x assembler-with-cpp -MMD -mlongcalls "-I{runtime.tools.xtensa-lx106-elf-gcc.path}/include/"
 
-compiler.c.elf.flags=-g "{compiler.warning_flags}-cflags" -Os -nostdlib -Wl,--no-check-sections -u app_entry {build.float} -Wl,-static "-L{compiler.sdk.path}/lib" "-L{compiler.sdk.path}/lib/{build.sdk}" "-L{build.path}" "-L{compiler.libc.path}/lib" "-Tlocal.eagle.flash.ld" -Wl,--gc-sections -Wl,-wrap,system_restart_local -Wl,-wrap,spi_flash_read
+compiler.c.elf.flags=-g "{compiler.warning_flags}-cflags" -nostdlib -Wl,--no-check-sections -u app_entry {build.float} -Wl,-static "-L{compiler.sdk.path}/lib" "-L{compiler.sdk.path}/lib/{build.sdk}" "-L{build.path}" "-L{compiler.libc.path}/lib" "-Tlocal.eagle.flash.ld" -Wl,--gc-sections -Wl,-wrap,system_restart_local -Wl,-wrap,spi_flash_read
 
 compiler.c.elf.cmd=xtensa-lx106-elf-gcc
 compiler.c.elf.libs=-lhal -lphy -lpp -lnet80211 {build.lwip_lib} -lwpa -lcrypto -lmain -lwps -lbearssl -lespnow -lsmartconfig -lairkiss -lwpa2 {build.stdcpp_lib} -lm -lc -lgcc
 
 compiler.cpp.cmd=xtensa-lx106-elf-g++
-compiler.cpp.flags=-c "{compiler.warning_flags}-cppflags" {build.stacksmash_flags} -Os -g -free -fipa-pta -Werror=return-type -mlongcalls -mtext-section-literals -fno-rtti -falign-functions=4 {build.stdcpp_level} -MMD -ffunction-sections -fdata-sections {build.exception_flags} {build.sslflags} {build.mmuflags} {build.non32xferflags}
+compiler.cpp.flags=-c "{compiler.warning_flags}-cppflags" {build.stacksmash_flags} -g -free -fipa-pta -Werror=return-type -mlongcalls -mtext-section-literals -fno-rtti -falign-functions=4 {build.stdcpp_level} -MMD -ffunction-sections -fdata-sections {build.exception_flags} {build.sslflags} {build.mmuflags} {build.non32xferflags}
 
 compiler.as.cmd=xtensa-lx106-elf-as
 

diff --git a/tools/platformio-build.py b/tools/platformio-build.py
@@ -205,14 +205,6 @@ def scons_patched_match_splitext(path, suffixes=None):
     LIBPATH=[NONOSDK_LIBPATH],
 )
 
-#
-# debug
-#
-for define in env["CCFLAGS"]:
-    if "DEBUG_ESP_PORT" in define:
-        env.Append(CCFLAGS=["-fno-optimize-sibling-calls"])
-        break
-
 #
 # lwIP
 #
@@ -257,6 +249,12 @@ def scons_patched_match_splitext(path, suffixes=None):
     )
     lwip_lib = "lwip2-536-feat"
 
+#
+# debug
+#
+if "DEBUG_ESP_PORT" in flatten_cppdefines:
+    env.Append(CCFLAGS=["-fno-optimize-sibling-calls"])
+
 #
 # Waveform
 #
Original file line number	Diff line number	Diff line change
Expand Up		@@ -64,4 +64,4 @@ It's possible to decode the Stack to readable information. For more info see the

		ESP Exception Decoder

		For more on troubleshooting, read `My ESP Crashes <../faq/a02-my-esp-crashes.rst>`__.
		For more on troubleshooting, read `FAQ: My ESP Crashes <../faq/a02-my-esp-crashes.rst>`__.