Skip to content

Commit

Permalink
Update README and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@HampusAdolfsson
HampusAdolfsson committed Nov 25, 2024
1 parent d81a67c commit 924048d
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 44 deletions.
78 changes: 38 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,73 +1,71 @@
# IAR C-SPY Debugger
# IAR C-SPY Debug

Use IAR System's C-SPY Debugger to debug embedded programs using Visual Studio Code, with support for a wide range of embedded devices and debug probes. This extension can be used with IAR Embedded Workbench (.ewp) projects, or with other build systems such as CMake. An IAR Embedded Workbench installation using IDE version 8 or newer is required to use this extension. See [Compatibility](#compatibility) table below for detailed information.
Debug your applications with the IAR C-SPY Debugger in Visual Studio Code with the IAR C-SPY Debug extension. The IAR C-SPY Debugger features support for a wide range of embedded devices and debug probes. This extension can be used for debugging programs created from IAR Embedded Workbench projects (`*.ewp`, `*.ewd`), or from 3<sup>rd</sup> party build systems such as CMake.

![A VS Code window with a C-SPY debug session](https://raw.githubusercontent.com/IARSystems/iar-vsc-debug/master/md-images/debug-session.png)

## Getting Started

**To debug an IAR Embedded Workbench (`.ewp`) project**, we recommend also installing the [IAR Build](https://marketplace.visualstudio.com/items?itemName=iarsystems.iar-build) extension.
The extension will then automatically provide debug configurations for your project.
If you do not have a `launch.json` file in the workspace,
simply press `Run and Debug` in the Debug view to start debugging the current project and configuration.
An IAR Embedded Workbench or IAR Build Tools installation is required to use this extension. See the [Compatibility](#compatibility) section below for detailed information.

![A user clicking 'Run and Debug' and starting a debug session](https://raw.githubusercontent.com/IARSystems/iar-vsc-debug/master/md-images/start-session2.gif)
### Debugging an executable built from an IAR Embedded Workbench project

If you already have a `launch.json` file, automatic C-SPY debug configurations can be accessed by pressing `IAR C-SPY Debug...` in
the debug configuration dropdown.
For the best experience, install the [IAR Build](https://marketplace.visualstudio.com/items?itemName=iarsystems.iar-build) extension. The IAR C-SPY Debug extension will then automatically provide debug configurations taken from the IAR Embedded Workbench project (`*.ewp`, `*.ewd`). Simply switch to the __Run and Debug__ view, press the __Run and Debug__ button, and start debugging the current executable.

![A user hovering over the 'IAR C-SPY Debug...' option](https://raw.githubusercontent.com/IARSystems/iar-vsc-debug/master/md-images/debug-dropdown.png)
![A user clicking 'Run and Debug' and starting a debug session](https://raw.githubusercontent.com/iarsystems/iar-vsc-debug/master/md-images/start-session2.gif)

**To debug a program without an IAR Embedded Workbench project** (e.g. from a CMake project) you need to manually provide a debug
configuration in the form of a `launch.json` file.
There are two ways to do this:
Visual Studio Code stores debug configurations for its current workspace in the `.vscode/launch.json` configuration file. If the workspace already has a `.vscode/launch.json` file, choosing __IAR C-SPY Debug...__ in the debug configuration dropdown menu will offer debug configurations generated for your project.

* Follow the instructions for [generating a launch.json configuration](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#CustomizingADebugConfig)
from an IAR Embedded Workbench project and copy the `launch.json file`.
* Create the configuration yourself. Please see the reference for [the launch.json format](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#launch-json-format).
![A user hovering over the 'IAR C-SPY Debug...' option](https://raw.githubusercontent.com/iarsystems/iar-vsc-debug/master/md-images/debug-dropdown.png)

For more help, see [Debugging a stand-alone application](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#debuggingstandaloneprogram).
### Debugging an executable built from a 3<sup>rd</sup> party build system

## Documentation
There are two ways for creating the `.vscode/launch.json` configuration file when debugging a program built from a 3<sup>rd</sup> party build system, such as CMake:

* [Customizing a debug configuration](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#CustomizingADebugConfig)
* Follow the instructions for [generating a launch.json configuration](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#CustomizingADebugConfig) from a separate IAR Embedded Workbench project with the desired target and probe selections and copy the generated `.vscode/launch.json` configuration file to the workspace.
* Create the configuration yourself. Please see the reference for [the launch.json format](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#launch-json-format).

* [Making IAR C-SPY Debug settings](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#MakingIARC-SPYDebugSettings)
For more help, see [Debugging a stand-alone application](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#debuggingstandaloneprogram).

* [Run menu](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#RunMenu)
## Documentation

* [The Side Bar views](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#IARBuildTasks)
* [Customizing a debug configuration](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#CustomizingADebugConfig)

* [Breakpoint types](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#BreakpointTypes)
* [Making IAR C-SPY Debug settings](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#MakingIARC-SPYDebugSettings)

* [Debugging a stand-alone application](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#debuggingstandaloneprogram)
* [Run menu](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#RunMenu)

* [The launch.json format](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md#launch-json-format)
* [The Side Bar views](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#IARBuildTasks)

[Click here](https://github.com/IARSystems/iar-vsc-debug/blob/master/docs/README.md) to view the full documentation.
* [Breakpoint types](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#BreakpointTypes)

## Compatibility
* [Debugging a stand-alone application](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#debuggingstandaloneprogram)

This extension is compatible with selected IAR Embedded Workbench (EW) products. The following table describes the level of support for your specific product:
* [The launch.json format](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md#launch-json-format)

| Target architecture | Product Version | Known Limitation
|---------------------|-----------------|-------------
| Arm<br>RISC-V<br>RL78<br>AVR<br>RX | v9.30.1 or later<br>v3.11.1 or later<br>v5.10.1 or later<br>v8.10.1 or later<br>v5.10.1 or later| None
| RISC-V | v3.10.1 | Terminal I/O is not supported
| Arm<br>RH850 | v8.50.1-9.20.4<br>v3.10.1 or later | An initial debug session with EW is required prior to debugging in VSCode
| Arm | v8.40.1-8.50.1 | The variables view is not supported
[Click here](https://github.com/iarsystems/iar-vsc-debug/blob/master/docs/README.md) to view the full documentation.

## Compatibility

**Note:** You may experience crashes using multicore debugging with Arm 9.10.2 and earlier, as well as RH850 3.10.2 and earlier.
This extension is compatible with selected versions of the IAR Embedded Workbench (EW) or IAR Build Tools (BX) installations. The table below lists known limitations of this extension concerning earlier versions of both IAR products for each supported target architecture:

</details>
| Target architecture | Product Version | Known Limitation
|------------------------|-----------------|-----------
| Arm | v9.60.2 or later | None.
| Arm | v9.50.1-9.50.2 | IAR Build Tools on Linux and IAR Embedded Workbench only.
| Arm<br>RISC-V<br>AVR<br>RH850<br>RL78<br>RX| v8.40.1-9.40.2 <br>v3.10.1 or later <br>v8.10.1 or later <br>v3.10.1 or later <br>v5.10.1 or later <br>v5.10.1 or later | IAR Embedded Workbench on Windows only.
| RISC-V | v3.10.1 | Terminal I/O is not supported.
| Arm<br>RH850 | v8.50.1-9.20.4 <br>v3.10.1 or later | A prior debug session launched from EW is initially required<br>before launching a debug session in VS Code.
| Arm<br>RH850 | v8.40.1-9.10.2 <br>v3.10.1-3.10.2 | Multicore debugging instability, leading to potential crashes.
| Arm | v8.40.1-8.50.10 | The _variables view_ is not supported.

## Feedback

If you are unable to start a debug session in Visual Studio Code, please verify that debugging in IAR Embedded Workbench works (to rule out any non-Visual Studio Code related issues).
If you are unable to launch a debug session in Visual Studio Code, rule out any unrelated issues by verifying that debugging in IAR Embedded Workbench works.
Depending on the type of feedback you want to share with us, here are our preferred options:

* For urgent matters with the extension, or if you have issues with the underlying IAR Embedded Workbench product, report this via the IAR Systems technical support channel at [IAR Technical Support](https://www.iar.com/knowledge/support/request-technical-support/).
* For urgent matters with the extension, or if you have issues with the underlying IAR Embedded Workbench or IAR Build Tools product, report them via the [IAR Technical Support](https://www.iar.com/knowledge/support/request-technical-support/) channel.

* For other matters isolated to this extension, file a [New issue](https://github.com/IARSystems/iar-vsc-debug/issues/new/choose) using the provided template. We will reply on a "best effort basis".
* For other matters isolated to this extension, file a [New issue](https://github.com/iarsystems/iar-vsc-debug/issues/new/choose) using the provided template. We will reply on a "best effort basis".

* If you have ideas on how to improve this extension, see [CONTRIBUTING.md](https://github.com/IARSystems/iar-vsc-debug/blob/master/CONTRIBUTING.md) on how to proceed.
* If you have ideas on how to improve this extension, see [CONTRIBUTING.md](https://github.com/iarsystems/iar-vsc-debug/blob/master/CONTRIBUTING.md) on how to proceed.
15 changes: 11 additions & 4 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ These types of variables are can be inspected in the **Variables** view:

* CPU Registers. The CPU registers are grouped in register groups.

Clicking the **View Binary Data** button opens the **Memory** view, where you can inspect the variable as binary data in memory. See [Memory view](#MemoryView).
Clicking the **View Binary Data** button opens the **Memory** view, where you can inspect the variable as binary data in memory. With the [Memory Inspector](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.memory-inspector) extension installed, you can also right click a variable and click **Show in Memory Inspector** to open an alternative memory view implementation. See [Memory view](#MemoryView).

On the context menu are commands for setting or copying the value of the selected variable.

Expand Down Expand Up @@ -219,9 +219,9 @@ This view is provided by the VS Code and can be opened by right-clicking in the

<h3 id="MemoryView">Memory view</h3>

This view is a hex editor that can be opened by clicking on the **View Binary Data** icon to the right of a static variable in the **Variables** view. The view opens at the variable's location in memory. Arbitrary memory locations cannot be opened.
VS Code's default memory view is a hex editor that can be opened by clicking on the **View Binary Data** icon to the right of a static variable in the **Variables** view. The view opens at the variable's location in memory. Arbitrary memory locations cannot be opened.

This view is provided by the VS Code.
If you install the [Memory Inspector](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.memory-inspector) extension, you can use an alternative memory view which provides additional functionality. It can be opened by right clicking a static variable in the **Variables** view and clicking **Show in Memory Inspector**.

### Peripheral view

Expand All @@ -231,6 +231,13 @@ This view is provided by the VS Code Embedded Tools extension. See the VS Code d

This view is provided by the VS Code Embedded Tools extension. See the VS Code documentation for more information.

### Views from the IAR Embedded Workbench IDE

This extension provides several views that are identical to ones found in the
IAR Embedded Workbench IDE. Among others, these include the Live Watch, Trace,
Profiling and Code Coverage views. For documentation on these views, see the
*IAR Embedded Workbench C-SPY® Debugging Guide* (PDF).

<h2 id="BreakpointTypes">Breakpoint types</h2>

For most debugger drivers, the IAR C-SPY Debugger lets you decide whether to use hardware breakpoints, software breakpoints, or whether to let the driver decide the type to use. To work with breakpoint types, use the commands on the command palette.
Expand Down Expand Up @@ -328,7 +335,7 @@ The `driverOptions` attribute takes C-SPY command line parameters. For reference

The current version of the IAR C-SPY Debug extension adds support for leaving the application running after the debug session is closed (`"leaveTargetRunning": true`) and for making the debugger attach to a running application at its current location, without resetting the target system (`"request": "attach"`). You can, for example, use this to create one debug configuration to flash and launch your application in C-SPY, and one configuration to reattach to the application when needed.

If you have installed the [IAR Build](https://marketplace.visualstudio.com/items?itemName=iarsystems.iar-vsc) extension, and have specified a `projectPath` and a `projectConfiguration` in your `launch.json` configuration, you can omitt other `launch.json` fields to have them automatically filled from the referenced project configuration. For example, a `launch.json` configuration where all missing fields are taken from the selected project configuration can look like this:
If you have installed the [IAR Build](https://marketplace.visualstudio.com/items?itemName=iarsystems.iar-vsc) extension, and have specified a `projectPath` and a `projectConfiguration` in your `launch.json` configuration, you can omit other `launch.json` fields to have them automatically filled from the referenced project configuration. For example, a `launch.json` configuration where all missing fields are taken from the selected project configuration can look like this:

```json
{
Expand Down
Binary file modified md-images/debug-session.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 924048d

Please sign in to comment.