From e7bf95bf20d842b924bce037b4b34cb124cc7ac3 Mon Sep 17 00:00:00 2001
From: Joe Campbell <10763991+needs-coffee@users.noreply.github.com>
Date: Thu, 14 Apr 2022 01:58:11 +0100
Subject: [PATCH] FreeRTOS debugging documentation (#446)

---
 BUILDING.md           | 11 +++++++++++
 DEBUGGING_FREERTOS.md | 46 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 DEBUGGING_FREERTOS.md

diff --git a/BUILDING.md b/BUILDING.md
index 9c8d573..8e1c39a 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -1,5 +1,16 @@
+# Building
+
 This project uses [PlatformIO](https://platformio.org/) to simplify development.  The easiest way to get started is to install [VSCode](https://code.visualstudio.com/) and the [PlatformIO VSCode plugin](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) (simple instructions [here](https://platformio.org/install/ide?install=vscode)).
 
 Once you have opened this project, building and uploading the project to your ESP32 board is as easy as clicking on the Build and Upload buttons.
 
 ![PlatformIO Build/Upload Buttons](https://docs.platformio.org/en/latest/_images/platformio-ide-vscode-build-project.png)
+
+## Changing PlatformIO project environment  
+Project environments are used for different board configurations and are stored in ```platformio.ini```
+Platforms can be changed by:
+
+- Selecting the PlatformIO icon from the left bar in VSCode
+- Selecting the desired build target under project tasks
+
+![PlatformIO Env](https://community.platformio.org/uploads/default/original/2X/4/4d87f4672f1892ce54852fed3b8e3cf21b8aed4f.png)
\ No newline at end of file
diff --git a/DEBUGGING_FREERTOS.md b/DEBUGGING_FREERTOS.md
new file mode 100644
index 0000000..2520ace
--- /dev/null
+++ b/DEBUGGING_FREERTOS.md
@@ -0,0 +1,46 @@
+# Debugging FreeRTOS Stacks
+
+PlatformIOs built in tools for debugging the FreeRTOS stack are limited.
+NXP have a free FreeRTOS debug plugin for Eclipse which will give more detailed debug information regarding stack usage. 
+
+### Requirements 
+- [**MCUXpresso IDE**](https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-integrated-development-environment-ide:MCUXpresso-IDE) - This requires a free NXP account to access the download link. Any Eclipse install will work but if using another install, the FreeRTOS plugin will need to be installed separately. 
+- **JTAG Debugger** - Any debugger compatible with OpenOCD should work. This below steps were tested with a Segger J-Link
+- **PlatformIO**
+- **OpenOCD** - Changing the PlatformIO project environment to an environment set to use ```upload_protocol = jlink``` will automatically download the ```tool-openocd-esp32``` package.
+
+### Setup the MCUXpresso debugger
+1. Open MCUXpresso - any workspace can be used
+2. Select Run > Debug Configurations
+3. Double click on ``` GDB Hardware Debugging``` to create a new configuration
+4. On the *Main* tab -
+    a. **Project** - Can be left blank, or point to project code.
+    b. **C/C++ Application** - Point to the ```firmware.elf``` file. If built from PlatformIO will be in the ```ESPresense/.pio/build/<env name>``` directory. 
+    c. **Build** - Disable auto build
+5. On the *Debugger* tab -
+    a. **GDB Command** - Path to ```xtensa-esp32-elf-gdb.exe```, if using defaults in PlatformIO will be ```~/.platformio/packages/toolchain-xtensa32/bin/xtensa-esp32-elf-gdb.exe```
+    b. **Remote Target** - Check Use remote target, JTAG Device - ```OpenOCD (via socket)```, GDB Connection String ```localhost:3333```
+6. On the *Startup* tab - 
+    a. **Initialisation commands**:
+        - ```set mem inaccessible-by-default off```
+        - ```mon reset halt```
+        - ```flushregs```
+        - ```set remote hardware-watchpoint-limit 2```
+    b. **Load Symbols** - Use project binary
+    c. Uncheck all boxes except ```Load Symbols``` and ```Resume```
+7. Apply Changes
+
+### Running the debug tool
+1. Program the ESP32 with the target build and connect the ESP32 to the debug probe.
+2. Start the OpenOCD Server:
+```bash
+cd ~\.platformio\packages\tool-openocd-esp32
+.\bin\openocd.exe -f .\share\openocd\scripts\interface\J-Link.cfg -f .\share\openocd\scripts\board\esp-wroom-32.cfg -c "adapter_khz 4000"
+```
+3. Start the debug tool in MCDExpresso with the debug symbol on the taskbar. **Note**: I have found the first connection to the debug session often fails with a warning ```failed to execute MI Command
+--exec-continue```. Canceling this and selecting the debug symbol again correctly starts the debugger.
+4. FreeRTOS information can be viewed from the RTOS > Task List from the top menu. This will refresh after pausing the debugger or reaching a breakpoint. 
+
+
+### References
+https://mcuoneclipse.com/2019/09/22/eclipse-jtag-debugging-the-esp32-with-a-segger-j-link/
\ No newline at end of file