GDB support w/new toolchain and UART driver (#5559)

* Add full gdb support with uart/Serial integration

* Fix GDB merge errors

* Update to unpatched GDB protocol specification

It appears that Espressif patched the open source xtensa GDB port in
order to build their old GDB executable and their old gdbstub (basically
removing any register in a generic xtensa and only leaving those
present in the chip they synthesized).  Their GDBStub also assumed this
behavior.

Unpatched upstream GNU GDB now expects all the registers in
xtensa-config.c to be sent/read on a 'g' command.  Change the GDB stub
to send "xxxxxxxx"s (legal per the spec) for unimplemented registers.
This makes the 'g' response much longer, but it's results are cached
and in an interactive debugger it isn't noticeable.

* Fix .iram.literal to come before .iram.text for GDB

* Move functions to flash, call using wrappers

All functions which are not interrupt or exception called are now in
flash. A small IRAM wrapper enables flash when processing main GDB ops
by calling Cache_Read_Enable_New() and then jumping to the main flash
code.  This seems to work for catching exceptions, data and code breaks,
and Ctrl-C.

The UART ISR handler and exception handler register-saving bits of
code in ASM are still in IRAM.

GDB IRAM usage is now about 670 bytes.

* Remove LWIP2 builder commit

* Add documentation and gdbstub_init header

Add some simple GDB documentation to the main tree showing a worked
example.

Adds the definition of `void gdbstub_init()` to <GDBStub.h>

* Clean up GDB include and library dir

Replace GDBstub.h with the version in the internal/ directory, and
adjust stub code accordingly.  This way, only one copy of a file called
"GDBstub.h" will exist.

Update the gdbcommands and replace the obsolete ESPRESSIF readme with
@kylefleming's version since we're mainly doing serial, not TCP,
connected debugging.

Bump the library rev. number since this is a pretty big functionality
change.

Minor documentation tweak.

* Undo much of UART refactoring, set fifo IRQ to 16

Remove the refactoring of pin control and other little things not directly
related to GDB processing.  Should greatly reduce the diff size in uart.c.
Should also remove any register value changes (intended or otherwise)
introduced in the original PR from @kylefleming.

Set the FIFO interrupt to 16 chars when in GDB mode, matching the latest
UART configuration for highest speed.

* Add architecture comments, cleanup uart.c code

Comments added to UART.c trying to explain (as best as I understand it)
the changes done to support GDB and how they interact with standard
operation.

Fix the uart_uninit to stop the ISR and then free appropriately.

Fix uart_isr_handle_data (GDB's shim for sending chars to the 8266 app)
to do the exact same thing as the standard UART handler including set
the overflow properly and either discard or overwrite in that case.

Fix serial reception when GDB enabled by enabling the user recv ISR.

Remove commented attributes from gdbstub, leftover from the move to
flash.

General logic cleanup per comments in the PR.

* Also set the UART flags for HW error in GDB

Ensure we also check the UART flags and set the uart status
appropriately when in GDB mode.

Author: earlephilhower

cores/esp8266/gdb_hooks.c

@@ -25,12 +25,18 @@
    value is in register, it doesn't hurt to return a bool, so that the
    same stub can be used for gdb_present. */
 
-bool ICACHE_RAM_ATTR __gdb_no_op()
+static bool ICACHE_RAM_ATTR __gdb_no_op()
 {
     return false;
 }
 
-extern void gdb_init(void) __attribute__ ((weak, alias("__gdb_no_op")));
-extern void gdb_do_break(void) __attribute__ ((weak, alias("__gdb_no_op")));
-extern bool gdb_present(void) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdb_init(void) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdb_do_break(void) __attribute__ ((weak, alias("__gdb_no_op")));
+bool gdb_present(void) __attribute__ ((weak, alias("__gdb_no_op")));
+bool gdbstub_has_putc1_control(void) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdbstub_set_putc1_callback(void (*func)(char)) __attribute__ ((weak, alias("__gdb_no_op")));
+bool gdbstub_has_uart_isr_control(void) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdbstub_set_uart_isr_callback(void (*func)(void*, uint8_t), void* arg) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdbstub_write_char(char c) __attribute__ ((weak, alias("__gdb_no_op")));
+void gdbstub_write(const char* buf, size_t size) __attribute__ ((weak, alias("__gdb_no_op")));
 

cores/esp8266/gdb_hooks.h

@@ -52,6 +52,71 @@ void gdb_do_break(void);
  */
 bool gdb_present(void);
 
+// If gdbstub has these set true, then we will disable our own
+// usage of them, but use gdbstub's callbacks for them instead
+/**
+ * @brief Check if GDB is installing a putc1 callback.
+ * 
+ * By default, this function returns false. When GDBStub library is linked,
+ * this function is overriden and returns true.
+ * 
+ * @return true if GDB is installing a putc1 callback
+ */
+bool gdbstub_has_putc1_control(void);
+
+/**
+ * @brief Register a putc1 callback with GDB.
+ * @param func function GDB will proxy putc1 data to
+ * 
+ * By default, this function is a no-op. When GDBStub library is linked,
+ * this function is overriden and sets GDB stub's secondary putc1 callback to
+ * func. When GDB stub is linked, but a GDB session is not current attached,
+ * then GDB stub will pass putc1 chars directly to this function.
+ */
+void gdbstub_set_putc1_callback(void (*func)(char));
+
+/**
+ * @brief Check if GDB is installing a uart0 isr callback.
+ * 
+ * By default, this function returns false. When GDBStub library is linked,
+ * this function is overriden and returns true.
+ * 
+ * @return true if GDB is installing a uart0 isr callback
+ */
+bool gdbstub_has_uart_isr_control(void);
+
+/**
+ * @brief Register a uart0 isr callback with GDB.
+ * @param func function GDB will proxy uart0 isr data to
+ * 
+ * By default, this function is a no-op. When GDBStub library is linked,
+ * this function is overriden and sets GDB stub's secondary uart0 isr callback
+ * to func. When GDB stub is linked, but a GDB session is not current attached,
+ * then GDB stub will pass uart0 isr data back to this function.
+ */
+void gdbstub_set_uart_isr_callback(void (*func)(void*, uint8_t), void* arg);
+
+/**
+ * @brief Write a character for output to a GDB session on uart0.
+ * @param c character to write
+ * 
+ * By default, this function is a no-op. When GDBStub library is linked,
+ * this function is overriden and writes a char to either the GDB session on
+ * uart0 or directly to uart0 if not GDB session is attached.
+ */
+void gdbstub_write_char(char c);
+
+/**
+ * @brief Write a char buffer for output to a GDB session on uart0.
+ * @param buf buffer of data to write
+ * @param size length of buffer
+ * 
+ * By default, this function is a no-op. When GDBStub library is linked,
+ * this function is overriden and writes a buffer to either the GDB session on
+ * uart0 or directly to uart0 if not GDB session is attached.
+ */
+void gdbstub_write(const char* buf, size_t size);
+
 #ifdef __cplusplus
 }
 #endif