Review debuggging notes

Sming/Arch/Esp32/Components/gdbstub/README.rst

@@ -3,6 +3,4 @@ GDB Stub for Esp32
 
 This defines the command line to use when ``make gdb`` is run.
 
-Esp32 debugging is handled via JTAG interface.
-
-No additional code is required as serial debugging is not (currently) implemented.
+See :doc:`/arch/esp32/debugging/index`.

Sming/Arch/Esp32/Components/heap/README.rst

@@ -1,4 +1,4 @@
 Esp32 Heap
 ==========
 
-This Component supplments the actual heap implementation provided by the ESP IDF SDK.
+This Component supplements the actual heap implementation provided by the ESP IDF SDK.

Sming/Arch/Esp8266/Components/gdbstub/README.rst

@@ -9,11 +9,10 @@ This is a rewrite of gdbstub based on the
 
 To use the GNU Debugger (GDB) with Sming requires your application to
 include some code (``gdbstub``) which communicates via the serial port.
-On the ESP8266 only UART0 may be used for this as UART1 is
-transmit-only.
+On the ESP8266 only UART0 may be used for this as UART1 is transmit-only.
 
-The gdbstub code will only be built if you specify :envvar:`ENABLE_GDB`
-=1 when compiling your application. At startup, before your init()
+The gdbstub code will only be built if you specify :envvar:`ENABLE_GDB=1 <ENABLE_GDB>`
+when compiling your application. At startup, before your init()
 function is called, it will claim UART0 so your application will be
 unable to use it directly. Therefore, the default port for ``Serial``
 is changed to ``UART2``.
@@ -29,23 +28,6 @@ Refer to the official
 `GDB documentation <https://sourceware.org/gdb/current/onlinedocs/gdb/index.html>`__
 for further details.
 
-GDB
----
-
-This is the application which runs on your development system and talks
-to ``gdbstub``.
-
--  Linux: A version of this should be available in
-   ``$ESP_HOME/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb``
-
--  Windows: At time of writing, UDK doesn't provide a GDB application
-   - Download and run the executable installer at `SysProgs <http://gnutoolchains.com/esp8266/>`__
-
-   - Copy the
-     ``C:\SysGCC\esp8266\opt\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb.exe``
-     to a suitable location.
-
--  Mac: ?
 
 Usage
 -----
@@ -91,6 +73,8 @@ To run manually, see the following variables which you can inspect using ``make
 .. envvar:: GDB
 
    Path to the GDB executable being used.
+   This is the application which runs on your development system and talks to ``gdbstub``.
+   It is provided in the standard toolchain.
 
 
 .. _useful-gdb-commands:

Sming/Arch/Host/Components/gdbstub/README.rst

@@ -1,10 +1,16 @@
 GDB Stub for Host
 =================
 
-This defines the command line to use when ``make gdb`` is run. No additional code is required to debug for the Host.
+This defines command lines to run Host debuggers, either the GNU debugger::
 
-If you want to debug your application while having a separate UART then make sure to send the following commands to your debugger::
+   make gdb
 
-   handle SIGUSR1 nostop noprint
+Or LLVM debugger::
 
-This component provides also ``gdbinit`` file containing the optimal settings needed for debugging.
+   make lldb
+
+Generally the GNU debugger is used but for MacOS lldb is the default.
+
+This Component also provides default settings for each in the ``gdbcmds`` and ``lldbcmds`` files.
+
+See :doc:`/arch/host/debugging/index`.

Sming/Arch/Rp2040/Components/gdbstub/README.rst

@@ -3,4 +3,4 @@ GDB Stub for RP2040
 
 This defines the command line to use when ``make gdb`` is run.
 
-TODO: Implement stub code to allow serial debugging.
+See :doc:`arch/rp2040/debugging/index`.

docs/source/arch/esp32/debugging/index.rst

@@ -8,14 +8,14 @@ If an exception occurs in debug builds then a prompt will be printed to the seri
 such as ``Entering gdb stub``.
 
 As with the ESP8266, if such an exception occurs you can stop the serial debug terminal and type ``make gdb``.
+See also :envvar:`ENABLE_GDB`.
 
-More advanced debugging is available via JTAG if you have the appropriate tools.
-
-See https://docs.espressif.com/projects/esp-idf/en/release-v4.3/esp32/api-guides/fatal-errors.html for further details.
 
+JTAG debugging
+--------------
 
-Required tools and hardware
----------------------------
+More advanced debugging is available via JTAG if you have the appropriate tools.
+See https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html.
 
 A debugger and a JTAG hardware are required.
 The debugger is part of the provided toolchain.

docs/source/arch/esp8266/debugging/index.rst

@@ -1,43 +1,18 @@
 Debugging on ESP8266
 ====================
 
-Required tools and hardware
----------------------------
-A debugger is the only requirement for ESP8266. It is usually part of the provided toolchain.
-Make sure that you have the following executable in your PATH::
-
-    xtensa-lx106-elf-gdb
-
-No additional hardware is required (Apart from a standard USB-to-UART adapter).
-
 Recompilation is required
 -------------------------
 
 In order to debug applications based on Sming Framework make sure that
-you are using Sming version 3.8.0 or newer.
-
-Framework
-~~~~~~~~~
-
-If you want to debug inside of the Sming Framework make sure to
-(re)compile it with :envvar:`ENABLE_GDB=1 <ENABLE_GDB>` directive::
-
-   cd $SMING_HOME
-   make dist-clean
-   make ENABLE_GDB=1
-
-The commands above will re-compile Sming with debug symbols and
-optimizations for debugging. These commands need to be executed once.
-
-Application
-~~~~~~~~~~~
+you are using Sming version 4 or newer.
 
-To use, (re)compile your application with the ENABLE_GDB option and
+To use, (re)compile your application with the :envvar:`ENABLE_GDB` option and
 flash it to the board. For this example we will use the :sample:`LiveDebug`
 sample application::
 
    cd $SMING_HOME/../samples/LiveDebug
-   make clean
+   make components-clean # -- required if you need to debug inside framework or libraries
    make ENABLE_GDB=1 # -- recompiles your application with debugging support
    make flashapp # flashes ONLY the (re)compiled application
 

docs/source/arch/host/debugging/index.rst

@@ -28,7 +28,7 @@ If you want to debug your application and the Sming Framework code make sure to
 (re)compile it with :envvar:`ENABLE_GDB=1 <ENABLE_GDB>` directive::
 
    cd $SMING_HOME/../samples/LiveDebug
-   make dist-clean
+   make components-clean # -- Forces a rebuild of all Components
    make ENABLE_GDB=1
 
 The commands above will re-compile Sming with debug symbols and
@@ -46,7 +46,6 @@ To use, (re)compile your application with the ENABLE_GDB option.
 For this example we will use the :sample:`LiveDebug` sample application::
 
    cd $SMING_HOME/../samples/LiveDebug
-   make clean
    make ENABLE_GDB=1 # -- recompiles your application with debugging support
 
 The next step is to start the debugger. This can be done with the command below::

docs/source/arch/rp2040/debugging/index.rst

@@ -1,6 +1,8 @@
 Debugging on RP2040
 ===================
 
-Currently debugging support on Sming is limited to serial output and inspecting disassembly using GDB.
+This is best accomplished using a JTAG debugger as discussed here
+https://www.raspberrypi.org/documentation/microcontrollers/raspberry-pi-pico.html
+under ``Debugging using another Raspberry Pi Pico``.
 
-See https://www.raspberrypi.org/documentation/microcontrollers/raspberry-pi-pico.html
+See :envvar:`ENABLE_GDB`.