readme updates

Signed-off-by: Jens Reinecke <jens.reinecke@arm.com>

Author: jreineckearm

README.md

@@ -33,23 +33,25 @@ We recommend to install the following extensions to simplify the user experience
 
 ## Debug Setup
 
-All debug setups require a GDB installation which supports the GDB remote protocol and can establish the connection to a GDB server like pyOCD.
+All debug setups require a GDB installation that supports the GDB remote protocol and can connect to a GDB server like pyOCD.
 
-We recommend to install the `GCC compiler for ARM CPUs` with the `Arm Tools Environment Manager` extension to get access to such a GDB variant. It comes with `arm-none-eabi-gdb` which is used in this extension's default debug configurations.
+We recommend to install the `GCC compiler for ARM CPUs` using the `Arm Tools Environment Manager` extension.<br>
+It comes with `arm-none-eabi-gdb` which is used in the Arm CMSIS Debugger default debug configurations.
 
 ### pyOCD Debug Setup
 
 This extension includes a pyOCD distribution which is used by default.
 
-If you would like to use a different pyOCD installation, then update the `target`.`server` item of your debug launch configuration with the path to its `pyocd` executable.
+Update your debug configuration's `target`>`server` setting to use a different pyOCD installation. Enter the full path to its `pyocd` executable (including the file name).
 
 ### SEGGER® J-LINK® Debug Setup
 
 Install the latest [J-LINK Software and Documentation Pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) from [SEGGER](https://www.segger.com/). Ensure all required drivers and host platform specific settings are done.
 
-Ensure the installation folder is added to your system's `PATH` environment variable to use default debug configurations provided by this extension. Alternatively, update the `target`.`server` item of your debug launch configuration with the path to the J-LINK GDB server executable to use.
+The extension expects the installation folder to be on your system `PATH` environment variable.<br>
+Alternatively, update your debug configuration's `target`>`server` setting to contain the full path to the J-LINK GDB server executable (including the file name).
 
-## Additional Extension Functionality
+## Extension Functionality
 
 This extension contributes additional functionality to more seamlessly integrate the included extensions:
 
@@ -63,32 +65,94 @@ This section describes the contributed pseudo debugger types and their support t
 
 #### CMSIS Debugger (pyOCD) - `cmsis-debug-pyocd`
 
-The `cmsis-debug-pyocd` debugger type allows to add default debug configurations to the workspace's `launch.json` file to debug via GDB and pyOCD. The actually used debugger type is `gdbtarget`.
+The `cmsis-debug-pyocd` debugger type allows to add default debug configurations to the workspace's `launch.json` file for debug with GDB and pyOCD.<br>
+Those configurations then use the `gdbtarget` debugger type registered by the CDT GDB Debug Adapter Extension.
 
-In addition this extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
+Additionaly, the extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
 
-- If option `target`.`server` is set to `pyocd`, then it expands this option to the absolute path of the built-in pyOCD distribution.
-- Adds/extends the `target`.`serverParameters` list of `pyocd` command line arguments:
+- 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` and the corresponding `port` value if `target`.`port` is set.
-  - Appends `--cbuild-run` and the corresponding `cbuildRunFile` path if `cmsis`.`cbuildRunFile` is set.
+  - 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`. However, this is a new option which isn't contained yet in releases outside this extension.
 
 #### CMSIS Debugger (J-LINK) - `cmsis-debug-jlink`
 
-The `cmsis-debug-jlink` debugger type allows to add default debug configurations to the workspace's `launch.json` file to debug via GDB and the SEGGER J-LINK GDB server. The actually used debugger type is `gdbtarget`.
+The `cmsis-debug-jlink` debugger type allows to add default debug configurations to the workspace's `launch.json` file for debug with GDB and the SEGGER J-LINK GDB server.<br>
+Those configurations then use the `gdbtarget` debugger type registered by the CDT GDB Debug Adapter Extension.
 
-**Note**: The generated default debug configuration uses `JLinkGDBServer` as `target`.`server` setting. The executable with this name has slightly differing behavior depending on your host platform. It launches a GUI-less server on Linux and macOS. Whereas a GDB server with GUI is launched on Windows®. Please change the value to `JLinkGDBServerCL` to suppress the GUI on Windows.
+**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.
 
-In addition this extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
+Additionaly, the extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
 
-- Adds/extends the `target`.`serverParameters` list of `JLinkGDBServer`/`JLinkGDBServerCL` command line arguments:
-  - Appends `--port` and the corresponding `port` value if `target`.`port` is set.
+- 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.
 
-## Known Limitations
+## Known Limitations and Workarounds
 
-- Requires ELF files built with GCC and DWARF5 debug information to operate seamlessly.
+### pyOCD fails to load `*.cbuild-run.yml` in the default configuration
+
+When I use the default debug configuration for pyOCD, I get errors that pyOCD cannot find the solutions `*.cbuild-run.yml` file.
+
+**Possible Reasons**:
+
+1. The application's CSolution was initially built with a CMSIS-Toolbox version prior to v2.8.0 which is the first version to generate `*.cbuild-run.yml` files.
+1. You are using an [Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) prior to v1.52.0 which is the first version to fully support the `${command:cmsis-csolution.getCbuildRunFile}` command.
+
+**Workarounds/Solutions**:
+
+1. Update the CMSIS Toolbox to the latest version. Additionally, you may have to run `cbuild setup --update-rte` in a terminal for a first-time generation of `*.cbuild-run.yml` file in an existing workspace.
+1. Update to Arm CMSIS Solution v1.52.0. Alternatively, replace `${command:cmsis-csolution.getCbuildRunFile}` with the path to the `*.cbuild-run.yml` in your workspace (`cmsis`>`cbuildRunFile` debug configuration setting).
+
+### AXF files built with Arm Compiler 6 toolchain
+
+When I download an AXF file built with Arm Compiler 6 I see the following warning and my application does not execute correctly. This happens regardless of the selected GDB server.
+```
+warning: Loadable section "RW_RAM0" outside of ELF segments
+  in /path/to/my/application.axf
+```
+
+**Possible Reason**: `arm-none-eabi-gdb` does not correctly load ELF program segments due to the way that Arm Compiler 6 generates section and program header information when scatterloading is used.
+
+**Workaround**: You can generate a HEX file for the program download, and the ELF file for debug purposes only. The following steps are required if you build a [CSolution](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview/)-based application with the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/):
+
+1. Edit the `*.cproject.yml` file(s) of your application.
+1. Modify the [`output:type:`](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format/#output) node to generate both an `elf` and a `hex` file:
+```
+  output:
+    type:
+      - elf
+      - hex  
+```
+1. Build the solution.
+1. Keep the default configuration's `program` setting as is.
+```
+"program": "${command:cmsis-csolution.getBinaryFile}",
+```
+1. Modify the default debug configuration's `initCommands` list, so that the `load` command gets the relative path to the generated HEX file.
+```
+            "initCommands": [
+                "load ./relative/path/to/my/application.hex",
+                "break main"
+            ],
+```
+
+The debugger then loads the debug information from the ELF file. But uses the HEX file instead of the ELF file for program download.
+
+### `arm-none-eabi-gdb` requires DWARF5 debug information
+
+`arm-none-eabi-gdb` generates the following warnings when I debug ELF files with [DWARF](https://dwarfstd.org/) debug information of standard version 4 and earlier. And the debug illusion seems to be broken in many places.<br>
+```
+warning: (Internal error: pc 0x8006a18 in read in CU, but not in symtab.)
+```
+
+**Possible Reason**: `arm-none-eabi-gdb` works best with DWARF debug information of standard version 5.
+
+**Solution**: Make sure to build your application ELF file with DWARF version 5 debug information. Please refer to your toolchain's user reference manual. This may require updates to all build tools like compiler, assembler, and linker.
 
 ## Trademarks