Docs updates and release preparations v0.1.0

CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log
 
 ## Unreleased
+- Updates included pyOCD distribution
+  - Fixes support for `<memory>` elements from CMSIS PDSC files.
+  - Fixes progress bar output during program download.
+  - Improves connection robustness and DP sticky error bits handling for temporary target communication losses and `__errorcontrol` usage (CMSIS debug descriptions). For example in reset scenarios.
+  - Extends and improves support for `*.cbuild-run.yml` debug configuration files.
+
+## 0.0.3
 - Fixes [#84](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/84): Cannot use cbuild-run files with pyOCD without CMSIS_PACK_ROOT environment variable.
 - Implements [#83](https://github.com/Open-CMSIS-Pack/vscode-cmsis-debugger/issues/83): Make built-in pyOCD available in VS Code terminals.
   - Note that there is a known issue with a pyOCD installation in Python virtual environments taking precedence over the built-in pyOCD variant.

README.md

@@ -31,16 +31,27 @@ 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 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.
 
-## pyOCD Debug Setup
+## Debug Setup
 
-- Install `GCC compiler for ARM CPUs` with the `Arm Tools Environment Manager` extension to get access to a GDB (`arm-none-eabi-gdb`).
+All debug setups require a GDB installation that supports the GDB remote protocol and can connect to a GDB server like pyOCD.
 
-## SEGGER® J-LINK® Debug Setup
+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.
 
-- 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. Alternatively, you can add an absolute path to your installation in the debug launch configuration.
+### pyOCD Debug Setup
 
-## Additional Extension Functionality
+This extension includes a pyOCD distribution which is used by default.
+
+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.
+
+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).
+
+## Extension Functionality
 
 This extension contributes additional functionality to more seamlessly integrate the included extensions:
 
@@ -54,33 +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 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.
+
+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.
+
+## Known Limitations and Workarounds
+
+### 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"
+            ],
+```
 
-**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.
+The debugger then loads the debug information from the ELF file. But uses the HEX file instead of the ELF file for program download.
 
-In addition this extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:
+### `arm-none-eabi-gdb` requires DWARF5 debug information
 
-- Adds/extends the `target`.`serverParameters` list of `JLinkGDBServer`/`JLinkGDBServerCL` command line arguments:
-  - Appends `--port` and the corresponding `port` value if `target`.`port` is set.
+`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.)
+```
 
-## Known Limitations
+**Possible Reason**: `arm-none-eabi-gdb` works best with DWARF debug information of standard version 5.
 
-- Requires ELF files built with GCC and DWARF5 debug information to operate seamlessly.
-- The shipped pyOCD version accepts the new command line option `--cbuild-run`. But only extracts device and DFP names.
+**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