Added troubleshooting, minor corrections (#215)

* Added troubleshooting, minor corrections

* Renamed filw

* Added note about Windows

* Update README.md

---------

Co-authored-by: Jens Reinecke <[email protected]>

Author: KeilChris

CHANGELOG.md

@@ -13,7 +13,7 @@
 
 ## 0.1.0
 - Updates included pyOCD distribution
-  - Fixes [#92](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/92): `monitor reset halt` command fails for LPCXpresso55S69 if using CMSIS Pack support in pyOCD.
+  - Fixes [#92](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/92): `monitor reset halt` command fails for LPCXpresso55S69 if using CMSIS-Pack support in pyOCD.
   - Fixes [#93](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/93): Download to LPC55S69 flash with GDB and pyOCD ends in errors.
   - Fixes [#94](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/94): Cannot connect to NXP FRDM-K32L3A6 with pyOCD.
   - Fixes support for `<memory>` elements from CMSIS PDSC files.

README.md

@@ -21,14 +21,17 @@ The Arm CMSIS Debugger extension is an [extension pack](https://code.visualstudi
 The following extensions are included in this extension pack:
 
 - [CDT™ GDB Debug Adapter Extension](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.cdt-gdb-vscode), an Eclipse CDT.cloud extension that supports debugging using GDB and any other debuggers that supports the MI protocol.
+
 - [Memory Inspector](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.memory-inspector), an Eclipse CDT.cloud extension that provides a powerful and configurable memory viewer that works with debug adapters.
+
 - [Peripheral Inspector](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.peripheral-inspector), an Eclipse CDT.cloud extension that provides a CMSIS SVD viewer and works with debug adapters.
 
 ## Recommended Extensions
 
 We recommend to install the following extensions to simplify the user experience:
 
-- [Arm Tools Environment Manager](https://marketplace.visualstudio.com/items?itemName=Arm.environment-manager), an extension that allows to download, install, and manage software development tools using [Microsoft® Vcpkg](https://vcpkg.io/en/index.html) artifacts. Use this extension to for example install the `GCC compiler for ARM CPUs` which comes with a GDB variant for Arm CPUs.
+- [Arm Tools Environment Manager](https://marketplace.visualstudio.com/items?itemName=Arm.environment-manager), an extension that allows you to download, install, and manage software development tools using [Microsoft® Vcpkg](https://vcpkg.io/en/index.html) artifacts. For example, use this extension to install the [Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) which comes with a GDB variant for Arm CPUs.
+
 - [Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution), an extension that is a graphical user interface for csolution projects that use the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/). Use this extension to build your csolution projects, to generate `*.cbuild-run.yml` debug configuration files, and to make use of contributed commands in your debug launch configurations.
 
 ## Debug Setup
@@ -70,9 +73,9 @@ Additionaly, the extension contributes a debug configuration resolver which auto
 
 - If option `target`>`server` is set to `pyocd`, then it expands to the absolute path of the built-in pyOCD distribution.
 - Extends the `target`>`serverParameters` list of `pyocd` command line arguments:
-  - Prepends `gdbserver` if not present.
-  - Appends `--port <gdbserver_port>` if the `target`>`port` setting is set, where `<gdbserver_port>` gets that port setting's value.
-  - Appends `--cbuild-run` and the corresponding `cbuildRunFile` path if `cmsis`>`cbuildRunFile` is set.
+    - Prepends `gdbserver` if not present.
+    - Appends `--port <gdbserver_port>` if the `target`>`port` setting is set, where `<gdbserver_port>` gets that port setting's value.
+    - Appends `--cbuild-run` and the corresponding `cbuildRunFile` path if `cmsis`>`cbuildRunFile` is set.
 
 **Note**: The built-in version of pyOCD supports the command line option `--cbuild-run` which isn't available in releases outside this extension.
 
@@ -82,13 +85,14 @@ The `cmsis-debug-jlink` debugger type is used to add a debug configuration in th
 This configuration uses the `gdbtarget` debugger type registered by the CDT GDB Debug Adapter Extension.
 
 **Note**: The generated default debug configuration uses the value `JLinkGDBServer` as `target`>`server` setting. This executable has differing behavior on supported host platform:
-* Linux and macOS: A GUI-less version of the GDB server is launched.
-* Windows®: A GDB server with GUI is launched. Update `target`>`server` to `JLinkGDBServerCL` to launch a GUI-less version on Windows, too.
+
+- Linux and macOS: A GUI-less version of the GDB server is launched.
+- Windows®: A GDB server with GUI is launched. Update `target`>`server` to `JLinkGDBServerCL` to launch a GUI-less version on Windows, too.
 
 Additionaly, the extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
 
 - Extends the `target`>`serverParameters` list of `JLinkGDBServer`/`JLinkGDBServerCL` command line arguments:
-  - Appends `--port <gdbserver_port>` if the `target`>`port` setting is set, where `<gdbserver_port>` gets that port setting's value.
+    - Appends `--port <gdbserver_port>` if the `target`>`port` setting is set, where `<gdbserver_port>` gets that port setting's value.
 
 ## Known Limitations and Workarounds
 

docs/configure.md

@@ -62,11 +62,7 @@ For debugging with pyOCD, the following is added to the `launch.json` file:
 
 ### Single-core (pyOCD)
 
-For a single-core device, you need to add:
-
-- the relative path to the HEX file to `"initCommands"` - `"load"`.
-
-- an absolute `"definitionPath"` to the device's SVD file to be able to use the [Periperals view](./debug.md).
+For a single-core device, you need to add the relative path to the HEX file to `"initCommands"` - `"load"`.
 
 **Example**
 
@@ -91,7 +87,6 @@ For a single-core device, you need to add:
             "cmsis": {
                 "cbuildRunFile": "${command:cmsis-csolution.getCbuildRunFile}"
             }
-            "definitionPath": "/Users/user/.cache/arm/packs/Keil/STM32U5xx_DFP/3.0.0/CMSIS/SVD/STM32U585.svd"
         }
     ]
 }
@@ -105,13 +100,7 @@ For a multi-core device, you need to:
 
 - for the secondary core: comment out the  `"initCommands"`.
 
-- for each core:
-
-    - add an absolute `"definitionPath"` to the device's SVD file to be able to use the
-      [Periperals view](./debug.md).
-
-    - add the relative path to the AXF (ELF) files for each core to `"program"`.
-
+- add for each core the relative path to the AXF (ELF) files for each core to `"program"`.
 
 **Example**
 
@@ -136,9 +125,8 @@ For a multi-core device, you need to:
                 "port": "3333"
             },
             "cmsis": {
-                "cbuildRunFile": "FRDM-K32L3A6.cbuild-run.yml"
+                "cbuildRunFile": "${command:cmsis-csolution.getCbuildRunFile}"
             },
-            "definitionPath": "/Users/user/.cache/arm/packs/NXP/K32L3A60_DFP/19.0.0/devices/K32L3A60/K32L3A60_cm4.xml"
         },
         {
             "name": "CM0+: CMSIS Debugger: pyOCD",
@@ -155,7 +143,6 @@ For a multi-core device, you need to:
                 "server": "pyocd",
                 "port": "3334"
             },
-            "definitionPath": "/Users/user/.cache/arm/packs/NXP/K32L3A60_DFP/19.0.0/devices/K32L3A60/K32L3A60_cm0plus.xml"
         }
     ]
 }
@@ -210,9 +197,6 @@ added to the `launch.json` file:
 
 For a single-core device, the configuration template contains all the information that is required to start debugging.
 
-!!! Attention
-    **Check if the above statement is true!**
-
 ### Multi-core (J-Link)
 
 For a multi-core device, you need to:

docs/debug_views.md

@@ -15,7 +15,7 @@ following aspects:
 
 - [BREAKPOINTS section](#breakpoints-section) is available.
 
-- [Peripheral Inspector](#peripherals-inspector) is available (requires configuration).
+- [Peripheral Inspector](#peripheral-inspector) is available (requires configuration).
 
 - [Memory Inspector](#memory-inspector) can be opened.
 

docs/images/remote_comms_err.png

@@ -16,7 +16,7 @@ The following extensions are included in this extension pack:
 
 We recommend installing the following extensions to simplify the user experience:
 
-- [Arm Tools Environment Manager](https://marketplace.visualstudio.com/items?itemName=Arm.environment-manager), an extension that allows to download, install, and manage software development tools using [Microsoft® Vcpkg](https://vcpkg.io/en/index.html) artifacts. Use this extension to for example install the `GCC compiler for ARM CPUs` which comes with a GDB variant for Arm CPUs.
+- [Arm Tools Environment Manager](https://marketplace.visualstudio.com/items?itemName=Arm.environment-manager), an extension that allows you to download, install, and manage software development tools using [Microsoft® Vcpkg](https://vcpkg.io/en/index.html) artifacts. For example, use this extension to install the [Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) which comes with a GDB variant for Arm CPUs.
 
 - [Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution), an extension that is a graphical user interface for csolution projects that use the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/). Use this extension to build your csolution projects, to generate `*.cbuild-run.yml` debug configuration files, and to make use of contributed commands in your debug launch configurations.
 
@@ -26,17 +26,18 @@ The **Arm CMSIS Debugger** extension pack supports a wide range of debug probes:
 
 - [CMSIS-DAP v2.x](https://arm-software.github.io/CMSIS-DAP/latest/).
 
-- [STMicroeletronics ST-LINK/V2/V3](https://www.st.com/en/development-tools/hardware-debugger-and-programmer-tools-for-stm32/products.html).
+- [STMicroelectronics ST-LINK/V2/V3](https://www.st.com/en/development-tools/hardware-debugger-and-programmer-tools-for-stm32/products.html).
 
 - [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/).
 
-- any debug probe that comes with a GDB Server.
+- debug probes with a compatible GDB server interface.
 
 ## Multi-core debugging
 
-The Arm CMSIS Debugger is capable of multi-core debugging. For every core that you wish to connect to, you need to
-[create a debug configuration](./configure.md#create-a-launch-configuration). Using the same debug adapter, you can connect
-to the different target cores within one instance of VS Code.
+The Arm CMSIS Debugger is capable of multi-core debugging. You can
+[create a debug configuration](./configure.md#create-a-launch-configuration) for multiple target cores to be debugged within
+a single VS Code session using the same debug adapter, provided the adapter and target support concurrent multi-core
+debugging.
 
 ## Contents
 
@@ -46,10 +47,11 @@ to the different target cores within one instance of VS Code.
 
 - [**Start debugging**](./debug.md) demonstrates how to enter the VS Code debugger.
 
-- [**Debug views**](./debug_views.md) give you access to the code execution and device peripherals.
+- [**Debug views**](./debug_views.md) provide access to code execution and device peripherals.
 
 ## Revision history
 
 Version            | Description
 :------------------|:-------------------------
-0.1.0              | Initial release for the CMSIS Debugger extension version 0.1.0
+0.1.1              | Release for the Arm CMSIS Debugger extension version 0.1.1
+0.1.0              | Initial release for the Arm CMSIS Debugger extension version 0.1.0

docs/index.md

@@ -0,0 +1,77 @@
+# Troubleshooting
+
+This chapter describes problems that might occur during debugging and how to solve them.
+
+## Loadable section outside of ELF segments
+
+When downloading an AXF file built with [Arm Compiler for Embedded](https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded),
+the following warning might appear and the application does not execute correctly. This happens regardless of the selected GDB server.
+
+```txt
+warning: Loadable section "RW_RAM0" outside of ELF segments
+  in /path/to/my/application.axf
+```
+
+### Possible Reason: scatterloading issues
+
+`arm-none-eabi-gdb` does not correctly load ELF program segments due to the way that Arm Compiler for Embedded generates
+section and program header information when scatterloading is used.
+
+### Workaround: Generate a HEX file
+
+Generate a HEX file for the program download, and the ELF file for debug purposes only.
+
+Refer to the [Project setup](./setup.md#project-setup) section for further details.
+
+## Broken debug illusion
+
+When debugging ELF files with [DWARF](https://dwarfstd.org/) debug information of standard version 4 and earlier, `arm-none-eabi-gdb` generates the following warnings:
+
+```txt
+warning: (Internal error: pc 0x8006a18 in read in CU, but not in symtab.)
+```
+
+The debug illusion will be broken in many places.
+
+### Possible Reason: Missing DWARF5 debug information
+
+`arm-none-eabi-gdb` works best with DWARF debug information of standard version 5.
+
+### Solution: Build the ELF file using DWARF5
+
+Make sure to build your application ELF file with DWARF version 5 debug information.
+
+Follow the steps explained in [Project setup](./setup.md#project-setup).
+
+## pyOCD port not available
+
+When starting a debug session, you might see this error:
+
+![Remote communication error](./images/remote_comms_err.png)
+
+### Possible reason: A running instance of pyOCD
+
+This error might occur if a previous debug session has ended prematuerly and pyOCD has not exited. The orphaned instance
+will still keep the port open (usually 3333) and thus you won't be able to open the port again in the new session.
+
+### Solution: Check open files and kill pyOCD
+
+On Linux and macOS you can check the running open files using the [`lsof`](https://de.wikipedia.org/wiki/Lsof) command:
+
+```sh
+sudo lsof -i -n -P | grep 3333
+
+Python    41836       user01    3u  IPv4 0xa6ef66ad5be49a4f      0t0    TCP *:3333 (LISTEN)
+pyocd     41842       user01    8u  IPv4 0x9d09900145f3ca41
+```
+
+To kill the running pyOCD process, use:
+
+```sh
+sudo killall pyocd
+```
+
+On Windows systems, use the
+[Windows Task Manager](https://learn.microsoft.com/en-us/troubleshoot/windows-server/support-tools/support-tools-task-manager)
+or the [Process Explorer](https://learn.microsoft.com/en-us/sysinternals/downloads/process-explorer) to find orphaned
+processes.

docs/troubleshooting.md

@@ -8,6 +8,7 @@ nav:
     - Create launch configuration: configure.md
     - Start debugging: debug.md
     - Debug views: debug_views.md
+    - Troubleshooting: troubleshooting.md
 theme:
   name: readthedocs
 markdown_extensions: