Set the specific
version for a
pack to be used on the csolution/cproject/clayer level. Use these version specifiers:
-Unspecified: use the latest installed version of a packUnspecified: use the latest installed version of a pack and the cbuild-pack.yml for locked versions.@: exact version@>=: equal or higher@^: equal or higher with same major versionManage software packs
Add a pack to a csolution/cproject/clayer.
Below that, the used pack version is shown. It is computed from the requirements above.
-In the Update Pack section, you can see the latest installed version and check for updates.
+In the Update Pack section, you can see the latest installed version and check for updates. The button on the left
+is enabled when there is a more recent version of a pack installed, but the cbuild-pack.yml locks it to a
+smaller version. When pressing the button, the cbuild-pack.yml entry will be removed on save and the latest installed
+pack version will be set and used. The button to the right opens the version page of a public pack on
+keil.arm.com which then also shows you the latest available pack version.
diff --git a/site/debug.html b/site/debug.html
index 34de320..75f094e 100644
--- a/site/debug.html
+++ b/site/debug.html
@@ -673,6 +673,11 @@ Custom launch.json.vscode/launch.json.d/ and .vscode/tasks.json.d/ directories are included for the
active solution applying the same rules as above. This can be used to include solution specific content into the
workspace configuration based on the currently used solution.
+
+
Note
+
To trigger an update of the launch.json and tasks.json files, press Ctrl/Cmd+Shift+p and select
+Update Debug Tasks and Launch Configurations .
+
pyOCD
In the Manage Solution dialog, select the one of the debug adapters named xyz@pyOCD :
For the Debug Interface , you can:
diff --git a/site/index.html b/site/index.html
index 99c5337..6531ac1 100644
--- a/site/index.html
+++ b/site/index.html
@@ -272,5 +272,5 @@ Revision history
diff --git a/site/search/search_index.json b/site/search/search_index.json
index e81c80b..2d2a407 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"index.html","text":"Arm Keil Studio The Arm\u00ae Keil Studio extension pack for VS Code is a comprehensive software development platform for Arm Cortex-M processor-based devices. The IDE: supports single and multi-core processor systems, including Ethos-U NPUs. has wide software support for projects based on CMSIS, FreeRTOS, RTX, and Zephyr. utilizes CMSIS-Pack content to configure debug adapters and access re-usable software components. can be combined with other VS Code debug extensions, such as those for Linux application development. Contents Installation explains how to install Keil Studio along with a build environment for embedded applications that are based on Arm Cortex-M processors. User interface shows the main features available in the GUI. Work with CMSIS solutions explains how to start an embedded project from scratch or use pre-built examples. Work with Zephyr applications explains how to build applications based on Zephyr. Manage solutions explains how to configure csolution projects . Build and run shows how to build and run a CMSIS solution or Zephyr application. Debug explains how to debug a CMSIS solution or Zephyr application. Import \u00b5Vision project explains how to convert uvprojx-based files to the csolution format. Run external tools describes how to use external tools, such as debuggers and flash programmers. Tips and tricks provides tips and tricks to help you solve specific issues. Related documentation contains links to supporting documentation, videos, and webinars. Features and roadmap presents the implemented features and our current feature roadmap. Revision history Version Description 1.66.0 Added Software pack , Related Documentation , and Features and roadmap chapters 1.64.0 Added Work with Zephyr applications and reworked other chapters 1.62.0 Reworked Manage solutions and Debug chapters 1.55.0 Rework for better clarity 1.54.0 Added CMSIS-Toolbox Run and Debug Management 1.48.0 Initial release for the CMSIS Solution extension version 1.48.0","title":"Home"},{"location":"index.html#arm-keil-studio","text":"The Arm\u00ae Keil Studio extension pack for VS Code is a comprehensive software development platform for Arm Cortex-M processor-based devices. The IDE: supports single and multi-core processor systems, including Ethos-U NPUs. has wide software support for projects based on CMSIS, FreeRTOS, RTX, and Zephyr. utilizes CMSIS-Pack content to configure debug adapters and access re-usable software components. can be combined with other VS Code debug extensions, such as those for Linux application development.","title":"Arm Keil Studio"},{"location":"index.html#contents","text":"Installation explains how to install Keil Studio along with a build environment for embedded applications that are based on Arm Cortex-M processors. User interface shows the main features available in the GUI. Work with CMSIS solutions explains how to start an embedded project from scratch or use pre-built examples. Work with Zephyr applications explains how to build applications based on Zephyr. Manage solutions explains how to configure csolution projects . Build and run shows how to build and run a CMSIS solution or Zephyr application. Debug explains how to debug a CMSIS solution or Zephyr application. Import \u00b5Vision project explains how to convert uvprojx-based files to the csolution format. Run external tools describes how to use external tools, such as debuggers and flash programmers. Tips and tricks provides tips and tricks to help you solve specific issues. Related documentation contains links to supporting documentation, videos, and webinars. Features and roadmap presents the implemented features and our current feature roadmap.","title":"Contents"},{"location":"index.html#revision-history","text":"Version Description 1.66.0 Added Software pack , Related Documentation , and Features and roadmap chapters 1.64.0 Added Work with Zephyr applications and reworked other chapters 1.62.0 Reworked Manage solutions and Debug chapters 1.55.0 Rework for better clarity 1.54.0 Added CMSIS-Toolbox Run and Debug Management 1.48.0 Initial release for the CMSIS Solution extension version 1.48.0","title":"Revision history"},{"location":"build_run.html","text":"Build Before you can download the application on your target device, you need to build it. There are various ways to trigger a build: In the Explorer view , right-click the *.csolution.yml file and select Build solution . In the CMSIS view , click . Continue to load and run the solution. Build output After you initiate the build process, a Terminal opens and displays the build operation: Execute: cbuild /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/Blinky.csolution.yml --active NUCLEO-F756ZG --packs +--------------------------------------------------- (1/1) Building context: \"Blinky.Debug+NUCLEO-F756ZG\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Blinky.Debug+NUCLEO-F756ZG' [1/51] Building C object CMakeFiles/Group_Source_Files_retarget_stdio_c.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/retarget_stdio.o [2/51] Building ASM object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/MDK-ARM/startup_stm32f756xx.o Warning: A1950W: The legacy armasm assembler is deprecated. Consider using the armclang integrated assembler instead. 0 Errors, 1 Warning [3/51] Building C object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/Src/stm32f7xx_hal_timebase_tim.o ... [49/51] Building C object CMakeFiles/Keil_CMSIS_Driver_USART_3_0_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-Driver_STM32/1.1.0/Drivers/USART_STM32.o [50/51] Building C object CMakeFiles/ARM_CMSIS_RTOS2_Keil_RTX5_Source_5_9_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-RTX/5.9.0/Source/rtx_thread.o [51/51] Linking C executable /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/out/Blinky/NUCLEO-F756ZG/Debug/Blinky.axf Program Size: Code=31972 RO-data=1076 RW-data=512 ZI-data=38760 +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:04 +============================================================ Completed: cbuild succeed with exit code 0 Build complete The output directory usually contains an ELF ( .axf ) and a HEX ( .hex ) file. To learn about the solution structure, refer to CMSIS-Toolbox documentation Load and Run Check target information In the CMSIS view, click and then select \"Target Information\" to check that your target is connected. In the Terminal , the result of the pyocd list command is shown: * Executing task: pyocd list --cbuild-run /Users/user/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml # Probe/Board Unique ID Target ------------------------------------------------------------------- 0 STLINK-V3 001000254D46501220383832 \u2716\ufe0e stm32u585aiix B-U585I-IOT02A Note Various debug adapters are supported. Select them using the manage solutions dialog. The configure run and debug chapter explains the details. If your debug adapter is not shown, make sure that all drivers are installed and that the target is connected to the PC. Download and run the application In the CMSIS view, click . This executes the \"Load & Run application\" command that executes the commands CMSIS Load and CMSIS Run from the tasks.json file. This flashes the project onto the target and issues a reset to start the application. To verify that the step has run correctly, check the Terminal output: * Executing task: pyocd load --probe stlink: --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000712 I Loading /Users/user/B-U585-Board/Blinky/out/Blinky/B-U585I-IOT02A/Debug/Blinky.axf [load_cmd] [==================================================] 100% 0003015 I Erased 49152 bytes (6 sectors), programmed 49152 bytes (48 pages), skipped 0 bytes (0 pages) at 20.96 kB/s [loader] * Terminal will be reused by tasks, press any key to close it. * Executing task: pyocd gdbserver --probe stlink: --connect attach --persist --reset-run --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000251 I Target type is stm32u585aiix [board] 0000434 I DP IDR = 0x0be12477 (v2 MINDP rev0) [dap] 0000511 I debugvar 'DbgMCU_AHB1_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_AHB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1H_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1L_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB2_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_CR' = 0x6 (6) [cbuild_run] 0000511 I debugvar 'DoOptionByteLoading' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'TraceClk_Pin' = 0x40002 (262146) [cbuild_run] 0000511 I debugvar 'TraceD0_Pin' = 0x20009 (131081) [cbuild_run] 0000511 I debugvar 'TraceD1_Pin' = 0x2000a (131082) [cbuild_run] 0000511 I debugvar 'TraceD2_Pin' = 0x40005 (262149) [cbuild_run] 0000511 I debugvar 'TraceD3_Pin' = 0x2000c (131084) [cbuild_run] 0000516 I AHB5-AP#0 IDR = 0x14770015 (AHB5-AP var1 rev1) [discovery] 0000517 I AHB5-AP#0 Class 0x1 ROM table #0 @ 0xe00fe000 (designer=020:ST part=482) [rom_table] 0000518 I [0] [rom_table] 0000518 I AHB5-AP#0 Class 0x1 ROM table #1 @ 0xe00ff000 (designer=43b:Arm part=4c9) [rom_table] 0000520 I [0] [rom_table] 0000520 I [1] [rom_table] 0000521 I [2] [rom_table] 0000522 I [3] [rom_table] 0000523 I [5] [rom_table] 0000524 I [6] [rom_table] 0000524 I [1] [rom_table] 0000525 I [2] [rom_table] 0000533 I CPU core #0: Cortex-M33 r0p4, v8.0-M architecture [cortex_m] 0000533 I Extensions: [DSP, FPU, FPU_V5, MPU] [cortex_m] 0000533 I FPU present: FPv5-SP-D16-M [cortex_m] 0000534 I Setting core #0 (Cortex-M33) default reset sequence to ResetSystem [cbuild_run] 0000534 I 4 hardware watchpoints [dwt] 0000537 I 8 hardware breakpoints, 1 literal comparators [fpb] 0000662 I Semihost server started on port 4444 (core 0) [server] 0000718 I GDB server started on port 3333 (core 0) [gdbserver] When running, changes to . Use it to stop the GDB session anytime. Notes When you have several solutions in one folder, VS Code ignores the tasks.json and launch.json files that you created for each solution. Instead, VS Code generates new JSON files at the root of the workspace in a .vscode folder and ignores the other JSON files. As a workaround, open one solution first, then add other solutions to your workspace with the File > Add Folder to Workspace option. If you are using a multi-core device and you did not specify a \"processorName\" in the launch.json file, select the appropriate processor for your project in the Select a processor drop-down list at the top of the window. If you want to run the application on an Arm FVP simulation model, you need to configure it in the Manage Solution dialog. Monitor printf messages Keil Studio includes the Serial Monitor extension that connects to the target's serial output port. If your example contains printf statements, use the Serial Monitor to observe them.","title":"Build and run"},{"location":"build_run.html#build","text":"Before you can download the application on your target device, you need to build it. There are various ways to trigger a build: In the Explorer view , right-click the *.csolution.yml file and select Build solution . In the CMSIS view , click . Continue to load and run the solution.","title":"Build"},{"location":"build_run.html#build-output","text":"After you initiate the build process, a Terminal opens and displays the build operation: Execute: cbuild /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/Blinky.csolution.yml --active NUCLEO-F756ZG --packs +--------------------------------------------------- (1/1) Building context: \"Blinky.Debug+NUCLEO-F756ZG\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Blinky.Debug+NUCLEO-F756ZG' [1/51] Building C object CMakeFiles/Group_Source_Files_retarget_stdio_c.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/retarget_stdio.o [2/51] Building ASM object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/MDK-ARM/startup_stm32f756xx.o Warning: A1950W: The legacy armasm assembler is deprecated. Consider using the armclang integrated assembler instead. 0 Errors, 1 Warning [3/51] Building C object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/Src/stm32f7xx_hal_timebase_tim.o ... [49/51] Building C object CMakeFiles/Keil_CMSIS_Driver_USART_3_0_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-Driver_STM32/1.1.0/Drivers/USART_STM32.o [50/51] Building C object CMakeFiles/ARM_CMSIS_RTOS2_Keil_RTX5_Source_5_9_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-RTX/5.9.0/Source/rtx_thread.o [51/51] Linking C executable /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/out/Blinky/NUCLEO-F756ZG/Debug/Blinky.axf Program Size: Code=31972 RO-data=1076 RW-data=512 ZI-data=38760 +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:04 +============================================================ Completed: cbuild succeed with exit code 0 Build complete The output directory usually contains an ELF ( .axf ) and a HEX ( .hex ) file. To learn about the solution structure, refer to CMSIS-Toolbox documentation","title":"Build output"},{"location":"build_run.html#load-and-run","text":"","title":"Load and Run"},{"location":"build_run.html#check-target-information","text":"In the CMSIS view, click and then select \"Target Information\" to check that your target is connected. In the Terminal , the result of the pyocd list command is shown: * Executing task: pyocd list --cbuild-run /Users/user/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml # Probe/Board Unique ID Target ------------------------------------------------------------------- 0 STLINK-V3 001000254D46501220383832 \u2716\ufe0e stm32u585aiix B-U585I-IOT02A Note Various debug adapters are supported. Select them using the manage solutions dialog. The configure run and debug chapter explains the details. If your debug adapter is not shown, make sure that all drivers are installed and that the target is connected to the PC.","title":"Check target information"},{"location":"build_run.html#download-and-run-the-application","text":"In the CMSIS view, click . This executes the \"Load & Run application\" command that executes the commands CMSIS Load and CMSIS Run from the tasks.json file. This flashes the project onto the target and issues a reset to start the application. To verify that the step has run correctly, check the Terminal output: * Executing task: pyocd load --probe stlink: --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000712 I Loading /Users/user/B-U585-Board/Blinky/out/Blinky/B-U585I-IOT02A/Debug/Blinky.axf [load_cmd] [==================================================] 100% 0003015 I Erased 49152 bytes (6 sectors), programmed 49152 bytes (48 pages), skipped 0 bytes (0 pages) at 20.96 kB/s [loader] * Terminal will be reused by tasks, press any key to close it. * Executing task: pyocd gdbserver --probe stlink: --connect attach --persist --reset-run --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000251 I Target type is stm32u585aiix [board] 0000434 I DP IDR = 0x0be12477 (v2 MINDP rev0) [dap] 0000511 I debugvar 'DbgMCU_AHB1_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_AHB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1H_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1L_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB2_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_CR' = 0x6 (6) [cbuild_run] 0000511 I debugvar 'DoOptionByteLoading' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'TraceClk_Pin' = 0x40002 (262146) [cbuild_run] 0000511 I debugvar 'TraceD0_Pin' = 0x20009 (131081) [cbuild_run] 0000511 I debugvar 'TraceD1_Pin' = 0x2000a (131082) [cbuild_run] 0000511 I debugvar 'TraceD2_Pin' = 0x40005 (262149) [cbuild_run] 0000511 I debugvar 'TraceD3_Pin' = 0x2000c (131084) [cbuild_run] 0000516 I AHB5-AP#0 IDR = 0x14770015 (AHB5-AP var1 rev1) [discovery] 0000517 I AHB5-AP#0 Class 0x1 ROM table #0 @ 0xe00fe000 (designer=020:ST part=482) [rom_table] 0000518 I [0] [rom_table] 0000518 I AHB5-AP#0 Class 0x1 ROM table #1 @ 0xe00ff000 (designer=43b:Arm part=4c9) [rom_table] 0000520 I [0] [rom_table] 0000520 I [1] [rom_table] 0000521 I [2] [rom_table] 0000522 I [3] [rom_table] 0000523 I [5] [rom_table] 0000524 I [6] [rom_table] 0000524 I [1] [rom_table] 0000525 I [2] [rom_table] 0000533 I CPU core #0: Cortex-M33 r0p4, v8.0-M architecture [cortex_m] 0000533 I Extensions: [DSP, FPU, FPU_V5, MPU] [cortex_m] 0000533 I FPU present: FPv5-SP-D16-M [cortex_m] 0000534 I Setting core #0 (Cortex-M33) default reset sequence to ResetSystem [cbuild_run] 0000534 I 4 hardware watchpoints [dwt] 0000537 I 8 hardware breakpoints, 1 literal comparators [fpb] 0000662 I Semihost server started on port 4444 (core 0) [server] 0000718 I GDB server started on port 3333 (core 0) [gdbserver] When running, changes to . Use it to stop the GDB session anytime. Notes When you have several solutions in one folder, VS Code ignores the tasks.json and launch.json files that you created for each solution. Instead, VS Code generates new JSON files at the root of the workspace in a .vscode folder and ignores the other JSON files. As a workaround, open one solution first, then add other solutions to your workspace with the File > Add Folder to Workspace option. If you are using a multi-core device and you did not specify a \"processorName\" in the launch.json file, select the appropriate processor for your project in the Select a processor drop-down list at the top of the window. If you want to run the application on an Arm FVP simulation model, you need to configure it in the Manage Solution dialog.","title":"Download and run the application"},{"location":"build_run.html#monitor-printf-messages","text":"Keil Studio includes the Serial Monitor extension that connects to the target's serial output port. If your example contains printf statements, use the Serial Monitor to observe them.","title":"Monitor printf messages"},{"location":"create_app.html","text":"Work with CMSIS solutions This section explains how to create a CMSIS solution-based project that is using CMSIS-Packs. In the CMSIS view, click Create a New Solution . If you already have a solution opened, use the menu ( ... ) item Create a Solution . The Create new solution dialog allows to start projects based on a Target Board or Target Device selection. Examples, templates, and reference applications depend on the selected board or device and on installed CMSIS-Packs. Examples are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals. Reference applications use defined interfaces (APIs) and are therefore hardware agnostic. These projects require the installation of related CMSIS-Packs and additional software layers for an evaluation board. Templates are stub projects that help you getting started. Some CMSIS-Packs may contain device-specific templates. GitHub repositories may contain projects showcasing a specific use case. These repos can be cloned directly into VS Code. The Source Control view helps maintaining these repos. Further settings include: The Solution Sub Folder is typically a sub-directory in your workspace. The Solution Base Folder specifies your workspace location that may contain multiple projects. With Initialize Git repository the related .gitignore file is created. Show project opening options allows you to open the solution a new instance of VS Code. By default, it is loaded into the current VS Code instance. Examples Click the Target Board (Optional) drop-down list. Enter a search term tp filter the list and then select your board. The details of the selected board are displayed. Click Select . Next, select the example project. There are two types of example projects (available either from Local packs and/or from the Web ): Csolution Examples are using Keil Studio's native project format. uVision Examples are in *.uvprojx format and are converted automatically. To verify the Keil Studio installation, select a Blinky project for example. Specify a Solution Base Folder and click Create . Note First time users may need to confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in the vcpkg-configuration.json file included in a project. A typical Blinky example includes a REAMDE.md file that contains valuable information about the hardware setup and specific tasks that need to be done before working with the target board: Continue to build the project . Reference applications Reference applications show the usage of middleware, software libraries, and custom code that can run on many different target hardware boards. Examples display only if you selected a board and a software layer is available for that board. Reference applications are not dependent on specific hardware. You can deploy them to various evaluation boards using additional software layers that provide driver APIs for specific target hardware. Layers are provided using CMSIS-Packs. Reference applications are available with these CMSIS-Packs: MDK-Middleware : use software components for IPv4 and IPv6 networking, USB Host and Device communication, and file system for data storage. SDS Framework : record real-world data off a device and playing it back on Arm Virtual Hardware. LiteRT : demonstrates the fundamental integration and usage of the LiteRT stack for ML inference on a microcontroller. Attention You need to have the CMSIS-Packs installed before you can create a new reference application. Please follow the instruction for installing packs . Configuration Reference applications use software layers that help scaling example projects to many different target boards. To be able to use the selected board with the reference application, you need to configure the solution and select an appropriate layer. More information about the layer requirements and other configuration options can be found in the documentation: MDK-Middleware SDS Framework Documentation Continue to build the project . Templates Templates help you to get started without application-specific code. Blank solution : Start a project from scratch with an empty main.c file and the CMSIS device startup component selected TrustZone solution : If the board or device that you selected is compatible, you can use TrustZone and define whether projects in the solution use secure or non-secure zones Continue to build the project . GitHub repositories Nowadays, many projects are available in GitHub repositories. VS Code provides easy access to these repos with the built-in Git support . The easiest way to do so is to clone a repository directly in VS Code: In the Explorer view , click Clone Repository (you can do the same in the Source Control view ). Open the CMSIS view and use the ... menu to choose an example via Select Active Solution from workspace . The related tools and software packs are downloaded and installed. Continue to build the project . Note You can also download the repository content as a ZIP file. In that case, extract the content and open the top-level folder in VS Code ( File - Open Folder... ). Ready-to-run examples are available on GitHub . Configure a solution The Configure Solution view opens automatically, if: Your solution has a select-compiler: node, but no compiler: node is set in the csolution.yml file, or You are working with a reference application that requires the configuration of a software layer. Click Next to display the different options available. You can indicate where the layers should be copied to in the Board-Layer , Shield-Layer , and Socket-Layer fields. Click Default to reset the paths to their default values. If there are no compatible layers, errors display. If no compiler is set for the reference application, Select Compiler displays under the layers selection and shows the compilers available in your environment. Select a compiler. For example, AC6 or GCC. If you are working with another solution type, only Select Compiler displays. Select a compiler. Click OK . For reference applications only, a Board.clayer.yml file, a Shield.clayer.yml file, or a Socket.clayer.yml file, along with other files that make up the layer, are added in the folders that you selected. The files are available from the Explorer view. The .clayer.yml files come from the CMSIS-Pack. Layers are automatically added in the csolution.yml file of your solution under target-types: variables: for the active target. For all solution types, the compiler is added with the compiler: key in the csolution.yml file. Note Not all Board Support Packs (BSPs) have board layers. Not all layers are compatible with the connections that your reference application requires. The CMSIS-Packs which contain reference applications and layers generally provide an Overview.md file where the connections are detailed. Software components and packs A software component encapsulates a set of related functions and is delivered in a software pack . The Software Components view enables you to manage the software components and software packs selected in the active project of a solution. Software Components view Open the CMSIS view and click to open the Software Components view: You can: Switch between components and software packs . View only components that are part of the csolution or components from all installed packs . Set the context for which the component selection applies (including layers). Select/remove software components. View more information about the component (name, pack, version, and description). Select different variants of a component. Open related documentation . Validation In the Software Components view , you can manage the dependencies between components and solve validation issues. Issues are highlighted with a yellow exclamation mark icon . If there are validation issues: Either click on and select the issue in the pop-up box (a) or Click the \"Resolve\" button for access to the pop-up box (a). Once a components with validation issues is opened, you can use the \"eye\" icon to see which component is missing/affected (b). Use the \"Apply\" button to select the missing components (only available if there is no choice between different components available). When done, don't forget to Save the changes! RTOS example This example shows how to add a real-time operating systems (RTOS), such as Keil RTX5. Before adding the component, add the CMSIS-RTX pack to your local installation. In a Terminal, run: cpackget add ARM::CMSIS-RTX Once the pack is installed, open the Software Components view, click on All installed packs and select: Enable CMSIS - RTOS2 (API) - Keil RTX5 and choose your Variant (select Library or Source ). Enable CMSIS - OS Tick (API) - SysTick . Click Save After saving, the *.cproject.yml file contains: project: components: # SysTick timer component added: - component: CMSIS:OS Tick:SysTick # Keil RTX5 in Source variant added: - component: CMSIS:RTOS2:Keil RTX5&Source packs: # CMSIS-Pack containing the RTOS component added: - pack: ARM::CMSIS-RTX Software packs You can: Switch between components and software packs . View only software packs that are part of the csolution or view all installed packs . Select the scope for which the software pack selection applies (solution/project/layer). Examine on which level the packs are references (csolution/cproject/clayer). Manage software packs . Open related documentation . Manage software packs Click on either icon: to open the Manage Pack dialog: In the Current References section, you can: Set the specific version for a pack to be used on the csolution/cproject/clayer level. Use these version specifiers: Unspecified : use the latest installed version of a pack @ : exact version @>= : equal or higher @^ : equal or higher with same major version @~ : Equal or higher with same major and minor version Add a pack to a csolution/cproject/clayer. Below that, the used pack version is shown. It is computed from the requirements above. In the Update Pack section, you can see the latest installed version and check for updates.","title":"Work with CMSIS solutions"},{"location":"create_app.html#work-with-cmsis-solutions","text":"This section explains how to create a CMSIS solution-based project that is using CMSIS-Packs. In the CMSIS view, click Create a New Solution . If you already have a solution opened, use the menu ( ... ) item Create a Solution . The Create new solution dialog allows to start projects based on a Target Board or Target Device selection. Examples, templates, and reference applications depend on the selected board or device and on installed CMSIS-Packs. Examples are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals. Reference applications use defined interfaces (APIs) and are therefore hardware agnostic. These projects require the installation of related CMSIS-Packs and additional software layers for an evaluation board. Templates are stub projects that help you getting started. Some CMSIS-Packs may contain device-specific templates. GitHub repositories may contain projects showcasing a specific use case. These repos can be cloned directly into VS Code. The Source Control view helps maintaining these repos. Further settings include: The Solution Sub Folder is typically a sub-directory in your workspace. The Solution Base Folder specifies your workspace location that may contain multiple projects. With Initialize Git repository the related .gitignore file is created. Show project opening options allows you to open the solution a new instance of VS Code. By default, it is loaded into the current VS Code instance.","title":"Work with CMSIS solutions"},{"location":"create_app.html#examples","text":"Click the Target Board (Optional) drop-down list. Enter a search term tp filter the list and then select your board. The details of the selected board are displayed. Click Select . Next, select the example project. There are two types of example projects (available either from Local packs and/or from the Web ): Csolution Examples are using Keil Studio's native project format. uVision Examples are in *.uvprojx format and are converted automatically. To verify the Keil Studio installation, select a Blinky project for example. Specify a Solution Base Folder and click Create . Note First time users may need to confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in the vcpkg-configuration.json file included in a project. A typical Blinky example includes a REAMDE.md file that contains valuable information about the hardware setup and specific tasks that need to be done before working with the target board: Continue to build the project .","title":"Examples"},{"location":"create_app.html#reference-applications","text":"Reference applications show the usage of middleware, software libraries, and custom code that can run on many different target hardware boards. Examples display only if you selected a board and a software layer is available for that board. Reference applications are not dependent on specific hardware. You can deploy them to various evaluation boards using additional software layers that provide driver APIs for specific target hardware. Layers are provided using CMSIS-Packs. Reference applications are available with these CMSIS-Packs: MDK-Middleware : use software components for IPv4 and IPv6 networking, USB Host and Device communication, and file system for data storage. SDS Framework : record real-world data off a device and playing it back on Arm Virtual Hardware. LiteRT : demonstrates the fundamental integration and usage of the LiteRT stack for ML inference on a microcontroller. Attention You need to have the CMSIS-Packs installed before you can create a new reference application. Please follow the instruction for installing packs .","title":"Reference applications"},{"location":"create_app.html#configuration","text":"Reference applications use software layers that help scaling example projects to many different target boards. To be able to use the selected board with the reference application, you need to configure the solution and select an appropriate layer. More information about the layer requirements and other configuration options can be found in the documentation: MDK-Middleware SDS Framework Documentation Continue to build the project .","title":"Configuration"},{"location":"create_app.html#templates","text":"Templates help you to get started without application-specific code. Blank solution : Start a project from scratch with an empty main.c file and the CMSIS device startup component selected TrustZone solution : If the board or device that you selected is compatible, you can use TrustZone and define whether projects in the solution use secure or non-secure zones Continue to build the project .","title":"Templates"},{"location":"create_app.html#github-repositories","text":"Nowadays, many projects are available in GitHub repositories. VS Code provides easy access to these repos with the built-in Git support . The easiest way to do so is to clone a repository directly in VS Code: In the Explorer view , click Clone Repository (you can do the same in the Source Control view ). Open the CMSIS view and use the ... menu to choose an example via Select Active Solution from workspace . The related tools and software packs are downloaded and installed. Continue to build the project . Note You can also download the repository content as a ZIP file. In that case, extract the content and open the top-level folder in VS Code ( File - Open Folder... ). Ready-to-run examples are available on GitHub .","title":"GitHub repositories"},{"location":"create_app.html#configure-a-solution","text":"The Configure Solution view opens automatically, if: Your solution has a select-compiler: node, but no compiler: node is set in the csolution.yml file, or You are working with a reference application that requires the configuration of a software layer. Click Next to display the different options available. You can indicate where the layers should be copied to in the Board-Layer , Shield-Layer , and Socket-Layer fields. Click Default to reset the paths to their default values. If there are no compatible layers, errors display. If no compiler is set for the reference application, Select Compiler displays under the layers selection and shows the compilers available in your environment. Select a compiler. For example, AC6 or GCC. If you are working with another solution type, only Select Compiler displays. Select a compiler. Click OK . For reference applications only, a Board.clayer.yml file, a Shield.clayer.yml file, or a Socket.clayer.yml file, along with other files that make up the layer, are added in the folders that you selected. The files are available from the Explorer view. The .clayer.yml files come from the CMSIS-Pack. Layers are automatically added in the csolution.yml file of your solution under target-types: variables: for the active target. For all solution types, the compiler is added with the compiler: key in the csolution.yml file. Note Not all Board Support Packs (BSPs) have board layers. Not all layers are compatible with the connections that your reference application requires. The CMSIS-Packs which contain reference applications and layers generally provide an Overview.md file where the connections are detailed.","title":"Configure a solution"},{"location":"create_app.html#software-components-and-packs","text":"A software component encapsulates a set of related functions and is delivered in a software pack . The Software Components view enables you to manage the software components and software packs selected in the active project of a solution.","title":"Software components and packs"},{"location":"create_app.html#software-components-view","text":"Open the CMSIS view and click to open the Software Components view: You can: Switch between components and software packs . View only components that are part of the csolution or components from all installed packs . Set the context for which the component selection applies (including layers). Select/remove software components. View more information about the component (name, pack, version, and description). Select different variants of a component. Open related documentation .","title":"Software Components view"},{"location":"create_app.html#validation","text":"In the Software Components view , you can manage the dependencies between components and solve validation issues. Issues are highlighted with a yellow exclamation mark icon . If there are validation issues: Either click on and select the issue in the pop-up box (a) or Click the \"Resolve\" button for access to the pop-up box (a). Once a components with validation issues is opened, you can use the \"eye\" icon to see which component is missing/affected (b). Use the \"Apply\" button to select the missing components (only available if there is no choice between different components available). When done, don't forget to Save the changes!","title":"Validation"},{"location":"create_app.html#rtos-example","text":"This example shows how to add a real-time operating systems (RTOS), such as Keil RTX5. Before adding the component, add the CMSIS-RTX pack to your local installation. In a Terminal, run: cpackget add ARM::CMSIS-RTX Once the pack is installed, open the Software Components view, click on All installed packs and select: Enable CMSIS - RTOS2 (API) - Keil RTX5 and choose your Variant (select Library or Source ). Enable CMSIS - OS Tick (API) - SysTick . Click Save After saving, the *.cproject.yml file contains: project: components: # SysTick timer component added: - component: CMSIS:OS Tick:SysTick # Keil RTX5 in Source variant added: - component: CMSIS:RTOS2:Keil RTX5&Source packs: # CMSIS-Pack containing the RTOS component added: - pack: ARM::CMSIS-RTX","title":"RTOS example"},{"location":"create_app.html#software-packs","text":"You can: Switch between components and software packs . View only software packs that are part of the csolution or view all installed packs . Select the scope for which the software pack selection applies (solution/project/layer). Examine on which level the packs are references (csolution/cproject/clayer). Manage software packs . Open related documentation .","title":"Software packs"},{"location":"create_app.html#manage-software-packs","text":"Click on either icon: to open the Manage Pack dialog: In the Current References section, you can: Set the specific version for a pack to be used on the csolution/cproject/clayer level. Use these version specifiers: Unspecified : use the latest installed version of a pack @ : exact version @>= : equal or higher @^ : equal or higher with same major version @~ : Equal or higher with same major and minor version Add a pack to a csolution/cproject/clayer. Below that, the used pack version is shown. It is computed from the requirements above. In the Update Pack section, you can see the latest installed version and check for updates.","title":"Manage software packs"},{"location":"debug.html","text":"Debug Debugger User Interface Many features of the CMSIS Debugger extension are exposed in the Run and Debug view of VS Code. Start debugging selects a configuration: launch to start download/debug, attach to connect with a running system. Debug Toolbar has buttons for the most common debugging actions that control execution. The Trace and Live View shows the LIVE WATCH window. Debug Statusbar shows the time spent running the application. The Debug Console can be used to interact with the debugger on the command line. Most editor features are available during debugging. For example, developers can use Find and edit source code to correct program errors. The Run and Debug view provides: VARIABLES section, which includes local function variables and CPU register values. WATCH section, which allows viewing user-defined expressions, for example, variable values. CALL STACK section that shows active RTOS threads along with the call stack. BREAKPOINTS section for managing stop points in application execution to inspect the state. TIP Click on a line number badge to navigate to the source code line. Other debugger specific views or features: Live Watch offers run-time viewing of user-defined expressions, for example, variable values. Disassembly shows assembly instructions and supports run control, for example with stepping and breakpoints. Debug Console lists debug output messages and allows entering expressions or GDB commands. Peripherals show the device peripheral registers and allow changing their values. Serial Monitor uses serial or TCP communication to interact with application I/O functions ( printf , getc , etc.). CPU Time shows execution timing and statistics of the past five breakpoints. Multi-Core Debug to view and control several processors in a device. Debug toolbar During debugging, the Debug toolbar contains actions to control the flow of the debug session, such as stepping through code, pausing execution, and stopping the debug session. Action Description Continue/Pause Continue : Resume normal program execution (up to the next breakpoint). Pause : Inspect code executing at the current location. Step Over Execute the next statement as a single command without inspecting or following its component steps. Step Into Enter the next statement to follow its execution line-by-line. Step Out When inside a function, return to the earlier execution context by completing remaining lines of the current method as though it were a single command. Restart Terminate the current program execution and start debugging again using the current run configuration. Stop/Disconnect Stop : Terminate the current debug session. Disconnect: Detach debugger from a core without changing the execution status (running/pause). Debug Session For multi-core devices, the list of active debug sessions and switch between them. Reset Target Reset the target device. VARIABLES During debugging, you can inspect variables, expressions, and registers in the VARIABLES section of the Run and Debug view or by hovering over a variable or expression in the source code editor. Variable values and expressions are evaluated in the context of the selected stack frame in the CALL STACK section. In the case of multi-core, the content is relative to the active debug session. To change the value of a variable during the debugging session, right-click on the variable in the VARIABLES section and select Set Value . You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. To filter variables by their name or value, use the Alt/Opt + Ctrl/Cmd + F keyboard shortcut while the focus is on the VARIABLES section , and type a search term. WATCH Variables and expressions can also be evaluated and watched in the WATCH section. You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. CALL STACK The CALL STACK section shows the function call tree that is currently on the stack. Threads are shown for applications that use an RTOS. Each function call is associated to its location and when source code is available a line number badge is shown. A click on this badge navigates to source file location. The window content is updated whenever program execution stops. BREAKPOINTS A breakpoint pauses the code execution at a specific point, so you can inspect the state of your application at that point. There are several breakpoint types. Setting breakpoints To set or unset a breakpoint, click on the editor margin or use F9 on the current line. Breakpoints in the editor margin are normally shown as red-filled circles. Disabled breakpoints have a filled grey circle. When a debugging session starts, breakpoints that can't be registered with the debugger change to a grey hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running. For more control of breakpoints, use the BREAKPOINTS section that lists and manages all breakpoints. \ud83d\udcdd Note: You can set breakpoints anytime during your debug session. However, when setting a breakpoint while running an application, the target stops for a short period of time. Breakpoint types Apart from the code breakpoint, there are other breakpoint types to satisfy specific use cases. Function breakpoints Instead of placing breakpoints directly in source code, a debugger can support creating breakpoints by specifying a function name. This is useful in situations where the source is not available but a function name is known. To create a function breakpoint, select the + button in the BREAKPOINTS section header and enter the function name. Function breakpoints are shown with a red triangle in the BREAKPOINTS section . Conditional breakpoints Set breakpoint conditions based on expressions, hit counts, or a combination of both. Expression condition: The breakpoint is hit whenever the expression evaluates to true. Hit count: The hit count controls how many times a breakpoint needs to be hit before it interrupts execution. Wait for breakpoint: The breakpoint is activated when another breakpoint is hit ( triggered breakpoint ). To add a conditional breakpoint: Create a conditional breakpoint Right-click in the editor margin and select Add Conditional Breakpoint. Use the Add Conditional Breakpoint command in the Command Palette (\u21e7\u2318P). Choose the type of condition you want to set (expression, hit count, or wait for a breakpoint). To add a condition to an existing breakpoint: Edit an existing breakpoint Right-click on the breakpoint in the editor margin and select Edit Breakpoint. Select the pencil icon next for an existing breakpoint in the BREAKPOINTS section of the Run and Debug view . Edit the condition (expression, hit count, or wait for breakpoint). \ud83d\udcdd Note: For checking the the breakpoint condition, the target is halted for a short period of time. Data breakpoints Data breakpoints can be set from the context menu of a variable in the WATCH section . The Break on Value Change/Read/Access commands add a data breakpoint that is hit when the value of the underlying variable changes/is read/is accessed. Data breakpoints are shown with a red hexagon in the BREAKPOINTS section and the type of breakpoint is shown (Write/Read/Access). \ud83d\udcdd Note: When hitting a data breakpoint, the program execution does not stop exactly on that line of code. Depending on the underlying CPU architecture, stopping can be delayed by up to 5 cycles. Use the Call Stack view to determine what caused the execution to stop. Triggered breakpoints A triggered breakpoint is type of conditional breakpoint that is enabled once another breakpoint is hit. They can be useful when diagnosing failure cases in code that happen only after a certain precondition. Triggered breakpoints can be set by right-clicking on the glyph margin, selecting Add Triggered Breakpoint , and then, choose which other breakpoint enables the breakpoint. Logpoints A logpoint pauses the program execution for a short period of time, sends a message to the debug console, and then continues with the application. Logpoints can help you save time by not having to add or remove logging statements in your code. A logpoint is represented by a diamond-shaped icon. Log messages are plain text, but can also include expressions to be evaluated within curly braces ( {} ). To add a logpoint, right-click in the editor left margin and select Add Logpoint, or use the Debug: Add Logpoint... command in the Command Palette ( Ctrl/Cmd + Shift + p ). Just like regular breakpoints, logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count. CPU Time Most Arm Cortex-M processors (except Cortex-M0/M0+/M23) include a DWT->CYCCNT register that counts CPU states. In combination with the CMSIS variable SystemCoreClock the CMSIS Debugger calculates execution time and displays it along with the selected processor core in the CPU Time Status bar. A click on the CPU Time Status bar opens the related VS Code command palette . Command Description CPU Time Print CPU execution time and history of past program stops. Reset CPU Time Reset CPU execution time and history. Set new reference time (zero point). \ud83d\udcdd Notes: The first program stop (typically at function main ) is the initial reference time (zero point). DWT->CYCCNT is a 32-bit register incremented with SystemCoreClock frequency. The time calculation copes with one overflow between program stops. Multiple overflows between program stops deliver wrong time information. Each processor in a multi-processor system has and independent DWT->CYCCNT register. Trace and Live view The Trace and Live View (available from the VS Code Activity Bar) currently shows the LIVE WATCH . You can add expressions to this view that are updated while the application is running on your target. You can add expressions to the LIVE WATCH by: Pressing the + sign and entering an expression. Using the context menu item Add to Live Watch in the editor or the the Run and Debug view. PERIPHERALS The PERIPHERALS view shows the device peripheral registers and allows to change their values. It uses the CMSIS-SVD files that are provided by silicon vendors and distributed as part of the CMSIS Device Family Packs (DFP). For more information, refer to the Peripheral Inspector GitHub repository . Memory Inspector The Memory Inspector provides a powerful and configurable memory viewer that features: Configurable Memory Display: Shows memory data with various display options. Address Navigation: Easily jump to and scroll through memory addresses. Variable Highlights: Colors memory ranges for variables. Multiple Memory Formats: Shows memory data on hover in multiple formats. Edit Memory: Allows in-place memory editing if the debug adapter supports the WriteMemoryRequest. Memory Management: Enables saving and restoring memory data for specific address ranges (Intel Hex format). Customized Views: Create and customize as many memory views as you need. Lock Views: Keep views static, unaffected by updates from the debug session. Periodic Refresh: Automatically refresh the memory data. Multiple Debug Sessions: Switch between multiple debug sessions using a dropdown in the memory view. For more information, refer to the Memory Inspector GitHub repository . Disassembly The command Open Disassembly View (available from command palette or context menus) shows the assembler instructions of the program intermixed with the source code. Using this view allows single stepping or managing breakpoints at the CPU instruction level. \ud83d\udcdd Note: Enable the VS Code setting Features > Debug > Disassembly View: Show Source Code to show assembler instructions interleaved with source code. RTOS Views For RTOS awareness, the RTOS Views extension needs to be added to CS Code. This extension supports a wide range of real-time operating systems, such as FreeRTOS, Zephyr, embOS,and Keil RTX5. \ud83d\udcdd Note: This is not a live view. It only gets updated when the program execution is stopped. To enable the view, you need to go to the debug view and press Ctrl/Cmd - Shift - P. Select RTOS Views: Toggle RTOS Panel . Afterwards, start your debug session. The view is located in the Terminal panel at the bottom and is called XRTOS . If it does not show values after entering a debug session and running the application, press Ctrl/Cmd - Shift - P again and select RTOS Views: Refresh . Debug Console The Debug Console enables viewing and interacting with the output of your code running in the debugger. Expressions can be evaluated with the Debug Console REPL (Read-Eval-Print Loop) feature. With the CMSIS Debug extension, you can use the Debug Console REPL to enter GDB commands while debugging. Before entering a GDB command, you have to explicitly enter a \"greater-than\"-character > so that the following strings can be evaluated as a GDB command. Debug Console input uses the mode of the active editor, which means that it supports syntax coloring, indentation, auto closing of quotes and other language features. Example The following example shows how to check the currently set breakpoints with the > info break command. Afterwards, the application is run with the > continue command. Serial Monitor The Serial Monitor allows users to configure, monitor, and communicate with serial or TCP ports. Multi-Core Debug A GDB server provides multiple connections to the processor cores (identified with pname ) of a device. The list below shows the output of pyOCD in the DEBUG CONSOLE of VS Code. 0000680 I Target device: MCXN947VDF [cbuild_run] 0001585 I core 0: Cortex-M33 r0p4, pname: cm33_core0 [cbuild_run] 0001585 I core 1: Cortex-M33 r0p4, pname: cm33_core1 [cbuild_run] 0001585 I start-pname: cm33_core0 [cbuild_run] 0001600 I Semihost server started on port 4444 (core 0) [server] 0001636 I GDB server started on port 3333 (core 0) [gdbserver] 0001641 I Semihost server started on port 4445 (core 1) [server] 0001642 I GDB server started on port 3334 (core 1) [gdbserver] 0007560 I Client connected to port 3333! [gdbserver] The start-pname indicates the processor that starts first and boots the system. A debug launch command connects to this processor. Use a debug attach command to connect to processors that are running. The picture below highlights the parts of the user interface that interact with processors. Select a processor and Start Debug . This connects the debugger. Select a Processor in the debug toolbar, or Click in CALL STACK on a thread or function name to select a processor. The selected processor is also shown in the CPU Time Status bar . This processor context is used in the VARIABLES and WATCH view. \ud83d\udcdd Notes: The SEGGER JLink GDB server uses a launch command to connect to a running processor whereas other GDB servers use an attach command. A Disassembly View opens only for a selected processor; otherwise the command is shown as disabled. Debug adapter support Keil Studio support various debug adapters and and GDB server implementations from different vendors: Most of the debug adapters (including ST-Link) are served by pyOCD using the Arm CMSIS Debugger extension . Segger J-Link Server is supported. Arm Debugger is supported. Running on Arm FVPs is possible. Arm Keil \u00b5Vision is supported (only on Windows). If you are using a third-party debug adapter, make sure that the latest drivers are installed on your machine and that the debug adapters are running the latest firmware. Set the PATH variable correctly. Debug Adapter Notes Arm ULINKplus Make sure that the V2.x.x firmware is installed. Infineon KitProg3 Make sure that the latest firmware is installed . Microchip PICKit Basic Use the Python utility pycmsisdapswitcher to switch the firmware to a CMSIS-DAP v2 implementation. Nuvoton NuLink Make sure that the latest firmware is installed . NXP MCU-Link Make sure that the latest firmware is installed . Raspberry Pi Debugprobe Make sure that the latest firmware is installed . SEGGER J-Link For J-Link support, visit J-Link/J-Trace Downloads . Set the PATH variable to the bin directory of the installation. STMicroelectronics ST-Link For ST-LINK/V2 and ST-LINK/V2-1 support on Windows, download the USB driver here: STSW-LINK009 . Select debug adapter In the CMSIS view , open the Manage Solution dialog and go to the Debug Adapter section . Select one of the debug adapters. Once selected, the following JSON files are created automatically: In the launch.json file, attach and launch configurations are added that let you attach the debug adapter to an already running GDB instance (for example when you have issued a load and run before) or launch a new debug session. In the tasks.json file, the tasks CMSIS Erase , CMSIS Load , and CMSIS Run are created. Note If you wish to preserve manual modification to the JSON files, uncheck \"Update launch.json and tasks.json\" in the Debug Adapter for ... section. Set debug adapter ID In case you have multiple debug adapters connected to your computer, you can set the ID of the probe you wish to use in the CMSIS Solution extension settings. Open the settings by pressing CTRL/CMD + , . Enter probe in the search field. Select if you want to set the probe ID for your user or only for the current workspace (recommended). Enter the Unique ID you have retrieved using Target Information . Configure run and debug In VS Code, you can integrate external tools via a tasks.json file. The debug configuration is managed via the launch.json file. Both files are generated automatically based on your *.csolution.yml file: When creating a Target Set in the Manage Solution view and selecting a Debug Adapter , the information is stored in the target-set: node in the *.csolution.yml file (refer to the CMSIS-Toolbox user's guide for details on target-set ). When you save the target set, the CMSIS Solution extension calls cbuild setup that generates the *.cbuild-run.yml file which contains the run and debug description of your solution. Using template files for the various debug adapters from the Debug Adapter Registry and taking the user inputs into account, the CMSIS Solution extension then generates the launch.json and tasks.json files. Custom launch.json and tasks.json settings User defined launch configurations and tasks can be added directly into the workspace files. When updating these files custom or modified entries are kept untouched if detected: .vscode/launch.json Each auto-generated configuration has an additional property cmsis.updateConfiguration=\"auto\" . By either removing this property, or by setting it to manual will exclude it from further automatic updates. .vscode/tasks.json All auto-generated tasks have labels starting with CMSIS . Such tasks are removed on updates. Custom tasks must assure they use names not starting with CMSIS . Instead of adding custom content into these automatically updated files causing version system modifications all the time, one can extract those into configuration subfolders and only keep these under version control: .vscode/launch.json.d/*.json Each JSON file must respect the launch.json schema. All contained configurations are merged into the workspace .vscode/launch.json file by name property. Auto-generated configurations can be overwritten if required without attention to the cmsis.updateConfiguration property. .vscode/tasks.json.d/*.json Each JSON file must respect the tasks.json schema. All contained tasks are merged into the workspace .vscode/tasks.json file by label property. Auto-generated CMSIS tasks can be overwritten if required. For multi-solution workspaces, i.e., having multiple .csolution.yml files in subfolders, solution-specific files in solution's .vscode/launch.json.d/ and .vscode/tasks.json.d/ directories are included for the active solution applying the same rules as above. This can be used to include solution specific content into the workspace configuration based on the currently used solution. pyOCD In the Manage Solution dialog, select the one of the debug adapters named xyz@pyOCD : For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Text File: saves the output to a file in the project workspace. Disabled: does not redirect the serial output. J-Link Server In the Manage Solution dialog select J-Link Server . For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Disabled: does not redirect the serial output. Arm Debugger You can use the Arm Debugger with Keil Studio. Prerequisites Before you can launch a debug session using Arm Debugger, you need to: Install the Arm Debugger VS Code extension . Add the Arm Debugger to your vcpkg-configuration.json file, for example: \"arm:debuggers/arm/armdbg\": \"6.6.0\" Setup for Arm Debugger In the Manage Solution dialog, select the one of the debug adapters named xyz@Arm-Debugger . Arm FVPs In the Manage Solution dialog: Select the Arm-FVP debug adapter Select the model you wish to use Point to your configuration file If you wish to set a simulation limit, add this in the Misc box: Keil uVision In the Manage Solution dialog: Select the Keil uVision debug adapter. Set the path to the UV4.exe file (the default is %LOCALAPPDATA%\\Keil_v5\\UV4\\UV4.exe ). This setting is saved in the *.csolution.yml file. Attention This only works on a Windows PC. Changing the default for the current workspace If you wish to change the default path to \u00b5Vision for your current workspace , you need to create the following entry in your .vscode/settings.json file: { \"cmsis-csolution.debug-adapters\": { \"Keil uVision\": { \"uv4\": \"/path/to/UV4.exe\" } } } Attention If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default. Changing the default for a user If you wish to set the \u00b5Vision path for your user, open the global settings.json file: Press Ctrl/Cmd + Shift + p and type settings . Select Preferences: Open User Settings (JSON) . This opens the global settings.json file. Enter the path as shown above and save the file. Enhancing the debug experience To ensure the best debug experience with Arm Compiler for Embedded, make sure that your CMSIS solution files contain the following. csolution.yml In the *.csolution.yml file, insert the following block in - target-types\\- type section: target-set: - set: debugger: name: # set to name of your debug adapter Insert the following before the - projects section: misc: - for-compiler: AC6 C-CPP: - -gdwarf-5 ASM: - -gdwarf-5 cproject.yml In the *.cproject.yml file, add at the end: output: type: - elf - hex - map","title":"Debug"},{"location":"debug.html#debug","text":"","title":"Debug"},{"location":"debug.html#debugger-user-interface","text":"Many features of the CMSIS Debugger extension are exposed in the Run and Debug view of VS Code. Start debugging selects a configuration: launch to start download/debug, attach to connect with a running system. Debug Toolbar has buttons for the most common debugging actions that control execution. The Trace and Live View shows the LIVE WATCH window. Debug Statusbar shows the time spent running the application. The Debug Console can be used to interact with the debugger on the command line. Most editor features are available during debugging. For example, developers can use Find and edit source code to correct program errors. The Run and Debug view provides: VARIABLES section, which includes local function variables and CPU register values. WATCH section, which allows viewing user-defined expressions, for example, variable values. CALL STACK section that shows active RTOS threads along with the call stack. BREAKPOINTS section for managing stop points in application execution to inspect the state. TIP Click on a line number badge to navigate to the source code line. Other debugger specific views or features: Live Watch offers run-time viewing of user-defined expressions, for example, variable values. Disassembly shows assembly instructions and supports run control, for example with stepping and breakpoints. Debug Console lists debug output messages and allows entering expressions or GDB commands. Peripherals show the device peripheral registers and allow changing their values. Serial Monitor uses serial or TCP communication to interact with application I/O functions ( printf , getc , etc.). CPU Time shows execution timing and statistics of the past five breakpoints. Multi-Core Debug to view and control several processors in a device.","title":"Debugger User Interface"},{"location":"debug.html#debug-toolbar","text":"During debugging, the Debug toolbar contains actions to control the flow of the debug session, such as stepping through code, pausing execution, and stopping the debug session. Action Description Continue/Pause Continue : Resume normal program execution (up to the next breakpoint). Pause : Inspect code executing at the current location. Step Over Execute the next statement as a single command without inspecting or following its component steps. Step Into Enter the next statement to follow its execution line-by-line. Step Out When inside a function, return to the earlier execution context by completing remaining lines of the current method as though it were a single command. Restart Terminate the current program execution and start debugging again using the current run configuration. Stop/Disconnect Stop : Terminate the current debug session. Disconnect: Detach debugger from a core without changing the execution status (running/pause). Debug Session For multi-core devices, the list of active debug sessions and switch between them. Reset Target Reset the target device.","title":"Debug toolbar"},{"location":"debug.html#variables","text":"During debugging, you can inspect variables, expressions, and registers in the VARIABLES section of the Run and Debug view or by hovering over a variable or expression in the source code editor. Variable values and expressions are evaluated in the context of the selected stack frame in the CALL STACK section. In the case of multi-core, the content is relative to the active debug session. To change the value of a variable during the debugging session, right-click on the variable in the VARIABLES section and select Set Value . You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. To filter variables by their name or value, use the Alt/Opt + Ctrl/Cmd + F keyboard shortcut while the focus is on the VARIABLES section , and type a search term.","title":"VARIABLES"},{"location":"debug.html#watch","text":"Variables and expressions can also be evaluated and watched in the WATCH section. You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section.","title":"WATCH"},{"location":"debug.html#call-stack","text":"The CALL STACK section shows the function call tree that is currently on the stack. Threads are shown for applications that use an RTOS. Each function call is associated to its location and when source code is available a line number badge is shown. A click on this badge navigates to source file location. The window content is updated whenever program execution stops.","title":"CALL STACK"},{"location":"debug.html#breakpoints","text":"A breakpoint pauses the code execution at a specific point, so you can inspect the state of your application at that point. There are several breakpoint types.","title":"BREAKPOINTS"},{"location":"debug.html#setting-breakpoints","text":"To set or unset a breakpoint, click on the editor margin or use F9 on the current line. Breakpoints in the editor margin are normally shown as red-filled circles. Disabled breakpoints have a filled grey circle. When a debugging session starts, breakpoints that can't be registered with the debugger change to a grey hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running. For more control of breakpoints, use the BREAKPOINTS section that lists and manages all breakpoints. \ud83d\udcdd Note: You can set breakpoints anytime during your debug session. However, when setting a breakpoint while running an application, the target stops for a short period of time.","title":"Setting breakpoints"},{"location":"debug.html#breakpoint-types","text":"Apart from the code breakpoint, there are other breakpoint types to satisfy specific use cases.","title":"Breakpoint types"},{"location":"debug.html#function-breakpoints","text":"Instead of placing breakpoints directly in source code, a debugger can support creating breakpoints by specifying a function name. This is useful in situations where the source is not available but a function name is known. To create a function breakpoint, select the + button in the BREAKPOINTS section header and enter the function name. Function breakpoints are shown with a red triangle in the BREAKPOINTS section .","title":"Function breakpoints"},{"location":"debug.html#conditional-breakpoints","text":"Set breakpoint conditions based on expressions, hit counts, or a combination of both. Expression condition: The breakpoint is hit whenever the expression evaluates to true. Hit count: The hit count controls how many times a breakpoint needs to be hit before it interrupts execution. Wait for breakpoint: The breakpoint is activated when another breakpoint is hit ( triggered breakpoint ). To add a conditional breakpoint: Create a conditional breakpoint Right-click in the editor margin and select Add Conditional Breakpoint. Use the Add Conditional Breakpoint command in the Command Palette (\u21e7\u2318P). Choose the type of condition you want to set (expression, hit count, or wait for a breakpoint). To add a condition to an existing breakpoint: Edit an existing breakpoint Right-click on the breakpoint in the editor margin and select Edit Breakpoint. Select the pencil icon next for an existing breakpoint in the BREAKPOINTS section of the Run and Debug view . Edit the condition (expression, hit count, or wait for breakpoint). \ud83d\udcdd Note: For checking the the breakpoint condition, the target is halted for a short period of time.","title":"Conditional breakpoints"},{"location":"debug.html#data-breakpoints","text":"Data breakpoints can be set from the context menu of a variable in the WATCH section . The Break on Value Change/Read/Access commands add a data breakpoint that is hit when the value of the underlying variable changes/is read/is accessed. Data breakpoints are shown with a red hexagon in the BREAKPOINTS section and the type of breakpoint is shown (Write/Read/Access). \ud83d\udcdd Note: When hitting a data breakpoint, the program execution does not stop exactly on that line of code. Depending on the underlying CPU architecture, stopping can be delayed by up to 5 cycles. Use the Call Stack view to determine what caused the execution to stop.","title":"Data breakpoints"},{"location":"debug.html#triggered-breakpoints","text":"A triggered breakpoint is type of conditional breakpoint that is enabled once another breakpoint is hit. They can be useful when diagnosing failure cases in code that happen only after a certain precondition. Triggered breakpoints can be set by right-clicking on the glyph margin, selecting Add Triggered Breakpoint , and then, choose which other breakpoint enables the breakpoint.","title":"Triggered breakpoints"},{"location":"debug.html#logpoints","text":"A logpoint pauses the program execution for a short period of time, sends a message to the debug console, and then continues with the application. Logpoints can help you save time by not having to add or remove logging statements in your code. A logpoint is represented by a diamond-shaped icon. Log messages are plain text, but can also include expressions to be evaluated within curly braces ( {} ). To add a logpoint, right-click in the editor left margin and select Add Logpoint, or use the Debug: Add Logpoint... command in the Command Palette ( Ctrl/Cmd + Shift + p ). Just like regular breakpoints, logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count.","title":"Logpoints"},{"location":"debug.html#cpu-time","text":"Most Arm Cortex-M processors (except Cortex-M0/M0+/M23) include a DWT->CYCCNT register that counts CPU states. In combination with the CMSIS variable SystemCoreClock the CMSIS Debugger calculates execution time and displays it along with the selected processor core in the CPU Time Status bar. A click on the CPU Time Status bar opens the related VS Code command palette . Command Description CPU Time Print CPU execution time and history of past program stops. Reset CPU Time Reset CPU execution time and history. Set new reference time (zero point). \ud83d\udcdd Notes: The first program stop (typically at function main ) is the initial reference time (zero point). DWT->CYCCNT is a 32-bit register incremented with SystemCoreClock frequency. The time calculation copes with one overflow between program stops. Multiple overflows between program stops deliver wrong time information. Each processor in a multi-processor system has and independent DWT->CYCCNT register.","title":"CPU Time"},{"location":"debug.html#trace-and-live-view","text":"The Trace and Live View (available from the VS Code Activity Bar) currently shows the LIVE WATCH . You can add expressions to this view that are updated while the application is running on your target. You can add expressions to the LIVE WATCH by: Pressing the + sign and entering an expression. Using the context menu item Add to Live Watch in the editor or the the Run and Debug view.","title":"Trace and Live view"},{"location":"debug.html#peripherals","text":"The PERIPHERALS view shows the device peripheral registers and allows to change their values. It uses the CMSIS-SVD files that are provided by silicon vendors and distributed as part of the CMSIS Device Family Packs (DFP). For more information, refer to the Peripheral Inspector GitHub repository .","title":"PERIPHERALS"},{"location":"debug.html#memory-inspector","text":"The Memory Inspector provides a powerful and configurable memory viewer that features: Configurable Memory Display: Shows memory data with various display options. Address Navigation: Easily jump to and scroll through memory addresses. Variable Highlights: Colors memory ranges for variables. Multiple Memory Formats: Shows memory data on hover in multiple formats. Edit Memory: Allows in-place memory editing if the debug adapter supports the WriteMemoryRequest. Memory Management: Enables saving and restoring memory data for specific address ranges (Intel Hex format). Customized Views: Create and customize as many memory views as you need. Lock Views: Keep views static, unaffected by updates from the debug session. Periodic Refresh: Automatically refresh the memory data. Multiple Debug Sessions: Switch between multiple debug sessions using a dropdown in the memory view. For more information, refer to the Memory Inspector GitHub repository .","title":"Memory Inspector"},{"location":"debug.html#disassembly","text":"The command Open Disassembly View (available from command palette or context menus) shows the assembler instructions of the program intermixed with the source code. Using this view allows single stepping or managing breakpoints at the CPU instruction level. \ud83d\udcdd Note: Enable the VS Code setting Features > Debug > Disassembly View: Show Source Code to show assembler instructions interleaved with source code.","title":"Disassembly"},{"location":"debug.html#rtos-views","text":"For RTOS awareness, the RTOS Views extension needs to be added to CS Code. This extension supports a wide range of real-time operating systems, such as FreeRTOS, Zephyr, embOS,and Keil RTX5. \ud83d\udcdd Note: This is not a live view. It only gets updated when the program execution is stopped. To enable the view, you need to go to the debug view and press Ctrl/Cmd - Shift - P. Select RTOS Views: Toggle RTOS Panel . Afterwards, start your debug session. The view is located in the Terminal panel at the bottom and is called XRTOS . If it does not show values after entering a debug session and running the application, press Ctrl/Cmd - Shift - P again and select RTOS Views: Refresh .","title":"RTOS Views"},{"location":"debug.html#debug-console","text":"The Debug Console enables viewing and interacting with the output of your code running in the debugger. Expressions can be evaluated with the Debug Console REPL (Read-Eval-Print Loop) feature. With the CMSIS Debug extension, you can use the Debug Console REPL to enter GDB commands while debugging. Before entering a GDB command, you have to explicitly enter a \"greater-than\"-character > so that the following strings can be evaluated as a GDB command. Debug Console input uses the mode of the active editor, which means that it supports syntax coloring, indentation, auto closing of quotes and other language features. Example The following example shows how to check the currently set breakpoints with the > info break command. Afterwards, the application is run with the > continue command.","title":"Debug Console"},{"location":"debug.html#serial-monitor","text":"The Serial Monitor allows users to configure, monitor, and communicate with serial or TCP ports.","title":"Serial Monitor"},{"location":"debug.html#multi-core-debug","text":"A GDB server provides multiple connections to the processor cores (identified with pname ) of a device. The list below shows the output of pyOCD in the DEBUG CONSOLE of VS Code. 0000680 I Target device: MCXN947VDF [cbuild_run] 0001585 I core 0: Cortex-M33 r0p4, pname: cm33_core0 [cbuild_run] 0001585 I core 1: Cortex-M33 r0p4, pname: cm33_core1 [cbuild_run] 0001585 I start-pname: cm33_core0 [cbuild_run] 0001600 I Semihost server started on port 4444 (core 0) [server] 0001636 I GDB server started on port 3333 (core 0) [gdbserver] 0001641 I Semihost server started on port 4445 (core 1) [server] 0001642 I GDB server started on port 3334 (core 1) [gdbserver] 0007560 I Client connected to port 3333! [gdbserver] The start-pname indicates the processor that starts first and boots the system. A debug launch command connects to this processor. Use a debug attach command to connect to processors that are running. The picture below highlights the parts of the user interface that interact with processors. Select a processor and Start Debug . This connects the debugger. Select a Processor in the debug toolbar, or Click in CALL STACK on a thread or function name to select a processor. The selected processor is also shown in the CPU Time Status bar . This processor context is used in the VARIABLES and WATCH view. \ud83d\udcdd Notes: The SEGGER JLink GDB server uses a launch command to connect to a running processor whereas other GDB servers use an attach command. A Disassembly View opens only for a selected processor; otherwise the command is shown as disabled.","title":"Multi-Core Debug"},{"location":"debug.html#debug-adapter-support","text":"Keil Studio support various debug adapters and and GDB server implementations from different vendors: Most of the debug adapters (including ST-Link) are served by pyOCD using the Arm CMSIS Debugger extension . Segger J-Link Server is supported. Arm Debugger is supported. Running on Arm FVPs is possible. Arm Keil \u00b5Vision is supported (only on Windows). If you are using a third-party debug adapter, make sure that the latest drivers are installed on your machine and that the debug adapters are running the latest firmware. Set the PATH variable correctly. Debug Adapter Notes Arm ULINKplus Make sure that the V2.x.x firmware is installed. Infineon KitProg3 Make sure that the latest firmware is installed . Microchip PICKit Basic Use the Python utility pycmsisdapswitcher to switch the firmware to a CMSIS-DAP v2 implementation. Nuvoton NuLink Make sure that the latest firmware is installed . NXP MCU-Link Make sure that the latest firmware is installed . Raspberry Pi Debugprobe Make sure that the latest firmware is installed . SEGGER J-Link For J-Link support, visit J-Link/J-Trace Downloads . Set the PATH variable to the bin directory of the installation. STMicroelectronics ST-Link For ST-LINK/V2 and ST-LINK/V2-1 support on Windows, download the USB driver here: STSW-LINK009 .","title":"Debug adapter support"},{"location":"debug.html#select-debug-adapter","text":"In the CMSIS view , open the Manage Solution dialog and go to the Debug Adapter section . Select one of the debug adapters. Once selected, the following JSON files are created automatically: In the launch.json file, attach and launch configurations are added that let you attach the debug adapter to an already running GDB instance (for example when you have issued a load and run before) or launch a new debug session. In the tasks.json file, the tasks CMSIS Erase , CMSIS Load , and CMSIS Run are created. Note If you wish to preserve manual modification to the JSON files, uncheck \"Update launch.json and tasks.json\" in the Debug Adapter for ... section.","title":"Select debug adapter"},{"location":"debug.html#set-debug-adapter-id","text":"In case you have multiple debug adapters connected to your computer, you can set the ID of the probe you wish to use in the CMSIS Solution extension settings. Open the settings by pressing CTRL/CMD + , . Enter probe in the search field. Select if you want to set the probe ID for your user or only for the current workspace (recommended). Enter the Unique ID you have retrieved using Target Information .","title":"Set debug adapter ID"},{"location":"debug.html#configure-run-and-debug","text":"In VS Code, you can integrate external tools via a tasks.json file. The debug configuration is managed via the launch.json file. Both files are generated automatically based on your *.csolution.yml file: When creating a Target Set in the Manage Solution view and selecting a Debug Adapter , the information is stored in the target-set: node in the *.csolution.yml file (refer to the CMSIS-Toolbox user's guide for details on target-set ). When you save the target set, the CMSIS Solution extension calls cbuild setup that generates the *.cbuild-run.yml file which contains the run and debug description of your solution. Using template files for the various debug adapters from the Debug Adapter Registry and taking the user inputs into account, the CMSIS Solution extension then generates the launch.json and tasks.json files.","title":"Configure run and debug"},{"location":"debug.html#custom-launchjson-and-tasksjson-settings","text":"User defined launch configurations and tasks can be added directly into the workspace files. When updating these files custom or modified entries are kept untouched if detected: .vscode/launch.json Each auto-generated configuration has an additional property cmsis.updateConfiguration=\"auto\" . By either removing this property, or by setting it to manual will exclude it from further automatic updates. .vscode/tasks.json All auto-generated tasks have labels starting with CMSIS . Such tasks are removed on updates. Custom tasks must assure they use names not starting with CMSIS . Instead of adding custom content into these automatically updated files causing version system modifications all the time, one can extract those into configuration subfolders and only keep these under version control: .vscode/launch.json.d/*.json Each JSON file must respect the launch.json schema. All contained configurations are merged into the workspace .vscode/launch.json file by name property. Auto-generated configurations can be overwritten if required without attention to the cmsis.updateConfiguration property. .vscode/tasks.json.d/*.json Each JSON file must respect the tasks.json schema. All contained tasks are merged into the workspace .vscode/tasks.json file by label property. Auto-generated CMSIS tasks can be overwritten if required. For multi-solution workspaces, i.e., having multiple .csolution.yml files in subfolders, solution-specific files in solution's .vscode/launch.json.d/ and .vscode/tasks.json.d/ directories are included for the active solution applying the same rules as above. This can be used to include solution specific content into the workspace configuration based on the currently used solution.","title":"Custom launch.json and tasks.json settings"},{"location":"debug.html#pyocd","text":"In the Manage Solution dialog, select the one of the debug adapters named xyz@pyOCD : For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Text File: saves the output to a file in the project workspace. Disabled: does not redirect the serial output.","title":"pyOCD"},{"location":"debug.html#j-link-server","text":"In the Manage Solution dialog select J-Link Server . For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Disabled: does not redirect the serial output.","title":"J-Link Server"},{"location":"debug.html#arm-debugger","text":"You can use the Arm Debugger with Keil Studio.","title":"Arm Debugger"},{"location":"debug.html#prerequisites","text":"Before you can launch a debug session using Arm Debugger, you need to: Install the Arm Debugger VS Code extension . Add the Arm Debugger to your vcpkg-configuration.json file, for example: \"arm:debuggers/arm/armdbg\": \"6.6.0\"","title":"Prerequisites"},{"location":"debug.html#setup-for-arm-debugger","text":"In the Manage Solution dialog, select the one of the debug adapters named xyz@Arm-Debugger .","title":"Setup for Arm Debugger"},{"location":"debug.html#arm-fvps","text":"In the Manage Solution dialog: Select the Arm-FVP debug adapter Select the model you wish to use Point to your configuration file If you wish to set a simulation limit, add this in the Misc box:","title":"Arm FVPs"},{"location":"debug.html#keil-uvision","text":"In the Manage Solution dialog: Select the Keil uVision debug adapter. Set the path to the UV4.exe file (the default is %LOCALAPPDATA%\\Keil_v5\\UV4\\UV4.exe ). This setting is saved in the *.csolution.yml file. Attention This only works on a Windows PC.","title":"Keil uVision"},{"location":"debug.html#changing-the-default-for-the-current-workspace","text":"If you wish to change the default path to \u00b5Vision for your current workspace , you need to create the following entry in your .vscode/settings.json file: { \"cmsis-csolution.debug-adapters\": { \"Keil uVision\": { \"uv4\": \"/path/to/UV4.exe\" } } } Attention If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default.","title":"Changing the default for the current workspace"},{"location":"debug.html#changing-the-default-for-a-user","text":"If you wish to set the \u00b5Vision path for your user, open the global settings.json file: Press Ctrl/Cmd + Shift + p and type settings . Select Preferences: Open User Settings (JSON) . This opens the global settings.json file. Enter the path as shown above and save the file.","title":"Changing the default for a user"},{"location":"debug.html#enhancing-the-debug-experience","text":"To ensure the best debug experience with Arm Compiler for Embedded, make sure that your CMSIS solution files contain the following.","title":"Enhancing the debug experience"},{"location":"debug.html#csolutionyml","text":"In the *.csolution.yml file, insert the following block in - target-types\\- type section: target-set: - set: debugger: name: # set to name of your debug adapter Insert the following before the - projects section: misc: - for-compiler: AC6 C-CPP: - -gdwarf-5 ASM: - -gdwarf-5","title":"csolution.yml"},{"location":"debug.html#cprojectyml","text":"In the *.cproject.yml file, add at the end: output: type: - elf - hex - map","title":"cproject.yml"},{"location":"featureroadmap.html","text":"Roadmap Project management Project creation and organization Feature Description \ud83d\udfe2 Project creation Create, open, and manage CMSIS solution projects \ud83d\udfe2 Multi-project solution Manage multiple related projects within a single CMSIS solution \ud83d\udfe2 Multi-solution workspace Manage multiple solutions within one workspace (VS Code built-in) \ud83d\udfe2 Target types Multiple targets (e.g., HW, models) within one solution \ud83d\udfe2 Build types Multiple build types (e.g., Debug, Release) within one solution \ud83d\udfe2 File groups Logical grouping of source, header, and library files \ud83d\udfe2 Layer support Easily retarget hardware connections \ud83d\udfe2 Software components Manage software components on a project/layer level \ud83d\udfe1 Manage packs Manage CMSIS-Packs and versions graphically \ud83d\udfe2 Zephyr project support Build and debug Zephyr-based applications \ud83d\udfe2 Configuration Wizard GUI-assisted generation and modification of configuration code Build system Feature Description \ud83d\udfe2 Integrated build Based on CMSIS-Toolbox \ud83d\udfe2 Incremental build Dependency tracking to rebuild only changed files \ud83d\udfe2 Toolchain options Per-target configuration of compiler, assembler, linker, and debugger \ud83d\udfe2 west support Build Zephyr projects natively Build output and feedback Feature Description \ud83d\udfe2 Map file Memory map of the image \ud83d\udfe2 Build log Detailed output of errors, warnings, and build status \ud83d\udfe2 Error navigation Direct navigation from build messages to source code Integration and extensibility Feature Description \ud83d\udfe2 External tools Invoke third-party tools via configurable commands \ud83d\udfe2 Version control Excellent integration with Git (VS Code built-in) \ud83d\udfe2 AI coding agents Integration with third-party coding agents (via VS Code extensions) \ud83d\udfe2 Additional extensions Use third-party extensions with Keil Studio (VS Code built-in) Compiler support Feature Description \ud83d\udfe2 Arm Compiler for Embedded (AC6) Professional toolchain from Arm \ud83d\udfe2 Arm Toolchain for Embedded (ATfE) Open-source, LLVM-based toolchain from Arm \ud83d\udfe2 Arm GNU Toolchain (GCC) Open-source, GCC-based toolchain from Arm \ud83d\udfe2 Clangd support For comprehensive code completion \ud83d\udfe2 Library generation Generate libraries using library manager \ud83d\udfe2 Compiler and assembler control options Interface for configuring compiler flags and options Debug Core debug control Category Debug Features \ud83d\udfe2 Run control Run, halt, reset, step into, step over, step out \ud83d\udfe2 Breakpoints Various types of breakpoints \ud83d\udfe1 Watchpoints Data read/write/access breakpoints (DWT) \ud83d\udfe2 Multi-core Single GUI for multiple cores in a device Register and memory inspection Category Debug Features \ud83d\udfe2 Core registers R0\u2013R15, PSR, MSP, PSP, CONTROL \ud83d\udfe1 Core peripheral registers NVIC, SysTick, MPU \ud83d\udfe2 Peripheral registers CMSIS-SVD decoded peripheral views \ud83d\udfe2 Memory inspection Configurable memory views \ud83d\udfe2 Memory inspection Memory access breakpoints \ud83d\udfe2 Memory inspection Memory window live update Source-level debugging Category Debug Features \ud83d\udfe2 Variables Call stack view \ud83d\udfe2 Variables Local variable inspection \ud83d\udfe2 Disassembly Disassembly window \ud83d\udfe1 Disassembly Sync Disassembly and source \ud83d\udfe2 Variable inspection Inline variable display \ud83d\udfe2 Variable inspection Variable hover inspection \ud83d\udfe1 Execution flow Function call trace Real-time and trace features Category Debug Features \ud83d\udfe1 Serial wire output ITM printf -style output \ud83d\udfe2 Variable tracing Real-time data watch \ud83d\udfe1 Event tracing Exception trace \ud83d\udfe1 Event tracing Interrupt trace \ud83d\udfe2 Sampling CPU time \ud83d\udfe1 Embedded trace buffer ETB instruction trace \ud83d\udfe1 Micro trace buffer MTB instruction trace \ud83d\udd34 Instruction trace Embedded trace macrocell Component Viewer and Event Recorder Category Debug Features \ud83d\udfe1 Component Viewer Display and live update \ud83d\udfe1 Event Recorder Show event information \ud83d\udfe1 Event Recorder Save/log \ud83d\udfe1 Event Recorder Event filtering \ud83d\udfe1 Event Recorder Event statistics RTOS awareness Category Debug Features \ud83d\udfe2 RTOS support Keil RTX5, FreeRTOS, Zephyr awareness \ud83d\udfe2 Thread visibility Thread list and state display \ud83d\udfe2 Stack usage Per-task stack usage Analysis and visualization Category Debug Features \ud83d\udfe1 Logic Analyzer Graphical variable and signal display \ud83d\udfe1 System Analyzer Data trace, core clock, ITM, current/voltage \ud83d\udfe2 Serial monitor Communication via serial/TCP ports \ud83d\udd34 Performance analysis Execution time analysis \ud83d\udd34 Performance analysis Function profiling \ud83d\udd34 Execution statistics Code coverage \ud83d\udfe1 Execution statistics Timing statistics (only via Event Recorder) Simulation Category Debug Features \ud83d\udfe2 Fast models (FVPs) Instruction-accurate CPU simulation \ud83d\udfe1 Debug FVPs Debugging on FVPs Note FVP simulation models are not available in the MDK-Essential edition. Debug probe support Category Debug Features \ud83d\udfe2 Debug probes ULINK2/UILNKplus support \ud83d\udfe1 Debug probes UILNKpro support \ud83d\udfe2 Debug probes CMSIS-DAP support \ud83d\udfe2 Debug probes J-Link support \ud83d\udfe2 Debug interfaces SWD \ud83d\udfe2 Debug interfaces JTAG \ud83d\udfe2 Debug interfaces Target detection \ud83d\udfe1 Debug interfaces Connect configuration \ud83d\udfe2 Flash programming Flash download \ud83d\udfe1 Flash programming Flash verification \ud83d\udfe1 Flash programming Configuration Legend \ud83d\udfe2 available \ud83d\udfe1 feature implementation progressing \ud83d\udd34 investigating for alternative solution","title":"Features and roadmap"},{"location":"featureroadmap.html#roadmap","text":"","title":"Roadmap"},{"location":"featureroadmap.html#project-management","text":"","title":"Project management"},{"location":"featureroadmap.html#project-creation-and-organization","text":"Feature Description \ud83d\udfe2 Project creation Create, open, and manage CMSIS solution projects \ud83d\udfe2 Multi-project solution Manage multiple related projects within a single CMSIS solution \ud83d\udfe2 Multi-solution workspace Manage multiple solutions within one workspace (VS Code built-in) \ud83d\udfe2 Target types Multiple targets (e.g., HW, models) within one solution \ud83d\udfe2 Build types Multiple build types (e.g., Debug, Release) within one solution \ud83d\udfe2 File groups Logical grouping of source, header, and library files \ud83d\udfe2 Layer support Easily retarget hardware connections \ud83d\udfe2 Software components Manage software components on a project/layer level \ud83d\udfe1 Manage packs Manage CMSIS-Packs and versions graphically \ud83d\udfe2 Zephyr project support Build and debug Zephyr-based applications \ud83d\udfe2 Configuration Wizard GUI-assisted generation and modification of configuration code","title":"Project creation and organization"},{"location":"featureroadmap.html#build-system","text":"Feature Description \ud83d\udfe2 Integrated build Based on CMSIS-Toolbox \ud83d\udfe2 Incremental build Dependency tracking to rebuild only changed files \ud83d\udfe2 Toolchain options Per-target configuration of compiler, assembler, linker, and debugger \ud83d\udfe2 west support Build Zephyr projects natively","title":"Build system"},{"location":"featureroadmap.html#build-output-and-feedback","text":"Feature Description \ud83d\udfe2 Map file Memory map of the image \ud83d\udfe2 Build log Detailed output of errors, warnings, and build status \ud83d\udfe2 Error navigation Direct navigation from build messages to source code","title":"Build output and feedback"},{"location":"featureroadmap.html#integration-and-extensibility","text":"Feature Description \ud83d\udfe2 External tools Invoke third-party tools via configurable commands \ud83d\udfe2 Version control Excellent integration with Git (VS Code built-in) \ud83d\udfe2 AI coding agents Integration with third-party coding agents (via VS Code extensions) \ud83d\udfe2 Additional extensions Use third-party extensions with Keil Studio (VS Code built-in)","title":"Integration and extensibility"},{"location":"featureroadmap.html#compiler-support","text":"Feature Description \ud83d\udfe2 Arm Compiler for Embedded (AC6) Professional toolchain from Arm \ud83d\udfe2 Arm Toolchain for Embedded (ATfE) Open-source, LLVM-based toolchain from Arm \ud83d\udfe2 Arm GNU Toolchain (GCC) Open-source, GCC-based toolchain from Arm \ud83d\udfe2 Clangd support For comprehensive code completion \ud83d\udfe2 Library generation Generate libraries using library manager \ud83d\udfe2 Compiler and assembler control options Interface for configuring compiler flags and options","title":"Compiler support"},{"location":"featureroadmap.html#debug","text":"","title":"Debug"},{"location":"featureroadmap.html#core-debug-control","text":"Category Debug Features \ud83d\udfe2 Run control Run, halt, reset, step into, step over, step out \ud83d\udfe2 Breakpoints Various types of breakpoints \ud83d\udfe1 Watchpoints Data read/write/access breakpoints (DWT) \ud83d\udfe2 Multi-core Single GUI for multiple cores in a device","title":"Core debug control"},{"location":"featureroadmap.html#register-and-memory-inspection","text":"Category Debug Features \ud83d\udfe2 Core registers R0\u2013R15, PSR, MSP, PSP, CONTROL \ud83d\udfe1 Core peripheral registers NVIC, SysTick, MPU \ud83d\udfe2 Peripheral registers CMSIS-SVD decoded peripheral views \ud83d\udfe2 Memory inspection Configurable memory views \ud83d\udfe2 Memory inspection Memory access breakpoints \ud83d\udfe2 Memory inspection Memory window live update","title":"Register and memory inspection"},{"location":"featureroadmap.html#source-level-debugging","text":"Category Debug Features \ud83d\udfe2 Variables Call stack view \ud83d\udfe2 Variables Local variable inspection \ud83d\udfe2 Disassembly Disassembly window \ud83d\udfe1 Disassembly Sync Disassembly and source \ud83d\udfe2 Variable inspection Inline variable display \ud83d\udfe2 Variable inspection Variable hover inspection \ud83d\udfe1 Execution flow Function call trace","title":"Source-level debugging"},{"location":"featureroadmap.html#real-time-and-trace-features","text":"Category Debug Features \ud83d\udfe1 Serial wire output ITM printf -style output \ud83d\udfe2 Variable tracing Real-time data watch \ud83d\udfe1 Event tracing Exception trace \ud83d\udfe1 Event tracing Interrupt trace \ud83d\udfe2 Sampling CPU time \ud83d\udfe1 Embedded trace buffer ETB instruction trace \ud83d\udfe1 Micro trace buffer MTB instruction trace \ud83d\udd34 Instruction trace Embedded trace macrocell","title":"Real-time and trace features"},{"location":"featureroadmap.html#component-viewer-and-event-recorder","text":"Category Debug Features \ud83d\udfe1 Component Viewer Display and live update \ud83d\udfe1 Event Recorder Show event information \ud83d\udfe1 Event Recorder Save/log \ud83d\udfe1 Event Recorder Event filtering \ud83d\udfe1 Event Recorder Event statistics","title":"Component Viewer and Event Recorder"},{"location":"featureroadmap.html#rtos-awareness","text":"Category Debug Features \ud83d\udfe2 RTOS support Keil RTX5, FreeRTOS, Zephyr awareness \ud83d\udfe2 Thread visibility Thread list and state display \ud83d\udfe2 Stack usage Per-task stack usage","title":"RTOS awareness"},{"location":"featureroadmap.html#analysis-and-visualization","text":"Category Debug Features \ud83d\udfe1 Logic Analyzer Graphical variable and signal display \ud83d\udfe1 System Analyzer Data trace, core clock, ITM, current/voltage \ud83d\udfe2 Serial monitor Communication via serial/TCP ports \ud83d\udd34 Performance analysis Execution time analysis \ud83d\udd34 Performance analysis Function profiling \ud83d\udd34 Execution statistics Code coverage \ud83d\udfe1 Execution statistics Timing statistics (only via Event Recorder)","title":"Analysis and visualization"},{"location":"featureroadmap.html#simulation","text":"Category Debug Features \ud83d\udfe2 Fast models (FVPs) Instruction-accurate CPU simulation \ud83d\udfe1 Debug FVPs Debugging on FVPs Note FVP simulation models are not available in the MDK-Essential edition.","title":"Simulation"},{"location":"featureroadmap.html#debug-probe-support","text":"Category Debug Features \ud83d\udfe2 Debug probes ULINK2/UILNKplus support \ud83d\udfe1 Debug probes UILNKpro support \ud83d\udfe2 Debug probes CMSIS-DAP support \ud83d\udfe2 Debug probes J-Link support \ud83d\udfe2 Debug interfaces SWD \ud83d\udfe2 Debug interfaces JTAG \ud83d\udfe2 Debug interfaces Target detection \ud83d\udfe1 Debug interfaces Connect configuration \ud83d\udfe2 Flash programming Flash download \ud83d\udfe1 Flash programming Flash verification \ud83d\udfe1 Flash programming Configuration Legend \ud83d\udfe2 available \ud83d\udfe1 feature implementation progressing \ud83d\udd34 investigating for alternative solution","title":"Debug probe support"},{"location":"importuv.html","text":"Import a Keil \u00b5Vision project In Keil Studio, you can convert a Keil \u03bcVision project to a CMSIS solution by opening the folder that contains the *.uvprojx file that you want to convert. Then, do one of the following: From the Explorer view , right-click the *.uvprojx file and select Convert \u03bcVision project to CMSIS solution . From the CMSIS view , choose one of the following options: Click Convert a \u03bcVision Project to CMSIS Solution and open your *.uvprojx file to convert it. Click Views and More Actions , then select Convert \u03bcVision project to CMSIS solution and open your *.uvprojx file to convert it. A dialog box displays. You can carry out the following tasks: - Open the solution in a new workspace with the **Open** option. - Open the solution in a new window and new workspace with the **Open project in new window** option. You can also run the CMSIS: Convert \u03bcVision project to CMSIS solution command from the Command Palette. In that case, select the *.uvprojx that you want to convert on your machine and click Select. If a *.csolution.yml file already exists in the same folder as the *.uvprojx file , then a pop-up message displays in the bottom right-hand corner. Click Overwrite to overwrite the existing file. The conversion starts immediately. Confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in your vcpkg-configuration.json file. Check the Output tab. If there are any conversion errors and warnings, they display in the CMSIS Solution category. You can also check the uv2csolution.log file. The *.cproject.yml and *.csolution.yml files are available in the folder where the *.uvprojx is stored. Caveats Depending on how your \u00b5Vision project is written, the conversion may encounter problems. The following is a (non-exhaustive) list of issues you might see. Using Arm Compiler 5 The conversion does not work with Arm Compiler 5-based projects. Only projects using Arm Compiler 6 can be converted. Solution Update an Arm Compiler 5 project to Arm Compiler 6 in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Note For more information, see the Migrate Arm Compiler 5 to Arm Compiler 6 application note and the Arm Compiler for Embedded Migration and Compatibility Guide . Using dollar sign in linker misc controls In \u00b5Vision, you can use the dollar sign ( $ ) for Linker misc options in the Options for Target dialog: This will cause a malformed YML access sequence in the generated cproject.yml file that will fail during builds. Solution Remove the $ sign and save the project in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Using dots in project file names In \u00b5Vision project names, you can use the dot, e.g. MyProject_1.0.uvprojx. In CMSIS solution project format, dots are used to separate project names, build type, and target types (refer to Context ). Thus, using dots in project names will lead to: error csolution: schema check failed, verify syntax Solution Remove dots from project names. Project located in paths containing a dollar sign In some operating systems, paths can contain the dollar ( $ ) sign. Building the project will fail with a similar message: error csolution: malformed access sequence: '/$test/Blinky_FRDM-K32L3A6 Solution Use the -O option to redirect all output to a directory without the $ sign. Component mismatches when using generators Older projects using GPDSC-based generators will see an issue after the conversion. In the original uvprojx file, an entry for STM32CubeMX could look like this: Modern DFPs with generator support would look like: uv2csolution adds a non-existing pack node Keil::FrameworkCubeMX@^1.0.0 which will lead to an error like this: error csolution: required pack: Keil::FrameworkCubeMX@^1.0.0 not installed Solution Delete the corresponding line from the cproject.yml file.","title":"Import uVision projects"},{"location":"importuv.html#import-a-keil-vision-project","text":"In Keil Studio, you can convert a Keil \u03bcVision project to a CMSIS solution by opening the folder that contains the *.uvprojx file that you want to convert. Then, do one of the following: From the Explorer view , right-click the *.uvprojx file and select Convert \u03bcVision project to CMSIS solution . From the CMSIS view , choose one of the following options: Click Convert a \u03bcVision Project to CMSIS Solution and open your *.uvprojx file to convert it. Click Views and More Actions , then select Convert \u03bcVision project to CMSIS solution and open your *.uvprojx file to convert it. A dialog box displays. You can carry out the following tasks: - Open the solution in a new workspace with the **Open** option. - Open the solution in a new window and new workspace with the **Open project in new window** option. You can also run the CMSIS: Convert \u03bcVision project to CMSIS solution command from the Command Palette. In that case, select the *.uvprojx that you want to convert on your machine and click Select. If a *.csolution.yml file already exists in the same folder as the *.uvprojx file , then a pop-up message displays in the bottom right-hand corner. Click Overwrite to overwrite the existing file. The conversion starts immediately. Confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in your vcpkg-configuration.json file. Check the Output tab. If there are any conversion errors and warnings, they display in the CMSIS Solution category. You can also check the uv2csolution.log file. The *.cproject.yml and *.csolution.yml files are available in the folder where the *.uvprojx is stored.","title":"Import a Keil \u00b5Vision project"},{"location":"importuv.html#caveats","text":"Depending on how your \u00b5Vision project is written, the conversion may encounter problems. The following is a (non-exhaustive) list of issues you might see.","title":"Caveats"},{"location":"importuv.html#using-arm-compiler-5","text":"The conversion does not work with Arm Compiler 5-based projects. Only projects using Arm Compiler 6 can be converted. Solution Update an Arm Compiler 5 project to Arm Compiler 6 in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Note For more information, see the Migrate Arm Compiler 5 to Arm Compiler 6 application note and the Arm Compiler for Embedded Migration and Compatibility Guide .","title":"Using Arm Compiler 5"},{"location":"importuv.html#using-dollar-sign-in-linker-misc-controls","text":"In \u00b5Vision, you can use the dollar sign ( $ ) for Linker misc options in the Options for Target dialog: This will cause a malformed YML access sequence in the generated cproject.yml file that will fail during builds. Solution Remove the $ sign and save the project in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code.","title":"Using dollar sign in linker misc controls"},{"location":"importuv.html#using-dots-in-project-file-names","text":"In \u00b5Vision project names, you can use the dot, e.g. MyProject_1.0.uvprojx. In CMSIS solution project format, dots are used to separate project names, build type, and target types (refer to Context ). Thus, using dots in project names will lead to: error csolution: schema check failed, verify syntax Solution Remove dots from project names.","title":"Using dots in project file names"},{"location":"importuv.html#project-located-in-paths-containing-a-dollar-sign","text":"In some operating systems, paths can contain the dollar ( $ ) sign. Building the project will fail with a similar message: error csolution: malformed access sequence: '/$test/Blinky_FRDM-K32L3A6 Solution Use the -O option to redirect all output to a directory without the $ sign.","title":"Project located in paths containing a dollar sign"},{"location":"importuv.html#component-mismatches-when-using-generators","text":"Older projects using GPDSC-based generators will see an issue after the conversion. In the original uvprojx file, an entry for STM32CubeMX could look like this: Modern DFPs with generator support would look like: uv2csolution adds a non-existing pack node Keil::FrameworkCubeMX@^1.0.0 which will lead to an error like this: error csolution: required pack: Keil::FrameworkCubeMX@^1.0.0 not installed Solution Delete the corresponding line from the cproject.yml file.","title":"Component mismatches when using generators"},{"location":"installation.html","text":"Installation Prerequisites Arm Keil Studio is a set of extensions for Microsoft Visual Studio Code , which is required to be installed on your machine. Installing Keil Studio The Arm Keil Studio Pack (MDK v6) extension pack includes the extensions that are required to work with CMSIS solution projects. In VS Code, open the Extensions view. Type Arm in the search bar. Click on \"Arm Keil Studio Pack\" and README is shown on the right. It contains links to the included extensions. Their READMEs include minimal user guides. Click Install to start. You need to trust the publishers \"Arm\" and \"LLVM\" to install the extension pack. When the installation is finished, the CMSIS view icon appears in the activity bar. Verify the installation Once you have installed Keil Studio, you can verify your installation by following the getting started guide that opens automatically: It's best practice to create a new CMSIS solution based on a Blinky example, which typically flashes an LED on a target board. Note When creating a solution based on an example, all required tools and packs are installed automatically. Set up a new workspace If you want to install tools and packs separately, you have to create a new workspace in VS Code by opening a blank folder. Tool installation Required tools (such as a compiler toolchain or the CMSIS-Toolbox) are installed via the Arm Tools Environment Manager , controlled by the vcpkg-configuration.json file. Open the Arm Tools Environment Manager via the command pallette (Ctrl/Cmd + Shift + p) and select Arm Tools: Configure Arm Tools Environment . The \"Arm Registry\" opens: Select at least an \"Arm CMSIS-Toolbox\" version as this is required to be able to install packs . The Output pane shows the status of the \"Arm Tools\" installation. Attention If you are using Keil Studio for the first time, the Arm Tools Environment Manager needs to download required tools from the Internet. This may take a couple of minutes (depending on your internet connection). You also need to provide a license. A free, non-commercial MDK-Community license can be activated from within the tool. If you need a commercial license, check our eStore or contact your preferred distributor . Pack installation CMSIS-Packs for device and board support as well as software delivery mechanism are an integral part of a CMSIS solution. Packs can be discovered online: List of CMSIS-Packs List of devices List of boards Each page contains information about how to download a pack with cpackget : Run this command in a Terminal (you will be asked to accept the license agreement): \u276f cpackget add Keil::MDK-Middleware@8.0.0 I: Updating public index I: Downloading index.pidx... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (216/216 kB, 405 kB/s) I: Updating PDSC files of public packs I: Adding pack \"Keil::MDK-Middleware@8.0.0\" I: Extracting files to /Users/chrsei01/.cache/arm/packs/Keil/MDK-Middleware/8.0.0... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (2180/2180, 2187 it/s) Activating Keil Studio Some of the Arm tools (for example Arm Compiler for Embedded and Arm Debugger ) require activation. You will be flagged with a pop up window: Click on \"Manage Arm license\" in the pop up. At the top, a new drop-down opens: If you want to evaluate Keil Studio or use it for non-commercial development, select \"Activate Arm Keil MDK Community Edition\". If you have a valid UBL server or activation code, use \"Activate or manage Arm licenses\" to activate Keil Studio. Note Open-source tools, such as Arm GNU Toolchain and Arm CMSIS Debugger do not require activation. For more information visit the user-based licensing web page. Configure the extension Press Ctrl+, (Windows and Linux) or Cmd+, (macOS) or go to at the bottom of the Activity Bar and select Settings . Then, select CMSIS Solution to change the extension settings. The available settings are: Setting Description Auto Debug Launch Create or update launch.json and tasks.json with the Debug Adapter configuration of the CMSIS solution project. Download Packs CMSIS-Toolbox downloads required software packs using cpackget during setup and project build. This option enables the option --packs for cbuild . Environment Variables Specify additional environment variables to be set for build, run, and terminals. Exclude Configure a glob pattern for excluding files and folders in searches for csolution files. Experimental Features Use the checkbox to enable experimental features. Generate Clang Setup Use the checkbox to automatically generate the required setup ( .clangd file and .vscode/settings.json ) for the active solution context. For Arm Compiler 6, include pre-defined macros in the .clangd file. Output Directory Enter an output directory prefix for 'outdir' and 'tmpdir' and relocated build information files (experimental). Probe-ID Specufy the unique identifier of a probe to be used for debugging. Use Web Services Use the checkbox to enable web services to obtain information about devices, boards, and examples. If enabled, information from the internet and locally installed packs is used. If disabled, only information from installed packs is used.","title":"Installation"},{"location":"installation.html#installation","text":"","title":"Installation"},{"location":"installation.html#prerequisites","text":"Arm Keil Studio is a set of extensions for Microsoft Visual Studio Code , which is required to be installed on your machine.","title":"Prerequisites"},{"location":"installation.html#installing-keil-studio","text":"The Arm Keil Studio Pack (MDK v6) extension pack includes the extensions that are required to work with CMSIS solution projects. In VS Code, open the Extensions view. Type Arm in the search bar. Click on \"Arm Keil Studio Pack\" and README is shown on the right. It contains links to the included extensions. Their READMEs include minimal user guides. Click Install to start. You need to trust the publishers \"Arm\" and \"LLVM\" to install the extension pack. When the installation is finished, the CMSIS view icon appears in the activity bar.","title":"Installing Keil Studio"},{"location":"installation.html#verify-the-installation","text":"Once you have installed Keil Studio, you can verify your installation by following the getting started guide that opens automatically: It's best practice to create a new CMSIS solution based on a Blinky example, which typically flashes an LED on a target board. Note When creating a solution based on an example, all required tools and packs are installed automatically.","title":"Verify the installation"},{"location":"installation.html#set-up-a-new-workspace","text":"If you want to install tools and packs separately, you have to create a new workspace in VS Code by opening a blank folder.","title":"Set up a new workspace"},{"location":"installation.html#tool-installation","text":"Required tools (such as a compiler toolchain or the CMSIS-Toolbox) are installed via the Arm Tools Environment Manager , controlled by the vcpkg-configuration.json file. Open the Arm Tools Environment Manager via the command pallette (Ctrl/Cmd + Shift + p) and select Arm Tools: Configure Arm Tools Environment . The \"Arm Registry\" opens: Select at least an \"Arm CMSIS-Toolbox\" version as this is required to be able to install packs . The Output pane shows the status of the \"Arm Tools\" installation. Attention If you are using Keil Studio for the first time, the Arm Tools Environment Manager needs to download required tools from the Internet. This may take a couple of minutes (depending on your internet connection). You also need to provide a license. A free, non-commercial MDK-Community license can be activated from within the tool. If you need a commercial license, check our eStore or contact your preferred distributor .","title":"Tool installation"},{"location":"installation.html#pack-installation","text":"CMSIS-Packs for device and board support as well as software delivery mechanism are an integral part of a CMSIS solution. Packs can be discovered online: List of CMSIS-Packs List of devices List of boards Each page contains information about how to download a pack with cpackget : Run this command in a Terminal (you will be asked to accept the license agreement): \u276f cpackget add Keil::MDK-Middleware@8.0.0 I: Updating public index I: Downloading index.pidx... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (216/216 kB, 405 kB/s) I: Updating PDSC files of public packs I: Adding pack \"Keil::MDK-Middleware@8.0.0\" I: Extracting files to /Users/chrsei01/.cache/arm/packs/Keil/MDK-Middleware/8.0.0... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (2180/2180, 2187 it/s)","title":"Pack installation"},{"location":"installation.html#activating-keil-studio","text":"Some of the Arm tools (for example Arm Compiler for Embedded and Arm Debugger ) require activation. You will be flagged with a pop up window: Click on \"Manage Arm license\" in the pop up. At the top, a new drop-down opens: If you want to evaluate Keil Studio or use it for non-commercial development, select \"Activate Arm Keil MDK Community Edition\". If you have a valid UBL server or activation code, use \"Activate or manage Arm licenses\" to activate Keil Studio. Note Open-source tools, such as Arm GNU Toolchain and Arm CMSIS Debugger do not require activation. For more information visit the user-based licensing web page.","title":"Activating Keil Studio"},{"location":"installation.html#configure-the-extension","text":"Press Ctrl+, (Windows and Linux) or Cmd+, (macOS) or go to at the bottom of the Activity Bar and select Settings . Then, select CMSIS Solution to change the extension settings. The available settings are: Setting Description Auto Debug Launch Create or update launch.json and tasks.json with the Debug Adapter configuration of the CMSIS solution project. Download Packs CMSIS-Toolbox downloads required software packs using cpackget during setup and project build. This option enables the option --packs for cbuild . Environment Variables Specify additional environment variables to be set for build, run, and terminals. Exclude Configure a glob pattern for excluding files and folders in searches for csolution files. Experimental Features Use the checkbox to enable experimental features. Generate Clang Setup Use the checkbox to automatically generate the required setup ( .clangd file and .vscode/settings.json ) for the active solution context. For Arm Compiler 6, include pre-defined macros in the .clangd file. Output Directory Enter an output directory prefix for 'outdir' and 'tmpdir' and relocated build information files (experimental). Probe-ID Specufy the unique identifier of a probe to be used for debugging. Use Web Services Use the checkbox to enable web services to obtain information about devices, boards, and examples. If enabled, information from the internet and locally installed packs is used. If disabled, only information from installed packs is used.","title":"Configure the extension"},{"location":"manage_settings.html","text":"Manage solutions In the Manage Solution view, you can select the active target , projects and images , and the debug adapter that you are using for target connectivity. In the CMSIS view , click to open the Manage Solution view: Active Target In this section, select the target for build, load, and debug: Select the target type that is used for build, run, and debug. The target set stores selected projects, images, and debug adapter configuration. If no target set name is specified, and empty is used. To specify your target types by editing the YAML file directly, click Edit csolution.yml . The status bar shows the current target type@target set (only the target type in case of a target set ): Projects and images In this section, select the projects, build types, and additional images that are included in the target set. Select the project(s) that are part of the solution. Select a build type for each project. You can set different build types for different projects in your solution. Set the load settings : Image & Symbols (default): debug adapter loads debug (DWARF) information and project output image. Symbols : debug adapter loads only debug (DWARF) information. Image : debug adapter loads only project output image. None : debug adapter does not use the output, however the project is included in build. Add further images with specific load settgings . To specify your projects and images by editing the YAML file directly, click Edit cproject.yml . Note If your *.csolution.yml file only includes one project, then you can't deselect it in this dialog as otherwise the solution can't be built. The projects and build types that you can select are defined by contexts for a particular target. Some options might be unavailable if they have been excluded for the target selected. To learn more about contexts and how to modify them, see the Context and Conditional build information in the CMSIS-Toolbox documentation. Errors and warnings You can inspect errors and warnings for a target set. For active projects in the target set, errors and warnings display when you move your cursor over the Target Set in the status bar. The indicator is red for errors and yellow in case of warnings. Click the indicator to open the Output tab for the CMSIS Solution category. If you previously closed the Manage Solution view, then this action also re-opens the view. You can also go to the Problems tab and check for errors. Debug Adapter A broad range of adapters is supported. Use this drop-down to select the debug adapter that you are using within the target set. Note Some of the debug adapters require further setup steps.","title":"Manage solutions"},{"location":"manage_settings.html#manage-solutions","text":"In the Manage Solution view, you can select the active target , projects and images , and the debug adapter that you are using for target connectivity. In the CMSIS view , click to open the Manage Solution view:","title":"Manage solutions"},{"location":"manage_settings.html#active-target","text":"In this section, select the target for build, load, and debug: Select the target type that is used for build, run, and debug. The target set stores selected projects, images, and debug adapter configuration. If no target set name is specified, and empty is used. To specify your target types by editing the YAML file directly, click Edit csolution.yml . The status bar shows the current target type@target set (only the target type in case of a target set ):","title":"Active Target"},{"location":"manage_settings.html#projects-and-images","text":"In this section, select the projects, build types, and additional images that are included in the target set. Select the project(s) that are part of the solution. Select a build type for each project. You can set different build types for different projects in your solution. Set the load settings : Image & Symbols (default): debug adapter loads debug (DWARF) information and project output image. Symbols : debug adapter loads only debug (DWARF) information. Image : debug adapter loads only project output image. None : debug adapter does not use the output, however the project is included in build. Add further images with specific load settgings . To specify your projects and images by editing the YAML file directly, click Edit cproject.yml . Note If your *.csolution.yml file only includes one project, then you can't deselect it in this dialog as otherwise the solution can't be built. The projects and build types that you can select are defined by contexts for a particular target. Some options might be unavailable if they have been excluded for the target selected. To learn more about contexts and how to modify them, see the Context and Conditional build information in the CMSIS-Toolbox documentation.","title":"Projects and images"},{"location":"manage_settings.html#errors-and-warnings","text":"You can inspect errors and warnings for a target set. For active projects in the target set, errors and warnings display when you move your cursor over the Target Set in the status bar. The indicator is red for errors and yellow in case of warnings. Click the indicator to open the Output tab for the CMSIS Solution category. If you previously closed the Manage Solution view, then this action also re-opens the view. You can also go to the Problems tab and check for errors.","title":"Errors and warnings"},{"location":"manage_settings.html#debug-adapter","text":"A broad range of adapters is supported. Use this drop-down to select the debug adapter that you are using within the target set. Note Some of the debug adapters require further setup steps.","title":"Debug Adapter"},{"location":"reldocs.html","text":"Related documentation These valuable resources help you getting further knowledge and insights into Keil MDK (its editions, licensing, legacy tools and example repositories). General product information Editions table Support page Release announcement Getting started guide Keil forum Videos and webinars Keil MDK v6 video tutorials Keil Studio webinar series Licensing User-Based Licensing (UBL) Knowledge Base article Subscription renewal for Arm developer store UBLs UBL resources on developer.arm.com UBL Administration Guide UBL User Guide Backwards compatibility (AC5, legacy tools) Video: Enabling legacy editions of Keil MDK Other documentation CMSIS-Toolbox user guide How to update the CMSIS-Toolbox version in \u00b5Vision installation?","title":"Related documentation"},{"location":"reldocs.html#related-documentation","text":"These valuable resources help you getting further knowledge and insights into Keil MDK (its editions, licensing, legacy tools and example repositories).","title":"Related documentation"},{"location":"reldocs.html#general-product-information","text":"Editions table Support page Release announcement Getting started guide Keil forum","title":"General product information"},{"location":"reldocs.html#videos-and-webinars","text":"Keil MDK v6 video tutorials Keil Studio webinar series","title":"Videos and webinars"},{"location":"reldocs.html#licensing","text":"User-Based Licensing (UBL) Knowledge Base article Subscription renewal for Arm developer store UBLs UBL resources on developer.arm.com UBL Administration Guide UBL User Guide Backwards compatibility (AC5, legacy tools) Video: Enabling legacy editions of Keil MDK","title":"Licensing"},{"location":"reldocs.html#other-documentation","text":"CMSIS-Toolbox user guide How to update the CMSIS-Toolbox version in \u00b5Vision installation?","title":"Other documentation"},{"location":"runexternal.html","text":"Run external tools VS Code uses the launch.json and tasks.json configuration files to integrate with external tools. The following section shows how to configure these files for typical use cases. Variables VS Code supports variable substitution in the Debugging and Tasks configuration files and selected settings. Variable substitution uses the ${variableName} syntax, for example in launch.json and tasks.json files. In addition to the VS Code built-in variables , the CMSIS Solution extension provides the following variables. Variable Description ${command:cmsis-csolution.getActiveTargetSet} Get name of active run and debug configuration (format: target-type@set) ${command:cmsis-csolution.getBinaryFile} The path and name of the first ELF/DWARF file available for the Active Target ${command:cmsis-csolution.getBinaryFiles} The paths and names of the ELF/DWARF files (comma separated) available for the Active Target ${command:cmsis-csolution.getBoardName} The board name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getBspName} The Board Support Pack (BSP) for the Active Target ${command:cmsis-csolution.getBspPath} The path to the content of the BSP for the Active Target ${command:cmsis-csolution.getCbuildRunFile} The path to the cbuild-run.yml file for the Active Target ${command:cmsis-csolution.getDeviceName} The device name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getDfpName} The Device Family Pack (DFP) for the Active Target ${command:cmsis-csolution.getDfpPath} The path to the content of the DFP for the Active Target ${command:cmsis-csolution.getProcessorName} The name of the processor for the Active Target; for multi-processor configurations start-pname ${command:cmsis-csolution.getSolutionFile} The path to the csolution.yml file for the Active Solution Note Active Solution refers to the csolution project that is currently loaded. Active Target refers to the target that is currently selected in the Manage Solution view. Substitution examples The following table illustrates the variable substition using the DualCore csolution example . Note that ... stands for the absolute path on the host computer that stores the csolution project or the CMSIS pack content . Variable Substitution ${command:cmsis-csolution.getBinaryFile} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf ${command:cmsis-csolution.getBinaryFiles} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf, .../DualCore/out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.axf ${command:cmsis-csolution.getBoardName} K32L3A60VPJ1A ${command:cmsis-csolution.getBspName} NXP::FRDM-K32L3A6_BSP@19.0.0 ${command:cmsis-csolution.getBspPath} .../NXP/FRDM-K32L3A6_BSP/19.0.0 ${command:cmsis-csolution.getCbuildRunFile} .../DualCore/DualCore+FRDM-K32L3A6.cbuild-run.yml ${command:cmsis-csolution.getDeviceName} K32L3A60VPJ1A ${command:cmsis-csolution.getDfpName} NXP::K32L3A60_DFP@19.0.0 ${command:cmsis-csolution.getDfpPath} .../NXP/K32L3A60_DFP/19.0.0 ${command:cmsis-csolution.getSolutionFile} .../DualCore/HelloWorld.csolution.yml Examples Arm Debugger Use the following launch.json file to start Arm Debugger: { \"version\": \"0.2.0\", \"configurations\": [ { \"name\": \"Arm Debugger\", \"type\": \"arm-debugger\", \"request\": \"launch\", \"serialNumber\": \"${command:device-manager.getSerialNumber}\", \"programs\": \"${command:cmsis-csolution.getBinaryFiles}\", \"cmsisPack\": \"${command:cmsis-csolution.getDfpPack}\", \"deviceName\": \"${command:cmsis-csolution.getDeviceName}\", } ] } Use \u00b5Vision for debugging The \u00b5Vision debugger offers advanced debug features such as Event Recorder and Component Viewer to analyze applications. To call \u00b5Vision with the csolution project that you are using in VS Code, add the following task to the .vscode\\tasks.json file. The command: is the path to the \u00b5Vision executable on your computer. \"tasks\": [ { \"label\": \"Start uVision\", \"type\": \"process\", \"command\": \"C:\\\\Keil_v5\\\\UV4\\\\UV4.exe\", \"args\": [ \"${command:cmsis-csolution.getSolutionFile}\" ], \"problemMatcher\": [] } ] Note This only works in Windows environments with \u00b5Vision installed on the local machine.","title":"Run external tools"},{"location":"runexternal.html#run-external-tools","text":"VS Code uses the launch.json and tasks.json configuration files to integrate with external tools. The following section shows how to configure these files for typical use cases.","title":"Run external tools"},{"location":"runexternal.html#variables","text":"VS Code supports variable substitution in the Debugging and Tasks configuration files and selected settings. Variable substitution uses the ${variableName} syntax, for example in launch.json and tasks.json files. In addition to the VS Code built-in variables , the CMSIS Solution extension provides the following variables. Variable Description ${command:cmsis-csolution.getActiveTargetSet} Get name of active run and debug configuration (format: target-type@set) ${command:cmsis-csolution.getBinaryFile} The path and name of the first ELF/DWARF file available for the Active Target ${command:cmsis-csolution.getBinaryFiles} The paths and names of the ELF/DWARF files (comma separated) available for the Active Target ${command:cmsis-csolution.getBoardName} The board name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getBspName} The Board Support Pack (BSP) for the Active Target ${command:cmsis-csolution.getBspPath} The path to the content of the BSP for the Active Target ${command:cmsis-csolution.getCbuildRunFile} The path to the cbuild-run.yml file for the Active Target ${command:cmsis-csolution.getDeviceName} The device name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getDfpName} The Device Family Pack (DFP) for the Active Target ${command:cmsis-csolution.getDfpPath} The path to the content of the DFP for the Active Target ${command:cmsis-csolution.getProcessorName} The name of the processor for the Active Target; for multi-processor configurations start-pname ${command:cmsis-csolution.getSolutionFile} The path to the csolution.yml file for the Active Solution Note Active Solution refers to the csolution project that is currently loaded. Active Target refers to the target that is currently selected in the Manage Solution view.","title":"Variables"},{"location":"runexternal.html#substitution-examples","text":"The following table illustrates the variable substition using the DualCore csolution example . Note that ... stands for the absolute path on the host computer that stores the csolution project or the CMSIS pack content . Variable Substitution ${command:cmsis-csolution.getBinaryFile} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf ${command:cmsis-csolution.getBinaryFiles} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf, .../DualCore/out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.axf ${command:cmsis-csolution.getBoardName} K32L3A60VPJ1A ${command:cmsis-csolution.getBspName} NXP::FRDM-K32L3A6_BSP@19.0.0 ${command:cmsis-csolution.getBspPath} .../NXP/FRDM-K32L3A6_BSP/19.0.0 ${command:cmsis-csolution.getCbuildRunFile} .../DualCore/DualCore+FRDM-K32L3A6.cbuild-run.yml ${command:cmsis-csolution.getDeviceName} K32L3A60VPJ1A ${command:cmsis-csolution.getDfpName} NXP::K32L3A60_DFP@19.0.0 ${command:cmsis-csolution.getDfpPath} .../NXP/K32L3A60_DFP/19.0.0 ${command:cmsis-csolution.getSolutionFile} .../DualCore/HelloWorld.csolution.yml","title":"Substitution examples"},{"location":"runexternal.html#examples","text":"","title":"Examples"},{"location":"runexternal.html#arm-debugger","text":"Use the following launch.json file to start Arm Debugger: { \"version\": \"0.2.0\", \"configurations\": [ { \"name\": \"Arm Debugger\", \"type\": \"arm-debugger\", \"request\": \"launch\", \"serialNumber\": \"${command:device-manager.getSerialNumber}\", \"programs\": \"${command:cmsis-csolution.getBinaryFiles}\", \"cmsisPack\": \"${command:cmsis-csolution.getDfpPack}\", \"deviceName\": \"${command:cmsis-csolution.getDeviceName}\", } ] }","title":"Arm Debugger"},{"location":"runexternal.html#use-vision-for-debugging","text":"The \u00b5Vision debugger offers advanced debug features such as Event Recorder and Component Viewer to analyze applications. To call \u00b5Vision with the csolution project that you are using in VS Code, add the following task to the .vscode\\tasks.json file. The command: is the path to the \u00b5Vision executable on your computer. \"tasks\": [ { \"label\": \"Start uVision\", \"type\": \"process\", \"command\": \"C:\\\\Keil_v5\\\\UV4\\\\UV4.exe\", \"args\": [ \"${command:cmsis-csolution.getSolutionFile}\" ], \"problemMatcher\": [] } ] Note This only works in Windows environments with \u00b5Vision installed on the local machine.","title":"Use \u00b5Vision for debugging"},{"location":"tipsandtricks.html","text":"Tips and tricks This chapter contains useful information to help you solve specific issues. Create vcpkg configuration file If your solution does not contain the vcpkg-configuration.json , right-click anywhere in the workspace and select Configure Arm Tools Environment . The Arm Tools Environment Manager extension then generates this file. Set current solution in workspace To activate a solution in the Solution outline view, use the Select Active Solution from workspace option in Views and More Actions : . Documentation does not open If you are using a Linux machine that uses the Snap package manager, your web browser will not be able to open documentation that is shipped in CMSIS-Packs as the CMSIS_PACK_ROOT directory is in ${HOME}/.cache/arm/packs which is not accessible to Snaps. Likewise, the Keil Studio help is located in ${HOME}/.vscode/extensions which is also not available. To get this working, use a browser that is not installed as a Snap package: Uninstall the Snap package. For example, run sudo snap remove firefox in a Terminal. Download the installer from the browser's web site. Install it on your machine. Memory and Peripheral Inspector are missing If your Debug view does not contain \"PERIPHERALS\" and you cannot open the Memory Inspector , check if the extensions are installed correctly. If you had previously uninstalled the Arm Debugger extension, these two extensions might have been removed with it. Just reinstall them via the Extensions view. Create a library file With Keil Studio, it is possible to create a library file. All you need to do is to change the output type in the *.cproject.yml file to lib : # Control output files (elf is generated by default) output: type: - lib In the CMSIS view , click . The Terminal output will look like this: Execute: cbuild /Users/user/project/Arm/ArmCM3/Library/Library.csolution.yml --build --context-set --packs +---------------------------------------------- (1/1) Cleaning context: \"Library.Debug+Library\" +---------------------------------------------- (1/1) Building context: \"Library.Debug+Library\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Library.Debug+Library' [1/2] Building C object CMakeFiles/Group_Source_Files.dir/Users/user/project/Arm/ArmCM3/Library/main.o [2/2] Linking C static library /Users/user/project/Arm/ArmCM3/Library/out/Library/Library/Debug/Library.lib +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:02 +============================================================ Completed: cbuild succeed with exit code 0 The corresponding library file will be present in the /out -directory. Note This only works with CMSIS-Toolbox starting v2.11.0. Downgrading tool versions When you downgrade a tool version in the vcpkg-configuration,json file, this will only be taken into account if you toggle the tools activation. Do the following: Click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Deactivate Environment . The status bar will show that tools are deactivated: Again, click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Reactivate Environment . The new settings will now the taken into account and you can start working with the downgraded tool version. STM32CubeMX generator issues If you are relying on the LL drivers, it may happen that STM32CubeMX does not generate/update a *.cgen.yml file. To get this fixed, go to: Project Manager Advanced Settings Select HAL (default) for at least one peripheral. If you rely on LL for your peripherals, select/add an unused peripheral: Now, the GENERATE CODE button creates/writes the *.cgen.yml file. Change variable display radix In the Watch and Live Watch views, you can change the radix of variables by using the set output-radix base command in the Debug Console . For example, > set output-radix 16 changes the radix to hexadecimal. Supported choices for base are decimal 8 , 10 , or 16 . Note The > is part of the entered command instructing the console processing to use GDB CLI. Refer to Numbers for more information.","title":"Tips and tricks"},{"location":"tipsandtricks.html#tips-and-tricks","text":"This chapter contains useful information to help you solve specific issues.","title":"Tips and tricks"},{"location":"tipsandtricks.html#create-vcpkg-configuration-file","text":"If your solution does not contain the vcpkg-configuration.json , right-click anywhere in the workspace and select Configure Arm Tools Environment . The Arm Tools Environment Manager extension then generates this file.","title":"Create vcpkg configuration file"},{"location":"tipsandtricks.html#set-current-solution-in-workspace","text":"To activate a solution in the Solution outline view, use the Select Active Solution from workspace option in Views and More Actions : .","title":"Set current solution in workspace"},{"location":"tipsandtricks.html#documentation-does-not-open","text":"If you are using a Linux machine that uses the Snap package manager, your web browser will not be able to open documentation that is shipped in CMSIS-Packs as the CMSIS_PACK_ROOT directory is in ${HOME}/.cache/arm/packs which is not accessible to Snaps. Likewise, the Keil Studio help is located in ${HOME}/.vscode/extensions which is also not available. To get this working, use a browser that is not installed as a Snap package: Uninstall the Snap package. For example, run sudo snap remove firefox in a Terminal. Download the installer from the browser's web site. Install it on your machine.","title":"Documentation does not open"},{"location":"tipsandtricks.html#memory-and-peripheral-inspector-are-missing","text":"If your Debug view does not contain \"PERIPHERALS\" and you cannot open the Memory Inspector , check if the extensions are installed correctly. If you had previously uninstalled the Arm Debugger extension, these two extensions might have been removed with it. Just reinstall them via the Extensions view.","title":"Memory and Peripheral Inspector are missing"},{"location":"tipsandtricks.html#create-a-library-file","text":"With Keil Studio, it is possible to create a library file. All you need to do is to change the output type in the *.cproject.yml file to lib : # Control output files (elf is generated by default) output: type: - lib In the CMSIS view , click . The Terminal output will look like this: Execute: cbuild /Users/user/project/Arm/ArmCM3/Library/Library.csolution.yml --build --context-set --packs +---------------------------------------------- (1/1) Cleaning context: \"Library.Debug+Library\" +---------------------------------------------- (1/1) Building context: \"Library.Debug+Library\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Library.Debug+Library' [1/2] Building C object CMakeFiles/Group_Source_Files.dir/Users/user/project/Arm/ArmCM3/Library/main.o [2/2] Linking C static library /Users/user/project/Arm/ArmCM3/Library/out/Library/Library/Debug/Library.lib +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:02 +============================================================ Completed: cbuild succeed with exit code 0 The corresponding library file will be present in the /out -directory. Note This only works with CMSIS-Toolbox starting v2.11.0.","title":"Create a library file"},{"location":"tipsandtricks.html#downgrading-tool-versions","text":"When you downgrade a tool version in the vcpkg-configuration,json file, this will only be taken into account if you toggle the tools activation. Do the following: Click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Deactivate Environment . The status bar will show that tools are deactivated: Again, click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Reactivate Environment . The new settings will now the taken into account and you can start working with the downgraded tool version.","title":"Downgrading tool versions"},{"location":"tipsandtricks.html#stm32cubemx-generator-issues","text":"If you are relying on the LL drivers, it may happen that STM32CubeMX does not generate/update a *.cgen.yml file. To get this fixed, go to: Project Manager Advanced Settings Select HAL (default) for at least one peripheral. If you rely on LL for your peripherals, select/add an unused peripheral: Now, the GENERATE CODE button creates/writes the *.cgen.yml file.","title":"STM32CubeMX generator issues"},{"location":"tipsandtricks.html#change-variable-display-radix","text":"In the Watch and Live Watch views, you can change the radix of variables by using the set output-radix base command in the Debug Console . For example, > set output-radix 16 changes the radix to hexadecimal. Supported choices for base are decimal 8 , 10 , or 16 . Note The > is part of the entered command instructing the console processing to use GDB CLI. Refer to Numbers for more information.","title":"Change variable display radix"},{"location":"userinterface.html","text":"User Interface The CMSIS Solution extension provides the Keil Studio GUI for project management and build tools with the CMSIS-Toolbox . Combined with other Arm and third-party extensions, it implements a powerful embedded development environment. The GUI consists of these views: View Description Explorer view lists all local files. Search view enables search/replace across all files. Source Control view allows you to work with git. Extensions view lets you work with VS Code extensions. Run and Debug view switches the GUI to a dedicated debug view . CMSIS view is the main view for working with CMSIS solution-based projects. Trace and Live view shows trace and live data during debugging. Note The ordering of the icons may be different in your VS Code environment. CMSIS view The CMSIS view shows the content of the active projects included in the solution. Each project contains configuration settings, source code files, build settings, and other project-specific information. The main area of the CMSIS view shows: Board and device information and related documentation. Groups and files : Groups and user files that you add to the project and that you can edit constructed-files : Contains generated files such as the RTE_Components.h header file for each context linker : Contains a linker script file and a .h file (or other user-defined header files) Components : Shows the software components selected for the project with their source files, user code templates, and APIs. Click the files to open them in the editor. Click the book icon of a component to open the related documentation. If you are using a generator to configure your device or board, then a Run Configuration Generator option is available to start a generator session. Layer Type (if available): The software layers in the project with their source files, preconfigured software components, and configuration files Actions available through the CMSIS view Action Description Build solution calls the compiler toolchain and builds the solution. Load & Run application flashes the binary onto the target and starts the application. Load & Debug application flashes the binary onto the target and starts a debug session. Open csolution.yml file opens the CMSIS solution YML file for editing. Open the Manage Solution view to configure project and debug settings. Show further commands . Main area icons Depending on the file and the context, various icons may appear: Action Description IntelliSense is active for this cproject file. Open the file. Manage the software components of the cproject file. Add groups or files to the cproject file. Configuration Wizard Configuration Wizard annotations enable GUI-like elements in IDEs for configuration source files. This graphical approach makes it easier for users to review and edit configuration settings as required by the application. For files containing configuration wizard annotations, open the graphical view by pressing the Open Preview button in the top right corner of the file window. The view will be opened next to the original source file. You can switch back pressing the Show Source button . Status bar The VS Code status bar displays information about the status of your development environment and the project. Status message of the clangd extension that provides smart features. You can inspect errors and warnings for the active csolution project when you move the cursor over the Target Set in the status bar. The indicator is red for errors and yellow for warnings. Click the indicator to open the Output - CMSIS Solution panel and the Manage Solution view. The Arm Tools Environment Manager extension downloads, installs, and manages software development tools. Move your mouse over Arm Tools to review the current list of installed tools. Click Arm Tools to get more options. If you are using licensed Arm tools, the active license displays. Click the active license to manage it. Run and Debug view Refer to the Debugger user interface section for more information. Available commands You can access commands to manage your solution and the related projects in the following ways: From the CMSIS view . With right-click to the *.csolution.yml file in the Explorer view. With the Command Palette that opens with Ctrl+Shift+P (Windows and Linux) or Cmd+Shift+P (macOS). Command Description Open Solution in Workspace... If your workspace contains several solutions, select the active solution to work with. Create Solution... Create a new csolution project . Convert a \u00b5Vision project to CMSIS solution... Convert uvprojx files to csolution project format. Close Solution Close the current active solution. Manage Solution Settings Configure the target set (active target, projects, images, and debug adapter) for the solution. Configure Solution Set a compiler and add software layers. Manage Software Components Review, add, or remove software components. Build solution Build the solution with the current target set. Rebuild solution Rebuild the solution with the current target set. Clean all out and tmp directories Clean all out and tmp directories for the active solution. Refresh (reload packs, update RTE) Reload information from all installed packs and run cbuild setup update-rte . Load & Run application Load the application to target and run it with active GDB server ( Debugger can be attached). Load & Debug application Load the application to target and start the debugger. Erase target device Erase the target device. Load application to target Load the application to target. Run application on target Run the current application in the target with active GDB server ( Debugger can be attached). Target Information Show information about debug adapter and target. Focus on Solution View Open the CMSIS view .","title":"User interface"},{"location":"userinterface.html#user-interface","text":"The CMSIS Solution extension provides the Keil Studio GUI for project management and build tools with the CMSIS-Toolbox . Combined with other Arm and third-party extensions, it implements a powerful embedded development environment. The GUI consists of these views: View Description Explorer view lists all local files. Search view enables search/replace across all files. Source Control view allows you to work with git. Extensions view lets you work with VS Code extensions. Run and Debug view switches the GUI to a dedicated debug view . CMSIS view is the main view for working with CMSIS solution-based projects. Trace and Live view shows trace and live data during debugging. Note The ordering of the icons may be different in your VS Code environment.","title":"User Interface"},{"location":"userinterface.html#cmsis-view","text":"The CMSIS view shows the content of the active projects included in the solution. Each project contains configuration settings, source code files, build settings, and other project-specific information. The main area of the CMSIS view shows: Board and device information and related documentation. Groups and files : Groups and user files that you add to the project and that you can edit constructed-files : Contains generated files such as the RTE_Components.h header file for each context linker : Contains a linker script file and a .h file (or other user-defined header files) Components : Shows the software components selected for the project with their source files, user code templates, and APIs. Click the files to open them in the editor. Click the book icon of a component to open the related documentation. If you are using a generator to configure your device or board, then a Run Configuration Generator option is available to start a generator session. Layer Type (if available): The software layers in the project with their source files, preconfigured software components, and configuration files","title":"CMSIS view"},{"location":"userinterface.html#actions-available-through-the-cmsis-view","text":"Action Description Build solution calls the compiler toolchain and builds the solution. Load & Run application flashes the binary onto the target and starts the application. Load & Debug application flashes the binary onto the target and starts a debug session. Open csolution.yml file opens the CMSIS solution YML file for editing. Open the Manage Solution view to configure project and debug settings. Show further commands .","title":"Actions available through the CMSIS view"},{"location":"userinterface.html#main-area-icons","text":"Depending on the file and the context, various icons may appear: Action Description IntelliSense is active for this cproject file. Open the file. Manage the software components of the cproject file. Add groups or files to the cproject file.","title":"Main area icons"},{"location":"userinterface.html#configuration-wizard","text":"Configuration Wizard annotations enable GUI-like elements in IDEs for configuration source files. This graphical approach makes it easier for users to review and edit configuration settings as required by the application. For files containing configuration wizard annotations, open the graphical view by pressing the Open Preview button in the top right corner of the file window. The view will be opened next to the original source file. You can switch back pressing the Show Source button .","title":"Configuration Wizard"},{"location":"userinterface.html#status-bar","text":"The VS Code status bar displays information about the status of your development environment and the project. Status message of the clangd extension that provides smart features. You can inspect errors and warnings for the active csolution project when you move the cursor over the Target Set in the status bar. The indicator is red for errors and yellow for warnings. Click the indicator to open the Output - CMSIS Solution panel and the Manage Solution view. The Arm Tools Environment Manager extension downloads, installs, and manages software development tools. Move your mouse over Arm Tools to review the current list of installed tools. Click Arm Tools to get more options. If you are using licensed Arm tools, the active license displays. Click the active license to manage it.","title":"Status bar"},{"location":"userinterface.html#run-and-debug-view","text":"Refer to the Debugger user interface section for more information.","title":"Run and Debug view"},{"location":"userinterface.html#available-commands","text":"You can access commands to manage your solution and the related projects in the following ways: From the CMSIS view . With right-click to the *.csolution.yml file in the Explorer view. With the Command Palette that opens with Ctrl+Shift+P (Windows and Linux) or Cmd+Shift+P (macOS). Command Description Open Solution in Workspace... If your workspace contains several solutions, select the active solution to work with. Create Solution... Create a new csolution project . Convert a \u00b5Vision project to CMSIS solution... Convert uvprojx files to csolution project format. Close Solution Close the current active solution. Manage Solution Settings Configure the target set (active target, projects, images, and debug adapter) for the solution. Configure Solution Set a compiler and add software layers. Manage Software Components Review, add, or remove software components. Build solution Build the solution with the current target set. Rebuild solution Rebuild the solution with the current target set. Clean all out and tmp directories Clean all out and tmp directories for the active solution. Refresh (reload packs, update RTE) Reload information from all installed packs and run cbuild setup update-rte . Load & Run application Load the application to target and run it with active GDB server ( Debugger can be attached). Load & Debug application Load the application to target and start the debugger. Erase target device Erase the target device. Load application to target Load the application to target. Run application on target Run the current application in the target with active GDB server ( Debugger can be attached). Target Information Show information about debug adapter and target. Focus on Solution View Open the CMSIS view .","title":"Available commands"},{"location":"zephyr.html","text":"Work with Zephyr applications It is possible to build and debug Zephyr applications that use the west build system with Keil Studio. The CMSIS solution extension displays an outline view of the Zephyr project. Prerequisites To work with Zephyr-based applications, make sure that the following is set up on your machine. Zephyr installation Follow the Zephyr Getting Started Guide for your host operating system and install Zephyr in a central location on your machine. Set environment variables For the build process, it is required to set environment variables for the CMSIS Solution extension. Open the Extension settings and navigate to CMSIS Solution . Select if you want to set the Environment Variables for the User or the current Workspace . Use Add Item to add the following environment variables: Item Value ZEPHYR_BASE $HOME/zephyrproject/zephyr PATH $HOME/zephyrproject/.venv/bin VIRTUAL_ENV $HOME/zephyrproject/.venv Note On Windows, specify the PATH as $HOME/zephyrproject/.venv/Scripts This will be translated into the following JSON code: \"cmsis-csolution.environmentVariables\": { \"ZEPHYR_BASE\": \"$HOME/zephyrproject/zephyr\", \"PATH\": \"$HOME/zephyrproject/.venv/bin\", \"VIRTUAL_ENV\": \"$HOME/zephyrproject/.venv\" }, Attention The workspace settings are stored in the .vscode\\settings.json file. If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default. Settings Copy the Zephyr application directory that you want to use to your CMSIS solution workspace/folder. Refer to the example available on GitHub: CMSIS-Zephyr . Csolution settings In a csolution.yml file, you may have west build -specific settings. You must not have a cproject.yml file present. Instead, the csolution.yml file points to the Zephyr project path: # List related projects. projects: - west: app-path: ./blinky Zephyr application settings When using the Arm GNU Toolchain for building the project via vcpkg , make sure that the C library shipped with the toolchain. This can be ensured with the following settings in the Zephyr prj.conf file: # Use Newlib from the Arm GNU Toolchain CONFIG_NEWLIB_LIBC=y # Disable Picolibc CONFIG_PICOLIBC=n CONFIG_PICOLIBC_USE_MODULE=n CONFIG_MINIMAL_LIBC=n For managing run and debug configurations, continue to manage the solution .","title":"Work with Zephyr applications"},{"location":"zephyr.html#work-with-zephyr-applications","text":"It is possible to build and debug Zephyr applications that use the west build system with Keil Studio. The CMSIS solution extension displays an outline view of the Zephyr project.","title":"Work with Zephyr applications"},{"location":"zephyr.html#prerequisites","text":"To work with Zephyr-based applications, make sure that the following is set up on your machine.","title":"Prerequisites"},{"location":"zephyr.html#zephyr-installation","text":"Follow the Zephyr Getting Started Guide for your host operating system and install Zephyr in a central location on your machine.","title":"Zephyr installation"},{"location":"zephyr.html#set-environment-variables","text":"For the build process, it is required to set environment variables for the CMSIS Solution extension. Open the Extension settings and navigate to CMSIS Solution . Select if you want to set the Environment Variables for the User or the current Workspace . Use Add Item to add the following environment variables: Item Value ZEPHYR_BASE $HOME/zephyrproject/zephyr PATH $HOME/zephyrproject/.venv/bin VIRTUAL_ENV $HOME/zephyrproject/.venv Note On Windows, specify the PATH as $HOME/zephyrproject/.venv/Scripts This will be translated into the following JSON code: \"cmsis-csolution.environmentVariables\": { \"ZEPHYR_BASE\": \"$HOME/zephyrproject/zephyr\", \"PATH\": \"$HOME/zephyrproject/.venv/bin\", \"VIRTUAL_ENV\": \"$HOME/zephyrproject/.venv\" }, Attention The workspace settings are stored in the .vscode\\settings.json file. If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default.","title":"Set environment variables"},{"location":"zephyr.html#settings","text":"Copy the Zephyr application directory that you want to use to your CMSIS solution workspace/folder. Refer to the example available on GitHub: CMSIS-Zephyr .","title":"Settings"},{"location":"zephyr.html#csolution-settings","text":"In a csolution.yml file, you may have west build -specific settings. You must not have a cproject.yml file present. Instead, the csolution.yml file points to the Zephyr project path: # List related projects. projects: - west: app-path: ./blinky","title":"Csolution settings"},{"location":"zephyr.html#zephyr-application-settings","text":"When using the Arm GNU Toolchain for building the project via vcpkg , make sure that the C library shipped with the toolchain. This can be ensured with the following settings in the Zephyr prj.conf file: # Use Newlib from the Arm GNU Toolchain CONFIG_NEWLIB_LIBC=y # Disable Picolibc CONFIG_PICOLIBC=n CONFIG_PICOLIBC_USE_MODULE=n CONFIG_MINIMAL_LIBC=n For managing run and debug configurations, continue to manage the solution .","title":"Zephyr application settings"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"index.html","text":"Arm Keil Studio The Arm\u00ae Keil Studio extension pack for VS Code is a comprehensive software development platform for Arm Cortex-M processor-based devices. The IDE: supports single and multi-core processor systems, including Ethos-U NPUs. has wide software support for projects based on CMSIS, FreeRTOS, RTX, and Zephyr. utilizes CMSIS-Pack content to configure debug adapters and access re-usable software components. can be combined with other VS Code debug extensions, such as those for Linux application development. Contents Installation explains how to install Keil Studio along with a build environment for embedded applications that are based on Arm Cortex-M processors. User interface shows the main features available in the GUI. Work with CMSIS solutions explains how to start an embedded project from scratch or use pre-built examples. Work with Zephyr applications explains how to build applications based on Zephyr. Manage solutions explains how to configure csolution projects . Build and run shows how to build and run a CMSIS solution or Zephyr application. Debug explains how to debug a CMSIS solution or Zephyr application. Import \u00b5Vision project explains how to convert uvprojx-based files to the csolution format. Run external tools describes how to use external tools, such as debuggers and flash programmers. Tips and tricks provides tips and tricks to help you solve specific issues. Related documentation contains links to supporting documentation, videos, and webinars. Features and roadmap presents the implemented features and our current feature roadmap. Revision history Version Description 1.66.0 Added Software pack , Related Documentation , and Features and roadmap chapters 1.64.0 Added Work with Zephyr applications and reworked other chapters 1.62.0 Reworked Manage solutions and Debug chapters 1.55.0 Rework for better clarity 1.54.0 Added CMSIS-Toolbox Run and Debug Management 1.48.0 Initial release for the CMSIS Solution extension version 1.48.0","title":"Home"},{"location":"index.html#arm-keil-studio","text":"The Arm\u00ae Keil Studio extension pack for VS Code is a comprehensive software development platform for Arm Cortex-M processor-based devices. The IDE: supports single and multi-core processor systems, including Ethos-U NPUs. has wide software support for projects based on CMSIS, FreeRTOS, RTX, and Zephyr. utilizes CMSIS-Pack content to configure debug adapters and access re-usable software components. can be combined with other VS Code debug extensions, such as those for Linux application development.","title":"Arm Keil Studio"},{"location":"index.html#contents","text":"Installation explains how to install Keil Studio along with a build environment for embedded applications that are based on Arm Cortex-M processors. User interface shows the main features available in the GUI. Work with CMSIS solutions explains how to start an embedded project from scratch or use pre-built examples. Work with Zephyr applications explains how to build applications based on Zephyr. Manage solutions explains how to configure csolution projects . Build and run shows how to build and run a CMSIS solution or Zephyr application. Debug explains how to debug a CMSIS solution or Zephyr application. Import \u00b5Vision project explains how to convert uvprojx-based files to the csolution format. Run external tools describes how to use external tools, such as debuggers and flash programmers. Tips and tricks provides tips and tricks to help you solve specific issues. Related documentation contains links to supporting documentation, videos, and webinars. Features and roadmap presents the implemented features and our current feature roadmap.","title":"Contents"},{"location":"index.html#revision-history","text":"Version Description 1.66.0 Added Software pack , Related Documentation , and Features and roadmap chapters 1.64.0 Added Work with Zephyr applications and reworked other chapters 1.62.0 Reworked Manage solutions and Debug chapters 1.55.0 Rework for better clarity 1.54.0 Added CMSIS-Toolbox Run and Debug Management 1.48.0 Initial release for the CMSIS Solution extension version 1.48.0","title":"Revision history"},{"location":"build_run.html","text":"Build Before you can download the application on your target device, you need to build it. There are various ways to trigger a build: In the Explorer view , right-click the *.csolution.yml file and select Build solution . In the CMSIS view , click . Continue to load and run the solution. Build output After you initiate the build process, a Terminal opens and displays the build operation: Execute: cbuild /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/Blinky.csolution.yml --active NUCLEO-F756ZG --packs +--------------------------------------------------- (1/1) Building context: \"Blinky.Debug+NUCLEO-F756ZG\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Blinky.Debug+NUCLEO-F756ZG' [1/51] Building C object CMakeFiles/Group_Source_Files_retarget_stdio_c.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/retarget_stdio.o [2/51] Building ASM object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/MDK-ARM/startup_stm32f756xx.o Warning: A1950W: The legacy armasm assembler is deprecated. Consider using the armclang integrated assembler instead. 0 Errors, 1 Warning [3/51] Building C object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/Src/stm32f7xx_hal_timebase_tim.o ... [49/51] Building C object CMakeFiles/Keil_CMSIS_Driver_USART_3_0_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-Driver_STM32/1.1.0/Drivers/USART_STM32.o [50/51] Building C object CMakeFiles/ARM_CMSIS_RTOS2_Keil_RTX5_Source_5_9_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-RTX/5.9.0/Source/rtx_thread.o [51/51] Linking C executable /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/out/Blinky/NUCLEO-F756ZG/Debug/Blinky.axf Program Size: Code=31972 RO-data=1076 RW-data=512 ZI-data=38760 +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:04 +============================================================ Completed: cbuild succeed with exit code 0 Build complete The output directory usually contains an ELF ( .axf ) and a HEX ( .hex ) file. To learn about the solution structure, refer to CMSIS-Toolbox documentation Load and Run Check target information In the CMSIS view, click and then select \"Target Information\" to check that your target is connected. In the Terminal , the result of the pyocd list command is shown: * Executing task: pyocd list --cbuild-run /Users/user/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml # Probe/Board Unique ID Target ------------------------------------------------------------------- 0 STLINK-V3 001000254D46501220383832 \u2716\ufe0e stm32u585aiix B-U585I-IOT02A Note Various debug adapters are supported. Select them using the manage solutions dialog. The configure run and debug chapter explains the details. If your debug adapter is not shown, make sure that all drivers are installed and that the target is connected to the PC. Download and run the application In the CMSIS view, click . This executes the \"Load & Run application\" command that executes the commands CMSIS Load and CMSIS Run from the tasks.json file. This flashes the project onto the target and issues a reset to start the application. To verify that the step has run correctly, check the Terminal output: * Executing task: pyocd load --probe stlink: --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000712 I Loading /Users/user/B-U585-Board/Blinky/out/Blinky/B-U585I-IOT02A/Debug/Blinky.axf [load_cmd] [==================================================] 100% 0003015 I Erased 49152 bytes (6 sectors), programmed 49152 bytes (48 pages), skipped 0 bytes (0 pages) at 20.96 kB/s [loader] * Terminal will be reused by tasks, press any key to close it. * Executing task: pyocd gdbserver --probe stlink: --connect attach --persist --reset-run --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000251 I Target type is stm32u585aiix [board] 0000434 I DP IDR = 0x0be12477 (v2 MINDP rev0) [dap] 0000511 I debugvar 'DbgMCU_AHB1_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_AHB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1H_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1L_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB2_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_CR' = 0x6 (6) [cbuild_run] 0000511 I debugvar 'DoOptionByteLoading' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'TraceClk_Pin' = 0x40002 (262146) [cbuild_run] 0000511 I debugvar 'TraceD0_Pin' = 0x20009 (131081) [cbuild_run] 0000511 I debugvar 'TraceD1_Pin' = 0x2000a (131082) [cbuild_run] 0000511 I debugvar 'TraceD2_Pin' = 0x40005 (262149) [cbuild_run] 0000511 I debugvar 'TraceD3_Pin' = 0x2000c (131084) [cbuild_run] 0000516 I AHB5-AP#0 IDR = 0x14770015 (AHB5-AP var1 rev1) [discovery] 0000517 I AHB5-AP#0 Class 0x1 ROM table #0 @ 0xe00fe000 (designer=020:ST part=482) [rom_table] 0000518 I [0] [rom_table] 0000518 I AHB5-AP#0 Class 0x1 ROM table #1 @ 0xe00ff000 (designer=43b:Arm part=4c9) [rom_table] 0000520 I [0] [rom_table] 0000520 I [1] [rom_table] 0000521 I [2] [rom_table] 0000522 I [3] [rom_table] 0000523 I [5] [rom_table] 0000524 I [6] [rom_table] 0000524 I [1] [rom_table] 0000525 I [2] [rom_table] 0000533 I CPU core #0: Cortex-M33 r0p4, v8.0-M architecture [cortex_m] 0000533 I Extensions: [DSP, FPU, FPU_V5, MPU] [cortex_m] 0000533 I FPU present: FPv5-SP-D16-M [cortex_m] 0000534 I Setting core #0 (Cortex-M33) default reset sequence to ResetSystem [cbuild_run] 0000534 I 4 hardware watchpoints [dwt] 0000537 I 8 hardware breakpoints, 1 literal comparators [fpb] 0000662 I Semihost server started on port 4444 (core 0) [server] 0000718 I GDB server started on port 3333 (core 0) [gdbserver] When running, changes to . Use it to stop the GDB session anytime. Notes When you have several solutions in one folder, VS Code ignores the tasks.json and launch.json files that you created for each solution. Instead, VS Code generates new JSON files at the root of the workspace in a .vscode folder and ignores the other JSON files. As a workaround, open one solution first, then add other solutions to your workspace with the File > Add Folder to Workspace option. If you are using a multi-core device and you did not specify a \"processorName\" in the launch.json file, select the appropriate processor for your project in the Select a processor drop-down list at the top of the window. If you want to run the application on an Arm FVP simulation model, you need to configure it in the Manage Solution dialog. Monitor printf messages Keil Studio includes the Serial Monitor extension that connects to the target's serial output port. If your example contains printf statements, use the Serial Monitor to observe them.","title":"Build and run"},{"location":"build_run.html#build","text":"Before you can download the application on your target device, you need to build it. There are various ways to trigger a build: In the Explorer view , right-click the *.csolution.yml file and select Build solution . In the CMSIS view , click . Continue to load and run the solution.","title":"Build"},{"location":"build_run.html#build-output","text":"After you initiate the build process, a Terminal opens and displays the build operation: Execute: cbuild /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/Blinky.csolution.yml --active NUCLEO-F756ZG --packs +--------------------------------------------------- (1/1) Building context: \"Blinky.Debug+NUCLEO-F756ZG\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Blinky.Debug+NUCLEO-F756ZG' [1/51] Building C object CMakeFiles/Group_Source_Files_retarget_stdio_c.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/retarget_stdio.o [2/51] Building ASM object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/MDK-ARM/startup_stm32f756xx.o Warning: A1950W: The legacy armasm assembler is deprecated. Consider using the armclang integrated assembler instead. 0 Errors, 1 Warning [3/51] Building C object CMakeFiles/Group_CubeMX.dir/Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/STM32CubeMX/NUCLEO-F756ZG/STM32CubeMX/Src/stm32f7xx_hal_timebase_tim.o ... [49/51] Building C object CMakeFiles/Keil_CMSIS_Driver_USART_3_0_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-Driver_STM32/1.1.0/Drivers/USART_STM32.o [50/51] Building C object CMakeFiles/ARM_CMSIS_RTOS2_Keil_RTX5_Source_5_9_0.dir/Users/user/.cache/arm/packs/ARM/CMSIS-RTX/5.9.0/Source/rtx_thread.o [51/51] Linking C executable /Users/user/03_work/02_Projects/ST/Nucleo-F756ZG/Blinky/out/Blinky/NUCLEO-F756ZG/Debug/Blinky.axf Program Size: Code=31972 RO-data=1076 RW-data=512 ZI-data=38760 +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:04 +============================================================ Completed: cbuild succeed with exit code 0 Build complete The output directory usually contains an ELF ( .axf ) and a HEX ( .hex ) file. To learn about the solution structure, refer to CMSIS-Toolbox documentation","title":"Build output"},{"location":"build_run.html#load-and-run","text":"","title":"Load and Run"},{"location":"build_run.html#check-target-information","text":"In the CMSIS view, click and then select \"Target Information\" to check that your target is connected. In the Terminal , the result of the pyocd list command is shown: * Executing task: pyocd list --cbuild-run /Users/user/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml # Probe/Board Unique ID Target ------------------------------------------------------------------- 0 STLINK-V3 001000254D46501220383832 \u2716\ufe0e stm32u585aiix B-U585I-IOT02A Note Various debug adapters are supported. Select them using the manage solutions dialog. The configure run and debug chapter explains the details. If your debug adapter is not shown, make sure that all drivers are installed and that the target is connected to the PC.","title":"Check target information"},{"location":"build_run.html#download-and-run-the-application","text":"In the CMSIS view, click . This executes the \"Load & Run application\" command that executes the commands CMSIS Load and CMSIS Run from the tasks.json file. This flashes the project onto the target and issues a reset to start the application. To verify that the step has run correctly, check the Terminal output: * Executing task: pyocd load --probe stlink: --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000712 I Loading /Users/user/B-U585-Board/Blinky/out/Blinky/B-U585I-IOT02A/Debug/Blinky.axf [load_cmd] [==================================================] 100% 0003015 I Erased 49152 bytes (6 sectors), programmed 49152 bytes (48 pages), skipped 0 bytes (0 pages) at 20.96 kB/s [loader] * Terminal will be reused by tasks, press any key to close it. * Executing task: pyocd gdbserver --probe stlink: --connect attach --persist --reset-run --cbuild-run /Users/user/B-U585-Board/Blinky/Blinky+B-U585I-IOT02A.cbuild-run.yml 0000251 I Target type is stm32u585aiix [board] 0000434 I DP IDR = 0x0be12477 (v2 MINDP rev0) [dap] 0000511 I debugvar 'DbgMCU_AHB1_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_AHB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1H_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB1L_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB2_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_APB3_Fz' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'DbgMCU_CR' = 0x6 (6) [cbuild_run] 0000511 I debugvar 'DoOptionByteLoading' = 0x0 (0) [cbuild_run] 0000511 I debugvar 'TraceClk_Pin' = 0x40002 (262146) [cbuild_run] 0000511 I debugvar 'TraceD0_Pin' = 0x20009 (131081) [cbuild_run] 0000511 I debugvar 'TraceD1_Pin' = 0x2000a (131082) [cbuild_run] 0000511 I debugvar 'TraceD2_Pin' = 0x40005 (262149) [cbuild_run] 0000511 I debugvar 'TraceD3_Pin' = 0x2000c (131084) [cbuild_run] 0000516 I AHB5-AP#0 IDR = 0x14770015 (AHB5-AP var1 rev1) [discovery] 0000517 I AHB5-AP#0 Class 0x1 ROM table #0 @ 0xe00fe000 (designer=020:ST part=482) [rom_table] 0000518 I [0] [rom_table] 0000518 I AHB5-AP#0 Class 0x1 ROM table #1 @ 0xe00ff000 (designer=43b:Arm part=4c9) [rom_table] 0000520 I [0] [rom_table] 0000520 I [1] [rom_table] 0000521 I [2] [rom_table] 0000522 I [3] [rom_table] 0000523 I [5] [rom_table] 0000524 I [6] [rom_table] 0000524 I [1] [rom_table] 0000525 I [2] [rom_table] 0000533 I CPU core #0: Cortex-M33 r0p4, v8.0-M architecture [cortex_m] 0000533 I Extensions: [DSP, FPU, FPU_V5, MPU] [cortex_m] 0000533 I FPU present: FPv5-SP-D16-M [cortex_m] 0000534 I Setting core #0 (Cortex-M33) default reset sequence to ResetSystem [cbuild_run] 0000534 I 4 hardware watchpoints [dwt] 0000537 I 8 hardware breakpoints, 1 literal comparators [fpb] 0000662 I Semihost server started on port 4444 (core 0) [server] 0000718 I GDB server started on port 3333 (core 0) [gdbserver] When running, changes to . Use it to stop the GDB session anytime. Notes When you have several solutions in one folder, VS Code ignores the tasks.json and launch.json files that you created for each solution. Instead, VS Code generates new JSON files at the root of the workspace in a .vscode folder and ignores the other JSON files. As a workaround, open one solution first, then add other solutions to your workspace with the File > Add Folder to Workspace option. If you are using a multi-core device and you did not specify a \"processorName\" in the launch.json file, select the appropriate processor for your project in the Select a processor drop-down list at the top of the window. If you want to run the application on an Arm FVP simulation model, you need to configure it in the Manage Solution dialog.","title":"Download and run the application"},{"location":"build_run.html#monitor-printf-messages","text":"Keil Studio includes the Serial Monitor extension that connects to the target's serial output port. If your example contains printf statements, use the Serial Monitor to observe them.","title":"Monitor printf messages"},{"location":"create_app.html","text":"Work with CMSIS solutions This section explains how to create a CMSIS solution-based project that is using CMSIS-Packs. In the CMSIS view, click Create a New Solution . If you already have a solution opened, use the menu ( ... ) item Create a Solution . The Create new solution dialog allows to start projects based on a Target Board or Target Device selection. Examples, templates, and reference applications depend on the selected board or device and on installed CMSIS-Packs. Examples are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals. Reference applications use defined interfaces (APIs) and are therefore hardware agnostic. These projects require the installation of related CMSIS-Packs and additional software layers for an evaluation board. Templates are stub projects that help you getting started. Some CMSIS-Packs may contain device-specific templates. GitHub repositories may contain projects showcasing a specific use case. These repos can be cloned directly into VS Code. The Source Control view helps maintaining these repos. Further settings include: The Solution Sub Folder is typically a sub-directory in your workspace. The Solution Base Folder specifies your workspace location that may contain multiple projects. With Initialize Git repository the related .gitignore file is created. Show project opening options allows you to open the solution a new instance of VS Code. By default, it is loaded into the current VS Code instance. Examples Click the Target Board (Optional) drop-down list. Enter a search term tp filter the list and then select your board. The details of the selected board are displayed. Click Select . Next, select the example project. There are two types of example projects (available either from Local packs and/or from the Web ): Csolution Examples are using Keil Studio's native project format. uVision Examples are in *.uvprojx format and are converted automatically. To verify the Keil Studio installation, select a Blinky project for example. Specify a Solution Base Folder and click Create . Note First time users may need to confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in the vcpkg-configuration.json file included in a project. A typical Blinky example includes a REAMDE.md file that contains valuable information about the hardware setup and specific tasks that need to be done before working with the target board: Continue to build the project . Reference applications Reference applications show the usage of middleware, software libraries, and custom code that can run on many different target hardware boards. Examples display only if you selected a board and a software layer is available for that board. Reference applications are not dependent on specific hardware. You can deploy them to various evaluation boards using additional software layers that provide driver APIs for specific target hardware. Layers are provided using CMSIS-Packs. Reference applications are available with these CMSIS-Packs: MDK-Middleware : use software components for IPv4 and IPv6 networking, USB Host and Device communication, and file system for data storage. SDS Framework : record real-world data off a device and playing it back on Arm Virtual Hardware. LiteRT : demonstrates the fundamental integration and usage of the LiteRT stack for ML inference on a microcontroller. Attention You need to have the CMSIS-Packs installed before you can create a new reference application. Please follow the instruction for installing packs . Configuration Reference applications use software layers that help scaling example projects to many different target boards. To be able to use the selected board with the reference application, you need to configure the solution and select an appropriate layer. More information about the layer requirements and other configuration options can be found in the documentation: MDK-Middleware SDS Framework Documentation Continue to build the project . Templates Templates help you to get started without application-specific code. Blank solution : Start a project from scratch with an empty main.c file and the CMSIS device startup component selected TrustZone solution : If the board or device that you selected is compatible, you can use TrustZone and define whether projects in the solution use secure or non-secure zones Continue to build the project . GitHub repositories Nowadays, many projects are available in GitHub repositories. VS Code provides easy access to these repos with the built-in Git support . The easiest way to do so is to clone a repository directly in VS Code: In the Explorer view , click Clone Repository (you can do the same in the Source Control view ). Open the CMSIS view and use the ... menu to choose an example via Select Active Solution from workspace . The related tools and software packs are downloaded and installed. Continue to build the project . Note You can also download the repository content as a ZIP file. In that case, extract the content and open the top-level folder in VS Code ( File - Open Folder... ). Ready-to-run examples are available on GitHub . Configure a solution The Configure Solution view opens automatically, if: Your solution has a select-compiler: node, but no compiler: node is set in the csolution.yml file, or You are working with a reference application that requires the configuration of a software layer. Click Next to display the different options available. You can indicate where the layers should be copied to in the Board-Layer , Shield-Layer , and Socket-Layer fields. Click Default to reset the paths to their default values. If there are no compatible layers, errors display. If no compiler is set for the reference application, Select Compiler displays under the layers selection and shows the compilers available in your environment. Select a compiler. For example, AC6 or GCC. If you are working with another solution type, only Select Compiler displays. Select a compiler. Click OK . For reference applications only, a Board.clayer.yml file, a Shield.clayer.yml file, or a Socket.clayer.yml file, along with other files that make up the layer, are added in the folders that you selected. The files are available from the Explorer view. The .clayer.yml files come from the CMSIS-Pack. Layers are automatically added in the csolution.yml file of your solution under target-types: variables: for the active target. For all solution types, the compiler is added with the compiler: key in the csolution.yml file. Note Not all Board Support Packs (BSPs) have board layers. Not all layers are compatible with the connections that your reference application requires. The CMSIS-Packs which contain reference applications and layers generally provide an Overview.md file where the connections are detailed. Software components and packs A software component encapsulates a set of related functions and is delivered in a software pack . The Software Components view enables you to manage the software components and software packs selected in the active project of a solution. Software Components view Open the CMSIS view and click to open the Software Components view: You can: Switch between components and software packs . View only components that are part of the csolution or components from all installed packs . Set the context for which the component selection applies (including layers). Select/remove software components. View more information about the component (name, pack, version, and description). Select different variants of a component. Open related documentation . Validation In the Software Components view , you can manage the dependencies between components and solve validation issues. Issues are highlighted with a yellow exclamation mark icon . If there are validation issues: Either click on and select the issue in the pop-up box (a) or Click the \"Resolve\" button for access to the pop-up box (a). Once a components with validation issues is opened, you can use the \"eye\" icon to see which component is missing/affected (b). Use the \"Apply\" button to select the missing components (only available if there is no choice between different components available). When done, don't forget to Save the changes! RTOS example This example shows how to add a real-time operating systems (RTOS), such as Keil RTX5. Before adding the component, add the CMSIS-RTX pack to your local installation. In a Terminal, run: cpackget add ARM::CMSIS-RTX Once the pack is installed, open the Software Components view, click on All installed packs and select: Enable CMSIS - RTOS2 (API) - Keil RTX5 and choose your Variant (select Library or Source ). Enable CMSIS - OS Tick (API) - SysTick . Click Save After saving, the *.cproject.yml file contains: project: components: # SysTick timer component added: - component: CMSIS:OS Tick:SysTick # Keil RTX5 in Source variant added: - component: CMSIS:RTOS2:Keil RTX5&Source packs: # CMSIS-Pack containing the RTOS component added: - pack: ARM::CMSIS-RTX Software packs You can: Switch between components and software packs . View only software packs that are part of the csolution or view all installed packs . Using the drop down, select the cproject/clayer scope. It always shows all packs but \"highlights\" (greyed) the packs specified in \"scope\". Examine on which level the packs are references (csolution/cproject/clayer). Manage software packs . Open related documentation . Manage software packs Click on either icon: to open the Manage Pack dialog: In the Current References section, you can: Set the specific version for a pack to be used on the csolution/cproject/clayer level. Use these version specifiers: Unspecified : use the latest installed version of a pack and the cbuild-pack.yml for locked versions. @ : exact version @>= : equal or higher @^ : equal or higher with same major version @~ : Equal or higher with same major and minor version Add a pack to a csolution/cproject/clayer. Below that, the used pack version is shown. It is computed from the requirements above. In the Update Pack section, you can see the latest installed version and check for updates. The button on the left is enabled when there is a more recent version of a pack installed, but the cbuild-pack.yml locks it to a smaller version. When pressing the button, the cbuild-pack.yml entry will be removed on save and the latest installed pack version will be set and used. The button to the right opens the version page of a public pack on keil.arm.com which then also shows you the latest available pack version.","title":"Work with CMSIS solutions"},{"location":"create_app.html#work-with-cmsis-solutions","text":"This section explains how to create a CMSIS solution-based project that is using CMSIS-Packs. In the CMSIS view, click Create a New Solution . If you already have a solution opened, use the menu ( ... ) item Create a Solution . The Create new solution dialog allows to start projects based on a Target Board or Target Device selection. Examples, templates, and reference applications depend on the selected board or device and on installed CMSIS-Packs. Examples are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals. Reference applications use defined interfaces (APIs) and are therefore hardware agnostic. These projects require the installation of related CMSIS-Packs and additional software layers for an evaluation board. Templates are stub projects that help you getting started. Some CMSIS-Packs may contain device-specific templates. GitHub repositories may contain projects showcasing a specific use case. These repos can be cloned directly into VS Code. The Source Control view helps maintaining these repos. Further settings include: The Solution Sub Folder is typically a sub-directory in your workspace. The Solution Base Folder specifies your workspace location that may contain multiple projects. With Initialize Git repository the related .gitignore file is created. Show project opening options allows you to open the solution a new instance of VS Code. By default, it is loaded into the current VS Code instance.","title":"Work with CMSIS solutions"},{"location":"create_app.html#examples","text":"Click the Target Board (Optional) drop-down list. Enter a search term tp filter the list and then select your board. The details of the selected board are displayed. Click Select . Next, select the example project. There are two types of example projects (available either from Local packs and/or from the Web ): Csolution Examples are using Keil Studio's native project format. uVision Examples are in *.uvprojx format and are converted automatically. To verify the Keil Studio installation, select a Blinky project for example. Specify a Solution Base Folder and click Create . Note First time users may need to confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in the vcpkg-configuration.json file included in a project. A typical Blinky example includes a REAMDE.md file that contains valuable information about the hardware setup and specific tasks that need to be done before working with the target board: Continue to build the project .","title":"Examples"},{"location":"create_app.html#reference-applications","text":"Reference applications show the usage of middleware, software libraries, and custom code that can run on many different target hardware boards. Examples display only if you selected a board and a software layer is available for that board. Reference applications are not dependent on specific hardware. You can deploy them to various evaluation boards using additional software layers that provide driver APIs for specific target hardware. Layers are provided using CMSIS-Packs. Reference applications are available with these CMSIS-Packs: MDK-Middleware : use software components for IPv4 and IPv6 networking, USB Host and Device communication, and file system for data storage. SDS Framework : record real-world data off a device and playing it back on Arm Virtual Hardware. LiteRT : demonstrates the fundamental integration and usage of the LiteRT stack for ML inference on a microcontroller. Attention You need to have the CMSIS-Packs installed before you can create a new reference application. Please follow the instruction for installing packs .","title":"Reference applications"},{"location":"create_app.html#configuration","text":"Reference applications use software layers that help scaling example projects to many different target boards. To be able to use the selected board with the reference application, you need to configure the solution and select an appropriate layer. More information about the layer requirements and other configuration options can be found in the documentation: MDK-Middleware SDS Framework Documentation Continue to build the project .","title":"Configuration"},{"location":"create_app.html#templates","text":"Templates help you to get started without application-specific code. Blank solution : Start a project from scratch with an empty main.c file and the CMSIS device startup component selected TrustZone solution : If the board or device that you selected is compatible, you can use TrustZone and define whether projects in the solution use secure or non-secure zones Continue to build the project .","title":"Templates"},{"location":"create_app.html#github-repositories","text":"Nowadays, many projects are available in GitHub repositories. VS Code provides easy access to these repos with the built-in Git support . The easiest way to do so is to clone a repository directly in VS Code: In the Explorer view , click Clone Repository (you can do the same in the Source Control view ). Open the CMSIS view and use the ... menu to choose an example via Select Active Solution from workspace . The related tools and software packs are downloaded and installed. Continue to build the project . Note You can also download the repository content as a ZIP file. In that case, extract the content and open the top-level folder in VS Code ( File - Open Folder... ). Ready-to-run examples are available on GitHub .","title":"GitHub repositories"},{"location":"create_app.html#configure-a-solution","text":"The Configure Solution view opens automatically, if: Your solution has a select-compiler: node, but no compiler: node is set in the csolution.yml file, or You are working with a reference application that requires the configuration of a software layer. Click Next to display the different options available. You can indicate where the layers should be copied to in the Board-Layer , Shield-Layer , and Socket-Layer fields. Click Default to reset the paths to their default values. If there are no compatible layers, errors display. If no compiler is set for the reference application, Select Compiler displays under the layers selection and shows the compilers available in your environment. Select a compiler. For example, AC6 or GCC. If you are working with another solution type, only Select Compiler displays. Select a compiler. Click OK . For reference applications only, a Board.clayer.yml file, a Shield.clayer.yml file, or a Socket.clayer.yml file, along with other files that make up the layer, are added in the folders that you selected. The files are available from the Explorer view. The .clayer.yml files come from the CMSIS-Pack. Layers are automatically added in the csolution.yml file of your solution under target-types: variables: for the active target. For all solution types, the compiler is added with the compiler: key in the csolution.yml file. Note Not all Board Support Packs (BSPs) have board layers. Not all layers are compatible with the connections that your reference application requires. The CMSIS-Packs which contain reference applications and layers generally provide an Overview.md file where the connections are detailed.","title":"Configure a solution"},{"location":"create_app.html#software-components-and-packs","text":"A software component encapsulates a set of related functions and is delivered in a software pack . The Software Components view enables you to manage the software components and software packs selected in the active project of a solution.","title":"Software components and packs"},{"location":"create_app.html#software-components-view","text":"Open the CMSIS view and click to open the Software Components view: You can: Switch between components and software packs . View only components that are part of the csolution or components from all installed packs . Set the context for which the component selection applies (including layers). Select/remove software components. View more information about the component (name, pack, version, and description). Select different variants of a component. Open related documentation .","title":"Software Components view"},{"location":"create_app.html#validation","text":"In the Software Components view , you can manage the dependencies between components and solve validation issues. Issues are highlighted with a yellow exclamation mark icon . If there are validation issues: Either click on and select the issue in the pop-up box (a) or Click the \"Resolve\" button for access to the pop-up box (a). Once a components with validation issues is opened, you can use the \"eye\" icon to see which component is missing/affected (b). Use the \"Apply\" button to select the missing components (only available if there is no choice between different components available). When done, don't forget to Save the changes!","title":"Validation"},{"location":"create_app.html#rtos-example","text":"This example shows how to add a real-time operating systems (RTOS), such as Keil RTX5. Before adding the component, add the CMSIS-RTX pack to your local installation. In a Terminal, run: cpackget add ARM::CMSIS-RTX Once the pack is installed, open the Software Components view, click on All installed packs and select: Enable CMSIS - RTOS2 (API) - Keil RTX5 and choose your Variant (select Library or Source ). Enable CMSIS - OS Tick (API) - SysTick . Click Save After saving, the *.cproject.yml file contains: project: components: # SysTick timer component added: - component: CMSIS:OS Tick:SysTick # Keil RTX5 in Source variant added: - component: CMSIS:RTOS2:Keil RTX5&Source packs: # CMSIS-Pack containing the RTOS component added: - pack: ARM::CMSIS-RTX","title":"RTOS example"},{"location":"create_app.html#software-packs","text":"You can: Switch between components and software packs . View only software packs that are part of the csolution or view all installed packs . Using the drop down, select the cproject/clayer scope. It always shows all packs but \"highlights\" (greyed) the packs specified in \"scope\". Examine on which level the packs are references (csolution/cproject/clayer). Manage software packs . Open related documentation .","title":"Software packs"},{"location":"create_app.html#manage-software-packs","text":"Click on either icon: to open the Manage Pack dialog: In the Current References section, you can: Set the specific version for a pack to be used on the csolution/cproject/clayer level. Use these version specifiers: Unspecified : use the latest installed version of a pack and the cbuild-pack.yml for locked versions. @ : exact version @>= : equal or higher @^ : equal or higher with same major version @~ : Equal or higher with same major and minor version Add a pack to a csolution/cproject/clayer. Below that, the used pack version is shown. It is computed from the requirements above. In the Update Pack section, you can see the latest installed version and check for updates. The button on the left is enabled when there is a more recent version of a pack installed, but the cbuild-pack.yml locks it to a smaller version. When pressing the button, the cbuild-pack.yml entry will be removed on save and the latest installed pack version will be set and used. The button to the right opens the version page of a public pack on keil.arm.com which then also shows you the latest available pack version.","title":"Manage software packs"},{"location":"debug.html","text":"Debug Debugger User Interface Many features of the CMSIS Debugger extension are exposed in the Run and Debug view of VS Code. Start debugging selects a configuration: launch to start download/debug, attach to connect with a running system. Debug Toolbar has buttons for the most common debugging actions that control execution. The Trace and Live View shows the LIVE WATCH window. Debug Statusbar shows the time spent running the application. The Debug Console can be used to interact with the debugger on the command line. Most editor features are available during debugging. For example, developers can use Find and edit source code to correct program errors. The Run and Debug view provides: VARIABLES section, which includes local function variables and CPU register values. WATCH section, which allows viewing user-defined expressions, for example, variable values. CALL STACK section that shows active RTOS threads along with the call stack. BREAKPOINTS section for managing stop points in application execution to inspect the state. TIP Click on a line number badge to navigate to the source code line. Other debugger specific views or features: Live Watch offers run-time viewing of user-defined expressions, for example, variable values. Disassembly shows assembly instructions and supports run control, for example with stepping and breakpoints. Debug Console lists debug output messages and allows entering expressions or GDB commands. Peripherals show the device peripheral registers and allow changing their values. Serial Monitor uses serial or TCP communication to interact with application I/O functions ( printf , getc , etc.). CPU Time shows execution timing and statistics of the past five breakpoints. Multi-Core Debug to view and control several processors in a device. Debug toolbar During debugging, the Debug toolbar contains actions to control the flow of the debug session, such as stepping through code, pausing execution, and stopping the debug session. Action Description Continue/Pause Continue : Resume normal program execution (up to the next breakpoint). Pause : Inspect code executing at the current location. Step Over Execute the next statement as a single command without inspecting or following its component steps. Step Into Enter the next statement to follow its execution line-by-line. Step Out When inside a function, return to the earlier execution context by completing remaining lines of the current method as though it were a single command. Restart Terminate the current program execution and start debugging again using the current run configuration. Stop/Disconnect Stop : Terminate the current debug session. Disconnect: Detach debugger from a core without changing the execution status (running/pause). Debug Session For multi-core devices, the list of active debug sessions and switch between them. Reset Target Reset the target device. VARIABLES During debugging, you can inspect variables, expressions, and registers in the VARIABLES section of the Run and Debug view or by hovering over a variable or expression in the source code editor. Variable values and expressions are evaluated in the context of the selected stack frame in the CALL STACK section. In the case of multi-core, the content is relative to the active debug session. To change the value of a variable during the debugging session, right-click on the variable in the VARIABLES section and select Set Value . You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. To filter variables by their name or value, use the Alt/Opt + Ctrl/Cmd + F keyboard shortcut while the focus is on the VARIABLES section , and type a search term. WATCH Variables and expressions can also be evaluated and watched in the WATCH section. You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. CALL STACK The CALL STACK section shows the function call tree that is currently on the stack. Threads are shown for applications that use an RTOS. Each function call is associated to its location and when source code is available a line number badge is shown. A click on this badge navigates to source file location. The window content is updated whenever program execution stops. BREAKPOINTS A breakpoint pauses the code execution at a specific point, so you can inspect the state of your application at that point. There are several breakpoint types. Setting breakpoints To set or unset a breakpoint, click on the editor margin or use F9 on the current line. Breakpoints in the editor margin are normally shown as red-filled circles. Disabled breakpoints have a filled grey circle. When a debugging session starts, breakpoints that can't be registered with the debugger change to a grey hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running. For more control of breakpoints, use the BREAKPOINTS section that lists and manages all breakpoints. \ud83d\udcdd Note: You can set breakpoints anytime during your debug session. However, when setting a breakpoint while running an application, the target stops for a short period of time. Breakpoint types Apart from the code breakpoint, there are other breakpoint types to satisfy specific use cases. Function breakpoints Instead of placing breakpoints directly in source code, a debugger can support creating breakpoints by specifying a function name. This is useful in situations where the source is not available but a function name is known. To create a function breakpoint, select the + button in the BREAKPOINTS section header and enter the function name. Function breakpoints are shown with a red triangle in the BREAKPOINTS section . Conditional breakpoints Set breakpoint conditions based on expressions, hit counts, or a combination of both. Expression condition: The breakpoint is hit whenever the expression evaluates to true. Hit count: The hit count controls how many times a breakpoint needs to be hit before it interrupts execution. Wait for breakpoint: The breakpoint is activated when another breakpoint is hit ( triggered breakpoint ). To add a conditional breakpoint: Create a conditional breakpoint Right-click in the editor margin and select Add Conditional Breakpoint. Use the Add Conditional Breakpoint command in the Command Palette (\u21e7\u2318P). Choose the type of condition you want to set (expression, hit count, or wait for a breakpoint). To add a condition to an existing breakpoint: Edit an existing breakpoint Right-click on the breakpoint in the editor margin and select Edit Breakpoint. Select the pencil icon next for an existing breakpoint in the BREAKPOINTS section of the Run and Debug view . Edit the condition (expression, hit count, or wait for breakpoint). \ud83d\udcdd Note: For checking the the breakpoint condition, the target is halted for a short period of time. Data breakpoints Data breakpoints can be set from the context menu of a variable in the WATCH section . The Break on Value Change/Read/Access commands add a data breakpoint that is hit when the value of the underlying variable changes/is read/is accessed. Data breakpoints are shown with a red hexagon in the BREAKPOINTS section and the type of breakpoint is shown (Write/Read/Access). \ud83d\udcdd Note: When hitting a data breakpoint, the program execution does not stop exactly on that line of code. Depending on the underlying CPU architecture, stopping can be delayed by up to 5 cycles. Use the Call Stack view to determine what caused the execution to stop. Triggered breakpoints A triggered breakpoint is type of conditional breakpoint that is enabled once another breakpoint is hit. They can be useful when diagnosing failure cases in code that happen only after a certain precondition. Triggered breakpoints can be set by right-clicking on the glyph margin, selecting Add Triggered Breakpoint , and then, choose which other breakpoint enables the breakpoint. Logpoints A logpoint pauses the program execution for a short period of time, sends a message to the debug console, and then continues with the application. Logpoints can help you save time by not having to add or remove logging statements in your code. A logpoint is represented by a diamond-shaped icon. Log messages are plain text, but can also include expressions to be evaluated within curly braces ( {} ). To add a logpoint, right-click in the editor left margin and select Add Logpoint, or use the Debug: Add Logpoint... command in the Command Palette ( Ctrl/Cmd + Shift + p ). Just like regular breakpoints, logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count. CPU Time Most Arm Cortex-M processors (except Cortex-M0/M0+/M23) include a DWT->CYCCNT register that counts CPU states. In combination with the CMSIS variable SystemCoreClock the CMSIS Debugger calculates execution time and displays it along with the selected processor core in the CPU Time Status bar. A click on the CPU Time Status bar opens the related VS Code command palette . Command Description CPU Time Print CPU execution time and history of past program stops. Reset CPU Time Reset CPU execution time and history. Set new reference time (zero point). \ud83d\udcdd Notes: The first program stop (typically at function main ) is the initial reference time (zero point). DWT->CYCCNT is a 32-bit register incremented with SystemCoreClock frequency. The time calculation copes with one overflow between program stops. Multiple overflows between program stops deliver wrong time information. Each processor in a multi-processor system has and independent DWT->CYCCNT register. Trace and Live view The Trace and Live View (available from the VS Code Activity Bar) currently shows the LIVE WATCH . You can add expressions to this view that are updated while the application is running on your target. You can add expressions to the LIVE WATCH by: Pressing the + sign and entering an expression. Using the context menu item Add to Live Watch in the editor or the the Run and Debug view. PERIPHERALS The PERIPHERALS view shows the device peripheral registers and allows to change their values. It uses the CMSIS-SVD files that are provided by silicon vendors and distributed as part of the CMSIS Device Family Packs (DFP). For more information, refer to the Peripheral Inspector GitHub repository . Memory Inspector The Memory Inspector provides a powerful and configurable memory viewer that features: Configurable Memory Display: Shows memory data with various display options. Address Navigation: Easily jump to and scroll through memory addresses. Variable Highlights: Colors memory ranges for variables. Multiple Memory Formats: Shows memory data on hover in multiple formats. Edit Memory: Allows in-place memory editing if the debug adapter supports the WriteMemoryRequest. Memory Management: Enables saving and restoring memory data for specific address ranges (Intel Hex format). Customized Views: Create and customize as many memory views as you need. Lock Views: Keep views static, unaffected by updates from the debug session. Periodic Refresh: Automatically refresh the memory data. Multiple Debug Sessions: Switch between multiple debug sessions using a dropdown in the memory view. For more information, refer to the Memory Inspector GitHub repository . Disassembly The command Open Disassembly View (available from command palette or context menus) shows the assembler instructions of the program intermixed with the source code. Using this view allows single stepping or managing breakpoints at the CPU instruction level. \ud83d\udcdd Note: Enable the VS Code setting Features > Debug > Disassembly View: Show Source Code to show assembler instructions interleaved with source code. RTOS Views For RTOS awareness, the RTOS Views extension needs to be added to CS Code. This extension supports a wide range of real-time operating systems, such as FreeRTOS, Zephyr, embOS,and Keil RTX5. \ud83d\udcdd Note: This is not a live view. It only gets updated when the program execution is stopped. To enable the view, you need to go to the debug view and press Ctrl/Cmd - Shift - P. Select RTOS Views: Toggle RTOS Panel . Afterwards, start your debug session. The view is located in the Terminal panel at the bottom and is called XRTOS . If it does not show values after entering a debug session and running the application, press Ctrl/Cmd - Shift - P again and select RTOS Views: Refresh . Debug Console The Debug Console enables viewing and interacting with the output of your code running in the debugger. Expressions can be evaluated with the Debug Console REPL (Read-Eval-Print Loop) feature. With the CMSIS Debug extension, you can use the Debug Console REPL to enter GDB commands while debugging. Before entering a GDB command, you have to explicitly enter a \"greater-than\"-character > so that the following strings can be evaluated as a GDB command. Debug Console input uses the mode of the active editor, which means that it supports syntax coloring, indentation, auto closing of quotes and other language features. Example The following example shows how to check the currently set breakpoints with the > info break command. Afterwards, the application is run with the > continue command. Serial Monitor The Serial Monitor allows users to configure, monitor, and communicate with serial or TCP ports. Multi-Core Debug A GDB server provides multiple connections to the processor cores (identified with pname ) of a device. The list below shows the output of pyOCD in the DEBUG CONSOLE of VS Code. 0000680 I Target device: MCXN947VDF [cbuild_run] 0001585 I core 0: Cortex-M33 r0p4, pname: cm33_core0 [cbuild_run] 0001585 I core 1: Cortex-M33 r0p4, pname: cm33_core1 [cbuild_run] 0001585 I start-pname: cm33_core0 [cbuild_run] 0001600 I Semihost server started on port 4444 (core 0) [server] 0001636 I GDB server started on port 3333 (core 0) [gdbserver] 0001641 I Semihost server started on port 4445 (core 1) [server] 0001642 I GDB server started on port 3334 (core 1) [gdbserver] 0007560 I Client connected to port 3333! [gdbserver] The start-pname indicates the processor that starts first and boots the system. A debug launch command connects to this processor. Use a debug attach command to connect to processors that are running. The picture below highlights the parts of the user interface that interact with processors. Select a processor and Start Debug . This connects the debugger. Select a Processor in the debug toolbar, or Click in CALL STACK on a thread or function name to select a processor. The selected processor is also shown in the CPU Time Status bar . This processor context is used in the VARIABLES and WATCH view. \ud83d\udcdd Notes: The SEGGER JLink GDB server uses a launch command to connect to a running processor whereas other GDB servers use an attach command. A Disassembly View opens only for a selected processor; otherwise the command is shown as disabled. Debug adapter support Keil Studio support various debug adapters and and GDB server implementations from different vendors: Most of the debug adapters (including ST-Link) are served by pyOCD using the Arm CMSIS Debugger extension . Segger J-Link Server is supported. Arm Debugger is supported. Running on Arm FVPs is possible. Arm Keil \u00b5Vision is supported (only on Windows). If you are using a third-party debug adapter, make sure that the latest drivers are installed on your machine and that the debug adapters are running the latest firmware. Set the PATH variable correctly. Debug Adapter Notes Arm ULINKplus Make sure that the V2.x.x firmware is installed. Infineon KitProg3 Make sure that the latest firmware is installed . Microchip PICKit Basic Use the Python utility pycmsisdapswitcher to switch the firmware to a CMSIS-DAP v2 implementation. Nuvoton NuLink Make sure that the latest firmware is installed . NXP MCU-Link Make sure that the latest firmware is installed . Raspberry Pi Debugprobe Make sure that the latest firmware is installed . SEGGER J-Link For J-Link support, visit J-Link/J-Trace Downloads . Set the PATH variable to the bin directory of the installation. STMicroelectronics ST-Link For ST-LINK/V2 and ST-LINK/V2-1 support on Windows, download the USB driver here: STSW-LINK009 . Select debug adapter In the CMSIS view , open the Manage Solution dialog and go to the Debug Adapter section . Select one of the debug adapters. Once selected, the following JSON files are created automatically: In the launch.json file, attach and launch configurations are added that let you attach the debug adapter to an already running GDB instance (for example when you have issued a load and run before) or launch a new debug session. In the tasks.json file, the tasks CMSIS Erase , CMSIS Load , and CMSIS Run are created. Note If you wish to preserve manual modification to the JSON files, uncheck \"Update launch.json and tasks.json\" in the Debug Adapter for ... section. Set debug adapter ID In case you have multiple debug adapters connected to your computer, you can set the ID of the probe you wish to use in the CMSIS Solution extension settings. Open the settings by pressing CTRL/CMD + , . Enter probe in the search field. Select if you want to set the probe ID for your user or only for the current workspace (recommended). Enter the Unique ID you have retrieved using Target Information . Configure run and debug In VS Code, you can integrate external tools via a tasks.json file. The debug configuration is managed via the launch.json file. Both files are generated automatically based on your *.csolution.yml file: When creating a Target Set in the Manage Solution view and selecting a Debug Adapter , the information is stored in the target-set: node in the *.csolution.yml file (refer to the CMSIS-Toolbox user's guide for details on target-set ). When you save the target set, the CMSIS Solution extension calls cbuild setup that generates the *.cbuild-run.yml file which contains the run and debug description of your solution. Using template files for the various debug adapters from the Debug Adapter Registry and taking the user inputs into account, the CMSIS Solution extension then generates the launch.json and tasks.json files. Custom launch.json and tasks.json settings User defined launch configurations and tasks can be added directly into the workspace files. When updating these files custom or modified entries are kept untouched if detected: .vscode/launch.json Each auto-generated configuration has an additional property cmsis.updateConfiguration=\"auto\" . By either removing this property, or by setting it to manual will exclude it from further automatic updates. .vscode/tasks.json All auto-generated tasks have labels starting with CMSIS . Such tasks are removed on updates. Custom tasks must assure they use names not starting with CMSIS . Instead of adding custom content into these automatically updated files causing version system modifications all the time, one can extract those into configuration subfolders and only keep these under version control: .vscode/launch.json.d/*.json Each JSON file must respect the launch.json schema. All contained configurations are merged into the workspace .vscode/launch.json file by name property. Auto-generated configurations can be overwritten if required without attention to the cmsis.updateConfiguration property. .vscode/tasks.json.d/*.json Each JSON file must respect the tasks.json schema. All contained tasks are merged into the workspace .vscode/tasks.json file by label property. Auto-generated CMSIS tasks can be overwritten if required. For multi-solution workspaces, i.e., having multiple .csolution.yml files in subfolders, solution-specific files in solution's .vscode/launch.json.d/ and .vscode/tasks.json.d/ directories are included for the active solution applying the same rules as above. This can be used to include solution specific content into the workspace configuration based on the currently used solution. Note To trigger an update of the launch.json and tasks.json files, press Ctrl/Cmd+Shift+p and select Update Debug Tasks and Launch Configurations . pyOCD In the Manage Solution dialog, select the one of the debug adapters named xyz@pyOCD : For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Text File: saves the output to a file in the project workspace. Disabled: does not redirect the serial output. J-Link Server In the Manage Solution dialog select J-Link Server . For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Disabled: does not redirect the serial output. Arm Debugger You can use the Arm Debugger with Keil Studio. Prerequisites Before you can launch a debug session using Arm Debugger, you need to: Install the Arm Debugger VS Code extension . Add the Arm Debugger to your vcpkg-configuration.json file, for example: \"arm:debuggers/arm/armdbg\": \"6.6.0\" Setup for Arm Debugger In the Manage Solution dialog, select the one of the debug adapters named xyz@Arm-Debugger . Arm FVPs In the Manage Solution dialog: Select the Arm-FVP debug adapter Select the model you wish to use Point to your configuration file If you wish to set a simulation limit, add this in the Misc box: Keil uVision In the Manage Solution dialog: Select the Keil uVision debug adapter. Set the path to the UV4.exe file (the default is %LOCALAPPDATA%\\Keil_v5\\UV4\\UV4.exe ). This setting is saved in the *.csolution.yml file. Attention This only works on a Windows PC. Changing the default for the current workspace If you wish to change the default path to \u00b5Vision for your current workspace , you need to create the following entry in your .vscode/settings.json file: { \"cmsis-csolution.debug-adapters\": { \"Keil uVision\": { \"uv4\": \"/path/to/UV4.exe\" } } } Attention If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default. Changing the default for a user If you wish to set the \u00b5Vision path for your user, open the global settings.json file: Press Ctrl/Cmd + Shift + p and type settings . Select Preferences: Open User Settings (JSON) . This opens the global settings.json file. Enter the path as shown above and save the file. Enhancing the debug experience To ensure the best debug experience with Arm Compiler for Embedded, make sure that your CMSIS solution files contain the following. csolution.yml In the *.csolution.yml file, insert the following block in - target-types\\- type section: target-set: - set: debugger: name: # set to name of your debug adapter Insert the following before the - projects section: misc: - for-compiler: AC6 C-CPP: - -gdwarf-5 ASM: - -gdwarf-5 cproject.yml In the *.cproject.yml file, add at the end: output: type: - elf - hex - map","title":"Debug"},{"location":"debug.html#debug","text":"","title":"Debug"},{"location":"debug.html#debugger-user-interface","text":"Many features of the CMSIS Debugger extension are exposed in the Run and Debug view of VS Code. Start debugging selects a configuration: launch to start download/debug, attach to connect with a running system. Debug Toolbar has buttons for the most common debugging actions that control execution. The Trace and Live View shows the LIVE WATCH window. Debug Statusbar shows the time spent running the application. The Debug Console can be used to interact with the debugger on the command line. Most editor features are available during debugging. For example, developers can use Find and edit source code to correct program errors. The Run and Debug view provides: VARIABLES section, which includes local function variables and CPU register values. WATCH section, which allows viewing user-defined expressions, for example, variable values. CALL STACK section that shows active RTOS threads along with the call stack. BREAKPOINTS section for managing stop points in application execution to inspect the state. TIP Click on a line number badge to navigate to the source code line. Other debugger specific views or features: Live Watch offers run-time viewing of user-defined expressions, for example, variable values. Disassembly shows assembly instructions and supports run control, for example with stepping and breakpoints. Debug Console lists debug output messages and allows entering expressions or GDB commands. Peripherals show the device peripheral registers and allow changing their values. Serial Monitor uses serial or TCP communication to interact with application I/O functions ( printf , getc , etc.). CPU Time shows execution timing and statistics of the past five breakpoints. Multi-Core Debug to view and control several processors in a device.","title":"Debugger User Interface"},{"location":"debug.html#debug-toolbar","text":"During debugging, the Debug toolbar contains actions to control the flow of the debug session, such as stepping through code, pausing execution, and stopping the debug session. Action Description Continue/Pause Continue : Resume normal program execution (up to the next breakpoint). Pause : Inspect code executing at the current location. Step Over Execute the next statement as a single command without inspecting or following its component steps. Step Into Enter the next statement to follow its execution line-by-line. Step Out When inside a function, return to the earlier execution context by completing remaining lines of the current method as though it were a single command. Restart Terminate the current program execution and start debugging again using the current run configuration. Stop/Disconnect Stop : Terminate the current debug session. Disconnect: Detach debugger from a core without changing the execution status (running/pause). Debug Session For multi-core devices, the list of active debug sessions and switch between them. Reset Target Reset the target device.","title":"Debug toolbar"},{"location":"debug.html#variables","text":"During debugging, you can inspect variables, expressions, and registers in the VARIABLES section of the Run and Debug view or by hovering over a variable or expression in the source code editor. Variable values and expressions are evaluated in the context of the selected stack frame in the CALL STACK section. In the case of multi-core, the content is relative to the active debug session. To change the value of a variable during the debugging session, right-click on the variable in the VARIABLES section and select Set Value . You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section. To filter variables by their name or value, use the Alt/Opt + Ctrl/Cmd + F keyboard shortcut while the focus is on the VARIABLES section , and type a search term.","title":"VARIABLES"},{"location":"debug.html#watch","text":"Variables and expressions can also be evaluated and watched in the WATCH section. You can use the Copy Value action to copy the variable's value, or the Copy as Expression action to copy an expression to access the variable. You can then use this expression in the WATCH section.","title":"WATCH"},{"location":"debug.html#call-stack","text":"The CALL STACK section shows the function call tree that is currently on the stack. Threads are shown for applications that use an RTOS. Each function call is associated to its location and when source code is available a line number badge is shown. A click on this badge navigates to source file location. The window content is updated whenever program execution stops.","title":"CALL STACK"},{"location":"debug.html#breakpoints","text":"A breakpoint pauses the code execution at a specific point, so you can inspect the state of your application at that point. There are several breakpoint types.","title":"BREAKPOINTS"},{"location":"debug.html#setting-breakpoints","text":"To set or unset a breakpoint, click on the editor margin or use F9 on the current line. Breakpoints in the editor margin are normally shown as red-filled circles. Disabled breakpoints have a filled grey circle. When a debugging session starts, breakpoints that can't be registered with the debugger change to a grey hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running. For more control of breakpoints, use the BREAKPOINTS section that lists and manages all breakpoints. \ud83d\udcdd Note: You can set breakpoints anytime during your debug session. However, when setting a breakpoint while running an application, the target stops for a short period of time.","title":"Setting breakpoints"},{"location":"debug.html#breakpoint-types","text":"Apart from the code breakpoint, there are other breakpoint types to satisfy specific use cases.","title":"Breakpoint types"},{"location":"debug.html#function-breakpoints","text":"Instead of placing breakpoints directly in source code, a debugger can support creating breakpoints by specifying a function name. This is useful in situations where the source is not available but a function name is known. To create a function breakpoint, select the + button in the BREAKPOINTS section header and enter the function name. Function breakpoints are shown with a red triangle in the BREAKPOINTS section .","title":"Function breakpoints"},{"location":"debug.html#conditional-breakpoints","text":"Set breakpoint conditions based on expressions, hit counts, or a combination of both. Expression condition: The breakpoint is hit whenever the expression evaluates to true. Hit count: The hit count controls how many times a breakpoint needs to be hit before it interrupts execution. Wait for breakpoint: The breakpoint is activated when another breakpoint is hit ( triggered breakpoint ). To add a conditional breakpoint: Create a conditional breakpoint Right-click in the editor margin and select Add Conditional Breakpoint. Use the Add Conditional Breakpoint command in the Command Palette (\u21e7\u2318P). Choose the type of condition you want to set (expression, hit count, or wait for a breakpoint). To add a condition to an existing breakpoint: Edit an existing breakpoint Right-click on the breakpoint in the editor margin and select Edit Breakpoint. Select the pencil icon next for an existing breakpoint in the BREAKPOINTS section of the Run and Debug view . Edit the condition (expression, hit count, or wait for breakpoint). \ud83d\udcdd Note: For checking the the breakpoint condition, the target is halted for a short period of time.","title":"Conditional breakpoints"},{"location":"debug.html#data-breakpoints","text":"Data breakpoints can be set from the context menu of a variable in the WATCH section . The Break on Value Change/Read/Access commands add a data breakpoint that is hit when the value of the underlying variable changes/is read/is accessed. Data breakpoints are shown with a red hexagon in the BREAKPOINTS section and the type of breakpoint is shown (Write/Read/Access). \ud83d\udcdd Note: When hitting a data breakpoint, the program execution does not stop exactly on that line of code. Depending on the underlying CPU architecture, stopping can be delayed by up to 5 cycles. Use the Call Stack view to determine what caused the execution to stop.","title":"Data breakpoints"},{"location":"debug.html#triggered-breakpoints","text":"A triggered breakpoint is type of conditional breakpoint that is enabled once another breakpoint is hit. They can be useful when diagnosing failure cases in code that happen only after a certain precondition. Triggered breakpoints can be set by right-clicking on the glyph margin, selecting Add Triggered Breakpoint , and then, choose which other breakpoint enables the breakpoint.","title":"Triggered breakpoints"},{"location":"debug.html#logpoints","text":"A logpoint pauses the program execution for a short period of time, sends a message to the debug console, and then continues with the application. Logpoints can help you save time by not having to add or remove logging statements in your code. A logpoint is represented by a diamond-shaped icon. Log messages are plain text, but can also include expressions to be evaluated within curly braces ( {} ). To add a logpoint, right-click in the editor left margin and select Add Logpoint, or use the Debug: Add Logpoint... command in the Command Palette ( Ctrl/Cmd + Shift + p ). Just like regular breakpoints, logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count.","title":"Logpoints"},{"location":"debug.html#cpu-time","text":"Most Arm Cortex-M processors (except Cortex-M0/M0+/M23) include a DWT->CYCCNT register that counts CPU states. In combination with the CMSIS variable SystemCoreClock the CMSIS Debugger calculates execution time and displays it along with the selected processor core in the CPU Time Status bar. A click on the CPU Time Status bar opens the related VS Code command palette . Command Description CPU Time Print CPU execution time and history of past program stops. Reset CPU Time Reset CPU execution time and history. Set new reference time (zero point). \ud83d\udcdd Notes: The first program stop (typically at function main ) is the initial reference time (zero point). DWT->CYCCNT is a 32-bit register incremented with SystemCoreClock frequency. The time calculation copes with one overflow between program stops. Multiple overflows between program stops deliver wrong time information. Each processor in a multi-processor system has and independent DWT->CYCCNT register.","title":"CPU Time"},{"location":"debug.html#trace-and-live-view","text":"The Trace and Live View (available from the VS Code Activity Bar) currently shows the LIVE WATCH . You can add expressions to this view that are updated while the application is running on your target. You can add expressions to the LIVE WATCH by: Pressing the + sign and entering an expression. Using the context menu item Add to Live Watch in the editor or the the Run and Debug view.","title":"Trace and Live view"},{"location":"debug.html#peripherals","text":"The PERIPHERALS view shows the device peripheral registers and allows to change their values. It uses the CMSIS-SVD files that are provided by silicon vendors and distributed as part of the CMSIS Device Family Packs (DFP). For more information, refer to the Peripheral Inspector GitHub repository .","title":"PERIPHERALS"},{"location":"debug.html#memory-inspector","text":"The Memory Inspector provides a powerful and configurable memory viewer that features: Configurable Memory Display: Shows memory data with various display options. Address Navigation: Easily jump to and scroll through memory addresses. Variable Highlights: Colors memory ranges for variables. Multiple Memory Formats: Shows memory data on hover in multiple formats. Edit Memory: Allows in-place memory editing if the debug adapter supports the WriteMemoryRequest. Memory Management: Enables saving and restoring memory data for specific address ranges (Intel Hex format). Customized Views: Create and customize as many memory views as you need. Lock Views: Keep views static, unaffected by updates from the debug session. Periodic Refresh: Automatically refresh the memory data. Multiple Debug Sessions: Switch between multiple debug sessions using a dropdown in the memory view. For more information, refer to the Memory Inspector GitHub repository .","title":"Memory Inspector"},{"location":"debug.html#disassembly","text":"The command Open Disassembly View (available from command palette or context menus) shows the assembler instructions of the program intermixed with the source code. Using this view allows single stepping or managing breakpoints at the CPU instruction level. \ud83d\udcdd Note: Enable the VS Code setting Features > Debug > Disassembly View: Show Source Code to show assembler instructions interleaved with source code.","title":"Disassembly"},{"location":"debug.html#rtos-views","text":"For RTOS awareness, the RTOS Views extension needs to be added to CS Code. This extension supports a wide range of real-time operating systems, such as FreeRTOS, Zephyr, embOS,and Keil RTX5. \ud83d\udcdd Note: This is not a live view. It only gets updated when the program execution is stopped. To enable the view, you need to go to the debug view and press Ctrl/Cmd - Shift - P. Select RTOS Views: Toggle RTOS Panel . Afterwards, start your debug session. The view is located in the Terminal panel at the bottom and is called XRTOS . If it does not show values after entering a debug session and running the application, press Ctrl/Cmd - Shift - P again and select RTOS Views: Refresh .","title":"RTOS Views"},{"location":"debug.html#debug-console","text":"The Debug Console enables viewing and interacting with the output of your code running in the debugger. Expressions can be evaluated with the Debug Console REPL (Read-Eval-Print Loop) feature. With the CMSIS Debug extension, you can use the Debug Console REPL to enter GDB commands while debugging. Before entering a GDB command, you have to explicitly enter a \"greater-than\"-character > so that the following strings can be evaluated as a GDB command. Debug Console input uses the mode of the active editor, which means that it supports syntax coloring, indentation, auto closing of quotes and other language features. Example The following example shows how to check the currently set breakpoints with the > info break command. Afterwards, the application is run with the > continue command.","title":"Debug Console"},{"location":"debug.html#serial-monitor","text":"The Serial Monitor allows users to configure, monitor, and communicate with serial or TCP ports.","title":"Serial Monitor"},{"location":"debug.html#multi-core-debug","text":"A GDB server provides multiple connections to the processor cores (identified with pname ) of a device. The list below shows the output of pyOCD in the DEBUG CONSOLE of VS Code. 0000680 I Target device: MCXN947VDF [cbuild_run] 0001585 I core 0: Cortex-M33 r0p4, pname: cm33_core0 [cbuild_run] 0001585 I core 1: Cortex-M33 r0p4, pname: cm33_core1 [cbuild_run] 0001585 I start-pname: cm33_core0 [cbuild_run] 0001600 I Semihost server started on port 4444 (core 0) [server] 0001636 I GDB server started on port 3333 (core 0) [gdbserver] 0001641 I Semihost server started on port 4445 (core 1) [server] 0001642 I GDB server started on port 3334 (core 1) [gdbserver] 0007560 I Client connected to port 3333! [gdbserver] The start-pname indicates the processor that starts first and boots the system. A debug launch command connects to this processor. Use a debug attach command to connect to processors that are running. The picture below highlights the parts of the user interface that interact with processors. Select a processor and Start Debug . This connects the debugger. Select a Processor in the debug toolbar, or Click in CALL STACK on a thread or function name to select a processor. The selected processor is also shown in the CPU Time Status bar . This processor context is used in the VARIABLES and WATCH view. \ud83d\udcdd Notes: The SEGGER JLink GDB server uses a launch command to connect to a running processor whereas other GDB servers use an attach command. A Disassembly View opens only for a selected processor; otherwise the command is shown as disabled.","title":"Multi-Core Debug"},{"location":"debug.html#debug-adapter-support","text":"Keil Studio support various debug adapters and and GDB server implementations from different vendors: Most of the debug adapters (including ST-Link) are served by pyOCD using the Arm CMSIS Debugger extension . Segger J-Link Server is supported. Arm Debugger is supported. Running on Arm FVPs is possible. Arm Keil \u00b5Vision is supported (only on Windows). If you are using a third-party debug adapter, make sure that the latest drivers are installed on your machine and that the debug adapters are running the latest firmware. Set the PATH variable correctly. Debug Adapter Notes Arm ULINKplus Make sure that the V2.x.x firmware is installed. Infineon KitProg3 Make sure that the latest firmware is installed . Microchip PICKit Basic Use the Python utility pycmsisdapswitcher to switch the firmware to a CMSIS-DAP v2 implementation. Nuvoton NuLink Make sure that the latest firmware is installed . NXP MCU-Link Make sure that the latest firmware is installed . Raspberry Pi Debugprobe Make sure that the latest firmware is installed . SEGGER J-Link For J-Link support, visit J-Link/J-Trace Downloads . Set the PATH variable to the bin directory of the installation. STMicroelectronics ST-Link For ST-LINK/V2 and ST-LINK/V2-1 support on Windows, download the USB driver here: STSW-LINK009 .","title":"Debug adapter support"},{"location":"debug.html#select-debug-adapter","text":"In the CMSIS view , open the Manage Solution dialog and go to the Debug Adapter section . Select one of the debug adapters. Once selected, the following JSON files are created automatically: In the launch.json file, attach and launch configurations are added that let you attach the debug adapter to an already running GDB instance (for example when you have issued a load and run before) or launch a new debug session. In the tasks.json file, the tasks CMSIS Erase , CMSIS Load , and CMSIS Run are created. Note If you wish to preserve manual modification to the JSON files, uncheck \"Update launch.json and tasks.json\" in the Debug Adapter for ... section.","title":"Select debug adapter"},{"location":"debug.html#set-debug-adapter-id","text":"In case you have multiple debug adapters connected to your computer, you can set the ID of the probe you wish to use in the CMSIS Solution extension settings. Open the settings by pressing CTRL/CMD + , . Enter probe in the search field. Select if you want to set the probe ID for your user or only for the current workspace (recommended). Enter the Unique ID you have retrieved using Target Information .","title":"Set debug adapter ID"},{"location":"debug.html#configure-run-and-debug","text":"In VS Code, you can integrate external tools via a tasks.json file. The debug configuration is managed via the launch.json file. Both files are generated automatically based on your *.csolution.yml file: When creating a Target Set in the Manage Solution view and selecting a Debug Adapter , the information is stored in the target-set: node in the *.csolution.yml file (refer to the CMSIS-Toolbox user's guide for details on target-set ). When you save the target set, the CMSIS Solution extension calls cbuild setup that generates the *.cbuild-run.yml file which contains the run and debug description of your solution. Using template files for the various debug adapters from the Debug Adapter Registry and taking the user inputs into account, the CMSIS Solution extension then generates the launch.json and tasks.json files.","title":"Configure run and debug"},{"location":"debug.html#custom-launchjson-and-tasksjson-settings","text":"User defined launch configurations and tasks can be added directly into the workspace files. When updating these files custom or modified entries are kept untouched if detected: .vscode/launch.json Each auto-generated configuration has an additional property cmsis.updateConfiguration=\"auto\" . By either removing this property, or by setting it to manual will exclude it from further automatic updates. .vscode/tasks.json All auto-generated tasks have labels starting with CMSIS . Such tasks are removed on updates. Custom tasks must assure they use names not starting with CMSIS . Instead of adding custom content into these automatically updated files causing version system modifications all the time, one can extract those into configuration subfolders and only keep these under version control: .vscode/launch.json.d/*.json Each JSON file must respect the launch.json schema. All contained configurations are merged into the workspace .vscode/launch.json file by name property. Auto-generated configurations can be overwritten if required without attention to the cmsis.updateConfiguration property. .vscode/tasks.json.d/*.json Each JSON file must respect the tasks.json schema. All contained tasks are merged into the workspace .vscode/tasks.json file by label property. Auto-generated CMSIS tasks can be overwritten if required. For multi-solution workspaces, i.e., having multiple .csolution.yml files in subfolders, solution-specific files in solution's .vscode/launch.json.d/ and .vscode/tasks.json.d/ directories are included for the active solution applying the same rules as above. This can be used to include solution specific content into the workspace configuration based on the currently used solution. Note To trigger an update of the launch.json and tasks.json files, press Ctrl/Cmd+Shift+p and select Update Debug Tasks and Launch Configurations .","title":"Custom launch.json and tasks.json settings"},{"location":"debug.html#pyocd","text":"In the Manage Solution dialog, select the one of the debug adapters named xyz@pyOCD : For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Text File: saves the output to a file in the project workspace. Disabled: does not redirect the serial output.","title":"pyOCD"},{"location":"debug.html#j-link-server","text":"In the Manage Solution dialog select J-Link Server . For the Debug Interface , you can: Set the maximum clock speed. Select the debug protocol ( SWD or JTAG ). For Telnet , you can: Enable or disable the use of Telnet for semihosting. Set the Telnet Mode to: Telnet Server: if you want to connect to the target with a standalone Telnet Client application. Debug Console: redirects the output to the VS Code DEBUG CONSOLE panel. Serial Monitor: redirects the output to the SERIAL MONITOR extension. Disabled: does not redirect the serial output.","title":"J-Link Server"},{"location":"debug.html#arm-debugger","text":"You can use the Arm Debugger with Keil Studio.","title":"Arm Debugger"},{"location":"debug.html#prerequisites","text":"Before you can launch a debug session using Arm Debugger, you need to: Install the Arm Debugger VS Code extension . Add the Arm Debugger to your vcpkg-configuration.json file, for example: \"arm:debuggers/arm/armdbg\": \"6.6.0\"","title":"Prerequisites"},{"location":"debug.html#setup-for-arm-debugger","text":"In the Manage Solution dialog, select the one of the debug adapters named xyz@Arm-Debugger .","title":"Setup for Arm Debugger"},{"location":"debug.html#arm-fvps","text":"In the Manage Solution dialog: Select the Arm-FVP debug adapter Select the model you wish to use Point to your configuration file If you wish to set a simulation limit, add this in the Misc box:","title":"Arm FVPs"},{"location":"debug.html#keil-uvision","text":"In the Manage Solution dialog: Select the Keil uVision debug adapter. Set the path to the UV4.exe file (the default is %LOCALAPPDATA%\\Keil_v5\\UV4\\UV4.exe ). This setting is saved in the *.csolution.yml file. Attention This only works on a Windows PC.","title":"Keil uVision"},{"location":"debug.html#changing-the-default-for-the-current-workspace","text":"If you wish to change the default path to \u00b5Vision for your current workspace , you need to create the following entry in your .vscode/settings.json file: { \"cmsis-csolution.debug-adapters\": { \"Keil uVision\": { \"uv4\": \"/path/to/UV4.exe\" } } } Attention If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default.","title":"Changing the default for the current workspace"},{"location":"debug.html#changing-the-default-for-a-user","text":"If you wish to set the \u00b5Vision path for your user, open the global settings.json file: Press Ctrl/Cmd + Shift + p and type settings . Select Preferences: Open User Settings (JSON) . This opens the global settings.json file. Enter the path as shown above and save the file.","title":"Changing the default for a user"},{"location":"debug.html#enhancing-the-debug-experience","text":"To ensure the best debug experience with Arm Compiler for Embedded, make sure that your CMSIS solution files contain the following.","title":"Enhancing the debug experience"},{"location":"debug.html#csolutionyml","text":"In the *.csolution.yml file, insert the following block in - target-types\\- type section: target-set: - set: debugger: name: # set to name of your debug adapter Insert the following before the - projects section: misc: - for-compiler: AC6 C-CPP: - -gdwarf-5 ASM: - -gdwarf-5","title":"csolution.yml"},{"location":"debug.html#cprojectyml","text":"In the *.cproject.yml file, add at the end: output: type: - elf - hex - map","title":"cproject.yml"},{"location":"featureroadmap.html","text":"Roadmap Project management Project creation and organization Feature Description \ud83d\udfe2 Project creation Create, open, and manage CMSIS solution projects \ud83d\udfe2 Multi-project solution Manage multiple related projects within a single CMSIS solution \ud83d\udfe2 Multi-solution workspace Manage multiple solutions within one workspace (VS Code built-in) \ud83d\udfe2 Target types Multiple targets (e.g., HW, models) within one solution \ud83d\udfe2 Build types Multiple build types (e.g., Debug, Release) within one solution \ud83d\udfe2 File groups Logical grouping of source, header, and library files \ud83d\udfe2 Layer support Easily retarget hardware connections \ud83d\udfe2 Software components Manage software components on a project/layer level \ud83d\udfe1 Manage packs Manage CMSIS-Packs and versions graphically \ud83d\udfe2 Zephyr project support Build and debug Zephyr-based applications \ud83d\udfe2 Configuration Wizard GUI-assisted generation and modification of configuration code Build system Feature Description \ud83d\udfe2 Integrated build Based on CMSIS-Toolbox \ud83d\udfe2 Incremental build Dependency tracking to rebuild only changed files \ud83d\udfe2 Toolchain options Per-target configuration of compiler, assembler, linker, and debugger \ud83d\udfe2 west support Build Zephyr projects natively Build output and feedback Feature Description \ud83d\udfe2 Map file Memory map of the image \ud83d\udfe2 Build log Detailed output of errors, warnings, and build status \ud83d\udfe2 Error navigation Direct navigation from build messages to source code Integration and extensibility Feature Description \ud83d\udfe2 External tools Invoke third-party tools via configurable commands \ud83d\udfe2 Version control Excellent integration with Git (VS Code built-in) \ud83d\udfe2 AI coding agents Integration with third-party coding agents (via VS Code extensions) \ud83d\udfe2 Additional extensions Use third-party extensions with Keil Studio (VS Code built-in) Compiler support Feature Description \ud83d\udfe2 Arm Compiler for Embedded (AC6) Professional toolchain from Arm \ud83d\udfe2 Arm Toolchain for Embedded (ATfE) Open-source, LLVM-based toolchain from Arm \ud83d\udfe2 Arm GNU Toolchain (GCC) Open-source, GCC-based toolchain from Arm \ud83d\udfe2 Clangd support For comprehensive code completion \ud83d\udfe2 Library generation Generate libraries using library manager \ud83d\udfe2 Compiler and assembler control options Interface for configuring compiler flags and options Debug Core debug control Category Debug Features \ud83d\udfe2 Run control Run, halt, reset, step into, step over, step out \ud83d\udfe2 Breakpoints Various types of breakpoints \ud83d\udfe1 Watchpoints Data read/write/access breakpoints (DWT) \ud83d\udfe2 Multi-core Single GUI for multiple cores in a device Register and memory inspection Category Debug Features \ud83d\udfe2 Core registers R0\u2013R15, PSR, MSP, PSP, CONTROL \ud83d\udfe1 Core peripheral registers NVIC, SysTick, MPU \ud83d\udfe2 Peripheral registers CMSIS-SVD decoded peripheral views \ud83d\udfe2 Memory inspection Configurable memory views \ud83d\udfe2 Memory inspection Memory access breakpoints \ud83d\udfe2 Memory inspection Memory window live update Source-level debugging Category Debug Features \ud83d\udfe2 Variables Call stack view \ud83d\udfe2 Variables Local variable inspection \ud83d\udfe2 Disassembly Disassembly window \ud83d\udfe1 Disassembly Sync Disassembly and source \ud83d\udfe2 Variable inspection Inline variable display \ud83d\udfe2 Variable inspection Variable hover inspection \ud83d\udfe1 Execution flow Function call trace Real-time and trace features Category Debug Features \ud83d\udfe1 Serial wire output ITM printf -style output \ud83d\udfe2 Variable tracing Real-time data watch \ud83d\udfe1 Event tracing Exception trace \ud83d\udfe1 Event tracing Interrupt trace \ud83d\udfe2 Sampling CPU time \ud83d\udfe1 Embedded trace buffer ETB instruction trace \ud83d\udfe1 Micro trace buffer MTB instruction trace \ud83d\udd34 Instruction trace Embedded trace macrocell Component Viewer and Event Recorder Category Debug Features \ud83d\udfe1 Component Viewer Display and live update \ud83d\udfe1 Event Recorder Show event information \ud83d\udfe1 Event Recorder Save/log \ud83d\udfe1 Event Recorder Event filtering \ud83d\udfe1 Event Recorder Event statistics RTOS awareness Category Debug Features \ud83d\udfe2 RTOS support Keil RTX5, FreeRTOS, Zephyr awareness \ud83d\udfe2 Thread visibility Thread list and state display \ud83d\udfe2 Stack usage Per-task stack usage Analysis and visualization Category Debug Features \ud83d\udfe1 Logic Analyzer Graphical variable and signal display \ud83d\udfe1 System Analyzer Data trace, core clock, ITM, current/voltage \ud83d\udfe2 Serial monitor Communication via serial/TCP ports \ud83d\udd34 Performance analysis Execution time analysis \ud83d\udd34 Performance analysis Function profiling \ud83d\udd34 Execution statistics Code coverage \ud83d\udfe1 Execution statistics Timing statistics (only via Event Recorder) Simulation Category Debug Features \ud83d\udfe2 Fast models (FVPs) Instruction-accurate CPU simulation \ud83d\udfe1 Debug FVPs Debugging on FVPs Note FVP simulation models are not available in the MDK-Essential edition. Debug probe support Category Debug Features \ud83d\udfe2 Debug probes ULINK2/UILNKplus support \ud83d\udfe1 Debug probes UILNKpro support \ud83d\udfe2 Debug probes CMSIS-DAP support \ud83d\udfe2 Debug probes J-Link support \ud83d\udfe2 Debug interfaces SWD \ud83d\udfe2 Debug interfaces JTAG \ud83d\udfe2 Debug interfaces Target detection \ud83d\udfe1 Debug interfaces Connect configuration \ud83d\udfe2 Flash programming Flash download \ud83d\udfe1 Flash programming Flash verification \ud83d\udfe1 Flash programming Configuration Legend \ud83d\udfe2 available \ud83d\udfe1 feature implementation progressing \ud83d\udd34 investigating for alternative solution","title":"Features and roadmap"},{"location":"featureroadmap.html#roadmap","text":"","title":"Roadmap"},{"location":"featureroadmap.html#project-management","text":"","title":"Project management"},{"location":"featureroadmap.html#project-creation-and-organization","text":"Feature Description \ud83d\udfe2 Project creation Create, open, and manage CMSIS solution projects \ud83d\udfe2 Multi-project solution Manage multiple related projects within a single CMSIS solution \ud83d\udfe2 Multi-solution workspace Manage multiple solutions within one workspace (VS Code built-in) \ud83d\udfe2 Target types Multiple targets (e.g., HW, models) within one solution \ud83d\udfe2 Build types Multiple build types (e.g., Debug, Release) within one solution \ud83d\udfe2 File groups Logical grouping of source, header, and library files \ud83d\udfe2 Layer support Easily retarget hardware connections \ud83d\udfe2 Software components Manage software components on a project/layer level \ud83d\udfe1 Manage packs Manage CMSIS-Packs and versions graphically \ud83d\udfe2 Zephyr project support Build and debug Zephyr-based applications \ud83d\udfe2 Configuration Wizard GUI-assisted generation and modification of configuration code","title":"Project creation and organization"},{"location":"featureroadmap.html#build-system","text":"Feature Description \ud83d\udfe2 Integrated build Based on CMSIS-Toolbox \ud83d\udfe2 Incremental build Dependency tracking to rebuild only changed files \ud83d\udfe2 Toolchain options Per-target configuration of compiler, assembler, linker, and debugger \ud83d\udfe2 west support Build Zephyr projects natively","title":"Build system"},{"location":"featureroadmap.html#build-output-and-feedback","text":"Feature Description \ud83d\udfe2 Map file Memory map of the image \ud83d\udfe2 Build log Detailed output of errors, warnings, and build status \ud83d\udfe2 Error navigation Direct navigation from build messages to source code","title":"Build output and feedback"},{"location":"featureroadmap.html#integration-and-extensibility","text":"Feature Description \ud83d\udfe2 External tools Invoke third-party tools via configurable commands \ud83d\udfe2 Version control Excellent integration with Git (VS Code built-in) \ud83d\udfe2 AI coding agents Integration with third-party coding agents (via VS Code extensions) \ud83d\udfe2 Additional extensions Use third-party extensions with Keil Studio (VS Code built-in)","title":"Integration and extensibility"},{"location":"featureroadmap.html#compiler-support","text":"Feature Description \ud83d\udfe2 Arm Compiler for Embedded (AC6) Professional toolchain from Arm \ud83d\udfe2 Arm Toolchain for Embedded (ATfE) Open-source, LLVM-based toolchain from Arm \ud83d\udfe2 Arm GNU Toolchain (GCC) Open-source, GCC-based toolchain from Arm \ud83d\udfe2 Clangd support For comprehensive code completion \ud83d\udfe2 Library generation Generate libraries using library manager \ud83d\udfe2 Compiler and assembler control options Interface for configuring compiler flags and options","title":"Compiler support"},{"location":"featureroadmap.html#debug","text":"","title":"Debug"},{"location":"featureroadmap.html#core-debug-control","text":"Category Debug Features \ud83d\udfe2 Run control Run, halt, reset, step into, step over, step out \ud83d\udfe2 Breakpoints Various types of breakpoints \ud83d\udfe1 Watchpoints Data read/write/access breakpoints (DWT) \ud83d\udfe2 Multi-core Single GUI for multiple cores in a device","title":"Core debug control"},{"location":"featureroadmap.html#register-and-memory-inspection","text":"Category Debug Features \ud83d\udfe2 Core registers R0\u2013R15, PSR, MSP, PSP, CONTROL \ud83d\udfe1 Core peripheral registers NVIC, SysTick, MPU \ud83d\udfe2 Peripheral registers CMSIS-SVD decoded peripheral views \ud83d\udfe2 Memory inspection Configurable memory views \ud83d\udfe2 Memory inspection Memory access breakpoints \ud83d\udfe2 Memory inspection Memory window live update","title":"Register and memory inspection"},{"location":"featureroadmap.html#source-level-debugging","text":"Category Debug Features \ud83d\udfe2 Variables Call stack view \ud83d\udfe2 Variables Local variable inspection \ud83d\udfe2 Disassembly Disassembly window \ud83d\udfe1 Disassembly Sync Disassembly and source \ud83d\udfe2 Variable inspection Inline variable display \ud83d\udfe2 Variable inspection Variable hover inspection \ud83d\udfe1 Execution flow Function call trace","title":"Source-level debugging"},{"location":"featureroadmap.html#real-time-and-trace-features","text":"Category Debug Features \ud83d\udfe1 Serial wire output ITM printf -style output \ud83d\udfe2 Variable tracing Real-time data watch \ud83d\udfe1 Event tracing Exception trace \ud83d\udfe1 Event tracing Interrupt trace \ud83d\udfe2 Sampling CPU time \ud83d\udfe1 Embedded trace buffer ETB instruction trace \ud83d\udfe1 Micro trace buffer MTB instruction trace \ud83d\udd34 Instruction trace Embedded trace macrocell","title":"Real-time and trace features"},{"location":"featureroadmap.html#component-viewer-and-event-recorder","text":"Category Debug Features \ud83d\udfe1 Component Viewer Display and live update \ud83d\udfe1 Event Recorder Show event information \ud83d\udfe1 Event Recorder Save/log \ud83d\udfe1 Event Recorder Event filtering \ud83d\udfe1 Event Recorder Event statistics","title":"Component Viewer and Event Recorder"},{"location":"featureroadmap.html#rtos-awareness","text":"Category Debug Features \ud83d\udfe2 RTOS support Keil RTX5, FreeRTOS, Zephyr awareness \ud83d\udfe2 Thread visibility Thread list and state display \ud83d\udfe2 Stack usage Per-task stack usage","title":"RTOS awareness"},{"location":"featureroadmap.html#analysis-and-visualization","text":"Category Debug Features \ud83d\udfe1 Logic Analyzer Graphical variable and signal display \ud83d\udfe1 System Analyzer Data trace, core clock, ITM, current/voltage \ud83d\udfe2 Serial monitor Communication via serial/TCP ports \ud83d\udd34 Performance analysis Execution time analysis \ud83d\udd34 Performance analysis Function profiling \ud83d\udd34 Execution statistics Code coverage \ud83d\udfe1 Execution statistics Timing statistics (only via Event Recorder)","title":"Analysis and visualization"},{"location":"featureroadmap.html#simulation","text":"Category Debug Features \ud83d\udfe2 Fast models (FVPs) Instruction-accurate CPU simulation \ud83d\udfe1 Debug FVPs Debugging on FVPs Note FVP simulation models are not available in the MDK-Essential edition.","title":"Simulation"},{"location":"featureroadmap.html#debug-probe-support","text":"Category Debug Features \ud83d\udfe2 Debug probes ULINK2/UILNKplus support \ud83d\udfe1 Debug probes UILNKpro support \ud83d\udfe2 Debug probes CMSIS-DAP support \ud83d\udfe2 Debug probes J-Link support \ud83d\udfe2 Debug interfaces SWD \ud83d\udfe2 Debug interfaces JTAG \ud83d\udfe2 Debug interfaces Target detection \ud83d\udfe1 Debug interfaces Connect configuration \ud83d\udfe2 Flash programming Flash download \ud83d\udfe1 Flash programming Flash verification \ud83d\udfe1 Flash programming Configuration Legend \ud83d\udfe2 available \ud83d\udfe1 feature implementation progressing \ud83d\udd34 investigating for alternative solution","title":"Debug probe support"},{"location":"importuv.html","text":"Import a Keil \u00b5Vision project In Keil Studio, you can convert a Keil \u03bcVision project to a CMSIS solution by opening the folder that contains the *.uvprojx file that you want to convert. Then, do one of the following: From the Explorer view , right-click the *.uvprojx file and select Convert \u03bcVision project to CMSIS solution . From the CMSIS view , choose one of the following options: Click Convert a \u03bcVision Project to CMSIS Solution and open your *.uvprojx file to convert it. Click Views and More Actions , then select Convert \u03bcVision project to CMSIS solution and open your *.uvprojx file to convert it. A dialog box displays. You can carry out the following tasks: - Open the solution in a new workspace with the **Open** option. - Open the solution in a new window and new workspace with the **Open project in new window** option. You can also run the CMSIS: Convert \u03bcVision project to CMSIS solution command from the Command Palette. In that case, select the *.uvprojx that you want to convert on your machine and click Select. If a *.csolution.yml file already exists in the same folder as the *.uvprojx file , then a pop-up message displays in the bottom right-hand corner. Click Overwrite to overwrite the existing file. The conversion starts immediately. Confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in your vcpkg-configuration.json file. Check the Output tab. If there are any conversion errors and warnings, they display in the CMSIS Solution category. You can also check the uv2csolution.log file. The *.cproject.yml and *.csolution.yml files are available in the folder where the *.uvprojx is stored. Caveats Depending on how your \u00b5Vision project is written, the conversion may encounter problems. The following is a (non-exhaustive) list of issues you might see. Using Arm Compiler 5 The conversion does not work with Arm Compiler 5-based projects. Only projects using Arm Compiler 6 can be converted. Solution Update an Arm Compiler 5 project to Arm Compiler 6 in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Note For more information, see the Migrate Arm Compiler 5 to Arm Compiler 6 application note and the Arm Compiler for Embedded Migration and Compatibility Guide . Using dollar sign in linker misc controls In \u00b5Vision, you can use the dollar sign ( $ ) for Linker misc options in the Options for Target dialog: This will cause a malformed YML access sequence in the generated cproject.yml file that will fail during builds. Solution Remove the $ sign and save the project in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Using dots in project file names In \u00b5Vision project names, you can use the dot, e.g. MyProject_1.0.uvprojx. In CMSIS solution project format, dots are used to separate project names, build type, and target types (refer to Context ). Thus, using dots in project names will lead to: error csolution: schema check failed, verify syntax Solution Remove dots from project names. Project located in paths containing a dollar sign In some operating systems, paths can contain the dollar ( $ ) sign. Building the project will fail with a similar message: error csolution: malformed access sequence: '/$test/Blinky_FRDM-K32L3A6 Solution Use the -O option to redirect all output to a directory without the $ sign. Component mismatches when using generators Older projects using GPDSC-based generators will see an issue after the conversion. In the original uvprojx file, an entry for STM32CubeMX could look like this: Modern DFPs with generator support would look like: uv2csolution adds a non-existing pack node Keil::FrameworkCubeMX@^1.0.0 which will lead to an error like this: error csolution: required pack: Keil::FrameworkCubeMX@^1.0.0 not installed Solution Delete the corresponding line from the cproject.yml file.","title":"Import uVision projects"},{"location":"importuv.html#import-a-keil-vision-project","text":"In Keil Studio, you can convert a Keil \u03bcVision project to a CMSIS solution by opening the folder that contains the *.uvprojx file that you want to convert. Then, do one of the following: From the Explorer view , right-click the *.uvprojx file and select Convert \u03bcVision project to CMSIS solution . From the CMSIS view , choose one of the following options: Click Convert a \u03bcVision Project to CMSIS Solution and open your *.uvprojx file to convert it. Click Views and More Actions , then select Convert \u03bcVision project to CMSIS solution and open your *.uvprojx file to convert it. A dialog box displays. You can carry out the following tasks: - Open the solution in a new workspace with the **Open** option. - Open the solution in a new window and new workspace with the **Open project in new window** option. You can also run the CMSIS: Convert \u03bcVision project to CMSIS solution command from the Command Palette. In that case, select the *.uvprojx that you want to convert on your machine and click Select. If a *.csolution.yml file already exists in the same folder as the *.uvprojx file , then a pop-up message displays in the bottom right-hand corner. Click Overwrite to overwrite the existing file. The conversion starts immediately. Confirm that the Arm Tools Environment Manager extension can automatically activate the workspace and download the tools specified in your vcpkg-configuration.json file. Check the Output tab. If there are any conversion errors and warnings, they display in the CMSIS Solution category. You can also check the uv2csolution.log file. The *.cproject.yml and *.csolution.yml files are available in the folder where the *.uvprojx is stored.","title":"Import a Keil \u00b5Vision project"},{"location":"importuv.html#caveats","text":"Depending on how your \u00b5Vision project is written, the conversion may encounter problems. The following is a (non-exhaustive) list of issues you might see.","title":"Caveats"},{"location":"importuv.html#using-arm-compiler-5","text":"The conversion does not work with Arm Compiler 5-based projects. Only projects using Arm Compiler 6 can be converted. Solution Update an Arm Compiler 5 project to Arm Compiler 6 in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code. Note For more information, see the Migrate Arm Compiler 5 to Arm Compiler 6 application note and the Arm Compiler for Embedded Migration and Compatibility Guide .","title":"Using Arm Compiler 5"},{"location":"importuv.html#using-dollar-sign-in-linker-misc-controls","text":"In \u00b5Vision, you can use the dollar sign ( $ ) for Linker misc options in the Options for Target dialog: This will cause a malformed YML access sequence in the generated cproject.yml file that will fail during builds. Solution Remove the $ sign and save the project in Keil \u03bcVision, then convert the project to a CMSIS solution in VS Code.","title":"Using dollar sign in linker misc controls"},{"location":"importuv.html#using-dots-in-project-file-names","text":"In \u00b5Vision project names, you can use the dot, e.g. MyProject_1.0.uvprojx. In CMSIS solution project format, dots are used to separate project names, build type, and target types (refer to Context ). Thus, using dots in project names will lead to: error csolution: schema check failed, verify syntax Solution Remove dots from project names.","title":"Using dots in project file names"},{"location":"importuv.html#project-located-in-paths-containing-a-dollar-sign","text":"In some operating systems, paths can contain the dollar ( $ ) sign. Building the project will fail with a similar message: error csolution: malformed access sequence: '/$test/Blinky_FRDM-K32L3A6 Solution Use the -O option to redirect all output to a directory without the $ sign.","title":"Project located in paths containing a dollar sign"},{"location":"importuv.html#component-mismatches-when-using-generators","text":"Older projects using GPDSC-based generators will see an issue after the conversion. In the original uvprojx file, an entry for STM32CubeMX could look like this: Modern DFPs with generator support would look like: uv2csolution adds a non-existing pack node Keil::FrameworkCubeMX@^1.0.0 which will lead to an error like this: error csolution: required pack: Keil::FrameworkCubeMX@^1.0.0 not installed Solution Delete the corresponding line from the cproject.yml file.","title":"Component mismatches when using generators"},{"location":"installation.html","text":"Installation Prerequisites Arm Keil Studio is a set of extensions for Microsoft Visual Studio Code , which is required to be installed on your machine. Installing Keil Studio The Arm Keil Studio Pack (MDK v6) extension pack includes the extensions that are required to work with CMSIS solution projects. In VS Code, open the Extensions view. Type Arm in the search bar. Click on \"Arm Keil Studio Pack\" and README is shown on the right. It contains links to the included extensions. Their READMEs include minimal user guides. Click Install to start. You need to trust the publishers \"Arm\" and \"LLVM\" to install the extension pack. When the installation is finished, the CMSIS view icon appears in the activity bar. Verify the installation Once you have installed Keil Studio, you can verify your installation by following the getting started guide that opens automatically: It's best practice to create a new CMSIS solution based on a Blinky example, which typically flashes an LED on a target board. Note When creating a solution based on an example, all required tools and packs are installed automatically. Set up a new workspace If you want to install tools and packs separately, you have to create a new workspace in VS Code by opening a blank folder. Tool installation Required tools (such as a compiler toolchain or the CMSIS-Toolbox) are installed via the Arm Tools Environment Manager , controlled by the vcpkg-configuration.json file. Open the Arm Tools Environment Manager via the command pallette (Ctrl/Cmd + Shift + p) and select Arm Tools: Configure Arm Tools Environment . The \"Arm Registry\" opens: Select at least an \"Arm CMSIS-Toolbox\" version as this is required to be able to install packs . The Output pane shows the status of the \"Arm Tools\" installation. Attention If you are using Keil Studio for the first time, the Arm Tools Environment Manager needs to download required tools from the Internet. This may take a couple of minutes (depending on your internet connection). You also need to provide a license. A free, non-commercial MDK-Community license can be activated from within the tool. If you need a commercial license, check our eStore or contact your preferred distributor . Pack installation CMSIS-Packs for device and board support as well as software delivery mechanism are an integral part of a CMSIS solution. Packs can be discovered online: List of CMSIS-Packs List of devices List of boards Each page contains information about how to download a pack with cpackget : Run this command in a Terminal (you will be asked to accept the license agreement): \u276f cpackget add Keil::MDK-Middleware@8.0.0 I: Updating public index I: Downloading index.pidx... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (216/216 kB, 405 kB/s) I: Updating PDSC files of public packs I: Adding pack \"Keil::MDK-Middleware@8.0.0\" I: Extracting files to /Users/chrsei01/.cache/arm/packs/Keil/MDK-Middleware/8.0.0... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (2180/2180, 2187 it/s) Activating Keil Studio Some of the Arm tools (for example Arm Compiler for Embedded and Arm Debugger ) require activation. You will be flagged with a pop up window: Click on \"Manage Arm license\" in the pop up. At the top, a new drop-down opens: If you want to evaluate Keil Studio or use it for non-commercial development, select \"Activate Arm Keil MDK Community Edition\". If you have a valid UBL server or activation code, use \"Activate or manage Arm licenses\" to activate Keil Studio. Note Open-source tools, such as Arm GNU Toolchain and Arm CMSIS Debugger do not require activation. For more information visit the user-based licensing web page. Configure the extension Press Ctrl+, (Windows and Linux) or Cmd+, (macOS) or go to at the bottom of the Activity Bar and select Settings . Then, select CMSIS Solution to change the extension settings. The available settings are: Setting Description Auto Debug Launch Create or update launch.json and tasks.json with the Debug Adapter configuration of the CMSIS solution project. Download Packs CMSIS-Toolbox downloads required software packs using cpackget during setup and project build. This option enables the option --packs for cbuild . Environment Variables Specify additional environment variables to be set for build, run, and terminals. Exclude Configure a glob pattern for excluding files and folders in searches for csolution files. Experimental Features Use the checkbox to enable experimental features. Generate Clang Setup Use the checkbox to automatically generate the required setup ( .clangd file and .vscode/settings.json ) for the active solution context. For Arm Compiler 6, include pre-defined macros in the .clangd file. Output Directory Enter an output directory prefix for 'outdir' and 'tmpdir' and relocated build information files (experimental). Probe-ID Specufy the unique identifier of a probe to be used for debugging. Use Web Services Use the checkbox to enable web services to obtain information about devices, boards, and examples. If enabled, information from the internet and locally installed packs is used. If disabled, only information from installed packs is used.","title":"Installation"},{"location":"installation.html#installation","text":"","title":"Installation"},{"location":"installation.html#prerequisites","text":"Arm Keil Studio is a set of extensions for Microsoft Visual Studio Code , which is required to be installed on your machine.","title":"Prerequisites"},{"location":"installation.html#installing-keil-studio","text":"The Arm Keil Studio Pack (MDK v6) extension pack includes the extensions that are required to work with CMSIS solution projects. In VS Code, open the Extensions view. Type Arm in the search bar. Click on \"Arm Keil Studio Pack\" and README is shown on the right. It contains links to the included extensions. Their READMEs include minimal user guides. Click Install to start. You need to trust the publishers \"Arm\" and \"LLVM\" to install the extension pack. When the installation is finished, the CMSIS view icon appears in the activity bar.","title":"Installing Keil Studio"},{"location":"installation.html#verify-the-installation","text":"Once you have installed Keil Studio, you can verify your installation by following the getting started guide that opens automatically: It's best practice to create a new CMSIS solution based on a Blinky example, which typically flashes an LED on a target board. Note When creating a solution based on an example, all required tools and packs are installed automatically.","title":"Verify the installation"},{"location":"installation.html#set-up-a-new-workspace","text":"If you want to install tools and packs separately, you have to create a new workspace in VS Code by opening a blank folder.","title":"Set up a new workspace"},{"location":"installation.html#tool-installation","text":"Required tools (such as a compiler toolchain or the CMSIS-Toolbox) are installed via the Arm Tools Environment Manager , controlled by the vcpkg-configuration.json file. Open the Arm Tools Environment Manager via the command pallette (Ctrl/Cmd + Shift + p) and select Arm Tools: Configure Arm Tools Environment . The \"Arm Registry\" opens: Select at least an \"Arm CMSIS-Toolbox\" version as this is required to be able to install packs . The Output pane shows the status of the \"Arm Tools\" installation. Attention If you are using Keil Studio for the first time, the Arm Tools Environment Manager needs to download required tools from the Internet. This may take a couple of minutes (depending on your internet connection). You also need to provide a license. A free, non-commercial MDK-Community license can be activated from within the tool. If you need a commercial license, check our eStore or contact your preferred distributor .","title":"Tool installation"},{"location":"installation.html#pack-installation","text":"CMSIS-Packs for device and board support as well as software delivery mechanism are an integral part of a CMSIS solution. Packs can be discovered online: List of CMSIS-Packs List of devices List of boards Each page contains information about how to download a pack with cpackget : Run this command in a Terminal (you will be asked to accept the license agreement): \u276f cpackget add Keil::MDK-Middleware@8.0.0 I: Updating public index I: Downloading index.pidx... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (216/216 kB, 405 kB/s) I: Updating PDSC files of public packs I: Adding pack \"Keil::MDK-Middleware@8.0.0\" I: Extracting files to /Users/chrsei01/.cache/arm/packs/Keil/MDK-Middleware/8.0.0... I: 100% |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| (2180/2180, 2187 it/s)","title":"Pack installation"},{"location":"installation.html#activating-keil-studio","text":"Some of the Arm tools (for example Arm Compiler for Embedded and Arm Debugger ) require activation. You will be flagged with a pop up window: Click on \"Manage Arm license\" in the pop up. At the top, a new drop-down opens: If you want to evaluate Keil Studio or use it for non-commercial development, select \"Activate Arm Keil MDK Community Edition\". If you have a valid UBL server or activation code, use \"Activate or manage Arm licenses\" to activate Keil Studio. Note Open-source tools, such as Arm GNU Toolchain and Arm CMSIS Debugger do not require activation. For more information visit the user-based licensing web page.","title":"Activating Keil Studio"},{"location":"installation.html#configure-the-extension","text":"Press Ctrl+, (Windows and Linux) or Cmd+, (macOS) or go to at the bottom of the Activity Bar and select Settings . Then, select CMSIS Solution to change the extension settings. The available settings are: Setting Description Auto Debug Launch Create or update launch.json and tasks.json with the Debug Adapter configuration of the CMSIS solution project. Download Packs CMSIS-Toolbox downloads required software packs using cpackget during setup and project build. This option enables the option --packs for cbuild . Environment Variables Specify additional environment variables to be set for build, run, and terminals. Exclude Configure a glob pattern for excluding files and folders in searches for csolution files. Experimental Features Use the checkbox to enable experimental features. Generate Clang Setup Use the checkbox to automatically generate the required setup ( .clangd file and .vscode/settings.json ) for the active solution context. For Arm Compiler 6, include pre-defined macros in the .clangd file. Output Directory Enter an output directory prefix for 'outdir' and 'tmpdir' and relocated build information files (experimental). Probe-ID Specufy the unique identifier of a probe to be used for debugging. Use Web Services Use the checkbox to enable web services to obtain information about devices, boards, and examples. If enabled, information from the internet and locally installed packs is used. If disabled, only information from installed packs is used.","title":"Configure the extension"},{"location":"manage_settings.html","text":"Manage solutions In the Manage Solution view, you can select the active target , projects and images , and the debug adapter that you are using for target connectivity. In the CMSIS view , click to open the Manage Solution view: Active Target In this section, select the target for build, load, and debug: Select the target type that is used for build, run, and debug. The target set stores selected projects, images, and debug adapter configuration. If no target set name is specified, and empty is used. To specify your target types by editing the YAML file directly, click Edit csolution.yml . The status bar shows the current target type@target set (only the target type in case of a target set ): Projects and images In this section, select the projects, build types, and additional images that are included in the target set. Select the project(s) that are part of the solution. Select a build type for each project. You can set different build types for different projects in your solution. Set the load settings : Image & Symbols (default): debug adapter loads debug (DWARF) information and project output image. Symbols : debug adapter loads only debug (DWARF) information. Image : debug adapter loads only project output image. None : debug adapter does not use the output, however the project is included in build. Add further images with specific load settgings . To specify your projects and images by editing the YAML file directly, click Edit cproject.yml . Note If your *.csolution.yml file only includes one project, then you can't deselect it in this dialog as otherwise the solution can't be built. The projects and build types that you can select are defined by contexts for a particular target. Some options might be unavailable if they have been excluded for the target selected. To learn more about contexts and how to modify them, see the Context and Conditional build information in the CMSIS-Toolbox documentation. Errors and warnings You can inspect errors and warnings for a target set. For active projects in the target set, errors and warnings display when you move your cursor over the Target Set in the status bar. The indicator is red for errors and yellow in case of warnings. Click the indicator to open the Output tab for the CMSIS Solution category. If you previously closed the Manage Solution view, then this action also re-opens the view. You can also go to the Problems tab and check for errors. Debug Adapter A broad range of adapters is supported. Use this drop-down to select the debug adapter that you are using within the target set. Note Some of the debug adapters require further setup steps.","title":"Manage solutions"},{"location":"manage_settings.html#manage-solutions","text":"In the Manage Solution view, you can select the active target , projects and images , and the debug adapter that you are using for target connectivity. In the CMSIS view , click to open the Manage Solution view:","title":"Manage solutions"},{"location":"manage_settings.html#active-target","text":"In this section, select the target for build, load, and debug: Select the target type that is used for build, run, and debug. The target set stores selected projects, images, and debug adapter configuration. If no target set name is specified, and empty is used. To specify your target types by editing the YAML file directly, click Edit csolution.yml . The status bar shows the current target type@target set (only the target type in case of a target set ):","title":"Active Target"},{"location":"manage_settings.html#projects-and-images","text":"In this section, select the projects, build types, and additional images that are included in the target set. Select the project(s) that are part of the solution. Select a build type for each project. You can set different build types for different projects in your solution. Set the load settings : Image & Symbols (default): debug adapter loads debug (DWARF) information and project output image. Symbols : debug adapter loads only debug (DWARF) information. Image : debug adapter loads only project output image. None : debug adapter does not use the output, however the project is included in build. Add further images with specific load settgings . To specify your projects and images by editing the YAML file directly, click Edit cproject.yml . Note If your *.csolution.yml file only includes one project, then you can't deselect it in this dialog as otherwise the solution can't be built. The projects and build types that you can select are defined by contexts for a particular target. Some options might be unavailable if they have been excluded for the target selected. To learn more about contexts and how to modify them, see the Context and Conditional build information in the CMSIS-Toolbox documentation.","title":"Projects and images"},{"location":"manage_settings.html#errors-and-warnings","text":"You can inspect errors and warnings for a target set. For active projects in the target set, errors and warnings display when you move your cursor over the Target Set in the status bar. The indicator is red for errors and yellow in case of warnings. Click the indicator to open the Output tab for the CMSIS Solution category. If you previously closed the Manage Solution view, then this action also re-opens the view. You can also go to the Problems tab and check for errors.","title":"Errors and warnings"},{"location":"manage_settings.html#debug-adapter","text":"A broad range of adapters is supported. Use this drop-down to select the debug adapter that you are using within the target set. Note Some of the debug adapters require further setup steps.","title":"Debug Adapter"},{"location":"reldocs.html","text":"Related documentation These valuable resources help you getting further knowledge and insights into Keil MDK (its editions, licensing, legacy tools and example repositories). General product information Editions table Support page Release announcement Getting started guide Keil forum Videos and webinars Keil MDK v6 video tutorials Keil Studio webinar series Licensing User-Based Licensing (UBL) Knowledge Base article Subscription renewal for Arm developer store UBLs UBL resources on developer.arm.com UBL Administration Guide UBL User Guide Backwards compatibility (AC5, legacy tools) Video: Enabling legacy editions of Keil MDK Other documentation CMSIS-Toolbox user guide How to update the CMSIS-Toolbox version in \u00b5Vision installation?","title":"Related documentation"},{"location":"reldocs.html#related-documentation","text":"These valuable resources help you getting further knowledge and insights into Keil MDK (its editions, licensing, legacy tools and example repositories).","title":"Related documentation"},{"location":"reldocs.html#general-product-information","text":"Editions table Support page Release announcement Getting started guide Keil forum","title":"General product information"},{"location":"reldocs.html#videos-and-webinars","text":"Keil MDK v6 video tutorials Keil Studio webinar series","title":"Videos and webinars"},{"location":"reldocs.html#licensing","text":"User-Based Licensing (UBL) Knowledge Base article Subscription renewal for Arm developer store UBLs UBL resources on developer.arm.com UBL Administration Guide UBL User Guide Backwards compatibility (AC5, legacy tools) Video: Enabling legacy editions of Keil MDK","title":"Licensing"},{"location":"reldocs.html#other-documentation","text":"CMSIS-Toolbox user guide How to update the CMSIS-Toolbox version in \u00b5Vision installation?","title":"Other documentation"},{"location":"runexternal.html","text":"Run external tools VS Code uses the launch.json and tasks.json configuration files to integrate with external tools. The following section shows how to configure these files for typical use cases. Variables VS Code supports variable substitution in the Debugging and Tasks configuration files and selected settings. Variable substitution uses the ${variableName} syntax, for example in launch.json and tasks.json files. In addition to the VS Code built-in variables , the CMSIS Solution extension provides the following variables. Variable Description ${command:cmsis-csolution.getActiveTargetSet} Get name of active run and debug configuration (format: target-type@set) ${command:cmsis-csolution.getBinaryFile} The path and name of the first ELF/DWARF file available for the Active Target ${command:cmsis-csolution.getBinaryFiles} The paths and names of the ELF/DWARF files (comma separated) available for the Active Target ${command:cmsis-csolution.getBoardName} The board name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getBspName} The Board Support Pack (BSP) for the Active Target ${command:cmsis-csolution.getBspPath} The path to the content of the BSP for the Active Target ${command:cmsis-csolution.getCbuildRunFile} The path to the cbuild-run.yml file for the Active Target ${command:cmsis-csolution.getDeviceName} The device name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getDfpName} The Device Family Pack (DFP) for the Active Target ${command:cmsis-csolution.getDfpPath} The path to the content of the DFP for the Active Target ${command:cmsis-csolution.getProcessorName} The name of the processor for the Active Target; for multi-processor configurations start-pname ${command:cmsis-csolution.getSolutionFile} The path to the csolution.yml file for the Active Solution Note Active Solution refers to the csolution project that is currently loaded. Active Target refers to the target that is currently selected in the Manage Solution view. Substitution examples The following table illustrates the variable substition using the DualCore csolution example . Note that ... stands for the absolute path on the host computer that stores the csolution project or the CMSIS pack content . Variable Substitution ${command:cmsis-csolution.getBinaryFile} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf ${command:cmsis-csolution.getBinaryFiles} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf, .../DualCore/out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.axf ${command:cmsis-csolution.getBoardName} K32L3A60VPJ1A ${command:cmsis-csolution.getBspName} NXP::FRDM-K32L3A6_BSP@19.0.0 ${command:cmsis-csolution.getBspPath} .../NXP/FRDM-K32L3A6_BSP/19.0.0 ${command:cmsis-csolution.getCbuildRunFile} .../DualCore/DualCore+FRDM-K32L3A6.cbuild-run.yml ${command:cmsis-csolution.getDeviceName} K32L3A60VPJ1A ${command:cmsis-csolution.getDfpName} NXP::K32L3A60_DFP@19.0.0 ${command:cmsis-csolution.getDfpPath} .../NXP/K32L3A60_DFP/19.0.0 ${command:cmsis-csolution.getSolutionFile} .../DualCore/HelloWorld.csolution.yml Examples Arm Debugger Use the following launch.json file to start Arm Debugger: { \"version\": \"0.2.0\", \"configurations\": [ { \"name\": \"Arm Debugger\", \"type\": \"arm-debugger\", \"request\": \"launch\", \"serialNumber\": \"${command:device-manager.getSerialNumber}\", \"programs\": \"${command:cmsis-csolution.getBinaryFiles}\", \"cmsisPack\": \"${command:cmsis-csolution.getDfpPack}\", \"deviceName\": \"${command:cmsis-csolution.getDeviceName}\", } ] } Use \u00b5Vision for debugging The \u00b5Vision debugger offers advanced debug features such as Event Recorder and Component Viewer to analyze applications. To call \u00b5Vision with the csolution project that you are using in VS Code, add the following task to the .vscode\\tasks.json file. The command: is the path to the \u00b5Vision executable on your computer. \"tasks\": [ { \"label\": \"Start uVision\", \"type\": \"process\", \"command\": \"C:\\\\Keil_v5\\\\UV4\\\\UV4.exe\", \"args\": [ \"${command:cmsis-csolution.getSolutionFile}\" ], \"problemMatcher\": [] } ] Note This only works in Windows environments with \u00b5Vision installed on the local machine.","title":"Run external tools"},{"location":"runexternal.html#run-external-tools","text":"VS Code uses the launch.json and tasks.json configuration files to integrate with external tools. The following section shows how to configure these files for typical use cases.","title":"Run external tools"},{"location":"runexternal.html#variables","text":"VS Code supports variable substitution in the Debugging and Tasks configuration files and selected settings. Variable substitution uses the ${variableName} syntax, for example in launch.json and tasks.json files. In addition to the VS Code built-in variables , the CMSIS Solution extension provides the following variables. Variable Description ${command:cmsis-csolution.getActiveTargetSet} Get name of active run and debug configuration (format: target-type@set) ${command:cmsis-csolution.getBinaryFile} The path and name of the first ELF/DWARF file available for the Active Target ${command:cmsis-csolution.getBinaryFiles} The paths and names of the ELF/DWARF files (comma separated) available for the Active Target ${command:cmsis-csolution.getBoardName} The board name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getBspName} The Board Support Pack (BSP) for the Active Target ${command:cmsis-csolution.getBspPath} The path to the content of the BSP for the Active Target ${command:cmsis-csolution.getCbuildRunFile} The path to the cbuild-run.yml file for the Active Target ${command:cmsis-csolution.getDeviceName} The device name for the Active Target as specified in the csolution.yml ${command:cmsis-csolution.getDfpName} The Device Family Pack (DFP) for the Active Target ${command:cmsis-csolution.getDfpPath} The path to the content of the DFP for the Active Target ${command:cmsis-csolution.getProcessorName} The name of the processor for the Active Target; for multi-processor configurations start-pname ${command:cmsis-csolution.getSolutionFile} The path to the csolution.yml file for the Active Solution Note Active Solution refers to the csolution project that is currently loaded. Active Target refers to the target that is currently selected in the Manage Solution view.","title":"Variables"},{"location":"runexternal.html#substitution-examples","text":"The following table illustrates the variable substition using the DualCore csolution example . Note that ... stands for the absolute path on the host computer that stores the csolution project or the CMSIS pack content . Variable Substitution ${command:cmsis-csolution.getBinaryFile} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf ${command:cmsis-csolution.getBinaryFiles} .../DualCore/out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf, .../DualCore/out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.axf ${command:cmsis-csolution.getBoardName} K32L3A60VPJ1A ${command:cmsis-csolution.getBspName} NXP::FRDM-K32L3A6_BSP@19.0.0 ${command:cmsis-csolution.getBspPath} .../NXP/FRDM-K32L3A6_BSP/19.0.0 ${command:cmsis-csolution.getCbuildRunFile} .../DualCore/DualCore+FRDM-K32L3A6.cbuild-run.yml ${command:cmsis-csolution.getDeviceName} K32L3A60VPJ1A ${command:cmsis-csolution.getDfpName} NXP::K32L3A60_DFP@19.0.0 ${command:cmsis-csolution.getDfpPath} .../NXP/K32L3A60_DFP/19.0.0 ${command:cmsis-csolution.getSolutionFile} .../DualCore/HelloWorld.csolution.yml","title":"Substitution examples"},{"location":"runexternal.html#examples","text":"","title":"Examples"},{"location":"runexternal.html#arm-debugger","text":"Use the following launch.json file to start Arm Debugger: { \"version\": \"0.2.0\", \"configurations\": [ { \"name\": \"Arm Debugger\", \"type\": \"arm-debugger\", \"request\": \"launch\", \"serialNumber\": \"${command:device-manager.getSerialNumber}\", \"programs\": \"${command:cmsis-csolution.getBinaryFiles}\", \"cmsisPack\": \"${command:cmsis-csolution.getDfpPack}\", \"deviceName\": \"${command:cmsis-csolution.getDeviceName}\", } ] }","title":"Arm Debugger"},{"location":"runexternal.html#use-vision-for-debugging","text":"The \u00b5Vision debugger offers advanced debug features such as Event Recorder and Component Viewer to analyze applications. To call \u00b5Vision with the csolution project that you are using in VS Code, add the following task to the .vscode\\tasks.json file. The command: is the path to the \u00b5Vision executable on your computer. \"tasks\": [ { \"label\": \"Start uVision\", \"type\": \"process\", \"command\": \"C:\\\\Keil_v5\\\\UV4\\\\UV4.exe\", \"args\": [ \"${command:cmsis-csolution.getSolutionFile}\" ], \"problemMatcher\": [] } ] Note This only works in Windows environments with \u00b5Vision installed on the local machine.","title":"Use \u00b5Vision for debugging"},{"location":"tipsandtricks.html","text":"Tips and tricks This chapter contains useful information to help you solve specific issues. Create vcpkg configuration file If your solution does not contain the vcpkg-configuration.json , right-click anywhere in the workspace and select Configure Arm Tools Environment . The Arm Tools Environment Manager extension then generates this file. Set current solution in workspace To activate a solution in the Solution outline view, use the Select Active Solution from workspace option in Views and More Actions : . Documentation does not open If you are using a Linux machine that uses the Snap package manager, your web browser will not be able to open documentation that is shipped in CMSIS-Packs as the CMSIS_PACK_ROOT directory is in ${HOME}/.cache/arm/packs which is not accessible to Snaps. Likewise, the Keil Studio help is located in ${HOME}/.vscode/extensions which is also not available. To get this working, use a browser that is not installed as a Snap package: Uninstall the Snap package. For example, run sudo snap remove firefox in a Terminal. Download the installer from the browser's web site. Install it on your machine. Memory and Peripheral Inspector are missing If your Debug view does not contain \"PERIPHERALS\" and you cannot open the Memory Inspector , check if the extensions are installed correctly. If you had previously uninstalled the Arm Debugger extension, these two extensions might have been removed with it. Just reinstall them via the Extensions view. Create a library file With Keil Studio, it is possible to create a library file. All you need to do is to change the output type in the *.cproject.yml file to lib : # Control output files (elf is generated by default) output: type: - lib In the CMSIS view , click . The Terminal output will look like this: Execute: cbuild /Users/user/project/Arm/ArmCM3/Library/Library.csolution.yml --build --context-set --packs +---------------------------------------------- (1/1) Cleaning context: \"Library.Debug+Library\" +---------------------------------------------- (1/1) Building context: \"Library.Debug+Library\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Library.Debug+Library' [1/2] Building C object CMakeFiles/Group_Source_Files.dir/Users/user/project/Arm/ArmCM3/Library/main.o [2/2] Linking C static library /Users/user/project/Arm/ArmCM3/Library/out/Library/Library/Debug/Library.lib +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:02 +============================================================ Completed: cbuild succeed with exit code 0 The corresponding library file will be present in the /out -directory. Note This only works with CMSIS-Toolbox starting v2.11.0. Downgrading tool versions When you downgrade a tool version in the vcpkg-configuration,json file, this will only be taken into account if you toggle the tools activation. Do the following: Click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Deactivate Environment . The status bar will show that tools are deactivated: Again, click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Reactivate Environment . The new settings will now the taken into account and you can start working with the downgraded tool version. STM32CubeMX generator issues If you are relying on the LL drivers, it may happen that STM32CubeMX does not generate/update a *.cgen.yml file. To get this fixed, go to: Project Manager Advanced Settings Select HAL (default) for at least one peripheral. If you rely on LL for your peripherals, select/add an unused peripheral: Now, the GENERATE CODE button creates/writes the *.cgen.yml file. Change variable display radix In the Watch and Live Watch views, you can change the radix of variables by using the set output-radix base command in the Debug Console . For example, > set output-radix 16 changes the radix to hexadecimal. Supported choices for base are decimal 8 , 10 , or 16 . Note The > is part of the entered command instructing the console processing to use GDB CLI. Refer to Numbers for more information.","title":"Tips and tricks"},{"location":"tipsandtricks.html#tips-and-tricks","text":"This chapter contains useful information to help you solve specific issues.","title":"Tips and tricks"},{"location":"tipsandtricks.html#create-vcpkg-configuration-file","text":"If your solution does not contain the vcpkg-configuration.json , right-click anywhere in the workspace and select Configure Arm Tools Environment . The Arm Tools Environment Manager extension then generates this file.","title":"Create vcpkg configuration file"},{"location":"tipsandtricks.html#set-current-solution-in-workspace","text":"To activate a solution in the Solution outline view, use the Select Active Solution from workspace option in Views and More Actions : .","title":"Set current solution in workspace"},{"location":"tipsandtricks.html#documentation-does-not-open","text":"If you are using a Linux machine that uses the Snap package manager, your web browser will not be able to open documentation that is shipped in CMSIS-Packs as the CMSIS_PACK_ROOT directory is in ${HOME}/.cache/arm/packs which is not accessible to Snaps. Likewise, the Keil Studio help is located in ${HOME}/.vscode/extensions which is also not available. To get this working, use a browser that is not installed as a Snap package: Uninstall the Snap package. For example, run sudo snap remove firefox in a Terminal. Download the installer from the browser's web site. Install it on your machine.","title":"Documentation does not open"},{"location":"tipsandtricks.html#memory-and-peripheral-inspector-are-missing","text":"If your Debug view does not contain \"PERIPHERALS\" and you cannot open the Memory Inspector , check if the extensions are installed correctly. If you had previously uninstalled the Arm Debugger extension, these two extensions might have been removed with it. Just reinstall them via the Extensions view.","title":"Memory and Peripheral Inspector are missing"},{"location":"tipsandtricks.html#create-a-library-file","text":"With Keil Studio, it is possible to create a library file. All you need to do is to change the output type in the *.cproject.yml file to lib : # Control output files (elf is generated by default) output: type: - lib In the CMSIS view , click . The Terminal output will look like this: Execute: cbuild /Users/user/project/Arm/ArmCM3/Library/Library.csolution.yml --build --context-set --packs +---------------------------------------------- (1/1) Cleaning context: \"Library.Debug+Library\" +---------------------------------------------- (1/1) Building context: \"Library.Debug+Library\" Using AC6 V6.24.0 compiler, from: '/Users/user/.vcpkg/artifacts/2139c4c6/compilers.arm.armclang/6.24.0/bin/' Building CMake target 'Library.Debug+Library' [1/2] Building C object CMakeFiles/Group_Source_Files.dir/Users/user/project/Arm/ArmCM3/Library/main.o [2/2] Linking C static library /Users/user/project/Arm/ArmCM3/Library/out/Library/Library/Debug/Library.lib +------------------------------------------------------------ Build summary: 1 succeeded, 0 failed - Time Elapsed: 00:00:02 +============================================================ Completed: cbuild succeed with exit code 0 The corresponding library file will be present in the /out -directory. Note This only works with CMSIS-Toolbox starting v2.11.0.","title":"Create a library file"},{"location":"tipsandtricks.html#downgrading-tool-versions","text":"When you downgrade a tool version in the vcpkg-configuration,json file, this will only be taken into account if you toggle the tools activation. Do the following: Click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Deactivate Environment . The status bar will show that tools are deactivated: Again, click on the Arm Tools entry in the status bar. In the Manage Arm Tools dialog, select Reactivate Environment . The new settings will now the taken into account and you can start working with the downgraded tool version.","title":"Downgrading tool versions"},{"location":"tipsandtricks.html#stm32cubemx-generator-issues","text":"If you are relying on the LL drivers, it may happen that STM32CubeMX does not generate/update a *.cgen.yml file. To get this fixed, go to: Project Manager Advanced Settings Select HAL (default) for at least one peripheral. If you rely on LL for your peripherals, select/add an unused peripheral: Now, the GENERATE CODE button creates/writes the *.cgen.yml file.","title":"STM32CubeMX generator issues"},{"location":"tipsandtricks.html#change-variable-display-radix","text":"In the Watch and Live Watch views, you can change the radix of variables by using the set output-radix base command in the Debug Console . For example, > set output-radix 16 changes the radix to hexadecimal. Supported choices for base are decimal 8 , 10 , or 16 . Note The > is part of the entered command instructing the console processing to use GDB CLI. Refer to Numbers for more information.","title":"Change variable display radix"},{"location":"userinterface.html","text":"User Interface The CMSIS Solution extension provides the Keil Studio GUI for project management and build tools with the CMSIS-Toolbox . Combined with other Arm and third-party extensions, it implements a powerful embedded development environment. The GUI consists of these views: View Description Explorer view lists all local files. Search view enables search/replace across all files. Source Control view allows you to work with git. Extensions view lets you work with VS Code extensions. Run and Debug view switches the GUI to a dedicated debug view . CMSIS view is the main view for working with CMSIS solution-based projects. Trace and Live view shows trace and live data during debugging. Note The ordering of the icons may be different in your VS Code environment. CMSIS view The CMSIS view shows the content of the active projects included in the solution. Each project contains configuration settings, source code files, build settings, and other project-specific information. The main area of the CMSIS view shows: Board and device information and related documentation. Groups and files : Groups and user files that you add to the project and that you can edit constructed-files : Contains generated files such as the RTE_Components.h header file for each context linker : Contains a linker script file and a .h file (or other user-defined header files) Components : Shows the software components selected for the project with their source files, user code templates, and APIs. Click the files to open them in the editor. Click the book icon of a component to open the related documentation. If you are using a generator to configure your device or board, then a Run Configuration Generator option is available to start a generator session. Layer Type (if available): The software layers in the project with their source files, preconfigured software components, and configuration files Actions available through the CMSIS view Action Description Build solution calls the compiler toolchain and builds the solution. Load & Run application flashes the binary onto the target and starts the application. Load & Debug application flashes the binary onto the target and starts a debug session. Open csolution.yml file opens the CMSIS solution YML file for editing. Open the Manage Solution view to configure project and debug settings. Show further commands . Main area icons Depending on the file and the context, various icons may appear: Action Description IntelliSense is active for this cproject file. Open the file. Manage the software components of the cproject file. Add groups or files to the cproject file. Configuration Wizard Configuration Wizard annotations enable GUI-like elements in IDEs for configuration source files. This graphical approach makes it easier for users to review and edit configuration settings as required by the application. For files containing configuration wizard annotations, open the graphical view by pressing the Open Preview button in the top right corner of the file window. The view will be opened next to the original source file. You can switch back pressing the Show Source button . Status bar The VS Code status bar displays information about the status of your development environment and the project. Status message of the clangd extension that provides smart features. You can inspect errors and warnings for the active csolution project when you move the cursor over the Target Set in the status bar. The indicator is red for errors and yellow for warnings. Click the indicator to open the Output - CMSIS Solution panel and the Manage Solution view. The Arm Tools Environment Manager extension downloads, installs, and manages software development tools. Move your mouse over Arm Tools to review the current list of installed tools. Click Arm Tools to get more options. If you are using licensed Arm tools, the active license displays. Click the active license to manage it. Run and Debug view Refer to the Debugger user interface section for more information. Available commands You can access commands to manage your solution and the related projects in the following ways: From the CMSIS view . With right-click to the *.csolution.yml file in the Explorer view. With the Command Palette that opens with Ctrl+Shift+P (Windows and Linux) or Cmd+Shift+P (macOS). Command Description Open Solution in Workspace... If your workspace contains several solutions, select the active solution to work with. Create Solution... Create a new csolution project . Convert a \u00b5Vision project to CMSIS solution... Convert uvprojx files to csolution project format. Close Solution Close the current active solution. Manage Solution Settings Configure the target set (active target, projects, images, and debug adapter) for the solution. Configure Solution Set a compiler and add software layers. Manage Software Components Review, add, or remove software components. Build solution Build the solution with the current target set. Rebuild solution Rebuild the solution with the current target set. Clean all out and tmp directories Clean all out and tmp directories for the active solution. Refresh (reload packs, update RTE) Reload information from all installed packs and run cbuild setup update-rte . Load & Run application Load the application to target and run it with active GDB server ( Debugger can be attached). Load & Debug application Load the application to target and start the debugger. Erase target device Erase the target device. Load application to target Load the application to target. Run application on target Run the current application in the target with active GDB server ( Debugger can be attached). Target Information Show information about debug adapter and target. Focus on Solution View Open the CMSIS view .","title":"User interface"},{"location":"userinterface.html#user-interface","text":"The CMSIS Solution extension provides the Keil Studio GUI for project management and build tools with the CMSIS-Toolbox . Combined with other Arm and third-party extensions, it implements a powerful embedded development environment. The GUI consists of these views: View Description Explorer view lists all local files. Search view enables search/replace across all files. Source Control view allows you to work with git. Extensions view lets you work with VS Code extensions. Run and Debug view switches the GUI to a dedicated debug view . CMSIS view is the main view for working with CMSIS solution-based projects. Trace and Live view shows trace and live data during debugging. Note The ordering of the icons may be different in your VS Code environment.","title":"User Interface"},{"location":"userinterface.html#cmsis-view","text":"The CMSIS view shows the content of the active projects included in the solution. Each project contains configuration settings, source code files, build settings, and other project-specific information. The main area of the CMSIS view shows: Board and device information and related documentation. Groups and files : Groups and user files that you add to the project and that you can edit constructed-files : Contains generated files such as the RTE_Components.h header file for each context linker : Contains a linker script file and a .h file (or other user-defined header files) Components : Shows the software components selected for the project with their source files, user code templates, and APIs. Click the files to open them in the editor. Click the book icon of a component to open the related documentation. If you are using a generator to configure your device or board, then a Run Configuration Generator option is available to start a generator session. Layer Type (if available): The software layers in the project with their source files, preconfigured software components, and configuration files","title":"CMSIS view"},{"location":"userinterface.html#actions-available-through-the-cmsis-view","text":"Action Description Build solution calls the compiler toolchain and builds the solution. Load & Run application flashes the binary onto the target and starts the application. Load & Debug application flashes the binary onto the target and starts a debug session. Open csolution.yml file opens the CMSIS solution YML file for editing. Open the Manage Solution view to configure project and debug settings. Show further commands .","title":"Actions available through the CMSIS view"},{"location":"userinterface.html#main-area-icons","text":"Depending on the file and the context, various icons may appear: Action Description IntelliSense is active for this cproject file. Open the file. Manage the software components of the cproject file. Add groups or files to the cproject file.","title":"Main area icons"},{"location":"userinterface.html#configuration-wizard","text":"Configuration Wizard annotations enable GUI-like elements in IDEs for configuration source files. This graphical approach makes it easier for users to review and edit configuration settings as required by the application. For files containing configuration wizard annotations, open the graphical view by pressing the Open Preview button in the top right corner of the file window. The view will be opened next to the original source file. You can switch back pressing the Show Source button .","title":"Configuration Wizard"},{"location":"userinterface.html#status-bar","text":"The VS Code status bar displays information about the status of your development environment and the project. Status message of the clangd extension that provides smart features. You can inspect errors and warnings for the active csolution project when you move the cursor over the Target Set in the status bar. The indicator is red for errors and yellow for warnings. Click the indicator to open the Output - CMSIS Solution panel and the Manage Solution view. The Arm Tools Environment Manager extension downloads, installs, and manages software development tools. Move your mouse over Arm Tools to review the current list of installed tools. Click Arm Tools to get more options. If you are using licensed Arm tools, the active license displays. Click the active license to manage it.","title":"Status bar"},{"location":"userinterface.html#run-and-debug-view","text":"Refer to the Debugger user interface section for more information.","title":"Run and Debug view"},{"location":"userinterface.html#available-commands","text":"You can access commands to manage your solution and the related projects in the following ways: From the CMSIS view . With right-click to the *.csolution.yml file in the Explorer view. With the Command Palette that opens with Ctrl+Shift+P (Windows and Linux) or Cmd+Shift+P (macOS). Command Description Open Solution in Workspace... If your workspace contains several solutions, select the active solution to work with. Create Solution... Create a new csolution project . Convert a \u00b5Vision project to CMSIS solution... Convert uvprojx files to csolution project format. Close Solution Close the current active solution. Manage Solution Settings Configure the target set (active target, projects, images, and debug adapter) for the solution. Configure Solution Set a compiler and add software layers. Manage Software Components Review, add, or remove software components. Build solution Build the solution with the current target set. Rebuild solution Rebuild the solution with the current target set. Clean all out and tmp directories Clean all out and tmp directories for the active solution. Refresh (reload packs, update RTE) Reload information from all installed packs and run cbuild setup update-rte . Load & Run application Load the application to target and run it with active GDB server ( Debugger can be attached). Load & Debug application Load the application to target and start the debugger. Erase target device Erase the target device. Load application to target Load the application to target. Run application on target Run the current application in the target with active GDB server ( Debugger can be attached). Target Information Show information about debug adapter and target. Focus on Solution View Open the CMSIS view .","title":"Available commands"},{"location":"zephyr.html","text":"Work with Zephyr applications It is possible to build and debug Zephyr applications that use the west build system with Keil Studio. The CMSIS solution extension displays an outline view of the Zephyr project. Prerequisites To work with Zephyr-based applications, make sure that the following is set up on your machine. Zephyr installation Follow the Zephyr Getting Started Guide for your host operating system and install Zephyr in a central location on your machine. Set environment variables For the build process, it is required to set environment variables for the CMSIS Solution extension. Open the Extension settings and navigate to CMSIS Solution . Select if you want to set the Environment Variables for the User or the current Workspace . Use Add Item to add the following environment variables: Item Value ZEPHYR_BASE $HOME/zephyrproject/zephyr PATH $HOME/zephyrproject/.venv/bin VIRTUAL_ENV $HOME/zephyrproject/.venv Note On Windows, specify the PATH as $HOME/zephyrproject/.venv/Scripts This will be translated into the following JSON code: \"cmsis-csolution.environmentVariables\": { \"ZEPHYR_BASE\": \"$HOME/zephyrproject/zephyr\", \"PATH\": \"$HOME/zephyrproject/.venv/bin\", \"VIRTUAL_ENV\": \"$HOME/zephyrproject/.venv\" }, Attention The workspace settings are stored in the .vscode\\settings.json file. If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default. Settings Copy the Zephyr application directory that you want to use to your CMSIS solution workspace/folder. Refer to the example available on GitHub: CMSIS-Zephyr . Csolution settings In a csolution.yml file, you may have west build -specific settings. You must not have a cproject.yml file present. Instead, the csolution.yml file points to the Zephyr project path: # List related projects. projects: - west: app-path: ./blinky Zephyr application settings When using the Arm GNU Toolchain for building the project via vcpkg , make sure that the C library shipped with the toolchain. This can be ensured with the following settings in the Zephyr prj.conf file: # Use Newlib from the Arm GNU Toolchain CONFIG_NEWLIB_LIBC=y # Disable Picolibc CONFIG_PICOLIBC=n CONFIG_PICOLIBC_USE_MODULE=n CONFIG_MINIMAL_LIBC=n For managing run and debug configurations, continue to manage the solution .","title":"Work with Zephyr applications"},{"location":"zephyr.html#work-with-zephyr-applications","text":"It is possible to build and debug Zephyr applications that use the west build system with Keil Studio. The CMSIS solution extension displays an outline view of the Zephyr project.","title":"Work with Zephyr applications"},{"location":"zephyr.html#prerequisites","text":"To work with Zephyr-based applications, make sure that the following is set up on your machine.","title":"Prerequisites"},{"location":"zephyr.html#zephyr-installation","text":"Follow the Zephyr Getting Started Guide for your host operating system and install Zephyr in a central location on your machine.","title":"Zephyr installation"},{"location":"zephyr.html#set-environment-variables","text":"For the build process, it is required to set environment variables for the CMSIS Solution extension. Open the Extension settings and navigate to CMSIS Solution . Select if you want to set the Environment Variables for the User or the current Workspace . Use Add Item to add the following environment variables: Item Value ZEPHYR_BASE $HOME/zephyrproject/zephyr PATH $HOME/zephyrproject/.venv/bin VIRTUAL_ENV $HOME/zephyrproject/.venv Note On Windows, specify the PATH as $HOME/zephyrproject/.venv/Scripts This will be translated into the following JSON code: \"cmsis-csolution.environmentVariables\": { \"ZEPHYR_BASE\": \"$HOME/zephyrproject/zephyr\", \"PATH\": \"$HOME/zephyrproject/.venv/bin\", \"VIRTUAL_ENV\": \"$HOME/zephyrproject/.venv\" }, Attention The workspace settings are stored in the .vscode\\settings.json file. If you use \"Initialize Git repository\" when creating a csolution, this file is ignored by default.","title":"Set environment variables"},{"location":"zephyr.html#settings","text":"Copy the Zephyr application directory that you want to use to your CMSIS solution workspace/folder. Refer to the example available on GitHub: CMSIS-Zephyr .","title":"Settings"},{"location":"zephyr.html#csolution-settings","text":"In a csolution.yml file, you may have west build -specific settings. You must not have a cproject.yml file present. Instead, the csolution.yml file points to the Zephyr project path: # List related projects. projects: - west: app-path: ./blinky","title":"Csolution settings"},{"location":"zephyr.html#zephyr-application-settings","text":"When using the Arm GNU Toolchain for building the project via vcpkg , make sure that the C library shipped with the toolchain. This can be ensured with the following settings in the Zephyr prj.conf file: # Use Newlib from the Arm GNU Toolchain CONFIG_NEWLIB_LIBC=y # Disable Picolibc CONFIG_PICOLIBC=n CONFIG_PICOLIBC_USE_MODULE=n CONFIG_MINIMAL_LIBC=n For managing run and debug configurations, continue to manage the solution .","title":"Zephyr application settings"}]}
\ No newline at end of file