diff --git a/docs/Proposal - Run+Debug Management.md b/docs/Proposal - Run+Debug Management.md new file mode 100644 index 0000000..bc25aea --- /dev/null +++ b/docs/Proposal - Run+Debug Management.md @@ -0,0 +1,158 @@ +# Proposal - Run and Debug Management + + + + + + +This proposal discusses how the CMSIS-Toolbox may simplify workflows with programming and debug tools. + +- [Proposal - Run and Debug Management](#proposal---run-and-debug-management) + - [Overview](#overview) + - [Run and Debug Information Management](#run-and-debug-information-management) + - [The problems to solve](#the-problems-to-solve) + - [Proposed solution](#proposed-solution) + - [Usage](#usage) + - [Questions](#questions) + +## Overview + +The CMSIS-Pack PDSC files contain information about device/board parameters and software components: + +- [Flash algorithms](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html) of device memory (in DFP) and board memory (in BSP). +- On-board debug adapter (a default programming/debug channel) including features. +- Available memory of device and board. +- Device parameters such as processor core(s) and clock speed. +- [Debug Access Sequences](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html) and [System Description Files](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/sdf_pg.html) that support more complex Cortex-A/R/M configurations. +- [CMSIS-SVD System View Description (SVD)](https://open-cmsis-pack.github.io/svd-spec/main/index.html) files for viewing device peripherals. +- [CMSIS-View Software Component Viewer Description (SCVD)](https://arm-software.github.io/CMSIS-View/latest/SCVD_Format.html) files for analysis of software components (RTOS, Middleware). + +The CMSIS-Toolbox build system manages device/board/software components and controls the build output (typically ELF/DWARF files) and has provisions for HEX, BIN and post-processing. It allows to manage different [target-types](build-overview.md#project-setup-for-multiple-targets-and-builds) and the [context set](build-overview.md#working-with-context-set) manages the images that belong to a target. + +In addition the user may need the following information which should be added to the YML-Input files for the CMSIS-Toolbox. + +- Flash algorithms for external memory in custom hardware. +- Additional images that should be loaded. +- Device configuration information. +- Access information for protected debug ports (i.e. encryption keys). + + +## Run and Debug Information Management + +### The problems to solve + +- Provide information for command line and IDE workflows in a consistent way. +- Simplify the implementation in run and debug tools, reduce dependency to other tools. +- Ensure that information is portable, i.e from a cloud-hosted CI system to a desktop test system. +- Provide flexibility and ease-of-use. + +Today, some programmers access DFP and BSP information via the packs. This results in additional complexity of the tool and more dependencies. + +In VS Code, [task configurations](https://code.visualstudio.com/docs/editor/tasks) control the **Run** action (`tasks.json`) and [launch configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) control the **Debug** action (`launch.json`). The `tasks.json` and `launch.json` files store multiple configurations and are located in the `.vscode` folder of your workspace (the csolution project root folder). The current implementation uses extension commands to obtain project information. This limits the portability of these files. + +**Example `launch.json:** + +```json +{ + "configurations": [ + { + "name": "Arm Debugger", + "type": "arm-debugger", + "request": "launch", + "serialNumber": "${command:device-manager.getSerialNumber}", + "programs": "${command:cmsis-csolution.getBinaryFiles}", + "cmsisPack": "${command:cmsis-csolution.getTargetPack}", + "deviceName": "${command:cmsis-csolution.getDeviceName}", + "processorName": "${command:cmsis-csolution.getProcessorName}" + } + ] +} +``` + +### Proposed solution + +- Introduce a new target-type specific file `*.cbuild-run.yml` generated by CMSIS-Toolbox. This file provides access to PDSC information and build output of one target. + - Potentially export the [Debug Access Sequences](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html) into an additional parameter file as PDSC file processing is complexity due to device dependencies. +- Introduce a new folder `.cmsis` that contains these additional files. This folder might be also used for other build information files. + +![Run and Debug Information Management](./images/cbuild-run.png "Run and Debug Information Management") + +The `cbuild-run.yml` file represents a context-set. + +**Content of `*.cbuild-run.yml`:** + +```yml +run: # Start of file, contains run and debug information for a target + generated-by: csolution version 2.7.0 + solution: ../USB_Device.csolution.yml + target-type: +STM32U585AIIx + compiler: AC6 + board: STMicroelectronics::B-U585I-IOT02A:Rev.C + board-pack: Keil::B-U585I-IOT02A_BSP@2.0.0 + device: STMicroelectronics::STM32U585AIIx + device-pack: Keil::STM32U5xx_DFP@3.0.0 + + programming: # Flash programming algorithms + - algorithm: ${CMSIS_PACK_ROOT}/DFP-path/ + - algorithm: ${CMSIS_PACK_ROOT}/BSP-path/ + config: # is this required + - algorithm: custom-hw-path/ + + output: # application image files + - type: elf + file: HID.axf + load: # all (default), symbols only, binary only + + system-description: + - file: ${CMSIS_PACK_ROOT}/DFP-path/ + type: svd + - file: ${CMSIS_PACK_ROOT}/pack-path/ + type: scvd + from-pack: + +# information from DFP, BSP specific to the target +# https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/packFormat.html + board: # Board element + debugProbe: + ... + debugInterface: + ... + debug-port: # Information from DFP + access-port-v1: + ... + access-port-v2: + ... + jtag: + cjtag: + swd: + + default-settings: # Default debug configuration + default: # debug protocol (SWD or JTAG) to use for target connections. + clock: # clock setting in Hz for a target connection. + swj: # allows Serial Wire Debug (SWD) and JTAG protocols + dormant: # device access via CoreSight DP requires the dormant state + sdf: ${CMSIS_PACK_ROOT}/DFP-path/ # path of the system description file (SDF). + + sequences: + ... + + trace: + ... +``` + +### Usage + +The `*.cbuild-run.yml` file can be directly passed to programmers and debug tools, for example using a command line option. It contains all information that needs to be passed. + +```bash +>programmer -csolution MySolution+MyHardware.cbuild-run.yml +``` + +## Questions + +- What should be done now to simplify above information while making it more future proof? + +For CMSIS-Toolbox 3.0: + +- Should the location of cbuild information files change to folder `.\.cmsis`? +- Should the structure of build information file change and include `cbuild-run.yml`? The cbuild information file will then represent a context-set, and not just one context. diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index 73170cc..2564489 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -302,9 +302,9 @@ The `context` name is also used in [`for-context:`](#for-context) and [`not-for- ## Access Sequences -The following **access sequences** allow to use arguments from the CMSIS Project Manager as arguments of the various -`*.yml` files in the key values for `define:`, `define-asm:`, `add-path:`, `misc:`, `files:`, and `executes:`. The **access sequences** -can refer in a different project and provide therefore a method to describe project dependencies. +The **access sequences** export values from the CMSIS Project Manager for the +`*.yml` file nodes `define:`, `define-asm:`, `add-path:`, `misc:`, `files:`, and `executes:`. The **access sequences** +can specify a different project and describe therefore project dependencies. Access Sequence | Description :----------------------------------------------|:-------------------------------------- @@ -332,7 +332,7 @@ Access Sequence | Description `$Dpack$` | Path to the pack that defines the selected device (DFP). `$Pack(vendor::name)$` | Path to a specific pack. Example: `$Pack(NXP::K32L3A60_DFP)$`. -For a [`context`](#context-name-conventions) the `project-name`, `.build-type`, and `+target-type` are optional. An **access sequence** that specifies only `project-name` uses the context that is currently processed. It is important that the `project` is part of the [context-set](build-overview.md#working-with-context-set) in the build process. is used. Example: `$ProjectDir()$` is the directory of the current processed `cproject.yml` file. When +For a [`context`](#context-name-conventions) the `project-name`, `.build-type`, and `+target-type` are optional. An **access sequence** that specifies only `project-name` uses the context that is currently processed. It is important that the `project` is part of the [context-set](build-overview.md#working-with-context-set) in the build process. Example: `$ProjectDir()$` is the directory of the current processed `cproject.yml` file. **Example:** diff --git a/docs/build-overview.md b/docs/build-overview.md index 4f4e267..f1d4e25 100644 --- a/docs/build-overview.md +++ b/docs/build-overview.md @@ -44,6 +44,7 @@ This chapter describes the overall concept of the CMSIS-Toolbox build process. I - [PLM of Configuration Files](#plm-of-configuration-files) - [RTE\_Components.h](#rte_componentsh) - [CMSIS\_device\_header](#cmsis_device_header) + - [\_RTE\_ Preprocessor Symbol](#_rte_-preprocessor-symbol) - [Linker Script Management](#linker-script-management) - [Linker Script Preprocessing](#linker-script-preprocessing) - [Automatic Linker Script generation](#automatic-linker-script-generation) @@ -838,14 +839,26 @@ The typical usage of the `RTE_Components.h` file is in other header files to con #include "RTE_Components.h" #include CMSIS_device_header -#ifdef RTE_Network_Interface_ETH_0 // if component Network Interface ETH 0 is included -#include "Net_Config_ETH_0.h" // add the related configuration file for this component +#ifdef RTE_Network_Interface_ETH_0 // if component Network Interface ETH 0 is included +#include "Net_Config_ETH_0.h" // add the related configuration file for this component #endif ``` ### CMSIS_device_header -The `CMSIS_device_header` represents the [device header file](https://arm-software.github.io/CMSIS_6/latest/Core/using_pg.html#using_packs) provided by the CMSIS-Core. It defines the registers and interrupt mapping of the device that is used. Refer to [Reference Applications > Header File Structure](ReferenceApplications.md#header-file-structure) for more information. +The preprocessor symbol `CMSIS_device_header` represents the [device header file](https://arm-software.github.io/CMSIS_6/latest/Core/using_pg.html#using_packs) provided by the CMSIS-Core. It defines the registers and interrupt mapping of the device that is used. Refer to [Reference Applications > Header File Structure](ReferenceApplications.md#header-file-structure) for more information. + +### \_RTE\_ Preprocessor Symbol + +The preprocessor symbol `_RTE_` is added to the compiler invocation when a CMSIS build system manages the file `RTE_Components.h`. This symbol can be used as follows: + +```c +#ifdef _RTE_ // Is a CMSIS build system used? +#include "RTE_Components.h" // Include Run-Time-Environment symbols +#else // Otherwise use different ways to supply required symbols +#define CMSIS_device_header "stm32f10x.h" +#endif +``` ## Linker Script Management diff --git a/docs/images/cbuild-run.png b/docs/images/cbuild-run.png new file mode 100644 index 0000000..37edf98 Binary files /dev/null and b/docs/images/cbuild-run.png differ diff --git a/docs/images/overview.pptx b/docs/images/overview.pptx index ab8dcc2..31902bc 100644 Binary files a/docs/images/overview.pptx and b/docs/images/overview.pptx differ