Arm Keil Studio Visual Studio Code Extensions

User Guide

Non-Confidential Issue 08
Copyright © 2023 Arm Limited (or its affiliates). 108029_0000_08_en
All rights reserved.
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Keil Studio Visual Studio Code Extensions

User Guide
Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.

Release information

Document history

Issue Date Confidentiality Change

0000-01 13 July 2023 Non-Confidential First release

0000-02 20 July 2023 Non-Confidential Updates

0000-03 6 September 2023 Non-Confidential Updates

0000-04 3 October 2023 Non-Confidential Updates

0000-05 19 October 2023 Non-Confidential Updates

0000-06 14 November 2023 Non-Confidential Updates

0000-07 5 December 2023 Non-Confidential Updates

0000-08 20 December 2023 Non-Confidential Updates

Proprietary Notice

This document is protected by copyright and other related rights and the practice or
implementation of the information contained in this document may be protected by one or more
patents or pending patent applications. No part of this document may be reproduced in any form
by any means without the express prior written permission of Arm. No license, express or implied,
by estoppel or otherwise to any intellectual property rights is granted by this document unless
specifically stated.

Your access to the information in this document is conditional upon your acceptance that you
will not use or permit others to use the information for the purposes of determining whether
implementations infringe any third party patents.

THIS DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO

WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION,
THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-
INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE
DOCUMENT. For the avoidance of doubt, Arm makes no representation with respect to, and has

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 2 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

undertaken no analysis to identify or understand the scope and content of, patents, copyrights,
trade secrets, or other rights.

This document may include technical inaccuracies or typographical errors.

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR
ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ANY USE OF THIS
DOCUMENT, EVEN IF ARM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

This document consists solely of commercial items. You shall be responsible for ensuring that
any use, duplication or disclosure of this document complies fully with any relevant export laws
and regulations to assure that this document or any portion thereof is not exported, directly
or indirectly, in violation of such export laws. Use of the word “partner” in reference to Arm’s
customers is not intended to create or refer to any partnership relationship with any other
company. Arm may make changes to this document at any time and without notice.

This document may be translated into other languages for convenience, and you agree that if there
is any conflict between the English version of this document and any translation, the terms of the
English version of the Agreement shall prevail.

The Arm corporate logo and words marked with ® or ™ are registered trademarks or trademarks
of Arm Limited (or its affiliates) in the US and/or elsewhere. All rights reserved. Other brands and
names mentioned in this document may be the trademarks of their respective owners. Please
follow Arm’s trademark usage guidelines at https://www.arm.com/company/policies/trademarks.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.

Arm Limited. Company 02557590 registered in England.

110 Fulbourn Road, Cambridge, England CB1 9NJ.

(LES-PRE-20349|version 21.0)

Confidentiality Status

This document is Non-Confidential. The right to use, copy and disclose this document may be
subject to license restrictions in accordance with the terms of the agreement entered into by Arm
and the party that Arm delivered this document to.

Unrestricted Access is an Arm internal classification.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 3 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Product Status

The information in this document is Final, that is for a developed product.

Feedback

Arm welcomes feedback on this product and its documentation. To provide feedback on the
product, create a ticket on https://support.developer.arm.com

To provide feedback on the document, fill the following survey: https://developer.arm.com/

documentation-feedback-survey.

Inclusive language commitment

Arm values inclusive communities. Arm recognizes that we and our industry have used language
that can be offensive. Arm strives to lead the industry and create change.

We believe that this document contains no offensive language. To report offensive language in this
document, email [email protected].

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 4 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Contents

Contents

1. Introduction...................................................................................................................................................... 8
1.1 Conventions......................................................................................................................................................8
1.2 Other information........................................................................................................................................... 9

2. Extension pack and extensions.................................................................................................................10

2.1 Keil Studio Pack pre-release...................................................................................................................... 11

3. Intended use cases for the extensions................................................................................................... 12

4. Get started with an example project...................................................................................................... 13

4.1 Import the Blinky_FRDM-K32L3A6 example........................................................................................ 14
4.2 Download and convert a Keil μVision example.................................................................................... 14
4.3 Finalize the setup of your development environment.........................................................................16
4.3.1 Configure an HTTP proxy (optional).....................................................................................................16
4.3.2 clangd (alternative).................................................................................................................................... 16
4.4 Build the example project.......................................................................................................................... 17
4.5 Set a context for your csolution...............................................................................................................17
4.6 Look at the Solution outline...................................................................................................................... 18
4.7 Manage software components..................................................................................................................18
4.8 Connect your board.....................................................................................................................................18
4.9 Run the csolution on your board............................................................................................................. 18
4.10 Start a debug session................................................................................................................................19
4.11 Check the serial output of your board.................................................................................................19

5. Arm Environment Manager extension.................................................................................................... 20

5.1 Tools installation with Microsoft vcpkg...................................................................................................20
5.2 Check the tools installed with Microsoft vcpkg....................................................................................20
5.3 Modify the manifest file............................................................................................................................. 21
5.4 vcpkg activation options............................................................................................................................. 21
5.5 Use vcpkg from the command line..........................................................................................................21

6. Arm CMSIS csolution extension...............................................................................................................22

6.1 Set a context for your csolution...............................................................................................................22
6.2 Use the Solution outline.............................................................................................................................23
Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 5 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Contents

6.3 Manage software components..................................................................................................................24

6.3.1 Open the Software Components view................................................................................................ 24
6.3.2 Modify the software components in your project............................................................................ 26
6.3.3 Undo changes............................................................................................................................................ 27
6.4 CMSIS-Packs.................................................................................................................................................. 27
6.5 Install missing CMSIS-Packs.......................................................................................................................27
6.6 Configure a build task................................................................................................................................. 28
6.7 Convert a Keil μVision project to a csolution project..........................................................................29
6.8 Create a csolution project..........................................................................................................................29
6.9 Initialize your csolution project................................................................................................................. 32
6.10 Use the CMSIS csolution API................................................................................................................. 32

7. Arm Device Manager extension............................................................................................................... 33

7.1 Supported hardware.................................................................................................................................... 33
7.1.1 Supported development boards and MCUs....................................................................................... 33
7.1.2 Supported debug probes.........................................................................................................................33
7.2 Connect your hardware.............................................................................................................................. 34
7.3 Edit your hardware.......................................................................................................................................34
7.4 Open a serial monitor................................................................................................................................. 35

8. Arm Embedded Debugger extension...................................................................................................... 36

8.1 Run your project on your hardware........................................................................................................ 36
8.1.1 Configure a task........................................................................................................................................ 36
8.1.2 Override or extend the default tasks configuration options...........................................................37
8.1.3 Run your project....................................................................................................................................... 39
8.2 Debug your project with Arm Embedded Debugger...........................................................................39
8.2.1 Add configuration......................................................................................................................................40
8.2.2 Override or extend the default launch configuration options........................................................40
8.2.3 Debug...........................................................................................................................................................41

9. Arm Debugger extension........................................................................................................................... 42

9.1 Run your project on your hardware........................................................................................................ 42
9.1.1 Configure a task........................................................................................................................................ 42
9.1.2 Override or extend the default tasks configuration options...........................................................42
9.1.3 Run your project....................................................................................................................................... 44
9.2 Debug your project with Arm Debugger................................................................................................44
9.2.1 Add configuration......................................................................................................................................45

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 6 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Contents

9.2.2 Override or extend the default launch configuration options........................................................45

9.2.3 Debug...........................................................................................................................................................46

10. Activate your license to use Arm tools................................................................................................ 48

11. Use CMSIS-Toolbox from the command line......................................................................................49

11.1 Add CMSIS-Toolbox to the system PATH........................................................................................... 49
11.2 Support for packs...................................................................................................................................... 49
11.2.1 Add public packs.................................................................................................................................... 50
11.2.2 Add private local packs.........................................................................................................................50
11.2.3 Add private remote packs.................................................................................................................... 51
11.2.4 Remove packs..........................................................................................................................................51

12. Known issues and troubleshooting....................................................................................................... 52

12.1 Known issues.............................................................................................................................................. 52
12.2 Troubleshooting.......................................................................................................................................... 52
12.2.1 Build fails to find toolchain.................................................................................................................. 52
12.2.2 Connected development board or debug probe not found......................................................... 53
12.2.3 Out-of-date firmware............................................................................................................................ 54

13. Submit feedback.........................................................................................................................................55

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 7 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Introduction

1. Introduction

1.1 Conventions
The following subsections describe conventions used in Arm documents.

Glossary
The Arm Glossary is a list of terms used in Arm documentation, together with definitions for
those terms. The Arm Glossary does not contain terms that are industry standard unless the Arm
meaning differs from the generally accepted meaning.

See the Arm Glossary for more information: developer.arm.com/glossary.

Typographic conventions
Arm documentation uses typographical conventions to convey specific meaning.

Convention Use
italic Citations.
bold Interface elements, such as menu names.

Terms in descriptive lists, where appropriate.

monospace Text that you can enter at the keyboard, such as commands, file and program names, and source code.
monospace underline A permitted abbreviation for a command or option. You can enter the underlined text instead of the full
command or option name.
<and> Encloses replaceable terms for assembler syntax where they appear in code or code fragments.

For example:

MRC p15, 0, <Rd>, <CRn>, <CRm>, <Opcode_2>

SMALL CAPITALS Terms that have specific technical meanings as defined in the Arm® Glossary. For example,
IMPLEMENTATION DEFINED, IMPLEMENTATION SPECIFIC, UNKNOWN, and UNPREDICTABLE.

Recommendations. Not following these recommendations might lead to system

failure or damage.

Requirements for the system. Not following these requirements might result in
system failure or damage.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 8 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Introduction

Requirements for the system. Not following these requirements will result in system
failure or damage.

An important piece of information that needs your attention.

A useful tip that might make it easier, better or faster to perform a task.

A reminder of something important that relates to the information you are reading.

1.2 Other information

See the Arm website for other relevant information.

• Arm® Developer.
• Arm® Documentation.
• Technical Support.
• Arm® Glossary.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 9 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Extension pack and extensions

2. Extension pack and extensions

The Keil® Studio Visual Studio Code extension pack, Keil Studio Pack, provides a comprehensive
software development environment for embedded systems and IoT software development on
Arm®-based microcontroller (MCU) devices.

You can install and use the extension pack with Visual Studio Code Desktop. An extension pack is a
set of related extensions that are installed together.

The pack contains the following extensions:

• Arm CMSIS csolution (Identifier: arm.cmsis-csolution): This extension provides support for
working with CMSIS solutions (csolution projects).
• Arm Device Manager (Identifier: arm.device-manager): This extension allows you to manage
hardware connections for Arm Cortex®-M based microcontrollers, development boards and
debug probes.
• Arm Embedded Debugger (Identifier: arm.embedded-debug): This extension allows you to run
and debug projects on Arm Cortex-M based microcontrollers, development boards and debug
probes implementing the Microsoft Debug Adapter Protocol (DAP).
• Arm Debugger (Identifier: arm.arm-debugger): This extension provides access to the Arm
Debugger engine for Visual Studio Code by implementing the Microsoft Debug Adapter
Protocol (DAP). Arm Debugger supports connections to physical targets, either through
external debug probes such as the Arm’s ULINK™ family of debug probes, or through on-board
low-cost debugging such as ST-Link or CMSIS-DAP based debug probes.
• Arm Environment Manager (Identifier: arm.environment-manager): This extension installs
the tools you specify in a manifest file in your environment. For example, Arm Compiler for
Embedded, CMSIS-Toolbox, CMake, and Ninja can be installed to work with CMSIS solutions.
• Arm Virtual Hardware (Identifier: arm.virtual-hardware): This extension allows you to manage
Arm Virtual Hardware and run embedded applications on them. An authentication token is
required to access the service. For more details on AVH, read the overview.

The Arm Virtual Hardware extension is experimental, and is not described in this
guide.

The extensions contained in the pack can be also installed and used individually. We however
recommend installing the Keil Studio Pack in Visual Studio Code Desktop to quickly set up your
environment and start working with an example. See the pack Readme for more details.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 10 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Extension pack and extensions

2.1 Keil Studio Pack pre-release

A pre-release of the Keil Studio Pack is also available and includes all the main extensions included
in the offical pack and Arm Debugger, instead of Arm Embedded Debugger. The pre-release also
includes the Memory Inspector and Peripheral Inspector extensions.

• Arm Debugger (Identifier: arm.arm-debugger): This extension provides access to the Arm
Debugger engine for Visual Studio Code by implementing the Microsoft Debug Adapter
Protocol (DAP). Arm Debugger supports connections to physical targets, either through
external debug probes such as the Arm’s ULINK™ family of debug probes, or through on-board
low-cost debugging such as ST-Link or CMSIS-DAP based debug probes.
• Memory Inspector (Identifier: eclipse-cdt.memory-inspector): This extension allows you to
analyze and monitor the memory contents in an embedded system. It helps you to identfiy and
debug memory-related issues during the development phase of your project.
• Peripheral Inspector (Identifier: eclipse-cdt.peripheral-inspector): This extension
uses System View Description (SVD) files to display peripheral details. SVD files provide
a standardized way to describe the memory-mapped registers and peripherals of a
microcontroller or a System-on-Chip (SoC).

See the pack Readme to install the pre-release.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 11 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Intended use cases for the extensions

3. Intended use cases for the extensions

Here are the intended use cases for the extensions:

• Embedded and IoT software development using CMSIS-Packs and csolution projects: The
“Common Microcontroller Software Interface Standard” (CMSIS) provides driver, peripheral
and middleware support for thousands of MCUs and hundreds of development boards. Using
the csolution project format, you can incorporate any CMSIS-Pack based device, board, and
software component into your application. For more information about supported hardware for
CMSIS projects, go to the Boards and Devices pages on keil.arm.com. For information about
CMSIS-Packs, go to open-cmsis-pack.org.
• Enhancement of a pre-existing Visual Studio Code embedded software development
workflow: USB device management and embedded debug can be adapted to other project
formats (for example CMake) and toolchains without additional overhead. This use case
requires familiarity with Visual Studio Code to configure tasks. See the individual extensions for
more details.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 12 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

4. Get started with an example project

Quickly set up your environment and start working with an example.

We recommend installing the Keil Studio Pack in Visual Studio Code Desktop as explained in the
Readme. The pack installs all the Keil® Studio extensions, including the Arm Environment Manager,
as well as the Red Hat YAML, Microsoft C/C++, and Microsoft C/C++ Themes extensions.

Then:
• Do the setup using the Blinky_FRDM-K32L3A6 csolution project available from keil.arm.com
(recommended).
• Download a Keil μVision *.uvprojx project from the website and convert it to a csolution
(alternative).

The examples available on keil.arm.com are shipped with a Microsoft vcpkg manifest file (vcpkg-
configuration.json). The Arm Environment Manager extension uses the manifest file to acquire
and activate the tools you need to work with csolution projects using Microsoft vcpkg.

Each example also comes with a tasks.json and launch.json to build, run, and debug the project.

The tools installed by default are:

• Arm® Compiler for Embedded.
• CMSIS-Toolbox.
• CMake and Ninja.

Finalize the setup of your development environment. If you do not want to use Microsoft C/C++
and Microsoft C/C++ Themes, you can install and set up the clangd extension instead to add smart
features to your editor.

When you are ready:

• Build the Blinky_FRDM-K32L3A6 example project.
• Explore what you can do with the CMSIS csolution extension: set a context, look at the
Solution outline, manage the software components of the solution.
• Connect your board and run the example on the board.
• Start a debug session.
• Check the serial output.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 13 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

4.1 Import the Blinky_FRDM-K32L3A6 example

Import the recommended csolution example in Visual Studio Code. Alternatively, you can download
a zip file that contains the csolution.

Procedure
1. Go to keil.arm.com.
2. Click the Hardware menu and select Boards.
3. Search for the FRDM-K32L3A6 board and click the Results box.
4. Find the Blinky project that is available in the Projects tab.
The Keil Studio compatibility label indicates that the example is compatible with Keil® Studio
Cloud and the Keil Studio Visual Studio Code extensions.
5. Hover over the Get Project button, then click Open in Keil Studio for VS Code to import the
csolution example.
6. Click the Open Visual Studio Code button in the “Open Visual Studio Code?” pop-up that
opens at the top of your browser window.
7. Click the Open button in the “Allow an extension to open this URI” pop-up that opens in Visual
Studio Code.
8. Choose a folder to import the project and click the Select as Unzip Destination button.
9. Click the Open button in the “Would you like to open the unzipped folder?” pop-up.
If there are missing CMSIS-Packs, a pop-up displays in the bottom right-hand corner with the
following message “Solution Blinky requires some packs that are not installed”.
10. Click Install.
You must activate a license to be able to use tools such as Arm® Compiler, Arm Debugger, or
Fixed Virtual Platforms in your toolchain. If you have not activated your license after installing
the pack, a pop-up displays in the bottom right-hand corner with the message “Activate license
for Arm tools?”. See Activate your license to use Arm tools for more details on licensing.
11.
Click the Explorer icon .
A vcpkg-configuration.json is available. The file records the vcpkg artifacts, such as the
compiler toolchain version, that you need to work with your projects. You do not need to do
anything to install the tools. Microsoft vcpkg and the Arm Environment Manager extension
take care of the setup. See Tools installation with Microsoft vcpkg.

A tasks.json and launch.json files are also available in the .vscode folder. Visual Studio Code
uses the tasks.json file to build and run the project, and the launch.json for debug.

4.2 Download and convert a Keil μVision example

Download a Keil® μVision® *.uvprojx project from keil.arm.com and convert it to a csolution.
Note that the conversion does not work with Arm® Compiler 5 projects. You can download Arm
Compiler 5 projects from the website, but you cannot use them with the extensions. Only Arm
Compiler 6 projects can be converted. As a workaround, you can update Arm Compiler 5 projects
to Arm Compiler 6 in Keil μVision, then convert the projects to csolutions in Visual Studio Code.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 14 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

Procedure
1. Go to keil.arm.com.
2. Connect your board over USB and click Detect Connected Hardware in the bottom right-hand
corner.
3. Select the device firmware for your board in the dialog box that displays at the top of the
window, then click Connect.
4. Click the Board link in the pop-up that displays in the bottom right-hand corner.
This takes you to the page for the board. Example projects are available in the Projects tab.
5. Look for an example with a μVision compatibility label.
6. Hover over the Get Project button for the project you want to use and click Download zip to
download the Keil μVision *.uvprojx example.
7. Unzip the example and open the folder in Visual Studio Code.
8. A pop-up displays in the bottom right-hand corner with the following message “Convert
μVision project [project-name].uvprojx to csolution?”.
9. Click Convert.
The conversion starts immediately.

Alternatively, you can right-click the *.uvprojx and select Convert μVision project to csolution
from the Explorer.

You can also run the CMSIS: Convert μVision project to csolution command from the
Command Palette. In that case, select the *.uvprojx that you want to convert on your machine
and click Select.
10. Check the OUTPUT tab (View > Output). Conversion messages are logged under the μVision
to Csolution Conversion category.
If there are missing CMSIS-Packs, a pop-up displays in the bottom right-hand corner with the
following message “Solution [solution-name] requires some packs that are not installed”.
11. Click Install.
You must activate a license to be able to use tools such as Arm® Compiler, Arm Debugger, or
Fixed Virtual Platforms in your toolchain. If you have not activated your license after installing
the pack, a pop-up displays in the bottom right-hand corner with the message “Activate license
for Arm tools?”. See Activate your license to use Arm tools for more details on licensing.
12.
Click the Explorer icon .
The *.cproject.yml and *.csolution.yml files are available next to the *.uvprojx.

A vcpkg-configuration.json file is available. The file records the vcpkg artifacts, such as the
compiler toolchain version, that you need to work with your projects. You do not need to do
anything to install the tools. Microsoft vcpkg and the Arm Environment Manager extension
take care of the setup. See Tools installation with Microsoft vcpkg.

A tasks.json and launch.json files are also available in the .vscode folder. Visual Studio Code
uses the tasks.json file to build and run the project, and the launch.json for debug.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 15 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

4.3 Finalize the setup of your development environment

To finalize the setup of your development environment:

• Configure an HTTP proxy. This step is only required if you are working behind an HTTP proxy.
• The pack installs all the Keil® Studio extensions as well as the Arm Environment Manager, Red
Hat YAML, Microsoft C/C++ and Microsoft C/C++ Themes extensions. If you do not want to
use the Microsoft C/C++ and Themes extensions, you can disable them in Visual Studio Code
and install and set up the clangd extension as an alternative.

4.3.1 Configure an HTTP proxy (optional)

This step is only required if you are working behind an HTTP proxy. The tools can be configured
using the following standard environment variables to use an HTTP proxy:

• HTTP_PROXY: Set to the proxy used for HTTP requests.

• HTTPS_PROXY: Set to the proxy used for HTTPS requests.
• NO_PROXY: Set to include at least localhost,127.0.0.1 to disable the proxy for internal traffic,
which is required for the extension to work correctly.

4.3.2 clangd (alternative)

Install the clangd extension. Similarly to the Microsoft C/C++ and Microsoft C/C++ Themes
extensions, clangd adds smart features such as code completion, compile errors, go-to-definition
and more to your editor.

The clangd extension requires the clangd language server. If the server is not found
on your PATH, add it with the clangd: Download language server command from
the Command Palette. Read the clangd extension Readme for more information.

There is no extra setup needed once clangd has been installed. The Arm CMSIS csolution
extension generates a compile_commands.json file for each project in a solution whenever a
csolution file changes or when you change the context of a solution (Target and Build types). A
.clangd file is kept up to date for each project in the solution. The .clangd file is used by the
clangd extension to locate the compile_commands.json files and enable IntelliSense. See the clangd
documentation for more details.

You can turn off the automatic generation of the .clangd file and compile_commands.json file.
1. Open the settings:
• On Windows or Linux, go to: File > Preferences > Settings.
• On macOS, go to: Code > Settings > Settings.
2. Find the Cmsis-csolution: Auto Generate Clangd File and Cmsis-csolution: Auto Generate
Compile Commands settings and clear their checkboxes.
Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 16 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

4.4 Build the example project

Check that your example project builds. You can build your project from the Explorer, using the
Build button, or from the Command Palette.

Procedure
1. Build the project:
• From the Explorer:
a.
Go to the Explorer view .
b. Right-click the *.csolution.yml file and select Build.

A Rebuild option is also available in the right-click menu. This option cleans output
directories before building the project.
• Using the Build button:
a.
Click the CMSIS icon in the Activity Bar.
b.
Click the Build button in the ACTIONS panel.

A Build (clean) option is also available when you click the arrow next to Build. Build
(clean) is the same as Rebuild in the right-click menu.

You can configure a build task in a tasks.json file to customise the behaviour of the build
button. A tasks.json is provided for all the examples available on keil.arm.com. See
Configure a build task for more details.
• From the Command Palette: Build and Rebuild can also be triggered from the Command
Palette with the CMSIS: Build and CMSIS: Rebuild commands.
2. Check the TERMINAL tab to find where the ELF file (.axf) was generated.

4.5 Set a context for your csolution

A context is the combination of a target type (build target) and build type (build configuration) for a
given project in your solution.

The Blinky_FRDM-K32L3A6 example has just one project and one target type FRDM-K32L3A6. You
can choose between Debug or Release for the build type.

Read Set a context for your csolution for more details.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 17 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

4.6 Look at the Solution outline

The SOLUTION outline presents the content of your solution in a tree view.

Read Use the Solution outline for more details.

4.7 Manage software components

The Software Components view shows all the software components selected in the active project
of your solution.

Read Manage software components for more details.

4.8 Connect your board

Connect your board. See Supported hardware for more details on the development boards, MCUs,
and debug probes supported by the extensions.

Procedure
1.
Click the Device Manager icon in the Activity Bar to open the Arm Device Manager
extension.
2. Connect your board to your computer over USB. In our example we use the FRDM-K32L3A6
board from NXP.

The board is detected and a pop-up message displays.

3. Click OK in the pop-up message to use the hardware.

Your board is now ready to be used to run and debug a project.

4.9 Run the csolution on your board

Run the csolution project on your board.

Procedure
1.
Click the CMSIS icon in the Activity Bar.
2.
Click the Run button in the ACTIONS panel.
You can configure a run task in a tasks.json file to customise the behaviour of the run button. A
tasks.json is provided for all the examples available on keil.arm.com. See Run your project on
your hardware for more details.
3. As we are using a FRDM-K32L3A6 board, a device with multiple cores, you must select the
appropriate processor for your project in the Select a processor drop-down list that displays at
the top of the window. Select cm4.
Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 18 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Get started with an example project

The project is run on the board.

4. Check the TERMINAL tab.

4.10 Start a debug session

Start a debug session.

Procedure
1.
Click the CMSIS icon in the Activity Bar.
2.
Click the Debug button in the ACTIONS panel.
You can configure a launch configuration in a launch.json file to customise the behaviour of the
debug button. A launch.json is provided for all the examples available on keil.arm.com. See
Debug your project with Arm Embedded Debugger or Debug your project with Arm Debugger
for more details.
3. Select the appropriate processor for your project in the Select a processor drop-down list that
displays at the top of the window. Select cm4.
The RUN AND DEBUG view displays and the debug session starts. The debugger stops at the
function “main” of your project.
4. Check the DEBUG CONSOLE tab to see the debugging output.

Next steps
Look at the Visual Studio Code documentation to learn more about the debugging features
available in Visual Studio Code.

4.11 Check the serial output of your board

The serial output shows the output of your board. The serial output can be used as a debugging
tool or to communicate directly with your board.

Procedure
1.
Click the CMSIS icon in the Activity Bar.
2.
Click the Open Serial button in the ACTIONS panel.
3. Select a baud rate of 115200 for your FRDM-K32L3A6 board in the drop-down list that opens
at the top of the window. The baud rate you select must be the same as the baud rate of the
project.
The serial output displays in the TERMINAL tab.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 19 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Environment Manager extension

5. Arm Environment Manager extension

The Arm Environment Manager extension allows you to manage environment artifacts, such as a
compiler toolchain, using Microsoft vcpkg. The extension uses a vcpkg manifest file to acquire and
activate the artifacts you need to set up your development environment.

The artifacts for your project are stored in the vcpkg-configuration.json file in the project source
code. This means that the same tools are available to everyone using the project.

5.1 Tools installation with Microsoft vcpkg

Arm uses Microsoft vcpkg to set up your environment. Microsoft vcpkg works in combination with
the Arm Environment Manager extension installed with the pack for the setup.

Each official Arm example project is shipped with a manifest file (vcpkg-configuration.json). The
manifest file records the vcpkg artifacts that you need to work with your projects. An artifact is a
set of packages required for a working development environment. Examples of relevant packages
include compilers, linkers, debuggers, build systems, and platform SDKs.

For more information on vcpkg, see the official Microsoft vcpkg documentation. See also the
Microsoft vcpkg-tool repository for more details on artifacts.

5.2 Check the tools installed with Microsoft vcpkg

The vcpkg-configuration.json manifest file instructs Microsoft vcpkg to install the artifacts. If you
open the manifest file, you can see for example:

"requires": {
"arm:tools/open-cmsis-pack/cmsis-toolbox": "^2.0.0-0",
"arm:compilers/arm/armclang": "^6.20.0",
"microsoft:tools/kitware/cmake": "^3.25.2",
"microsoft:tools/ninja-build/ninja": "^1.10.2"
}

The artifacts installed with this example manifest file are cmsis-toolbox, armclang (Arm Compiler for
Embedded), cmake and ninja.

Go to the OUTPUT tab (View > Output) and select the vcpkg category in the drop-down list to
see what has been installed. By default, Microsoft vcpkg installs the tools in the Visual Studio Code
application directory.

After Microsoft vcpkg has been activated for a project, any terminal that you open in Visual Studio
Code has all the tools added to the PATH by default (Arm Compiler for Embedded, CMSIS-Toolbox,
CMake and Ninja). This allows you to run the different CMSIS-Toolbox tools such as: cpackget,
cbuildgen, cbuild, or csolution.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 20 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Environment Manager extension

5.3 Modify the manifest file

You can add or change tools in your environment by modifying the artifacts contained in the
manifest file of your project.

The artifacts provided by Arm are listed on the Arm tools available in vcpkg page on keil.arm.com.

Simply copy the code snippets for the artifacts you want to install and paste them in the vcpkg-
configuration.json manifest file of your project in the "requires": section, then save the file.
The newly added or updated artifacts are automatically downloaded and activated.

5.4 vcpkg activation options

Several options are available to activate, deactivate, or reactivate your environment with Microsoft
vcpkg and update your vcpkg registries. If you are using an example from keil.arm.com or if
you created a csolution project from scratch from the Create New CMSIS Solution view, your
environment is activated by default.

Procedure
1. From the Explorer, open your workspace.
2. Right-click the vcpkg-configuration.json file.
Depending on the activation status of your environment and the Environment Manager
settings selected, the following options are available:
• Activate environment: Activate the environment. This option is available only if you
previously deactivated your environment or if you modified the Activate On Config
Creation or Activate On Workspace Open settings for the Environment Manager. Tools
are available on the PATH.
• Deactivate environment: Deactivate the active environment. Tools are also removed from
the PATH.
• Reactivate environment: Deactivate and activate the environment (for example, if you have
changed your vcpkg configuration).
• Update vcpkg registries: Check for fresh artifacts published in the registries.

5.5 Use vcpkg from the command line

You can also use vcpkg from the command line to create reproducible tool installations.

Information about vcpkg is available at vcpkg.io and at Microsoft Learn.

The Arm Developer Learning Paths also have an example scenario that shows you how to install
and initialize vcpkg, and how to create and use the configuration file. See Install tools on the
command line using vcpkg.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 21 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

6. Arm CMSIS csolution extension

The Arm CMSIS csolution extension provides support for working with CMSIS solutions (csolution
projects). The extension manages the information needed to create your csolution projects.

With the CMSIS csolution extension, you can:

• Set a context for your csolution.
• Use the Solution outline.
• Manage software components.

You can also:

• Install missing CMSIS-Packs.
• Configure a build task.
• Convert a Keil μVision project to a csolution project.
• Create a csolution project from scratch.

6.1 Set a context for your csolution

Look at your csolution contexts. A context is the combination of a target type and build type for a
given project in your solution.

Procedure
1.
Click the CMSIS icon in the Activity Bar to open the CMSIS view.
2. Look at the available contexts for the csolution in the CONTEXT panel. You can change the
target type (build target) and build configuration.
• Active Solution: The name of the active csolution, Blinky (Blinky.csolution.yml).
• Target Type: The build target FRDM-K32L3A6. Note that for this example you can only select
FRDM-K32L3A6. Some examples are compatible with Arm® Virtual Hardware (AVH) targets as
well, so you can have more options in the drop-down list in that case. For more details on
AVH, read the overview.
• Build Type: The build configuration Debug or Release. A build configuration adds the
flexibility to configure each target type towards a specific testing. Use Debug for a full debug
build of the software for interactive debug, or Release for the final code deployment to the
systems. Note that you can create your own build types as required by your application.
• Project: The name of the cproject, FRDM-K32L3A6 (FRDM-K32L3A6.cproject.yml). If you have
multiple projects in your solution, you can select the active one here.
3.
Click the Explorer icon
and open the Blinky.csolution.yml and FRDM-
files. YAML syntax support helps you with editing.
K32L3A6.cproject.yml
4. Go to the PROBLEMS tab and check for errors.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 22 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

5. Open the main.c file and check the IntelliSense features available. Read the Visual Studio Code
documentation on IntelliSense to find out about the different features.

Next steps
A *.cprj file is generated automatically for the context selected in the CONTEXT panel each time
you update the *.csolution.yml file.

You can turn off the automatic generation of cprj files. Note that this step is optional.
1. Open the settings:
• On Windows or Linux, go to: File > Preferences > Settings.
• On macOS, go to: Code > Settings > Settings.
2. Find the Cmsis-csolution: Auto Generate Cprj setting and clear its checkbox.

6.2 Use the Solution outline

The SOLUTION outline presents the content of your solution in a tree view.

Click the CMSIS icon in the Activity Bar to open the CMSIS view. The SOLUTION outline
displays under the CONTEXT and ACTIONS panels.

The SOLUTION outline shows the cprojects included in the solution. Each cproject file contains
configuration settings, source code files, build settings, and other project-specific information. The
extension uses these to manage and build a software project for a given board or device.

Details that can be included for a given cproject are:

• Groups: Groups are a way to structure code files into logical blocks.
• Components: All the software components selected for the cproject. Components are sorted by
component class (Cclass). Code files, user code templates, and APIs from selected components
display under their parent components. You can click the files, templates, or APIs to open them
in the editor.
• Layers: The clayer file, *.clayer.yml, defines the software layers for the cproject. A software
layer is a set of source files, pre-configured software components and configuration files. The
clayer file can be used by multiple projects. The software components used by each layer in the
cproject appear in the tree view.

When you hover over the SOLUTION label, you can choose one of the following actions:
•
Create a solution: Click the Create a solution icon to create a csolution project from
scratch. Note that the Create New CMSIS Solution view is still under development. To get
access to it, go to the settings, search for Cmsis-csolution: Experimental Features (in the
Extensions > CMSIS csolution category) and enable it.
•
Manage software components: Click the Manage software components icon to open the
Software Components view.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 23 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

•
Open csolution file: Click the Open csolution file icon to open the main csolution.yml file.
•
Collapse All: Click the Collapse All icon to close all the entries in the outline.

When you hover over a project, you can click the Open file icon to open the corresponding
cproject.yml file. An Open file icon is also available for each layer.

Press Ctrl+F (Windows) or Cmd+F (macOS) to look for an element in the SOLUTION outline.

The *.csolution.yml, *.cproject.yml, and *.clayer.yml file formats are described in the Open-
CMSIS-Pack documentation.

6.3 Manage software components

The Software Components view shows all the software components selected in the active project
of a CMSIS solution.

From this view you can see all the component details called attributes in the Open-CMSIS-Pack
documentation.

You can also:

• Modify the software components to include in the project and manage the dependencies
between components for each target type defined in your solution, or for all the target types at
once.
• Build the solution using different combinations of pack and component versions, and different
versions of a toolchain.

6.3.1 Open the Software Components view

Describes how to open the Software Components view.

Procedure
1.
Click the CMSIS icon in the Activity Bar to open the Arm CMSIS csolution extension.
2. Hover over the SOLUTION outline under the CONTEXT and ACTIONS panels, then click the
Manage software components icon .

Results
The Software Components view opens.

The default view displays the components included in the active project only (Selected toggle
button). If you click the All toggle button, all the components available for use display.

You can use the Search field to search the list of components.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 24 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

With the Target drop-down list, you can select components for the different target types you have
in your solution or for all the target types at once.

Figure 6-1: The ‘Software Components’ view showing all the components that are available for
use

The CMSIS-Pack specification states that each software component should have the following
attributes:
• Component class (Cclass): A top-level component name. For example: CMSIS.
• Component group (Cgroup): A component group name. For example: CORE for the CMSIS
component class.
• Component version (Cversion): The version number of the software component.

Optionally, a software component might have these additional attributes:

• Component sub-group (Csub): A component sub-group that is used when multiple compatible
implementations of a component are available. For example: Keil RTX5 under CMSIS > RTOS2.
• Component variant (Cvariant): A variant of the software component is typically used when the
same implementation has multiple top-level configurations, like Source for Keil RTX5.
• Component vendor (Cvendor): The supplier of the software component. For example: ARM.
• Bundle (Cbundle): Allows you to combine multiple software components into a software
bundle. Bundles have a different set of components available. All the components in a bundle
are compatible with each other but not with the components of another bundle. For example:
ARM Compiler for the Compiler component class.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 25 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

Layer icons indicate which components are used in layers. In the current version, layers are
read-only so you cannot select or clear them from the Software Components view. Click the layer
icon of a component to open the *.clayer.yml file or files associated.

Documentation links are available for some components at the class, group, or sub-group level.
Click the book icon of a component to open the related documentation.

6.3.2 Modify the software components in your project

You can add components from all the packs available. It is not limited to the packs that are already
selected for a given project.

Procedure
1. Click the All toggle button to display all the components available.
2. Select a specific target type in the Target drop-down list or, if you want to modify all the target
types at once, select All Targets. For the Blinky_FRDM-K32L3A6 example, there is just one
target.
3. Use the checkboxes to select or clear components as required. For some components, you can
also select a vendor, variant, or version.
The cproject.yml file is automatically updated.
4. Manage the dependencies between components and solve validation issues from the
Validation panel.

Issues are highlighted in red and have an exclamation mark icon next to them. You can
remove conflicting components from your selection or add missing component dependencies
from a suggested list.
5. If there are validation issues, hover over the issues in the Validation panel to get more details.
You can click the proposed fixes to find the components in the list. In some cases, you may
have to choose between different fix sets. Select a fix set in the drop-down list, make the
required component choices, and then click Apply.
If a pack is missing in the solution, a message “Component’s pack is not included in your
solution” displays in the Validation panel. An error also displays in the PROBLEMS view. See
Install missing CMSIS-Packs to know how to install CMSIS-Packs.

There can be other cases such as:

• A component you selected is incompatible with the selected hardware and toolchain.
• A component you selected has dependencies which are incompatible with the selected
hardware and toolchain.
• A component you selected has unresolvable dependencies. In such cases, you must remove
the component. Click Apply from the Validation panel.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 26 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

6.3.3 Undo changes

In the current version, you can undo changes from the Source Control view or by directly editing
the cproject.yml file.

6.4 CMSIS-Packs
CMSIS-Packs offer you a quick and easy way to create, build and debug embedded software
applications for Cortex®-M devices.

CMSIS-Packs are a delivery mechanism for software components, device parameters, and board
support. A CMSIS-Pack is a file collection that might include:
• Source code, header files, software libraries - for example RTOS, DSP and generic middleware.
• Device parameters, such as the memory layout or debug settings, along with startup code and
Flash programming algorithms.
• Board support, such as drivers, board parameters, and descriptions for debug connections.
• Documentation and source code templates.
• Example projects that show you how to assemble components into complete working systems.

CMSIS-Packs are developed by various silicon and software vendors, covering thousands of
different boards and devices. You can also use them to enable life-cycle management of in-house
software components.

See the Open-CMSIS-Pack documentation for more details.

CMSIS-Packs are available for download from keil.arm.com.

6.5 Install missing CMSIS-Packs

Install the missing CMSIS-Packs for your csolution.

Procedure
1.
Open the *.csolution.yml file for your csolution project from the Explorer view .
The required packs are listed under the packs key of the csolution.yml file. If one or several
CMSIS-Packs are missing, errors display in the PROBLEMS view and a pop-up displays in the
bottom right-hand corner with the following message “Solution [solution-name] requires some
packs that are not installed”.
2. Click Install.
Alternatively, right-click the error in the PROBLEMS view and select the Install missing pack
option. If there are several packs missing, use Install all missing packs.

You can also install missing packs with the CMSIS: Install required packs for active solution
command from the Command Palette.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 27 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

6.6 Configure a build task

In Visual Studio Code, you can automate certain tasks by configuring a file called tasks.json. See
Integrate with External Tools via Tasks for more details.

With the Arm CMSIS csolution extension, you can configure a build task using the tasks.json
file to build your projects. When you run the build task, the extension executes cbuild with the
options you defined.

As mentioned in Get started with an example project, the examples provided

on keil.arm.com are shipped with a tasks.json file that already contains some
configuration to build your project. You can modify the default configuration if
needed.

If you are working with an example for which no build task has been configured yet, follow the
steps below:
1. Go to Terminal > Configure Tasks….
2. In the drop-down list that opens at the top of the window, select the CMSIS Build task.

A tasks.json file opens with the default configuration.

{
"tasks": [
{
"label": "CMSIS Build",
"type": "cmsis-csolution.build",
"solution": "${command:cmsis-csolution.getSolutionPath}",
"project": "${command:cmsis-csolution.getProjectPath}",
"buildType": "${command:cmsis-csolution.getBuildType}",
"targetType": "${command:cmsis-csolution.getTargetType}",
"problemMatcher": [],
"group": {
"kind": "build",
"isDefault": true
}
}
]
}

3. Modify the configuration.

With IntelliSense, you can see the full set of task properties and values available in the
tasks.json file. You can bring up suggestions using Trigger Suggest from the Command
Palette. You can also display the task properties specific to cbuild by typing cbuild --help in
the terminal.
4. Save the tasks.json file.

Alternatively, you can define a default build task using Terminal > Configure Default Build Task….
The Terminal > Run Build Task… option triggers the execution of default build tasks.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 28 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

6.7 Convert a Keil μVision project to a csolution project

You can convert any Keil® μVision® project to a csolution project from the Arm CMSIS csolution
extension. Note that the conversion does not work with Arm® Compiler 5 projects. You can
download Arm Compiler 5 projects from the website, but you cannot use them with the
extensions. Only Arm Compiler 6 projects can be converted. As a workaround, you can update Arm
Compiler 5 projects to Arm Compiler 6 in Keil μVision, then convert the projects to csolutions in
Visual Studio Code.

Procedure
1. Open the project that contains the *.uvprojx you want to convert in Visual Studio Code.
2. A pop-up displays in the bottom right-hand corner with the following message “Convert
μVision project [project-name].uvprojx to csolution?”.
3. Click Convert.
The conversion starts immediately.

Alternatively, you can right-click the *.uvprojx and select Convert μVision project to csolution
from the Explorer.

You can also run the CMSIS: Convert μVision project to csolution command from the
Command Palette. In that case, select the *.uvprojx that you want to convert on your machine
and click Select.
4. Check the OUTPUT tab (View > Output). Conversion messages are logged under the μVision
to Csolution Conversion category.
The *.cproject.yml and *.csolution.yml files are available in the folder where the *.uvprojx
is stored.

6.8 Create a csolution project

Create a csolution project from scratch.

Before you begin

The Create New CMSIS Solution view is still under development. To get access to it, go to the
settings, search for Cmsis-csolution: Experimental Features (in the Extensions > CMSIS csolution
category) and enable it.

Procedure
1.
Click the CMSIS icon in the Activity Bar to open the Arm CMSIS csolution extension.
2. Hover over the SOLUTION outline under the CONTEXT and ACTIONS panels, then click the
Create a solution icon .

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 29 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

Figure 6-2: Create a solution icon

The Create New CMSIS Solution view opens.

3. Click the Target drop-down list and search, then select a board or a device from the Boards or
Devices lists available.
A hardware picker shows you the details of the board or device you selected.

.
4. Click Select.
You can create a blank solution or a TrustZone solution. TrustZone is a hardware-based security
feature that provides a secure execution environment on Arm-based processors. It allows the
isolation of secure and non-secure zones, enabling the secure processing of sensitive data and
applications. If the board or device you selected is compatible, you can decide if your solution
should use the TrustZone technology and define which project in the solution should use
secure or non-secure zones.
5. From the Template drop-down list, select Blank solution or TrustZone solution.
6. Type a name for your solution in the Solution Name field.
7. Configure the projects in your solution:

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 30 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

• If you selected Blank solution: One project is added for each processor in the target
hardware. Project Name and Core are filled in based on the board or device selected in the
Target drop-down list. You can change the project names. You can decide to add secure or
non-secure zones with the TrustZone drop-down list. By default, TrustZone is off.

• If you selected TrustZone solution: A secure and a non-secure projects are added for each
processor in the target hardware that supports TrustZone. The Project Name field and Core
and TrustZone drop-down lists are filled in based on the board or device selected in the
Target drop-down list. You can change the project names. You can also change the zones,
secure or non-secure in the TrustZone drop-down list, or remove TrustZone by selecting
off.
8. Click Add Project to add projects to your solution and configure them. For TrustZone, you can
add as many secure or non-secure projects as you need for a given processor.
9. Select a compiler: Arm Compiler 6, GCC, or LLVM.
10. Click Browse next to the Location field to choose where to store the files of the solution.
If you already have a workspace opened, by default the extension creates the files in the folder
of the current workspace. To store the files in a different folder, use the system dialog box that
opens to create and select a new folder.
11. Check the default options:
• Initialize Git repo: The extension initializes the solution as a Git repository. Clear the
checkbox if you do not want to turn your solution into a Git repository.
• Install required Packs: The extension automatically installs the CMSIS-Packs required by
the newly created solution.
12. Click Create.
A dialog box displays. You can:
• Open the solution in a new workspace (Open option)
• Open the solution in a new window and new workspace (Open project in new window
option)
• Add the solution to the current workspace (Add project to vscode workspace option)
13. Select one of the options.
The extension creates the solution.
14.
Click the Explorer icon in the Activity Bar to check that the files for the solution have been
created.
• A <solution_name>.csolution.yml file.
• One or more <project_name>.cproject.yml files, each available in a separate folder.
• A main.c template file for each project.

Next steps
Explore the autocomplete feature available to edit the csolution.yml and cproject.yml files. Read
the CMSIS-Toolbox > Build Overview documentation for project examples.

Add CMSIS components with the Software Components view. When you add components, the
cproject.yml files are updated.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 31 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm CMSIS csolution extension

6.9 Initialize your csolution project

If you have a csolution project that does not already contain a vcpkg-configuration.json, a
tasks.json, and a launch.json, you can use the Initialize CMSIS project option to generate these
files and start working with your project. Examples from keil.arm.com or csolution projects created
from scratch from the Create New CMSIS Solution view already contain the json files required.

Procedure
1. From the Explorer, open your workspace.
2. Right-click anywhere in the workspace and select Initialize CMSIS project.
The extension generates a vcpkg-configuration.json, a tasks.json, and a launch.json that
are already pre-configured.

6.10 Use the CMSIS csolution API

If you want to author and create your own Visual Studio Code csolution extension, the CMSIS
csolution extension exposes an API that other extensions can use.

For the API specification, see the CMSIS csolution extension API page.

For information about authoring extensions, see the Extension API chapter in the Visual Studio
Code documentation.

For csolution examples, go to keil.arm.com.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 32 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Device Manager extension

7. Arm Device Manager extension

Look at the hardware supported with the Keil® Studio extensions.

Then, manage your hardware with the Device Manager extension:

• Connect your hardware.
• Edit your hardware.
• Open a serial monitor.

7.1 Supported hardware

Describes the hardware that the Device Manager extension and other Keil® Studio extensions
support.

7.1.1 Supported development boards and MCUs

The extensions support the development boards and MCUs available on keil.arm.com.

7.1.2 Supported debug probes

Here are the supported debug probes.

7.1.2.1 WebUSB-enabled CMSIS-DAP debug probes

The extensions support debug probes that implement the CMSIS-DAP protocol. See the CMSIS-
DAP documentation for general information.

Such implementations are for example:

• The DAPLink implementation: see the ARMmbed/DAPLink repository.
• The LPC-Link2 implementation: see the LPC-Link2 documentation.
• The Nu-Link2 implementation: see the Nuvoton repository.
• The ULINKplus™ (firmware version 2) implementation: see the Keil MDK documentation.

7.1.2.2 ST-LINK debug probes

The extensions support ST-LINK/V2 probes and later, and the ST-LINK firmware available for these
probes.

The recommended debug implementation versions of the ST-LINK firmware are:

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 33 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Device Manager extension

• For ST-LINK/V2 and ST-LINK/V2-1 probes: J36 and later.

• For STLINK-V3 probes: J6 and later.

See “Firmware naming rules” in Overview of ST-LINK derivatives for more details on naming
conventions.

7.2 Connect your hardware

Describes how to connect your hardware for the first time.

Procedure
1.
Click the Device Manager icon in the Activity Bar to open the extension.
2. Connect your hardware to your computer over USB.
The hardware is detected and a pop-up displays in the bottom right-hand corner.
3. Click OK to use the hardware.
Alternatively, you can click the Add Device button and select
your hardware in the drop-down list that displays at the top of the window.

Your hardware is now ready to be used to run and debug a project.

Next steps
If you need to add more hardware, click the Add Device icon in the top right-hand corner.

7.3 Edit your hardware

If your board cannot be detected or if you are using an external debug probe, you can edit the
hardware entry from the Device Manager and specify a Device Family Pack (DFP) and a device
name retrieved from the pack to be able to work with your hardware. DFPs handle device support.

Procedure
1.
Hover over the hardware you want to edit and click the Edit Device icon .
2. Edit the hardware name in the field that displays at the top of the window if needed and press
Enter. This is the name that displays in the Device Manager.
3. Select a Device Family Pack (DFP) CMSIS-Pack for your hardware in the drop-down list.
4. Select a device name to use from the CMSIS-Pack in the field and press Enter.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 34 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Device Manager extension

7.4 Open a serial monitor

Open a serial monitor.

Procedure
1. Hover over the hardware for which you want to open a serial monitor and click the Open Serial
icon .
A drop-down list displays at the top of the window where you can select a baud rate (the data
rate in bits per second between your computer and your hardware). To view the output of your
hardware correctly, you must select an appropriate baud rate. The baud rate you select must be
the same as the baud rate of your active project.
2. Select a baud rate.
A Terminal tab opens with the baud rate selected.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 35 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

8. Arm Embedded Debugger extension

Run a project on your hardware and start a debug session with the Embedded Debugger
extension:

• Run your project on your hardware.

• Debug your project with Arm Embedded Debugger.

As mentioned in Get started with an example project, the examples provided on

keil.arm.com are shipped with a tasks.json and a launch.json files that already
contain some configuration to run your project and undertake debugging. You can
modify the default configuration if needed.

8.1 Run your project on your hardware

Find out how to configure a task to run your project on your hardware and what the configuration
options are.

8.1.1 Configure a task

You must first configure a task to be able to run a project on your hardware. The task transfers the
binary into the appropriate memory locations on the hardware’s flash memory.

There are two tasks available:

• Flash Device: Use this task for CMSIS-DAP (such as LPC-Link2, Nu-Link2, and ULINKplus™)
and ST-Link hardware. The CMSIS-Packs used in your project control the flash download.
• Flash Device (DAPLink): Use this task for DAPLink hardware. The DAPLink firmware takes care
of the flash download.

Procedure
1. Open the Command Palette and search for Tasks: Configure Task then select it.
2. Select the embedded-debug.flash:Flash Device task or the embedded-debug.daplink-
flash:Flash Device (DAPLink) task.

This adds the following lines in the tasks.json file that is stored in the .vscode folder of the
project.

Default configuration for Flash Device:

{
"label": "Flash Device",
"type": "embedded-debug.flash",
"program": "${command:embedded-debug.getApplicationFile}",

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 36 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "${command:device-manager.getDevicePack}",
"problemMatcher": [],
"dependsOn": "CMSIS Build"
}

Default configuration for Flash Device (DAPLink):

{
"type": "embedded-debug.daplink-flash",
"serialNumber": "${command:device-manager.getSerialNumber}",
"program": "${command:embedded-debug.getBinaryFile}",
"problemMatcher": [],
"label": "embedded-debug.daplink-flash: Flash Device (DAPLink)"
}

3. Save the tasks.json file.

8.1.2 Override or extend the default tasks configuration options

You can override or extend the default configuration options. See the Flash configuration options
for CMSIS-DAP and ST-Link hardware (Flash Device) and Flash configuration options for DAPLink
hardware (Flash Device DAPLink).

If you are using a Flash Device task, then in order to flash a hardware, the task configuration must
know which CMSIS-Pack to read information from and the device name in the CMSIS-Pack to use.
These are named as cmsisPack and deviceName and you can specify them in multiple ways.

If your target hardware is automatically detected, or if the pack and device name have been set for
it, the task configuration can automatically pick this up by using:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "${command:device-manager.getDevicePack}",
"deviceName": "${command:device-manager.getDeviceName}",
[...]
}

Alternatively, these can be specified directly as a full path to the CMSIS-Pack file or a folder on
your machine:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "/Users/me/mypack.pack",
"deviceName": "STM32H745XIHx",
[...]
}

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 37 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

You can also use the short code for the CMSIS-Pack in the form <vendor>::<pack>@<version>.
Note that this triggers an automatic download of the CMSIS-Pack:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "Keil::[email protected]",
"deviceName": "STM32H745XIHx",
[...]
}

8.1.2.1 Flash configuration options for CMSIS-DAP and ST-Link hardware (Flash
Device)
The extension provides the task options below. Other Visual Studio Code options are also available.
Use the Trigger Suggestions command (Ctrl+Space) to see what is available and read the Visual
Studio Code documentation on tasks, as well as the Schema for tasks.json page.

Configuration option Description

"cmsisPack" Path (file or URL) to a DFP (Device Family Pack) CMSIS-Pack for your hardware. Command available:
device-manager.getDevicePack - Gets the CMSIS-Pack for the selected device.
"connectMode" Connection mode. Possible values: auto (debugger decides), haltOnConnect (halts for any reset before
running), underReset (holds external NRST line asserted), preReset (pre-reset using NRST), running
(connects to running target without altering state). Default: auto.
"dbgconf" Path (file or URL) to a debug configuration file (dbgconf) file.
"deviceName" CMSIS-Pack device name. Command available: device-manager.getDeviceName - Gets the device
name from the DFP (Device Family Pack) of the selected device.
"eraseMode" Type of flash erase to use. Possible values: sectors (erase only sectors to be programmed), full (erase full
chip), none (skip flash erase). Default: sectors.
"flm" or "flms" Path(s) (file or URL) to an FLM file or FLM files.
"openSerial" Baud rate for connected device. Opens the serial output of the device in the TERMINAL tab with the baud
rate specified.
"pdsc" Path (file or URL) to a PDSC file.
"processorName" CMSIS-Pack processor name for multi-core devices.
"program" or Path(s) (file or URL) to the project(s) to use. Command available: embedded-debug.getApplicationFile
"programs" - Returns an AXF or ELF file used for CMSIS run and debug.
"programFlash" Program code into flash. Default: true.
"programMode" Mode to program an application to a target. Default: auto.
"resetAfterConnect" Resets the hardware after having acquired control of the CPU. Default: true.
"resetMode" Type of reset to use. Possible values: auto (debugger decides), system (use ResetSystem sequence),
hardware (use ResetHardware sequence), processor (use ResetProcessor sequence). Default: auto.
"resetRun" Issue a hardware reset at end of flash download. Default: true.
"sdf" Path (file or URL) to an SDF file.
"serialNumber" Serial number of the connected USB hardware to use. Command available: device-
manager.getSerialNumber - Gets the serial number of the selected device.
"targetAddress" Synonymous with serialNumber.
"vendorName" CMSIS-Pack vendor name.
"verifyFlash" Verify the contents downloaded to flash. Default: true.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 38 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

8.1.2.2 Flash configuration options for DAPLink hardware (Flash Device DAPLink)
The extension provides the task options below. Other Visual Studio Code options are also available.
Use the Trigger Suggestions command (Ctrl+Space) to see what is available and read the Visual
Studio Code documentation on tasks, as well as the Schema for tasks.json page.

Configuration Description
option
"openSerial" Baud rate for connected device. Opens the serial output of the device in the TERMINAL tab with the baud rate
specified.
"program" Path(s) (file or URL) to the project(s) to use. Command available: embedded-debug.getBinaryFile - Returns a
BIN or HEX file.
"serialNumber" Serial number of the connected USB hardware to use. Command available: device-manager.getSerialNumber
- Gets the serial number of the selected device.

8.1.3 Run your project

Run the project on your hardware.

Procedure
1. Check that your hardware is connected to your computer.
2. Open the Command Palette and search for Tasks: Run Task then select it.
3. Select the embedded-debug.flash:Flash Device task or the embedded-debug.daplink-
flash:Flash Device (DAPLink) task in the drop-down list.
If you have installed the Keil Studio Pack, you can alternatively go to the CMSIS view and click
the Run button in the ACTIONS panel.
4. If you are using a device with multiple cores, you must select the appropriate processor for your
project in the Select a processor drop-down list that displays at the top of the window.
5. Check the Terminal tab to verify that the project has run correctly.

8.2 Debug your project with Arm Embedded Debugger

Debug a project.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 39 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

8.2.1 Add configuration

As for running a project, you must first add a launch configuration to be able to do debugging.
Creating a launch configuration file allows you to configure and save debugging setup details.
Visual Studio Code keeps debugging configuration information in a launch.json file.

Procedure
1. Open the launch.json file that is stored in the .vscode folder of your project and add the
following lines inside "configurations":[ ]:
{
"configurations": [
{
"name": "Embedded Debug",
"type": "embedded-debug",
"request": "launch",
"serialNumber": "${command:device-manager.getSerialNumber}",
"program": "${command:embedded-debug.getApplicationFile}",
"cmsisPack": "${command:device-manager.getDevicePack}",
"debugFrom": "main"
}
]
}

2. Save the launch.json file.

8.2.2 Override or extend the default launch configuration options

You can override or extend the default configuration options as required. See Debug configuration
options for more details.

See also the details provided for the tasks.json file for cmsisPack and deviceName. In order to debug
a hardware, the launch configuration must know which CMSIS-Pack to read information from and
the device name in the CMSIS-Pack to use.

8.2.2.1 Debug configuration options

The extension provides the task options below. Other Visual Studio Code options are also available.
Use the Trigger Suggestions command (Ctrl+Space) to see what is available and read the Visual
Studio Code documentation on tasks.

Configuration option Description

"cmsisPack" Path (file or URL) to a DFP (Device Family Pack) CMSIS-Pack for your hardware. Command available:
device-manager.getDevicePack - Gets the CMSIS-Pack for the selected device.
"connectMode" Connection mode. Possible values: auto (debugger decides), haltOnConnect (halts for any reset before
running), underReset (holds external NRST line asserted), preReset (pre-reset using NRST), running
(connects to running target without altering state). Default: auto.
"dbgconf" Path (file or URL) to a debug configuration file (dbgconf) file.
"debugFrom" The symbol the debugger will run to before debugging. Default: "main".
"deviceName" CMSIS-Pack device name. Command available: device-manager.getDeviceName - Gets the device
name from the DFP (Device Family Pack) of the selected device.
"pathMapping" A mapping of remote paths to local paths to resolve source files.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 40 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Embedded Debugger extension

Configuration option Description

"pdsc" Path (file or URL) to a PDSC file.
"processorName" CMSIS-Pack processor name for multi-core devices.
"program" or Path(s) (file or URL) to the project(s) to use. Commands available: embedded-debug.getBinaryFile:
"programs" Returns a BIN or HEX file. embedded-debug.getApplicationFile: Returns an AXF or ELF file used for
CMSIS run and debug.
"programNames" Filename or filenames of the projects to be used. Only used for labelling.
"resetAfterConnect" Resets the hardware after having acquired control of the CPU. Default: true.
"resetMode" Type of reset to use. Possible values: auto (debugger decides), system (use ResetSystem sequence),
hardware (use ResetHardware sequence), processor (use ResetProcessor sequence). Default: auto.
"sdf" Path (file or URL) to an SDF file.
"serialNumber" Serial number of the connected USB hardware to use. Command available: device-
manager.getSerialNumber - Gets the serial number of the selected device.
"svd" or "svdPath" Path (file or URL) to an SVD file.
"targetAddress" Synonymous with serialNumber.
"vendorName" CMSIS-Pack vendor name.
"verifyApplication" Verify application against target memory for each application load operation in debug session. Default: true.

8.2.3 Debug
Start a debug session.

Procedure
1. Check that your device is connected to your computer.
2.
To start a debug session, go to the RUN AND DEBUG view and select the Embedded

Debug configuration in the list , then click the Start Debugging button.
If you have installed the Keil Studio Pack, you can alternatively go to the CMSIS view and click
the Debug button in the ACTIONS panel.

A Debug (no flash) option is also available when you click the arrow next to Debug.
3. If you are using a device with multiple cores, you must select the appropriate processor for your
project in the Select a processor drop-down list that displays at the top of the window.
The Run and Debug view displays and the debug session starts. The debugger stops at the
function “main” of your project.
4. Check the Debug Console tab to see the debugging output.

Next steps
Look at the Visual Studio Code documentation to learn more about the debugging features
available in Visual Studio Code.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 41 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

9. Arm Debugger extension

Run a project on your hardware and start a debug session with the Arm Debugger extension:

• Run your project on your hardware.

• Debug your project with Arm Debugger.

9.1 Run your project on your hardware

Find out how to configure a task to run your project on your hardware and what the configuration
options are.

9.1.1 Configure a task

You must first configure a task to be able to run a project on your hardware. The task transfers the
binary into the appropriate memory locations on the hardware’s flash memory.

Use the Flash Device task for CMSIS-DAP (such as LPC-Link2, Nu-Link2, and ULINKplus™) and ST-
Link hardware. The CMSIS-Packs used in your project control the flash download.

Procedure
1. Open the Command Palette and search for Tasks: Configure Task then select it.
2. Select the arm-debugger.flash: Flash Device task.

This adds the following lines in the tasks.json file that is stored in the .vscode folder of the
project.

{
"type": "arm-debugger.flash",
"serialNumber": "${command:device-manager.getSerialNumber}",
"program": "${command:arm-debugger.getApplicationFile}",
"cmsisPack": "${command:device-manager.getDevicePack}",
"problemMatcher": [],
"label": "arm-debugger.flash: Flash Device"
}

3. Save the tasks.json file.

9.1.2 Override or extend the default tasks configuration options

You can override or extend the default configuration options. See the Flash configuration options
for CMSIS-DAP and ST-Link hardware (Flash Device).

In order to flash a hardware, the task configuration must know which CMSIS-Pack to read
information from and the device name in the CMSIS-Pack to use. These are named as cmsisPack
and deviceName and you can specify them in multiple ways.
Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 42 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

If your target hardware is automatically detected, or if the pack and device name have been set for
it, the task configuration can automatically pick this up by using:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "${command:device-manager.getDevicePack}",
"deviceName": "${command:device-manager.getDeviceName}",
[...]
}

Alternatively, these can be specified directly as a full path to the CMSIS-Pack file or a folder on
your machine:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "/Users/me/mypack.pack",
"deviceName": "STM32H745XIHx",
[...]
}

You can also use the short code for the CMSIS-Pack in the form <vendor>::<pack>@<version>.
Note that this triggers an automatic download of the CMSIS-Pack:

{
[...]
"serialNumber": "${command:device-manager.getSerialNumber}",
"cmsisPack": "Keil::[email protected]",
"deviceName": "STM32H745XIHx",
[...]
}

9.1.2.1 Flash configuration options for CMSIS-DAP and ST-Link hardware (Flash
Device)
The extension provides the task options below. Other Visual Studio Code options are also available.
Use the Trigger Suggestions command (Ctrl+Space) to see what is available and read the Visual
Studio Code documentation on tasks, as well as the Schema for tasks.json page.

Configuration Description
option
"cmsisPack" Path (file or URL) to a DFP (Device Family Pack) CMSIS-Pack for your hardware. Command available: device-
manager.getDevicePack - Gets the CMSIS-Pack for the selected device.
"connectMode" Connection mode. Possible values: auto (debugger decides), haltOnConnect (halts for any reset before running),
underReset (holds external NRST line asserted), preReset (pre-reset using NRST), running (connects to
running target without altering state). Default: auto.
"deviceName" CMSIS-Pack device name. Command available: device-manager.getDeviceName - Gets the device name from
the DFP (Device Family Pack) of the selected device.
"openSerial" Baud rate to open the serial output of a device after flash (requires Arm Device Manager). Possible values: 115200,
57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600.
"pdsc" Path (file or URL) to a PDSC file.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 43 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

Configuration Description
option
"probe" Name of probe to use for the debug connection. Possible values: ULINKpro, ULINKpro D, ULINK2, CMSIS-DAP,
ULINKplus, FTDI MPSSE JTAG, ST-Link, DSTREAM. Default: CMSIS-DAP.
"processorName" CMSIS-Pack processor name for multi-core devices.
"program" or Path(s) (file or URL) to the project(s) to use. Command available: arm-debugger.getApplicationFile -
"programs" Returns an AXF or ELF file used for CMSIS run and debug.
"serialNumber" Serial number of the connected USB hardware to use. Command available: device-
manager.getSerialNumber - Gets the serial number of the selected device.
"targetAddress" Synonymous with serialNumber.
"vendorName" CMSIS-Pack vendor name.
"verifyFlash" Verify the contents downloaded to flash. Default: true.

9.1.3 Run your project

Run the project on your hardware.

Procedure
1. Check that your hardware is connected to your computer.
2. Open the Command Palette and search for Tasks: Run Task then select it.
3. Select arm-debugger.flash: Flash Device in the drop-down list.
If you have installed the Keil Studio Pack, you can alternatively go to the CMSIS view and click
the Run button in the ACTIONS panel.
4. If you are using a device with multiple cores, you must select the appropriate processor for your
project in the Select a processor drop-down list that displays at the top of the window.
5. Check the Terminal tab to verify that the project has run correctly.
If the Arm Debugger engine cannot be found on your machine, an Arm Debugger not found
dialog box displays.

Select one of these options:

• Click Install Arm Debugger to add it in your environment. The vcpkg-configuration.json
file is updated. Check that the environment is activated in the status bar .
• Click Configure Path to indicate the path to the Arm Debugger engine in the settings.

9.2 Debug your project with Arm Debugger

Debug a project.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 44 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

9.2.1 Add configuration

As for running a project, you must first add a launch configuration to be able to do debugging.
Creating a launch configuration file allows you to configure and save debugging setup details.
Visual Studio Code keeps debugging configuration information in a launch.json file.

Procedure
1. Open the launch.json file that is stored in the .vscode folder of your project and add the
following lines inside "configurations":[ ]:
{
"name": "Arm Debugger",
"type": "arm-debugger",
"request": "launch",
"serialNumber": "${command:device-manager.getSerialNumber}",
"program": "${command:embedded-debug.getApplicationFile}",
"cmsisPack": "${command:device-manager.getDevicePack}"
}

2. Save the launch.json file.

9.2.2 Override or extend the default launch configuration options

You can override or extend the default configuration options as required. See Debug configuration
options for more details.

See also the details provided for the tasks.json file for cmsisPack and deviceName. In order to debug
a hardware, the launch configuration must know which CMSIS-Pack to read information from and
the device name in the CMSIS-Pack to use.

9.2.2.1 Debug configuration options

The extension provides the task options below. Other Visual Studio Code options are also available.
Use the Trigger Suggestions command (Ctrl+Space) to see what is available and read the Visual
Studio Code documentation on tasks.

Configuration option Description

"cdbEntry" Arm Debugger Configuration Database Entry to select.
"cmsisDevice" Concatenation of CMSIS-Pack name, device vendor, device name, and processor name (if multicore).
"cmsisPack" Path (file or URL) to a DFP (Device Family Pack) CMSIS-Pack for your hardware. Command available: device-
manager.getDevicePack - Gets the CMSIS-Pack for the selected device.
"connectMode" Connection mode. Possible values: auto (debugger decides), haltOnConnect (halts for any reset before
running), underReset (holds external NRST line asserted), preReset (pre-reset using NRST), running
(connects to running target without altering state). Default: auto.
"debugFrom" The symbol the debugger will run to before debugging. Default: "main".
"deviceName" CMSIS-Pack device name. Command available: device-manager.getDeviceName - Gets the device name
from the DFP (Device Family Pack) of the selected device.
"pathMapping" A mapping of remote paths to local paths to resolve source files.
"pdsc" Path (file or URL) to a PDSC file.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 45 of 55
 Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

Configuration option Description

"probe" Name of probe to use for the debug connection. Possible values: ULINKpro, ULINKpro D, ULINK2, CMSIS-
DAP, ULINKplus, FTDI MPSSE JTAG, ST-Link, DSTREAM. Default: CMSIS-DAP.
"processorName" CMSIS-Pack processor name for multi-core devices.
"program" or Path(s) (file or URL) to the project(s) to use. Commands available: arm-debugger.getBinaryFile: Returns a
"programs" BIN or HEX file. arm-debugger.getApplicationFile: Returns an AXF or ELF file used for CMSIS run and
debug.
"programMode" Mode to program an application to a target. Possible values: auto, flash, ram, mixed. Default: auto.
"resetMode" Type of reset to use. Possible values: auto (debugger decides), system (use ResetSystem sequence), hardware
(use ResetHardware sequence), processor (use ResetProcessor sequence). Default: auto.
"searchPaths" Array of paths to source locations.
"serialNumber" Serial number of the connected USB hardware to use. Command available: device-
manager.getSerialNumber - Gets the serial number of the selected device.
"targetAddress" Synonymous with serialNumber.
"vendorName" CMSIS-Pack vendor name.
"workspaceFolder" Current Arm Debugger workspace folder. Default: "${workspaceFolder}".

9.2.3 Debug
Start a debug session.

Procedure
1. Check that your device is connected to your computer.
2.
To start a debug session, go to the RUN AND DEBUG view and select the Arm Debugger

configuration in the list , then click the Start Debugging button.

If you have installed the Keil Studio Pack, you can alternatively go to the CMSIS view and click
the Debug button in the ACTIONS panel.

A Debug (no flash) option is also available when you click the arrow next to Debug.
3. If you are using a device with multiple cores, you must select the appropriate processor for your
project in the Select a processor drop-down list that displays at the top of the window.
The Run and Debug view displays and the debug session starts. The debugger stops at the
function “main” of your project.
4. Check the Debug Console tab to see the debugging output.
If the Arm Debugger engine cannot be found on your machine, an Arm Debugger not found
dialog box displays.

Select one of these options:

• Click Install Arm Debugger to add it in your environment. The vcpkg-configuration.json
file is updated. Check that the environment is activated in the status bar .
• Click Configure Path to indicate the path to the Arm Debugger engine in the settings.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 46 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Arm Debugger extension

Next steps
Look at the Visual Studio Code documentation to learn more about the debugging features
available in Visual Studio Code.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 47 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Activate your license to use Arm tools

10. Activate your license to use Arm tools

If you are using tools such as Arm® Compiler, Arm Debugger, or Fixed Virtual Platforms in your
toolchain, you must activate a license to be able to use those tools.

After you have installed the pack, Keil Studio Pack, a pop-up displays in the bottom right-hand
corner.

Click Activate.

By default, this activates the Keil® MDK Community Edition license. After activation, the
Community license takes precedence over any existing licenses, including MDK and Flex licenses.

If you already have a commercial license, click Don’t Ask Again in the pop-up to ignore the Keil
MDK Community Edition license activation.

To turn the licensing notifications off, you can also go to the Keil Studio Pack category in the
settings and select the Silence Licensing Notifications checkbox.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 48 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Use CMSIS-Toolbox from the command line

11. Use CMSIS-Toolbox from the command

line
CMSIS-Toolbox is a set of command-line tools that are integrated into the Keil® Studio extensions
and that you can also use as standalone from the command line.

If you used an official example from keil.arm.com and installed the Keil Studio Pack as
recommended, then CMSIS-Toolbox is already available on your machine as explained in Get
started with an example project.

The main tools that CMSIS-Toolbox provides and that you can use with the command line are:
• cpackget:Pack Manager. Used to install and manage CMSIS-Packs in your development
environment.
• cbuild:Build invocation. Used to orchestrate the build process that translates a project to
an executable binary image. cbuild invokes the different tools (csolution, cpackget and
cbuildgen) and launches the CMake compilation process.

• csolution: Project Manager. Used to create build information for embedded applications that
consist of one or more related projects.

The Build Tools page describes how to use these tools with the command line.

11.1 Add CMSIS-Toolbox to the system PATH

The Environment Manager extension installs CMSIS-Toolbox and adds the tools into the Visual
Studio Code system PATH.

If you install CMSIS-Toolbox without using the Environment Manager extension, add the
installation path to the system PATH, or use the Cmsis-csolution: Cmsis Toolbox Path setting to
add the path.

11.2 Support for packs

CMSIS-Packs (also often referred to as software packs) contain everything you need to work with
specific microcontroller families or development boards.

You can work with different types of packs:

• Public packs. These are packs that Arm or silicon and software vendors created and that are
publicly available. Public packs are available from the CMSIS-Packs page on keil.arm.com.
• Private packs. These are packs that you have created but not shared yet, or packs that others
shared with you privately. These can be local packs available on your system or remote packs
available on the web.

This section gives you an overview on how to manage the different types of packs.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 49 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Use CMSIS-Toolbox from the command line

The Open-CMSIS-Pack documentation describes the different ways of adding or

removing packs from the command line in detail. See Adding packs and Removing
packs.

11.2.1 Add public packs

You can use the functionality available in the CMSIS csolution extension to install missing public
packs. See Install missing CMSIS-Packs for more details.

Alternatively, you can use the cpackget add command from the terminal to install the latest
published version of public packs listed in the package index of a vendor. A package index
file lists all the CMSIS-Packs hosted and maintained by a vendor. See the Open-CMSIS-Pack
documentation for more information on package index files.

For example, the following command installs the latest public version of a public pack:

cpackget pack add Vendor::PackName

Where:
• Vendor: Is the name of the vendor who created the CMSIS-Pack
• PackName: Is the name of the CMSIS-Pack

After running cpackget add, reload Visual Studio Code to update the packs available in the UI.

11.2.2 Add private local packs

To work with a CMSIS-Pack that you created locally, use the cpackget add command from the
terminal and reload Visual Studio Code so that the CMSIS csolution extension knows about the
registered pack. Components from the pack will appear in the Software Components view, and the
file validation will take the new pack into account.

For example, the following command registers a local pack using a PDSC (pack description) file:

cpackget add /path/to/Vendor.PackName.pdsc

Where:
• Vendor: Is the name of the vendor who created the CMSIS-Pack
• PackName: Is the name of the CMSIS-Pack

PDSC files contain information about the content of packs.

After running cpackget add to add packs to the pack root folder, reload Visual Studio Code to
update the packs available in the UI.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 50 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Use CMSIS-Toolbox from the command line

If you cannot see the components from the pack or packs that you have just added in the
Software Components view, check the Cmsis-csolution: Pack Cache Path setting and the
CMSIS_PACK_ROOT environment variable.

11.2.3 Add private remote packs

To install a remote pack available on the web, use the cpackget add command and the URL of the
pack.

For example, the following command installs a pack version that can be downloaded from the web:

cpackget add https://vendor.com/example/Vendor.PackName.x.y.z.pack

Where:
• Vendor: Is the name of the vendor who created the CMSIS-Pack
• PackName: Is the name of the CMSIS-Pack
• x.y.z: Is the specific version of the pack you want to install

After running cpackget add, reload Visual Studio Code to update the packs available in the UI.

11.2.4 Remove packs

To remove packs from your system, use cpackget rm.

For example, the following command removes a specific pack version:

cpackget rm Vendor.PackName.x.y.z

Where:
• Vendor: Is the name of the vendor who created the CMSIS-Pack
• PackName: Is the name of the CMSIS-Pack
• x.y.z: Is the specific version of the pack you want to remove

After running cpackget rm, reload Visual Studio Code to update the packs available in the UI.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 51 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Known issues and troubleshooting

12. Known issues and troubleshooting

Describes known issues with the Keil® Studio extensions and how to troubleshoot some common
issues.

12.1 Known issues

Here are the known issues.

Arm CMSIS csolution extension

The Arm CMSIS csolution extension has the following known issues:
• No support for cdefaults.yml. The Software Components view and validation do not use the
compiler set in the cdefaults file.

Arm Embedded Debugger

The Arm Embedded Debugger extension has the following known issues:
• Support for the DWARF debugging standard is limited to version 4. Please make sure that your
application is built with the appropriate settings.
• Variables and registers are read-only.
• Stack trace is limited if the debugger is halted in assembler source files.

12.2 Troubleshooting
Provides solutions to some common issues you might experience when you use the extensions.

12.2.1 Build fails to find toolchain

With the CMSIS csolution extension, errors such as ld: unknown option: --cpu=Cortex-M4
appear in the build output. In this example, the CMSIS-Toolbox is trying to use the system linker
rather than Arm® Compiler’s armlink.

Solution
1. If you have installed the CMSIS csolution extension separately, not using the Keil Studio
Pack, make sure that you follow the instructions for installing and setting up CMSIS-Toolbox.
In particular, make sure that the CMSIS_COMPILER_ROOT environment variable is set correctly.
Alternatively, you can install the Keil Studio Pack to benefit from an automated setup with
Microsoft vcpkg.
2. Clean the solution. In particular, delete the out and tmp directories.
3. Run the build again.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 52 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Known issues and troubleshooting

12.2.2 Connected development board or debug probe not found

You have connected your development board or debug probe, but the Device Manager extension
cannot detect the hardware.

Solution
• Run Device Manager (Windows), System Information (Mac), or a Linux system utility tool like
hardinfo (Linux) and check for warnings beside your hardware. Warnings can indicate that
hardware drivers are not installed. If necessary, obtain and install the appropriate drivers for
your hardware.
• On Windows: ST development boards and probes require extra drivers. You can download
them from the ST site.
• On Windows: Check if you have an Mbed™ serial port driver installed on your machine. The
Mbed serial port driver is required with Windows 7 only. Serial ports work out of the box
with Windows 8.1 or newer. The Mbed serial port driver breaks native Windows functionality
for updating drivers as it claims all the boards with a DAPLink firmware by default. It is
recommended to uninstall the driver if you do not need it. Alternatively, you can disable it.

You can either:

◦ Uninstall the Mbed serial port driver (recommended): Open a Command Prompt as an
administrator and find and delete the mbedserial_x64.inf, mbedcomposite_x64.inf drivers.

pnputil /enum-drivers

pnputil /delete-driver {oemnumber.inf} /force

Then, connect your hardware using a USB cable and open the Windows Device Manager.
In Ports (COM & LPT) and Universal Serial Bus controllers, find the mbed entries and
uninstall both by right-clicking them. Finally, disconnect and reconnect your hardware.
◦ Disable the Mbed serial port driver: Open the Windows Device Manager. In Ports (COM &
LPT), find the Mbed Serial Port. Right-click it and select Properties. Select the Driver tab
and click the Update Driver button. Then click Browse my computer for drivers and then
Let me pick from a list of available drivers on my computer. Select USB Serial Device
instead of mbed Serial Port.
• On Linux: udev rules grant permission to access USB boards and devices. You must install udev
rules to be able to build a project and run it on your hardware or debug a project.

Clone the pyOCD repository, then copy the rules files which are available in the udev folder to
/etc/udev/rules.d/ as explained in the Readme. Follow the instructions in the Readme.

After installing the udev rules, your connected hardware is detectable in the Device Manager
extension. You may still encounter a permission issue when accessing the serial output. If this is
the case, run sudo adduser "$USER" dialout then restart your machine.
• Check that the firmware version of your board or debug probe is supported and update the
firmware to the latest version. See Out-of-date firmware for more details.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 53 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Known issues and troubleshooting

• Your board or device may be claimed by other processes or tools. For example, if you are trying
to access a board or device with several instances of Visual Studio Code, or with Visual Studio
Code and another IDE.
• Activate the Manage All Devices setting. This allows you to select any USB hardware
connected to your computer. By default, the Device Manager extension only gives you access
to hardware from known vendors.
1. Open the settings:
◦ On Windows or Linux, go to: File > Preferences > Settings.
◦ On macOS, go to: Code > Settings > Settings.
2. Find the Device-manager: Manage All Devices setting and select its checkbox.

12.2.3 Out-of-date firmware

You have connected your development board or debug probe and a pop-up message appears
mentioning that the firmware is out of date.

Solution
Update the firmware of the board or debug probe to the latest version:
• DAPLink. If you cannot find your board or probe on daplink.io, then check the website of the
manufacturer for your hardware.
• ST-LINK.
• For other WebUSB-enabled CMSIS-DAP firmware updates, please contact your board or debug
probe vendor.

If you are using an FRDM-KL25Z board and the standard DAPLink firmware update
procedure does not work, follow this procedure (requires Windows 7 or Windows
XP).

For more information on firmware updates, see also the Debug Probe Firmware Update
Information Application Note.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 54 of 55
Arm Keil Studio Visual Studio Code Extensions User Guide Document ID: 108029_0000_08_en

Submit feedback

13. Submit feedback

If you have suggestions or you have discovered an issue with any of the Keil® Studio extensions,
please report them to us. Go to the keil.arm.com support page and use the links provided in the
Keil Studio for VS Code category.

Copyright © 2023 Arm Limited (or its affiliates). All rights reserved.
Non-Confidential
Page 55 of 55