From a70e834d1ea26316d28ae41b4623550d7b47ed34 Mon Sep 17 00:00:00 2001
From: "Earle F. Philhower, III" <earlephilhower@yahoo.com>
Date: Thu, 11 Jun 2020 15:24:21 -0700
Subject: [PATCH] Add a "-- CUT HERE --" marker to exception output (#7369)

Users aren't reporting/seeing the actual PC of failures because they
are only copying the >>stack<< into the decoder and not the Exception
line.  Add an ALL CAPS "CUT HERE FOR EXCEPTION DECODER" line to the
output to make it blindingly obvious to include the full crashdump
both in bug reports as well as exception decodes.
---
 cores/esp8266/core_esp8266_postmortem.cpp | 16 ++++++++++++++++
 doc/faq/a02-my-esp-crashes.rst            |  4 ++++
 2 files changed, 20 insertions(+)

diff --git a/cores/esp8266/core_esp8266_postmortem.cpp b/cores/esp8266/core_esp8266_postmortem.cpp
index 2af579883..5f285d686 100644
--- a/cores/esp8266/core_esp8266_postmortem.cpp
+++ b/cores/esp8266/core_esp8266_postmortem.cpp
@@ -92,6 +92,18 @@ static void ets_printf_P(const char *str, ...) {
     }
 }
 
+static void cut_here() {
+    ets_putc('\n');
+    for (auto i = 0; i < 15; i++ ) {
+        ets_putc('-');
+    }
+    ets_printf_P(PSTR(" CUT HERE FOR EXCEPTION DECODER "));
+    for (auto i = 0; i < 15; i++ ) {
+        ets_putc('-');
+    }
+    ets_putc('\n');
+}
+
 void __wrap_system_restart_local() {
     register uint32_t sp asm("a1");
     uint32_t sp_dump = sp;
@@ -113,6 +125,8 @@ void __wrap_system_restart_local() {
 
     ets_install_putc1(&uart_write_char_d);
 
+    cut_here();
+
     if (s_panic_line) {
         ets_printf_P(PSTR("\nPanic %S:%d %S"), s_panic_file, s_panic_line, s_panic_func);
         if (s_panic_what) {
@@ -193,6 +207,8 @@ void __wrap_system_restart_local() {
 #endif
     }
 
+    cut_here();
+
     custom_crash_callback( &rst_info, sp_dump + offset, stack_end );
 
     ets_delay_us(10000);
diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst
index 90d70c024..838880ea8 100644
--- a/doc/faq/a02-my-esp-crashes.rst
+++ b/doc/faq/a02-my-esp-crashes.rst
@@ -113,6 +113,10 @@ out in which line of application it is triggered. Please refer to `Check
 Where the Code Crashes <#check-where-the-code-crashes>`__ point below
 for a quick example how to do it.
 
+**NOTE:** When decoding exceptions be sure to include all lines between
+the ``---- CUT HERE ----`` marks in the output to allow the decoder to also
+provide the line of code that's actually causing the exception.
+
 Watchdog
 ^^^^^^^^