diff --git a/Sming/README.rst b/Sming/README.rst index 3edf6c5aca..f003fdeb13 100644 --- a/Sming/README.rst +++ b/Sming/README.rst @@ -85,27 +85,32 @@ Change it like this:: .. envvar:: ENABLE_GDB - In order to be able to debug live directly on the ESP8266 microcontroller you - should re-compile your application with :envvar:`ENABLE_GDB=1 ` directive. - undefined (default) Compile normally 1 - Compile with debugging support. Use varies by architecture: + Compile with debugging support. + + In order to be able to debug live directly on the microcontroller you + should re-compile your application with this setting enabled (set to 1). + + This setting reduces optimisation levels and ensures full symbolic debugging information is available. + However, because this affects the code produced it can mask some types of bug which only present in regular or release builds. + For this reason, when :envvar:`ENABLE_GDB` is changed only the application is recompiled automatically + to ensure that the necessary GDB stub code is linked to enable communication with the debugger. + + If you need to debug only a specific Component, rebuild **just** that component like this:: - - :doc:`/arch/esp8266/debugging/index` - - :doc:`/arch/esp32/debugging/index` - - :doc:`/arch/rp2040/debugging/index` - - :doc:`/arch/host/debugging/index` + make ssl-clean + make ENABLE_GDB=1 - For all architectures this setting also reduces optimisation levels and ensures full - symbolic debugging information is available. + The application code and ``ssl`` Component will now have debugging information, but everything else will remain unchanged. + To rebuild the entire framework:: - Note that gdb can be used to examine the source disassembly without requiring connection - to an actual device. Although it will have symbolic information for ROM routines, - those **do** require connection to a device for inspection. + make clean components-clean + make ENABLE_GDB=1 - See also the :sample:`LiveDebug` sample. + Note also that gdb can always be used to examine the source disassembly without requiring connection + to an actual device. Build caching diff --git a/docs/source/arch/esp32/debugging/debugging-1.png b/docs/source/arch/esp32/debugging/debug-esp32-1.png similarity index 100% rename from docs/source/arch/esp32/debugging/debugging-1.png rename to docs/source/arch/esp32/debugging/debug-esp32-1.png diff --git a/docs/source/arch/esp32/debugging/debugging-2.png b/docs/source/arch/esp32/debugging/debug-esp32-2.png similarity index 100% rename from docs/source/arch/esp32/debugging/debugging-2.png rename to docs/source/arch/esp32/debugging/debug-esp32-2.png diff --git a/docs/source/arch/esp32/debugging/debugging-3.png b/docs/source/arch/esp32/debugging/debug-esp32-3.png similarity index 100% rename from docs/source/arch/esp32/debugging/debugging-3.png rename to docs/source/arch/esp32/debugging/debug-esp32-3.png diff --git a/docs/source/arch/esp32/debugging/debugging-4.png b/docs/source/arch/esp32/debugging/debug-esp32-4.png similarity index 100% rename from docs/source/arch/esp32/debugging/debugging-4.png rename to docs/source/arch/esp32/debugging/debug-esp32-4.png diff --git a/docs/source/arch/esp32/debugging/eclipse.png b/docs/source/arch/esp32/debugging/eclipse-esp32.png similarity index 100% rename from docs/source/arch/esp32/debugging/eclipse.png rename to docs/source/arch/esp32/debugging/eclipse-esp32.png diff --git a/docs/source/arch/esp32/debugging/index.rst b/docs/source/arch/esp32/debugging/index.rst index 80e53eebb8..42775fc472 100644 --- a/docs/source/arch/esp32/debugging/index.rst +++ b/docs/source/arch/esp32/debugging/index.rst @@ -256,7 +256,7 @@ Here is how this can be done: - Point Eclipse to the location of the Basic_Blink sample - Import the Sming Framework (if you haven't done it yet) -.. figure:: debugging-1.png +.. figure:: debug-esp32-1.png :alt: Import Project Import Project @@ -274,7 +274,7 @@ Now create a new *Remote Debugging* Configuration: - *C/C++ Application*: *out/build/Esp8266/Debug/app.out* - disable for now the *auto* build -.. figure:: debugging-2.png +.. figure:: debug-esp32-2.png :alt: Remote Debugging Session Remote Debugging Session @@ -282,7 +282,7 @@ Now create a new *Remote Debugging* Configuration: Then go to the Debugger tab and point the GDB debugger to your Xtensa-gdb binary. (Type ``make list-config`` and look for :envvar:`GDB`.) -.. figure:: debugging-3.png +.. figure:: debug-esp32-3.png :alt: Remote Debugging Session Remote Debugging Session @@ -298,7 +298,7 @@ Finally we should configure the remote connection. Go to the - host: localhost - port: 3333 -.. figure:: debugging-4.png +.. figure:: debug-esp32-4.png :alt: Set remote connection Set remote connection @@ -308,7 +308,7 @@ screenshot above the Debug button is in the bottom-right corner.) After some seconds your debugging session should be up and running and you can enjoy live debugging. -.. figure:: eclipse.png +.. figure:: eclipse-esp32.png :alt: Live Debugging Session Live Debugging Session diff --git a/docs/source/arch/esp8266/debugging/debugging-1.png b/docs/source/arch/esp8266/debugging/debug-esp8266-1.png similarity index 100% rename from docs/source/arch/esp8266/debugging/debugging-1.png rename to docs/source/arch/esp8266/debugging/debug-esp8266-1.png diff --git a/docs/source/arch/esp8266/debugging/debugging-2.png b/docs/source/arch/esp8266/debugging/debug-esp8266-2.png similarity index 100% rename from docs/source/arch/esp8266/debugging/debugging-2.png rename to docs/source/arch/esp8266/debugging/debug-esp8266-2.png diff --git a/docs/source/arch/esp8266/debugging/debugging-3.png b/docs/source/arch/esp8266/debugging/debug-esp8266-3.png similarity index 100% rename from docs/source/arch/esp8266/debugging/debugging-3.png rename to docs/source/arch/esp8266/debugging/debug-esp8266-3.png diff --git a/docs/source/arch/esp8266/debugging/debugging-4.png b/docs/source/arch/esp8266/debugging/debug-esp8266-4.png similarity index 100% rename from docs/source/arch/esp8266/debugging/debugging-4.png rename to docs/source/arch/esp8266/debugging/debug-esp8266-4.png diff --git a/docs/source/arch/esp8266/debugging/eclipse.png b/docs/source/arch/esp8266/debugging/eclipse-esp8266.png similarity index 100% rename from docs/source/arch/esp8266/debugging/eclipse.png rename to docs/source/arch/esp8266/debugging/eclipse-esp8266.png diff --git a/docs/source/arch/esp8266/debugging/index.rst b/docs/source/arch/esp8266/debugging/index.rst index e7a13a7f74..8ce3bfe5f9 100644 --- a/docs/source/arch/esp8266/debugging/index.rst +++ b/docs/source/arch/esp8266/debugging/index.rst @@ -165,7 +165,7 @@ Here is how this can be done: - Point Eclipse to the location of the LiveDebug sample - Import the Sming Framework (if you haven't done it yet) -.. figure:: debugging-1.png +.. figure:: debug-esp8266-1.png :alt: Import Project Import Project @@ -183,7 +183,7 @@ Now create a new *Remote Debugging* Configuration: - *C/C++ Application*: *out/build/Esp8266/Debug/app.out* - disable for now the *auto* build -.. figure:: debugging-2.png +.. figure:: debug-esp8266-2.png :alt: Remote Debugging Session Remote Debugging Session @@ -191,7 +191,7 @@ Now create a new *Remote Debugging* Configuration: Then go to the Debugger tab and point the GDB debugger to your Xtensa-gdb binary. (Type ``make list-config`` and look for :envvar:`GDB`.) -.. figure:: debugging-3.png +.. figure:: debug-esp8266-3.png :alt: Remote Debugging Session Remote Debugging Session @@ -208,7 +208,7 @@ Finally we should configure the remote connection. Go to the - device: */dev/ttyUSB0* (or as required for your operating system) - speed: 115200 -.. figure:: debugging-4.png +.. figure:: debug-esp8266-4.png :alt: Set remote connection Set remote connection @@ -218,7 +218,7 @@ screenshot above the Debug button is in the bottom-right corner.) After some seconds your debugging session should be up and running and you can enjoy live debugging. -.. figure:: eclipse.png +.. figure:: eclipse-esp8266.png :alt: Live Debugging Session Live Debugging Session diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst index daeec922d5..e1ca9691eb 100644 --- a/docs/source/getting-started/index.rst +++ b/docs/source/getting-started/index.rst @@ -253,28 +253,19 @@ Live Debugging Applications based on Sming Framework that are flashed and running on an ESP8266 device can be debugged using interactive debuggers. In order to -debug an application it has to be re-compiled with the :envvar:`ENABLE_GDB=1 ` -directive. And then flashed on the device. As shown below: +debug an application it has to be re-compiled with the :envvar:`ENABLE_GDB` +directive, and then flashed to the device: -.. code-block:: bash - - cd $SMING_HOME/../samples/LiveDebug - make clean - make ENABLE_GDB=1 - make flashapp # <-- this will update only the application firmware. - -Once the debuggable application is flashed on the device the developers -have to run GDB. The easiest way to run the command-line GDB is to -execute the following command: +Use varies by architecture: -.. code-block:: bash - - make gdb +- :doc:`/arch/esp8266/debugging/index` +- :doc:`/arch/esp32/debugging/index` +- :doc:`/arch/rp2040/debugging/index` +- :doc:`/arch/host/debugging/index` Developers using Eclipse CDT can have debugging sessions like the one below: -.. :image:: /information/debugging/eclipse.png - -See :sample:`LiveDebug` sample for details. +.. image:: /arch/esp8266/debugging/eclipse-esp8266.png +The :sample:`LiveDebug` demonstrates general use of the debugger connection. diff --git a/samples/HttpServer_AJAX/README.rst b/samples/HttpServer_AJAX/README.rst index 6dba8d0155..20689dc32b 100644 --- a/samples/HttpServer_AJAX/README.rst +++ b/samples/HttpServer_AJAX/README.rst @@ -3,5 +3,5 @@ AJAX Http Server Demonstration of a simple web server with page updates using `AJAX `__. -.. :image:: esp8266-ajax-server.png +.. image:: esp8266-ajax-server.png :height:192px diff --git a/samples/Radio_si4432/README.rst b/samples/Radio_si4432/README.rst index 17c81592bc..b54a5926d7 100644 --- a/samples/Radio_si4432/README.rst +++ b/samples/Radio_si4432/README.rst @@ -4,5 +4,5 @@ SI443 Radio Example application for radio module Si4432 aka RF22 driver. Link: http://www.electrodragon.com/w/SI4432_433M-Wireless_Transceiver_Module_%281.5KM_Range,_Shield-Protected%29 -.. :image:: test_hardware.jpg +.. image:: test_hardware.jpg :height: 192px