From a105bdd3591a1fad64b6809ef90ebf4df3ef8995 Mon Sep 17 00:00:00 2001
From: M Hightower <27247790+mhightower83@users.noreply.github.com>
Date: Thu, 8 Jul 2021 16:11:58 -0700
Subject: [PATCH] add comments and corrections (#8201)

* Added comments for ets_install_uart_printf and corrected it usage.

* Correct case for hotkey 'p'.
Added conditional build around option 'p' to call stack_thunk_dump_stack
which can only print when debug is enabled.
---
 cores/esp8266/esp8266_undocumented.h              | 15 ++++++++++++---
 cores/esp8266/reboot_uart_dwnld.cpp               |  3 +--
 .../HelloServerBearSSL/HelloServerBearSSL.ino     |  8 +++++++-
 3 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/cores/esp8266/esp8266_undocumented.h b/cores/esp8266/esp8266_undocumented.h
index 277d46769..5e68e53fa 100644
--- a/cores/esp8266/esp8266_undocumented.h
+++ b/cores/esp8266/esp8266_undocumented.h
@@ -52,12 +52,22 @@ calls to ets_install_putc1().
  */
 extern void uart_buff_switch(uint8_t);
 
+/*
+  ROM function, ets_install_uart_printf, is used to installs the internal ROM
+  putc1 driver used to print on UART0 or UART1. The installed driver is use by ets_printf.
+  Side note, ets_install_uart_printf just happens to return the address of the
+  internal putc1 driver installed.
+*/
+extern void ets_install_uart_printf(void);
+
 /*
  ROM function, ets_uart_printf(), prints on the UART selected by
  uart_buff_switch(). Supported format options are the same as vprintf(). Also
  has cooked newline behavior. No flash format/string support; however, ISR safe.
- Also, uses a static function in ROM to print characters which is only
- controlled by uart_buff_switch().
+ It also uses a static function in ROM to print characters. The UART selection
+ is handled by a prior call to uart_buff_switch(). An advantage over ets_printf,
+ this call is not affected by calls made to ets_install_putc1 or
+ ets_install_putc2.
  */
 extern int ets_uart_printf(const char *format, ...) __attribute__ ((format (printf, 1, 2)));
 
@@ -236,7 +246,6 @@ extern void Cache_Read_Disable();
 extern int32_t system_func1(uint32_t);
 extern void clockgate_watchdog(uint32_t);
 extern void pm_open_rf();
-extern void ets_install_uart_printf(uint32_t uart_no);
 extern void UartDwnLdProc(uint8_t* ram_addr, uint32_t size, void (**user_start_ptr)());
 extern int boot_from_flash();
 extern void ets_run() __attribute__((noreturn));
diff --git a/cores/esp8266/reboot_uart_dwnld.cpp b/cores/esp8266/reboot_uart_dwnld.cpp
index 7b58fb222..d234c9c02 100644
--- a/cores/esp8266/reboot_uart_dwnld.cpp
+++ b/cores/esp8266/reboot_uart_dwnld.cpp
@@ -106,7 +106,7 @@ static inline void __wsr_vecbase(uint32_t vector_base) {
 	const uint32_t uart_no = 0;
 	uartAttach();
 	Uart_Init(uart_no);
-	ets_install_uart_printf(uart_no);
+	ets_install_uart_printf();
 
 	/* reverse engineered from boot_from_something() */
 	const uint16_t divlatch = uart_baudrate_detect(uart_no, 0);
@@ -148,4 +148,3 @@ static inline void __wsr_vecbase(uint32_t vector_base) {
 
 	esp8266UartDownloadMode();
 }
-
diff --git a/libraries/ESP8266WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino b/libraries/ESP8266WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino
index 8e9f4cd5b..185914f30 100644
--- a/libraries/ESP8266WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino
+++ b/libraries/ESP8266WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino
@@ -173,10 +173,14 @@ void processKey(Print& out, int hotKey) {
         }
         break;
       }
-    case 'P':
+#ifdef DEBUG_ESP_PORT
+    // From this context stack_thunk_dump_stack() will only work when Serial
+    // debug is enabled.
+    case 'p':
       out.println(F("Calling stack_thunk_dump_stack();"));
       stack_thunk_dump_stack();
       break;
+#endif
     case 'R':
       out.printf_P(PSTR("Restart, ESP.restart(); ...\r\n"));
       ESP.restart();
@@ -191,7 +195,9 @@ void processKey(Print& out, int hotKey) {
       out.println(F("  h    - Free Heap Report;"));
       out.println(F("  i    - iRAM umm_info(null, true);"));
       out.println(F("  d    - dRAM umm_info(null, true);"));
+#ifdef DEBUG_ESP_PORT
       out.println(F("  p    - call stack_thunk_dump_stack();"));
+#endif
       out.println(F("  R    - Restart, ESP.restart();"));
       out.println(F("  ?    - Print Help"));
       out.println();