diff --git a/docs/CreateApplications.md b/docs/CreateApplications.md index bfcf437..756cf5e 100644 --- a/docs/CreateApplications.md +++ b/docs/CreateApplications.md @@ -266,6 +266,64 @@ A [template *linker script file*](build-overview.md#linker-script-templates) is // Note: DMA descriptors and buffers are in this region ``` +### Troubleshooting + +The following section explains how to fix common linker problems. + +**Error: L6236E: No section matches selector - no section to be FIRST/LAST** + +Some devices (for example the NXP RT1064) use custom (non-CMSIS) assembly startup code. This is not compatible with the [default linker script](build-overview.md#linker-script-templates) that assume [C Startup code](https://arm-software.github.io/CMSIS_6/v6.0.0/Core/startup_c_pg.html) with standard CMSIS definitions. + +This problem can be solved by: + +- Using the linker script provided by the device vendor. +- Change the linker script source file `ac6_linker_script.sct.src` that is local in your project, for example as shown below: + +```txt + ER_ROM0 __ROM0_BASE __ROM0_SIZE { + *(.isr_vector, +First) + *(InRoot$$Sections) + *(+RO +XO) + } +``` + +**Using RAM1 .. RAM3 Areas** + +Currently there is a problem with the default AC6 linker script template. It does not use by default the RAM1 .. RAM3 area. + +A potential solution is discussed [here](https://github.com/Open-CMSIS-Pack/devtools/issues/1778#issuecomment-2356071535). The investigation is currently ongoing. + +**Duplicate Heap definition in Assembler startup file** + +When using memory allocation functions (i.e. `malloc`), the application ends in a hard fault handler. This is typically caused by different methods of stack and heap definitions. +The Arm Compiler offers [three ways to configure stack and heap](https://developer.arm.com/documentation/100073/0623/The-Arm-C-and-C---Libraries/Stack-and-heap-memory-allocation-and-the-Arm-C-and-C---libraries/Stack-pointer-initialization-and-heap-bounds). + +- Use a scatter file to define `ARM_LIB_STACKHEAP`, `ARM_LIB_STACK`, or `ARM_LIB_HEAP` regions. +- Use the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`. +- Implement `__user_setup_stackheap()` or `__user_initial_stackheap()`. + +!!! Warning + You have to choose one of these three ways. + +The [C startup code](https://arm-software.github.io/CMSIS_6/latest/Core/startup_c_pg.html) recommended by CMSIS Version 6 uses the linker scatter file for stack and heap definition. The C startup code is generic and works across all toolchains that are supported by the CMSIS-Toolbox. + +However, some assembler startup files define stack and heap with other methods, for example by using the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`. + +There are two options to solve the problem. + +1. Remove the stack and heap definition in the assembler startup code. + +2. Disable in the [Regions Header File](#regions-header-file) the stack and heap definition by setting `__STACK_SIZE` and `__HEAP_SIZE` to 0 as shown below. + +```txt +// Stack / Heap Configuration +// Stack Size (in Bytes) <0x0-0xFFFFFFFF:8> +// Heap Size (in Bytes) <0x0-0xFFFFFFFF:8> +#define __STACK_SIZE 0x00000000 +#define __HEAP_SIZE 0x00000000 +// +``` + ## Software Components A software component encapsulates a set of related functions. By offering API headers, it provides interfaces to other software components or to the user application. @@ -304,20 +362,20 @@ ToDo: A potential improvement is to use the command `csolution list components` The steps to create an application based on software components are: 1. Step: **Select software components** - - Install the software pack that provides the required functionality (this could be based on pack datasheets) and identify the required software component(s). - - Add the pack and the component to your `*.cproject.yml` file. - - Run `csolution *.csolution.yml list dependencies` to identify other required software components. - - Run `csolution list components --filter` to identify packs that provide this software components. - - Repeat this step until all software components are part of your project. + - Install the software pack that provides the required functionality (this could be based on pack datasheets) and identify the required software component(s). + - Add the pack and the component to your `*.cproject.yml` file. + - Run `csolution *.csolution.yml list dependencies` to identify other required software components. + - Run `csolution list components --filter` to identify packs that provide this software components. + - Repeat this step until all software components are part of your project. 2. Step: **Configure software components** - - Run `csolution *.csolution.yml update-rte` to copy configuration files into the [RTE directory](./build-overview.md#rte-directory-structure). - - Set the parameters in the configuration files for your application. + - Run `csolution *.csolution.yml update-rte` to copy configuration files into the [RTE directory](./build-overview.md#rte-directory-structure). + - Set the parameters in the configuration files for your application. 3. Step: **Use software components in application program** - - User code templates provide a starting point for your application. - - Copy these template files to your project directory add add it to your `*.cproject.yml` file. - - Adjust the code in the user template files as required. + - User code templates provide a starting point for your application. + - Copy these template files to your project directory add add it to your `*.cproject.yml` file. + - Adjust the code in the user template files as required. ### Example: Network Stack diff --git a/docs/CubeMX.md b/docs/CubeMX.md index 4c3f959..2b6ebe8 100644 --- a/docs/CubeMX.md +++ b/docs/CubeMX.md @@ -113,7 +113,7 @@ Directory `STM32CubeMX/MyBoard` | Content `STM32CubeMX/GCC` | Project files for GCC; only startup code and linker scripts are used for *csolution projects*. `STM32CubeMX/MDK-ARM` | Project files for MDK version 5; only startup code and linker scripts are used for *csolution projects*. -[!NOTE] +!!! Note CubeMX generates only the directory for the selected toolchain which is either `STM32CubeMX/EWARM`, `STM32CubeMX/GCC`, or `STM32CubeMX/MDK-ARM`. **Content of Generator Import File: `CubeMX.cgen.yml`** @@ -157,7 +157,10 @@ Many applications require an RTOS kernel. By default, CubeMX implements interrup Adding an RTOS kernel requires these steps: -1. **Add the RTOS kernel to application** (in this case RTX) +### Step 1: Add RTOS + +The example below adds the [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) RTOS kernel to a project. +Other kernels require different components and packs, but the concept is similar. **File: `CubeMX.cproject.yml`** @@ -176,12 +179,9 @@ project: - component: CMSIS:OS Tick:SysTick # OS Tick implementation for RTOS ``` -!!! Note - The example above uses CMSIS-RTX as the RTOS kernel, other kernels require different components and packs, but the concept is similar. +### Step 2: Configure interrupt handlers -2. **Configure interrupt handlers in CubeMX** - -Run CubeMX with: +Configure the interrupt handlers by running CubeMX with: ```bash csolution CubeMX.csolution.yml run --generator CubeMX --context CubeMX.Debug+MyBoard @@ -278,16 +278,15 @@ CMSIS-Driver | Provided by [CMSIS-Driver_STM32](https://gith To migrate existing projects that where using the previous STM32CubeMX integration (based on `*.gpdsc` files) use the following steps: 1. Remove all `component: Keil::Device:xxx` from the `*.cproject.yml` file. - 2. Add the `component: Device:CubeMX` to the `*.cproject.yml` file. 3. Use `csolution run *.csolution.yml -g CubeMX` to initialize the directory structure. 4. Replace the file `STM32CubeMX.ioc` with the file `STCubeGenerated.ioc` from the previous project. 5. Copy source and include files from previous location as they may contain user modifications. 6. Use `csolution run *.csolution.yml -g CubeMX` to generated the output from the previous STM32CubeMX project. 7. Update the configuration in STM32CubeMX: - - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to match the compiler selection in the csolution project. - - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. - - Click `GENERATE CODE` to complete the migration. + - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to match the compiler selection in the csolution project. + - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. + - Click `GENERATE CODE` to complete the migration. ### uVision - Update STM32 DFP Packs @@ -302,9 +301,9 @@ New `STM32*_DFP` software packs that contain in the release information **Update 4. Open the dialog *Manage - Run-Time Environment* again. 5. Select the component `Device:CubeMX` and start STM32CubeMX with the `play` button. 6. Update the configuration in STM32CubeMX: - - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`. - - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. - - Click `GENERATE CODE` to complete the migration. + - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`. + - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. + - Click `GENERATE CODE` to complete the migration. **Starting a new project** works similar with these steps: @@ -314,7 +313,7 @@ New `STM32*_DFP` software packs that contain in the release information **Update 2. Open the dialog *Manage - Run-Time Environment*. 3. Select the component `Device:CubeMX` and start STM32CubeMX with the `play` button. 4. Create a new device configuration in STM32CubeMX: - - Follow the instructions of STM32CubeMX and verify settings. - - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`. - - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. - - Click `GENERATE CODE` to complete the migration. + - Follow the instructions of STM32CubeMX and verify settings. + - In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`. + - In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`. + - Click `GENERATE CODE` to complete the migration. diff --git a/docs/Experimental-Features.md b/docs/Experimental-Features.md index 2894db7..a8609bf 100644 --- a/docs/Experimental-Features.md +++ b/docs/Experimental-Features.md @@ -7,18 +7,11 @@ Experimental features are implemented to iterate on new functionality. Experimental features have limited test coverage and the functionality may change in future versions of the CMSIS-Toolbox without further notice. -The CMSIS-Toolbox 2.7 implements the following experimental features: - -- [Experimental Features](#experimental-features) - - [Resource Management](#resource-management) - - [`resources:`](#resources) - - [Example `+.regions.h` file](#example-solution-nametarget-nameregionsh-file) - - [Question](#question) - - [Adding Memory](#adding-memory) - - [Run and Debug Management](#run-and-debug-management) - - [`+.cbuild-run.yml`](#solution-nametarget-namecbuild-runyml) - - [Usage](#usage) - - [Questions](#questions) +The CMSIS-Toolbox version 2.7 implements the experimental features for: +- [Resource Management](#resource-management) +- [Run and Debug Management](#run-and-debug-management) + +Hardening and finalizing of this features is planned for CMSIS-Toolbox version 2.8. ## Resource Management @@ -27,8 +20,8 @@ In a multi-processor or multi-project application the `target type` describes th The [linker script management](build-overview.md#linker-script-management) is extended for multi-processor or multi-project applications with the following features: - When [`resources:`](#resources) node is specified in one of the `*.cproject.yml` or `*.clayer.yml` files of a *csolution project*: - - The file `.\cmsis\+.regions.h` is generated. This file contains the global region settings of a solution for one target-type. - - The file `.\cmsis\+.regions.h` replaces the `regions_.h` that is located in the directory `./RTE/Device/`. The `regions_.h` is longer generated. + - The file `.\cmsis\+.regions.h` is generated. This file contains the global region settings of a solution for one target-type. + - The file `.\cmsis\+.regions.h` replaces the `regions_.h` that is located in the directory `./RTE/Device/`. The `regions_.h` is longer generated. - A `define: _cproject` is always added to the linker script pre-processor (also when no `resources:` node is used). @@ -41,9 +34,7 @@ The following picture explains the extended linker script management for multi-p The `resources:` node specifies the resources required by a project. It is used at the level of `project:`, `setup:`, or `layer:`. The `resources:` node is additive; when multiple `resources:` nodes specify the same region the size is added. !!! Note - -In a next iteration, the linker script may be generated by the CMSIS-Toolbox and [features from uVision to allocate source modules to specific regions](https://developer.arm.com/documentation/101407/0541/Creating-Applications/Tips-and-Tricks/File-and-Group-Specific-Options) may get added. -Therefore the `resources:` node is forward looking in the way heap and stack is specified. + In a next iteration, the linker script may be generated by the CMSIS-Toolbox and [features from uVision to allocate source modules to specific regions](https://developer.arm.com/documentation/101407/0541/Creating-Applications/Tips-and-Tricks/File-and-Group-Specific-Options) may get added. Therefore the `resources:` node is forward looking in the way heap and stack is specified. ```yml resources: @@ -68,7 +59,6 @@ Therefore the `resources:` node is forward looking in the way heap and stack is # - .text.function ``` - ### Example `+.regions.h` file ```c @@ -125,7 +115,7 @@ Therefore the `resources:` node is forward looking in the way heap and stack is ### Question -- Should the `+.regions.h` file contain also `#define's` for the overall avaiable memory, i.e. for a boot loader? +- Should the `+.regions.h` file contain also `#define` symbols for the overall available memory, i.e. for a boot loader? ## Adding Memory @@ -157,7 +147,7 @@ The CMSIS-Pack PDSC files contain information about device/board parameters and - [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, 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. +The CMSIS-Toolbox build system manages device/board/software components, 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-related-projects) 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. @@ -166,52 +156,58 @@ In addition the user may need the following information which should be added to - ToDo: Device configuration information. - ToDo: Access information for protected debug ports (i.e. encryption keys). -### `+.cbuild-run.yml` +### `.cbuild-run.yml` -The `+.cbuild-run.yml` is generated in the folder `.cmsis` and provides the relevant information for executing Run and Debug commands. Overall it: +The `.cbuild-run.yml` is generated in the `output` folder and provides the relevant information for executing Run and Debug commands. Using the option `--output` allows to redirect the build information files, the `tmp` and `out` directory. It is planned to introduce for VS Code the `.cmsis` folder that contains the output. Overall the `*.cbuild-run.yml` file: - simplifies the usage of flash programmers and debuggers. - provides information for command line and IDE workflows in a consistent way. - ensures that information is portable, i.e from a cloud-hosted CI system to a desktop test system. -The `+.cbuild-run.yml` file provides access to PDSC information and the build output of one target. It also exports the [Debug Access Sequences](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html). +The `.cbuild-run.yml` file provides access to PDSC information and the build output of one target. It also exports the [Debug Access Sequences](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html). ![Run and Debug Information Management](./images/cbuild-run.png "Run and Debug Information Management") The `+.cbuild-run.yml` file represents a context-set of a solution. -**Content of `+.cbuild-run.yml`:** +**Content of `.cbuild-run.yml`:** ```yml -run: # Start of file, contains run and debug information for a target +cbuild-run: generated-by: csolution version 2.7.0 - solution: ../USB_Device.csolution.yml - target-type: +STM32U585AIIx + solution: CubeMX.csolution.yml + target-type: MyBoard_ROM 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 + board: STMicroelectronics::B-U585I-IOT02A:Rev.C + board-pack: Keil::B-U585I-IOT02A_BSP@2.0.0 + programming: + - algorithm: ${CMSIS_PACK_ROOT}/Keil/STM32U5xx_DFP/3.0.0/CMSIS/Flash/STM32U5xx_2M_0800.FLM + start: 0x08000000 + size: 0x00200000 + ram-start: 0x20000000 + ram-size: 0x00008000 + default: true + - algorithm: ${CMSIS_PACK_ROOT}/Keil/STM32U5xx_DFP/3.0.0/CMSIS/Flash/STM32U5xx_2M_0C00.FLM + start: 0x0C000000 + size: 0x00200000 + ram-start: 0x20000000 + ram-size: 0x00008000 + default: true + - algorithm: ${CMSIS_PACK_ROOT}/Keil/STM32U5xx_DFP/3.0.0/CMSIS/Flash/MX25LM51245G_STM32U575I-EVAL.FLM + start: 0x70000000 + size: 0x04000000 + ram-start: 0x20000000 + ram-size: 0x000A0000 + system-descriptions: + - file: ${CMSIS_PACK_ROOT}/Keil/STM32U5xx_DFP/3.0.0/CMSIS/SVD/STM32U585.svd + type: svd + output: + - file: out/CubeMX/MyBoard_ROM/Debug/CubeMX.axf + type: elf + +# information that may get added (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: @@ -246,14 +242,5 @@ run: # Start of file, contains run and d 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 +>programmer --csolution 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/Proposal - Resource Management.md b/docs/Proposal - Resource Management.md deleted file mode 100644 index 3527d3b..0000000 --- a/docs/Proposal - Resource Management.md +++ /dev/null @@ -1,136 +0,0 @@ -# Proposal - Resource Management - - - - - - -The CMSIS-Toolbox has a simple linker management that assigns all available memory resources to a project. While this is useful for simple projects, it does not provide enough flexibility for multi-processor or multi-project applications. - -This is a proposal on how these features could be added. - -## Linker Script Management - -The current [linker script processing](build-overview.md#linker-script-management) is suitable for single core projects and uses: - -![Linker Script File Generation](./images/linker-script-file.png "Linker Script File Generation") - -At project level the [`linker:`](YML-Input-Format.md#linker) node specifies the files above. - -### Multi-processor or multi-project applications - -In a multi-processor or multi-project application the: - -- `target type` describes the target hardware. It contains memory resources from the `device:` and optionally `board:`. For many applications it is beneficial to list all resources in a single header file (that is specific to a `target type`.) -- A project uses a subset of resources (called regions at linker level). -- Depending on `build-types` the resources may need adjustments. - -A potential solution could be: - -- Target specific `regions+target.h` file that contains all available memory regions and allows to partition these regions for each project. This file could be auto-generated based on the information available in DFP and BSP. The `define` symbols for `ROM0..3`, `RAM0..3` would be extended with a project (see example below). - -- Project specific linker scripts that include the `regions+target.h` file. The project specific linker scripts use the extended `define` symbols described above. - -**Example:** - -The following is the `*.csolution.yml` file. It contains 4 projects: `Core2`, `TFM`, `MQTT_AWS`, and `Bootloader`. - -```yml - target-types: - type: MyTarget - - projects: - - project: ./core2/Core2.cproject.yml # Project that runs on a second core - - project: ./security/TFM.cproject.yml # Secure project - - project: ./application/MQTT_AWS.cproject.yml # Non-secure project - - project: ./bootloader/Bootloader.cproject.yml # Secure project (transfers control to TFM) -``` - -`regions-MyTarget.h` - -```c -// ROM Configuration -// ======================= -// __ROM0=Flash -// Base address <0x0-0xFFFFFFFF:8> -// Defines base address of memory region. -// Default: 0x08000000 -#define __ROM0_BASE 0x08000000 -// Region size [bytes] <0x0-0xFFFFFFFF:8> -// Defines size of memory region. -// Default: 0x00200000 -#define __ROM0_SIZE 0x00200000 - -// This are user configurable sizes -#define __ROM0_SIZE_Core2 0x10000 -#define __ROM0_SIZE_TFM 0x0 -#define __ROM0_SIZE_MQTT_AWS 0x20000 -#define __ROM0_SIZE_BootLoader 0x40000 - -// This is the allocation order -#define __ROM0_BASE_Core2 __ROM0_BASE -#define __ROM0_BASE_TFM (__ROM0_BASE_Core2+__ROM0_SIZE_Core2) -#define __ROM0_BASE_MQTT_AWS (__ROM0_BASE_TFM+__ROM0_SIZE_TFM) -#define __ROM0_BASE_BootLoader (__ROM0_MQTT_AWS+__ROM0_MQTT_AWS) - - // similar information is generated for ROM1..ROM3 + RAM0..RAM4 - // in case that memory is only available for a core, only a fraction of the project is created -``` - -The linker script is extended for each project using the project name. The copy process is similar to an %instance%, but expands %project% with the project name. - -Generic linker script `ac6_linker_script.sct.src` - -```txt -LR_ROM0 __ROM0_BASE_TFM __ROM0_SIZE_TFM { - - ER_ROM0 __ROM0_BASE_TFM __ROM0_SIZE_TFM { - *.o (RESET, +First) - *(InRoot$$Sections) - *(+RO +XO) - } - -#if defined (__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3U) - ER_CMSE_VENEER AlignExpr(+0, 32) (__ROM0_SIZE_TFM - AlignExpr(ImageLength(ER_ROM0), 32)) { - *(Veneer$$CMSE) - } -#endif - - RW_NOINIT __RAM0_BASE_TFM UNINIT (__RAM0_SIZE_TFM - __HEAP_SIZE - __STACK_SIZE - __STACKSEAL_SIZE) { - *.o(.bss.noinit) - *.o(.bss.noinit.*) - } - - RW_RAM0 AlignExpr(+0, 8) (__RAM0_SIZE_TFM - __HEAP_SIZE - __STACK_SIZE - __STACKSEAL_SIZE - AlignExpr(ImageLength(RW_NOINIT), 8)) { - *(+RW +ZI) - } - : -``` - -`ac6_linker_script.sct.src` expanded for TFM project - -```txt -LR_ROM0 __ROM0_BASE_TFM __ROM0_SIZE_TFM { - - ER_ROM0 __ROM0_BASE_TFM __ROM0_SIZE_TFM { - *.o (RESET, +First) - *(InRoot$$Sections) - *(+RO +XO) - } - -#if defined (__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3U) - ER_CMSE_VENEER AlignExpr(+0, 32) (__ROM0_SIZE_TFM - AlignExpr(ImageLength(ER_ROM0), 32)) { - *(Veneer$$CMSE) - } -#endif - - RW_NOINIT __RAM0_BASE_TFM UNINIT (__RAM0_SIZE_TFM - __HEAP_SIZE - __STACK_SIZE - __STACKSEAL_SIZE) { - *.o(.bss.noinit) - *.o(.bss.noinit.*) - } - - RW_RAM0 AlignExpr(+0, 8) (__RAM0_SIZE_TFM - __HEAP_SIZE - __STACK_SIZE - __STACKSEAL_SIZE - AlignExpr(ImageLength(RW_NOINIT), 8)) { - *(+RW +ZI) - } - : -``` diff --git a/docs/Proposal - Run+Debug Management.md b/docs/Proposal - Run+Debug Management.md deleted file mode 100644 index 1ec8277..0000000 --- a/docs/Proposal - Run+Debug Management.md +++ /dev/null @@ -1,150 +0,0 @@ -# Proposal - Run and Debug Management - - - - - - -This proposal discusses how the CMSIS-Toolbox may simplify workflows with programming and debug tools. - -## 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/ReferenceApplications.md b/docs/ReferenceApplications.md index c59ffb8..55f3032 100644 --- a/docs/ReferenceApplications.md +++ b/docs/ReferenceApplications.md @@ -361,9 +361,9 @@ Currently, the following **`connect` names** are used. . |. | **Arduino Shield Interface** [ARDUINO_UNO_UART](#arduino_uno_uart) | - | CMSIS-Driver USART connecting to UART on Arduino pins D0..D1 [ARDUINO_UNO_SPI](#arduino_uno_spi) | - | CMSIS-Driver SPI connecting to SPI on Arduino pins D10..D13 -[ARDUINO_UNO_I2C](#arduino_uno_i2c-arduino_uno_i2c-alt) | - | CMSIS-Driver I2C connecting to I2C on Arduino pins D20..D21 -[ARDUINO_UNO_I2C-Alt](#arduino_uno_i2c-arduino_uno_i2c-alt) | - | CMSIS-Driver I2C connecting to I2C on Arduino pins D18..D19 -[ARDUINO_UNO_D0 .. D21](#arduino_uno_d0-d21) | - | CMSIS-Driver GPIO connecting to Arduino pins D0..D21 +[ARDUINO_UNO_I2C](#arduino_uno_i2c) | - | CMSIS-Driver I2C connecting to I2C on Arduino pins D20..D21 +[ARDUINO_UNO_I2C-Alt](#arduino_uno_i2c) | - | CMSIS-Driver I2C connecting to I2C on Arduino pins D18..D19 +[ARDUINO_UNO_D0 .. D21](#arduino_uno_dx) | - | CMSIS-Driver GPIO connecting to Arduino pins D0..D21 . |. | **CMSIS Driver and RTOS Interfaces** [CMSIS_ETH](#cmsis_eth) | - | CMSIS-Driver ETH connected to physical board connector [CMSIS_MCI](#cmsis_mci) | - | CMSIS-Driver MCI connected to physical board connector @@ -372,9 +372,9 @@ Currently, the following **`connect` names** are used. [CMSIS_VIO](#cmsis_vio) | - | CMSIS-Driver VIO interface for virtual I/O CMSIS-RTOS2 | - | CMSIS-RTOS2 compliant RTOS . |. | **I/O Retargeting** -[STDERR](#stdin-stdout-stderr) | - | Standard Error output -[STDIN](#stdin-stdout-stderr) | - | Standard Input -[STDOUT](#stdin-stdout-stderr) | - | Standard Output +[STDERR](#stdio) | - | Standard Error output +[STDIN](#stdio) | - | Standard Input +[STDOUT](#stdio) | - | Standard Output . |. | **Memory allocation** Heap | Heap Size | Memory heap configuration @@ -393,9 +393,9 @@ Connects to a [CMSIS-Driver USART Interface](https://arm-software.github.io/CMSI #define ARDUINO_UNO_UART 3 // CMSIS-Driver USART instance number ``` -### ARDUINO_UNO_I2C / ARDUINO_UNO_I2C-Alt +### ARDUINO_UNO_I2C -Connects to a [CMSIS-Driver I2C Interface](https://arm-software.github.io/CMSIS_6/latest/Driver/group__i2c__interface__gr.html) configured in controller mode. +`ARDUINO_UNO_I2C` or `ARDUINO_UNO_I2C-Alt` connects to a [CMSIS-Driver I2C Interface](https://arm-software.github.io/CMSIS_6/latest/Driver/group__i2c__interface__gr.html) configured in controller mode. `CMSIS_target_header` contains driver instance number with this define: @@ -415,9 +415,9 @@ The Target Select (SS) pin (typically on ARDUINO_UNO_D10) is not handled by CMSI #define ARDUINO_UNO_SPI 1 // CMSIS-Driver SPI instance number ``` -### ARDUINO_UNO_D0 .. D21 +### ARDUINO_UNO_Dx -Connects to a [CMSIS-Driver GPIO Interface](https://arm-software.github.io/CMSIS_6/latest/Driver/group__gpio__interface__gr.html). +The `ARDUINO_UNO_D0` .. `ARDUINO_UNO_D21` connects to a [CMSIS-Driver GPIO Interface](https://arm-software.github.io/CMSIS_6/latest/Driver/group__gpio__interface__gr.html). `CMSIS_target_header` contains the pin mapping to the physical driver. @@ -490,9 +490,9 @@ Connects to a [CMSIS-Driver USB Host Interface](https://arm-software.github.io/C Connects to a [CMSIS-Driver VIO Interface](https://arm-software.github.io/CMSIS_6/latest/Driver/group__vio__interface__gr.html), a virtual I/O interface that connects on physical boards to LEDs and switches. -### STDIN / STDOUT / STDERR +### STDIO -I/O redirection via the [CMSIS-Compiler](https://arm-software.github.io/CMSIS-Compiler/main/index.html) software component. Typical the redirect is to a UART dedicated for debugging. +The `STDIN`, `STDOUT`, `STDERR` describes the I/O redirection via the [CMSIS-Compiler](https://arm-software.github.io/CMSIS-Compiler/main/index.html) software component. Typical the redirect is to a UART dedicated for debugging. ## Arduino Shield diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md index 4fe4b0c..9f444c3 100644 --- a/docs/YML-CBuild-Format.md +++ b/docs/YML-CBuild-Format.md @@ -175,8 +175,10 @@ The `cbuild.yml` file is structured into several sections. The top-level struct     `compiler:` | [Compiler toolchain](YML-Input-Format.md#compiler) used for code generation.     `board:` | [Board name](YML-Input-Format.md#board) used for this context.     `board-pack:` | BSP that is defining the [Board name](YML-Input-Format.md#board) used for this context. +    `board-books:` | List board documentation as defined in the [PDSC element ``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_boards_pg.html#element_board_book).     `device:` | [Device name](YML-Input-Format.md#device) with processor core selection used in this project context.     `device-pack:` | DFP that is defining the [Device name](YML-Input-Format.md#device) with processor core selection used in this project context. +    `device-books:` | List device documentation as defined in the [PDSC element ``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_book).     `processor:` | List of [processor attributes](YML-Input-Format.md#processor) used in this project context.     [`packs:`](#packs) | List of software [packs](#packs) along with path information used to generate this project context.     `optimize:` | Generic [optimize](YML-Input-Format.md#optimize) level for code generation. diff --git a/docs/YML-Input-Format - Preinclude.md b/docs/YML-Input-Format - Preinclude.md index 749fe84..1ccdfcb 100644 --- a/docs/YML-Input-Format - Preinclude.md +++ b/docs/YML-Input-Format - Preinclude.md @@ -1222,9 +1222,6 @@ A [`context`](#context-name-conventions) is an enviroment setup for a project th - `.build-type` that defines typically build specific settings such as for debug, release, or test. - `+target-type` that defines typically target specific settings such as device, board, or usage of processor features. -The section -[Project setup for multiple targets and test builds](build-overview.md#project-setup-for-multiple-targets-and-builds) -explains the overall concept of `target-types` and `build-types`. These `target-types` and `build-types` are defined in the `*.csolution.yml` that defines the overall application for a system. The settings of the `target-types:` are processed first; then the settings of the `build-types:` that potentially overwrite the `target-types:` settings. diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index 919efee..500ed38 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -29,10 +29,11 @@ File Extension | [Category](https://open-cmsis-pack.github.io/Open-CMS The **`csolution` Project Manager** uses the following syntax to specify the `pack:` names in the `*.yml` files. ```yml -[vendor ::] pack-name [@version] # If specified, with exact version -[vendor ::] pack-name [@>=version] # If specified, with version equal or higher -[vendor ::] pack-name [@^version] # If specified, with version equal or higher but same major version -[vendor ::] pack-name [@~version] # If specified, with version equal or higher but same major and minor version +[vendor ::] pack-name # Use latest version of the pack +[vendor ::] pack-name@version # With exact version +[vendor ::] pack-name@>=version # With version equal or higher +[vendor ::] pack-name@^version # With version equal or higher but same major version +[vendor ::] pack-name@~version # With version equal or higher but same major and minor version ``` Element | | Description @@ -51,13 +52,13 @@ Element | | Description **Examples:** ```yml -- pack: ARM::CMSIS@5.9.0 # 'CMSIS' Pack (with version 5.5.0) -- pack: MDK-Middleware@>=7.13.0 # 'MDK-Middleware` latest installed version 7.13.0 or higher -- pack: MDK-Middleware@^7.13.0 # 'MDK-Middleware' latest installed version 7.13.0 or higher but lower then 8.0.0 -- pack: Keil::TFM # 'TFM' Software Pack from vendor Keil, latest installed version -- pack: AWS # All latest versions of Software Packs from vendor 'AWS' -- pack: Keil::STM* # All latest versions of Software Packs that start with 'STM' from vendor 'Keil' -- pack: MDK-Middleware@>=8.0.0-0 # `MDK-Middleware` version 8.0.0 or higher including development versions +- pack: ARM::CMSIS@5.9.0 # 'CMSIS' Pack with version 5.5.0 +- pack: MDK-Middleware@>=7.13.0 # latest version 7.13.0 or higher +- pack: MDK-Middleware@^7.13.0 # latest version 7.13.0 or higher, but lower than 8.0.0 +- pack: Keil::TFM # 'TFM' Pack from vendor Keil, latest installed version +- pack: AWS # All Software Packs from vendor 'AWS', latest version +- pack: Keil::STM* # Software Packs that start with 'STM' from vendor 'Keil' +- pack: MDK-Middleware@>=8.0.0-0 # version 8.0.0 or higher including development versions ``` ### `component:` Name Conventions @@ -87,13 +88,16 @@ A component can be partly defined in *csolution project files* (`*.cproject.yml` - when a partly specified component resolves to several possible choices, the tool selects: - (a) the default `Cvariant` of the component as defined in the PDSC file. - (b) the component with the higher `Cversion` value. - - (c) and error message is issued when two identical components are defined by multiple vendors and `Cvendor` is not specified. + - (c) an error message is issued when two identical components are defined by multiple vendors and `Cvendor` is not specified. - the partly specified component is extended by: - version information from the software pack. - default variant definition from the software pack. The fully resolved component name is shown in the [`*.cbuild.yml`](YML-CBuild-Format.md) output file. +!!! Note + Before CMSIS-Toolbox 2.7, a component that omitted `Csub` resolved to the first matching component. Installing additional software packs could change therefore component selection. When a component is defined with `Csub` it is now required to specify. + **Multiple component definitions are rejected** - If a component is added more then once in the *csolution project files* and an *error* is issued. @@ -429,7 +433,7 @@ The `solution:` node is the start of a `*.csolution.yml` file that collects rela ```yml solution: - created-for: cmsis-toolbox@2.0 # minimum CMSIS-Toolbox version required for project build + created-for: cmsis-toolbox@2.6 # minimum CMSIS-Toolbox version required for project build cdefault: # use default setup of toolchain specific controls. compiler: GCC # overwrite compiler definition in 'cdefaults.yml' @@ -568,10 +572,9 @@ The following nodes control the directory structure for the application. Allows to control the directory structure for build output files and temporary files. ->**Note:** - -- This control is only possible at `csolution.yml` level. -- CMake manages the temporary directory of all projects therefore `tmpdir:` does not support access sequences. +!!! Notes + - This control is only possible at `csolution.yml` level. + - CMake manages the temporary directory of all projects therefore `tmpdir:` does not support access sequences. `output-dirs:` | | Content :----------------------------------|--------------|:------------------------------------ @@ -733,7 +736,7 @@ Refer to [Linker Script Management](build-overview.md#linker-script-management)    [`for-context:`](#for-context) | Optional | Include Linker Script for a list of *build* and *target* type names.    [`not-for-context:`](#not-for-context) | Optional | Exclude Linker Script for a list of *build* and *target* type names. -!!! Notes: +!!! Notes - The `linker:` node must have at least `regions:`, `script:`, `auto:`, or `define:`. - If no `script:` file is specified, compiler specific [Linker Script template files](build-overview.md#linker-script-templates) are used. - A Linker Script file is preprocessed when `regions:` or a `define:` is or the file extension is `*.src`. @@ -789,6 +792,7 @@ Configure the generated output files. `- elf` | Executable in ELF format. The file extension is toolchain specific. `- hex` | Intel HEX file in HEX-386 format. `- bin` | Binary image. +`- map` | Linker MAP file. The **default** setting for `output:` is: @@ -801,18 +805,25 @@ output: **Example:** ```yml -output: # configure output files +output: + type: + - elf # Generate executeable file. + - map # Generate Linker MAP file. +``` + +```yml +output: # configure output files. base-name: MyProject # used for all output files, including linker map file. type: - elf # Generate executeable file. - - hex # generate a HEX file - - bin # generate a BIN file + - hex # generate a HEX file. + - bin # generate a BIN file. ``` Generate a **library**: ```yml -output: # configure output files +output: # configure output files. type: lib # Generate library file. ``` @@ -862,6 +873,8 @@ Value | Select C++ Language Stan `gnu++17` | same as `c++17` but with additional GNU extensions. `c++20` | compile C++ source files as defined in C++20 standard (ISO/IEC 14882:2020). `gnu++20` | same as `c++20` but with additional GNU extensions. +`c++23` | compile C++ source files as defined in C++23 standard (ISO/IEC 14882:2023). +`gnu++23` | same as `c++23` but with additional GNU extensions. ### `optimize:` @@ -927,9 +940,8 @@ Contains a list of symbol #define statements that are passed via the command lin     `- : ` | #define symbol with value passed via command line     `- : \"\"` | #define symbol with string value passed via command line ->**Note:** - -This control only applies to C and C++ source files (or to the [linker](#linker) script preprocessor). For assembler source files use the `define-asm:` node. +!!! Note + This control only applies to C and C++ source files (or to the [linker](#linker) script preprocessor). For assembler source files use the `define-asm:` node. **Example:** @@ -986,9 +998,8 @@ Add include paths to the command line of the development tools for C and C++ sou :----------------------------------------------------------|:------------------------------------     `- ` | Named path to be added ->**Note:** - -This control only applies to C and C++ source files. For assembler source files use the `add-path-asm:` node. +!!! Note + This control only applies to C and C++ source files. For assembler source files use the `add-path-asm:` node. **Example:** @@ -1012,9 +1023,8 @@ Add include paths to the command line of the development tools for assembly sour :----------------------------------------------------------|:------------------------------------     `- ` | Named path to be added ->**Note:** - -This control only applies to assembler source files. For C and C++ source files use the `add-path:` node. +!!! Note + This control only applies to assembler source files. For C and C++ source files use the `add-path:` node. **Example:** @@ -1150,7 +1160,7 @@ The `packs:` node can be specified in the `*.csolution.yml` file allows you to: The [Pack Name Conventions](#pack-name-conventions) are used to specify the name of the software packs. The `pack:` definition may be specific to a [`context`](#context) that specifies `target-types:` and/or `build-types:` or provide a local path to a development repository of a software pack. -!!! Notes: +!!! Notes - By default, the **`csolution` Project Manager** only loads the latest version of the installed software packs. It is however possible to request specific versions using the `- pack:` node. - An attempt to add two different versions of the same software pack results in an error. @@ -1261,7 +1271,7 @@ A [`context`](#context-name-conventions) is an enviroment setup for a project th - The [`context`](#context-name-conventions) name is used througout the build process and is reflected in directory names. Even when there is not a fixed limit, keep identifiers short. Recommended is less than 32 characters for the [`context`](#context-name-conventions) name. - Blank characters (' ') in the context name are not permitted by CMake. -The section [Project setup for multiple targets and test builds](build-overview.md#project-setup-for-multiple-targets-and-builds) +The section [project setup for related projects](build-overview.md#project-setup-for-related-projects) explains the overall concept of `target-types` and `build-types`. These `target-types` and `build-types` are defined in the `*.csolution.yml` that defines the overall application for a system. The settings of the `target-types:` are processed first; then the settings of the `build-types:` that potentially overwrite the `target-types:` settings. @@ -1292,9 +1302,8 @@ The `target-types:` node may include [toolchain options](#toolchain-options), [t     [`context-map:`](#context-map) | Optional | Use different `target-types:` for specific projects.     [`variables:`](#variables) | Optional | Variables that can be used to define project components. -**Note::** - -Either `device:` or `board:` is required. +!!! Note + Either `device:` or `board:` is required. ### `build-types:` diff --git a/docs/build-overview.md b/docs/build-overview.md index a7e5044..7802ac0 100644 --- a/docs/build-overview.md +++ b/docs/build-overview.md @@ -6,9 +6,10 @@ This chapter describes the overall concept of the CMSIS-Toolbox build process. It outlines the content of *csolution project files* that describes the software application, and contains references to examples and project templates. - [Project Examples](#project-examples) helps to get started with the tools. +- [Software Layers](#software-layers) provide reusable configurations and give projects a better structure. - [Project Structure](#project-structure) describes the overall structure of projects. - [Linker Script Management](#linker-script-management) defines the available memory and controls the linker operation. -- [Generator Support](#generator-support) explains how to use configuration tools such as STM32CubeMX or MCUXpresso Config. +- [Generator Support](#generator-support) integrates configuration tools such as STM32CubeMX or MCUXpresso Config. ## Overview of Operation @@ -28,7 +29,7 @@ The tools process *csolution project files* (in YAML format) and *software packs - The term *CMSIS solution* refers to an application project that is specified with *csolution project files*. - *Software packs* describe software components in Open-CMSIS-Pack format that can contain middleware, drivers, board support, or device support. *Software packs* also provide documentation, examples, and reusable software layers. -The overall features are: +The features are: - Access the content of software packs in Open-CMSIS-Pack format to: - Setup the tool chain based on a *Device* or *Board* that is defined in software packs. @@ -41,9 +42,13 @@ The overall features are: - Manage multiple build types to support software verification (debug build, test build, release build, etc.) - Support multiple compiler toolchains (GCC, Arm Compiler 6, IAR, LLVM) for project deployment. -The diagram below outlines the operation of the `csolution` command `convert` that processes one or more [`context`](YML-Input-Format.md#context) configurations of the application (called *csolution project*). Refer to [Project Examples](#project-examples) for more information. +The diagram below outlines the operation of the `csolution` command `convert` that processes one or more [`context`](YML-Input-Format.md#context) configurations of the application (called *csolution project*). -![Operation Overview](./images/operation-overview.png "Operation Overview") +!!! Tip + - [Project Examples](#project-examples) show different project types and provides templates for user projects. + - [Build Process Overview](build-operation.md#build-process-overview) explains the complete end-to-end build process. + +![Operation Overview of csolution](./images/operation-overview.png "Operation Overview of csolution") Input Files | Description :------------------------|:--------------------------------- @@ -71,20 +76,20 @@ Output Files | Description To build an application project, the `csolution` command `convert` executes the following steps: 1. Read Input Files: - - Read *.YML input files and check files against schema (disable schema check with option: `--no-check-schema`) - - Parse *.YML input nodes. - - Load software packs for selected contexts (control packs with option: `--load [latest|all|required]`). + - Read *.YML input files and check files against schema (disable schema check with option: `--no-check-schema`) + - Parse *.YML input nodes. + - Load software packs for selected contexts (control packs with option: `--load [latest|all|required]`). 2. Process each project context (select a specific context with option: `--context`): - - Apply [`pack:`](YML-Input-Format.md#pack), [`device:`](YML-Input-Format.md#device), [`board:`](YML-Input-Format.md#board), and [`compiler:`](YML-Input-Format.md#compiler) to filter the content of software packs. - - From [`groups:`](YML-Input-Format.md#groups) add the list of user source files. - - From [`components:`](YML-Input-Format.md#components) add the list of component source files. - - From [*.GPDSC files](build-tools.md#use-generators) add the list of generated source files. + - Apply [`pack:`](YML-Input-Format.md#pack), [`device:`](YML-Input-Format.md#device), [`board:`](YML-Input-Format.md#board), and [`compiler:`](YML-Input-Format.md#compiler) to filter the content of software packs. + - From [`groups:`](YML-Input-Format.md#groups) add the list of user source files. + - From [`components:`](YML-Input-Format.md#components) add the list of component source files. + - From [*.GPDSC files](build-tools.md#use-generators) add the list of generated source files. 3. Generate output files: - - Update [configuration files](#plm-of-configuration-files) in RTE directory (disable with option: `--no-update-rte`). - - Print results of software component dependency validation. - - Create `cbuild-idx.yml`, `cbuild.yml` and `*.CPRJ` files. + - Update [configuration files](#plm-of-configuration-files) in RTE directory (disable with option: `--no-update-rte`). + - Print results of software component dependency validation. + - Create `cbuild-idx.yml`, `cbuild.yml` and `*.CPRJ` files. ### Source Code of Software Packs @@ -265,8 +270,6 @@ default: #### Compiler Selection -Toolchain agnostic projects do not contain a [`compiler:`](YML-Input-Format.md#compiler) selection in the `*.csolution.yml` project file. Instead the [`select-compiler:`](YML-Input-Format.md#select-compiler) node may list the compilers that this *csolution project* is tested with. - There are two ways to select a toolchain: - An explicit [`compiler:`](YML-Input-Format.md#compiler) selection in the `*.csolution.yml` project file: @@ -284,6 +287,9 @@ solution: cbuild Hello.csolution.yml --toolchain GCC ``` +!!! Tip + [Toolchain agnostic example projects](pack-tools.md#project-examples) do not contain a [`compiler:`](YML-Input-Format.md#compiler) selection in the `*.csolution.yml` project file. Instead the [`select-compiler:`](YML-Input-Format.md#select-compiler) node list the compilers that this *csolution project* is tested with. + ### Reproducible builds Reproducible builds are supported by the [*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) file that is created and read by the **csolution** project manager. This file: @@ -310,177 +316,11 @@ To support reproducible builds the following files should be committed to a repo !!! Note If the file `*.cbuild-set.yml` file is missing, the `setup` command creates a `*.cbuild-set` file with selection of the first `target-type` and the first `build-type`. -### Software Layers - -Software layers collect source files and software components along with configuration files for re-use in different projects as shown in the picture below. - -![Project Layers](./images/Layers.png "Project Layers") - -**Simple Example:** - -This example uses a layer to include an RTOS kernel. Using a layer has several benefits, for example that the configuration can be shared across many projects. - -The file `MyProject.cproject.yml` includes the file `RTOS.clayer.yml` using the [`layers:`](YML-Input-Format.md#linker) node: - -```yml -project: - groups: - - group: App - files: - - file: ./main.c - - components: - - component: CMSIS:CORE - - component: Device:Startup - - layers: - - layer: ../Layer/RTOS.clayer.yml -``` - -The `RTOS.clayer.yml` file defines the kernel along with configuration settings. - -```yml -layer: - description: RTX RTOS with configuration settings - - packs: - - pack: ARM:CMSIS-RTX - - components: - - component: CMSIS:RTOS2:Keil RTX5&Source -``` - -**Re-target Example:** - -The project [AVH-MLOps-Main](https://github.com/ARM-software/AVH-MLOps/tree/main/AVH-MLOps-main) is a test project that shows retargeting to different processors using a layer. - -**IoT Example:** - -The project [AWS_MQTT_MutualAuth_SW_Framework](https://github.com/Open-CMSIS-Pack/AWS_MQTT_MutualAuth_SW_Framework) provides an IoT cloud application that is composed of various layers: - -- **Demo.cproject.yml**: Implements the IoT Reference example. -- **Socket.clayer.yml**: A software layer that provides the socket interface for Internet connectivity. -- **Board.clayer.yml**: A software layer that provides the hardware interfaces to the device hardware. - -**Example:** - -#### Configuration Settings - -A software layer is a set of source files and pre-configured software components or source code that can be shared across multiple projects. To achieve this, the configuration files of a [`layer`](YML-Input-Format.md#layer) are stored within the directory structure of the software layer. This separate [RTE Directory Structure](#rte-directory-structure) allows that projects -can share a `layer` with common configuration settings. - -!!! Note - When using a generator, such as CubeMX or MCUxpresso, the output should be redirected as described under [Configure Generator Output](#configure-generator-output). - -#### Software Layers in Packs - -Software layers for [*reference applications*](ReferenceApplications.md) may be published in software packs. Refer to [Pack Creation » Layers](pack-tools.md#layers) for more information. - -### Project Setup for Multiple Targets and Builds - -Complex examples require frequently slightly different targets and/or modifications during build, i.e. for testing. The -picture below shows a setup during software development that supports: - -- Unit/Integration Testing on simulation models (called Virtual Hardware) where Virtual Drivers implement the interface - to simulated I/O. -- Unit/Integration Testing for the same software setup on a physical board where Hardware Drivers implement the interface to - physical I/O. -- System Testing where the software is combined with more software components that compose the final application. - -![Target and Build Types](./images/Target-Layer.png "Target and Build Types") - -As the software may share a large set of common files, provisions are required to manage such projects. The common is to add: - -- **target-types** (required) that select a target system. In the example this would be: - - `Virtual`: for simulation models. - - `Board`: for a physical evaluation board. - - `Production-HW`: for system integration test and product delivery on the final hardware. -- **build-types** (optional) add the flexibility to configure each target build towards a specific test. For example: - - `Debug`: for a full debug build of the software used in an interactive debug session. - - `Test`: for a specific timing test using a test interface with maximum code optimization. - - `Release`: for the final code deployment to the system. - -**Flexible Builds for Multi-Target Projects** - -Multi-target projects may be created using `target-types` that select different physical or virtual hardware systems. - -**File: MultiTarget.csolution.yml** - -```yml -solution: - cdefault: - compiler: AC6 - - : # pack definition not shown - - target-types: - - type: Board - board: NUCLEO-L552ZE-Q - variables: - - HAL-Layer: ./NUCLEO-L552ZE-Q/Board.clayer.yml - - - type: Production-HW - device: STM32L552XY # specifies device - variables: - - HAL-Layer: ./HW/Production.clayer.yml - - - type: Virtual - board: VHT-Corstone-300 # Virtual Hardware platform (appears as board) - variables: - - HAL-Layer: ./Corstone-300/AVH.clayer.yml - - build-types: - - type: Debug - optimize: none - debug: on - - - type: Test - optimize: size - debug: on - - - type: Release - optimize: size - debug: off - -projects: - - project: ./MyProject.cproject.yml -``` - -**File: MyProject.cproject.yml** - -```yml -project: - groups: - - group: My group1 - files: - - file: file1a.c - - file: file1b.c - - file: file1c.c - - - group: My group2 - files: - - file: file2a.c - - - group: Test-Interface - for-context: .Test - files: - - file: fileTa.c - - layers: - - layer: $HAL-Layer$ # include target-type specific HAL layer - - components: - - component: Device:Startup - - component: CMSIS:RTOS2:FreeRTOS - - component: ARM::CMSIS:DSP&Source # not added for build type: Test - not-for-context: .Test -``` - ### Project Setup for Related Projects A solution is the software view of the complete system. It combines projects that can be generated independently and therefore manages related projects. It may be also deployed to different targets during development as described in the -previous section under [Project Setup for Multiple Targets and Builds](#project-setup-for-multiple-targets-and-builds). +previous section under [Software Layers](#software-layers). The picture below shows a system that is composed of: @@ -599,6 +439,136 @@ project: # Non-secure project - file: $cmse-lib(Project_S)$ # Secure part of an application ``` +## Software Layers + +Software layers collect source files and software components along with configuration files for re-use in different projects. Software Layers gives projects a better structure and simplifies: + +- Development flows with evaluation boards and production hardware. +- Evaluation of middleware and hardware modules across different microcontroller boards. +- Code reuse across projects, i.e. board support for test-case deployment. +- Test-driven software development on simulation model and hardware. + +**Simple Example:** + +This example uses a layer to include an RTOS kernel. The file `MyProject.cproject.yml` includes the file `RTOS.clayer.yml` using the [`layers:`](YML-Input-Format.md#linker) node: + +```yml +project: + groups: + - group: App + files: + - file: ./main.c + + components: + - component: CMSIS:CORE + - component: Device:Startup + + layers: + - layer: ../Layer/RTOS.clayer.yml # Add RTOS kernel +``` + +The `RTOS.clayer.yml` file defines the kernel along with configuration settings. + +```yml +layer: + description: RTX RTOS with configuration settings + + packs: + - pack: ARM:CMSIS-RTX + + components: + - component: CMSIS:RTOS2:Keil RTX5&Source +``` + +The diagram below shows two different scenarios that are explained in the following sections. + +![Layer Usage](./images/Layers.png "Layer Usage") + +### Target Production Hardware + +Software development frequently starts on evalution boards. Using a board layer simplifes re-targeting to production hardware. The following `*.csolution.yml` file exemplifies the concept. A software developer starts with a board layer for the evaluation board in the folder `MyBoard`. Once the production hardware is available, this layer is copied to a different folder (i.e. `MyHardware`). As both layers are independently managed, the configuration of the `MyHardware` layer can be modified, for example to target different devices, pin layout, or peripheral configurations. + +In the `*.csolution.yml` project the layer is defined using a [variable](YML-Input-Format.md#variables). By changing the `target-type` during the build process the software developer can continue to use the evaluation board or target the production hardware. + +```yml +solution: + cdefault: + compiler: AC6 + + target-types: + - type: EvalBoard + board: STMicroelectronics::B-U585I-IOT02A:Rev.C + device: STMicroelectronics::STM32U585AIIx + variables: + - Board-Layer: $SolutionDir()$/MyBoard/Board.clayer.yml + + - type: ProductionHW + device: STMicroelectronics::STM32U575AIIx # uses a different device + variables: + - Board-Layer: $SolutionDir()$/MyHardware/Board.clayer.yml + + build-types: + - type: Debug + debug: on + optimize: debug + - type: Release + debug: off + optimize: balanced + + projects: + - project: HID/HID.cproject.yml +``` + +!!! Tip + - The [MDK-Middleware examples](https://arm-software.github.io/MDK-Middleware/latest/General/working_with_examples.html) are structured in this way. Start with a board layer that is provided in several [Board Support Packs](https://github.com/Open-CMSIS-Pack#stm32-packs-with-generator-support). + - Another project that extends this concept to hardware shields is the [Sensor-SDK-Example](https://github.com/Open-CMSIS-Pack/Sensor-SDK-Example). + +### Test Case Project + +Modern software design mandates for [test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) that utilizes DevOps or CI principals. Simulation models such as the [Arm Virtual Hardware (AVH) FVP](https://arm-software.github.io/AVH/main/overview/html/index.html) allow test automation without target hardware. + +However, in some cases test should be also performed physical hardware. A test case project may therefore contain targets for simulation and physical hardware. The *csolution project* format allows to combine multiple test projects that validate different parts of the application. + +```yml +solution: + cdefault: + compiler: GCC + : # pack definition not shown + + target-types: + - type: Board + board: NUCLEO-L552ZE-Q + variables: + - Board-Layer: ./Board/NUCLEO-L552ZE-Q/Board.clayer.yml + + - type: Virtual + board: VHT-Corstone-300 # Virtual Hardware platform (appears as board) + variables: + - Board-Layer: ./Board/Corstone-300/AVH.clayer.yml + + projects: + - project: ./TestSuite1/TestCases.cproject.yml + - project: ./TestSuite2/TestCases.cproject.yml + - project: ./TestSuite3/TestCases.cproject.yml +``` + +!!! Tip + - Several [examples for Arm Virtual Hardware (AVH) FVP simulation models](https://github.com/Arm-Examples#avh-fvp-examples) show usage of *csolution projects* in CI workflows. + - The project [AVH-MLOps-Main](https://github.com/ARM-software/AVH-MLOps/tree/main/AVH-MLOps-main) is a test project that shows retargeting to different processors using a layer. + - The project [AWS_MQTT_Demo](https://github.com/Arm-Examples/AWS_MQTT_Demo) extends this concept with retargeting of a IP communication to virtual or physical hardware. + +### Configuration Settings + +A software layer is a set of source files and pre-configured software components or source code that can be shared across multiple projects. To achieve this, the configuration files of a [`layer`](YML-Input-Format.md#layer) are stored within the directory structure of the software layer. This separate [RTE Directory Structure](#rte-directory-structure) allows that projects +can share a `layer` with common configuration settings. + +!!! Note + When using a generator, such as CubeMX or MCUxpresso, the output should be redirected as described under [Configure Generator Output](#configure-generator-output). + +### Software Layers in Packs + +Software layers for [*reference applications*](ReferenceApplications.md) may be published in software packs. Refer to [Pack Creation » Layers](pack-tools.md#layers) for more information. + ## Project Structure This section describes how the `csolution` based project files should be organized to allow the scenarios described above. This section gives also guidelines for a directory structure. @@ -667,7 +637,7 @@ Output | Content ### Software Components -Software components are re-usable library or source files that require no modification in the user application. +[Software components](CreateApplications.md#software-components) are re-usable library or source files that require no modification in the user application. Optionally, configurable source and header files are provided that allow to set parameters for the software component. - Configurable source and header files are copied to the project using the directory structure explained above. @@ -676,11 +646,10 @@ Optionally, configurable source and header files are provided that allow to set project. - An include path to the header files of the software component is added to the C/C++ Compiler control string. -!!! Note - -The `csolution` command `convert` provides the option `--no-update-rte` that disables generation of files in the `./RTE` directory and therefore the management of configuration files and the `RTE_Components.h` file. - -The `csolution` command `update-rte` only updates the configuration files in the `RTE` directory and provides with the option `--verbose` additional version details. +!!! Notes + - The `csolution` command `convert` provides the option `--no-update-rte` that disables generation of files in the `./RTE` directory and therefore the management of configuration files and the `RTE_Components.h` file. + - The `csolution` command `update-rte` only updates the configuration files in the `RTE` directory. + - Using the option `--verbose` outputs additional version details. ### PLM of Configuration Files @@ -817,11 +786,11 @@ This section describes the Linker Script management of the **`csolution` Project 1. The [`linker:`](YML-Input-Format.md#linker) node specifies an explicit Linker Script and/or memory regions header file. This overrules Linker Scripts that are part of software components or specified using the `file:` notation. -1. The [`linker:`](YML-Input-Format.md#linker) `auto:` enables the [automatic Linker Script generation](#automatic-linker-script-generation). +2. The [`linker:`](YML-Input-Format.md#linker) `auto:` enables the [automatic Linker Script generation](#automatic-linker-script-generation). -1. If no [`linker:`](YML-Input-Format.md#linker) node is used, a Linker Script file can be provided as part of software components. The extensions `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files. +3. If no [`linker:`](YML-Input-Format.md#linker) node is used, a Linker Script file can be provided as part of software components. The extensions `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files. -1. If no Linker Script is found, the [automatic Linker Script generation](#automatic-linker-script-generation) is used. +4. If no Linker Script is found, the [automatic Linker Script generation](#automatic-linker-script-generation) is used. ### Linker Script Preprocessing @@ -873,9 +842,9 @@ Linker Script Template | Linker control file for ... The steps for creating a `*.csolution.yml` application with a *Generator* are: 1. Create the `*.csolution.yml` container that refers the projects and selects `device:` or `board:` (by using `target-types:`) -1. Create `*.cproject.yml` files that are referred by the `*.csolution.yml` container. -1. Add `components:` to the `*.cproject.yml` file. -1. For components that have a ``, run the related generator. +2. Create `*.cproject.yml` files that are referred by the `*.csolution.yml` container. +3. Add `components:` to the `*.cproject.yml` file. +4. For components that have a ``, run the related generator. The *Generator* can add files, components, and settings to a project using the [*Generator* import file (`*.cgen.yml`)](YML-CBuild-Format.md#generator-import-file). The format of this file is similar to a [software layer](#software-layers). @@ -919,4 +888,7 @@ A Generator output configuration is useful for: ### Detailed Usage Instructions -[**Configure STM32 Devices with CubeMX**](CubeMX.md) explains how to use [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) to manage device and board configuration. +These chapters explain how to manage device and board configuration in more detail: + +- [**Configure STM32 Devices with CubeMX**](CubeMX.md) +- [**Configure NXP Devices with MCUXpresso Config Tools**](MCUXpressoConfig.md) diff --git a/docs/build-tools.md b/docs/build-tools.md index 8cf1341..956eb3d 100644 --- a/docs/build-tools.md +++ b/docs/build-tools.md @@ -22,7 +22,7 @@ There are several ways to configure the CMSIS-Pack repository: Orchestrate the overall build steps utilizing the various tools of the CMSIS-Toolbox and a CMake-based compilation process. ```txt -cbuild: Build Invocation 2.6.0 (C) 2024 Arm Ltd. and Contributors +cbuild: Build Invocation 2.7.0 (C) 2024 Arm Ltd. and Contributors Usage: cbuild [command] .csolution.yml [options] @@ -44,11 +44,12 @@ Options: -j, --jobs int Number of job slots for parallel execution (default 8) -l, --load arg Set policy for packs loading [latest | all | required] (default "required") --log arg Save output messages in a log file + -n, --no-schema-check Skip schema check -O, --output arg Add prefix to 'outdir' and 'tmpdir' -p, --packs Download missing software packs with cpackget -q, --quiet Suppress output messages except build invocations -r, --rebuild Remove intermediate and output directories and rebuild - -s, --schema Validate project input file(s) against schema + -s, --schema Validate project input file(s) against schema [deprecated] -t, --target arg Optional CMake target name --toolchain arg Input toolchain to be used --update-rte Update the RTE directory and files @@ -66,7 +67,7 @@ Use "cbuild [command] --help" for more information about a command. Create build information for embedded applications that consist of one or more related projects. ```text -csolution: Project Manager 2.6.0 (C) 2024 Arm Ltd. and Contributors +csolution: Project Manager 2.7.0 (C) 2024 Arm Ltd. and Contributors Usage: csolution [.csolution.yml] [options] @@ -99,7 +100,7 @@ Options: -m, --missing List only required packs that are missing in the pack repository -n, --no-check-schema Skip schema check -N, --no-update-rte Skip creation of RTE directory and files - -o,-O --output arg Add prefix to 'outdir' and 'tmpdir' + -o,-O --output base-dir Add prefix to 'outdir' and 'tmpdir' -q, --quiet Run silently, printing only error messages -R, --relative-paths Print paths relative to project or ${CMSIS_PACK_ROOT} -S, --context-set Select the context names from cbuild-set.yml for generating the target application @@ -350,9 +351,8 @@ variants. There are two ways to specify the CMSIS-PACK root directory: cpackget add Vendor.PackName --pack-root ./MyLocal/Packs ``` ->**Note:** - -As the various tools of the CMSIS-Toolbox all rely on the CMSIS-Pack root directory, it is recommended to use the `CMSIS_PACK_ROOT` environment variable. +!!! Note + As the various tools of the CMSIS-Toolbox all rely on the CMSIS-Pack root directory, it is recommended to use the `CMSIS_PACK_ROOT` environment variable. ### Initialize CMSIS-Pack root directory @@ -554,9 +554,8 @@ List all packs present in the local copy of the **Pack Index File** (`index.pidx cpackget list --public ``` ->**Note:** - -[Update Pack Index File](#update-pack-index) before using the `list` command to list all public software packs. +!!! Note + [Update Pack Index File](#update-pack-index) before using the `list` command to list all public software packs. ### Remove packs @@ -590,7 +589,7 @@ cpackget rm Vendor.PackName.pdsc ## DevOps Usage -The CMSIS-Toolbox supports Continuous Integration (CI) tests in DevOps systems. The `./out` directory contains all build artifacts of an application for execution on physical hardware or simulation models. [Arm Virtual Hardware - Fixed Virtual Platforms (AVH FVP)](https://github.com/ARM-software/AVH) enable unit tests and integration tests with simulation models and various virtual interfaces. Using layers allows a [Project Setup for Multiple Targets](build-overview.md#project-setup-for-multiple-targets-and-builds), for example to test on physical hardware or AVH-FVP simulation models. The following commands show typical usage of the CMSIS-Toolbox build system in CI environments. +The CMSIS-Toolbox supports Continuous Integration (CI) tests in DevOps systems. The `./out` directory contains all build artifacts of an application for execution on physical hardware or simulation models. [Arm Virtual Hardware - Fixed Virtual Platforms (AVH FVP)](https://github.com/ARM-software/AVH) enable unit tests and integration tests with simulation models and various virtual interfaces. Using [software layers](build-overview.md#software-layers) allows for example to test on physical hardware or AVH-FVP simulation models. The following commands show typical usage of the CMSIS-Toolbox build system in CI environments. The commands below show typical builds in a CI system. Using `--packs` installs all public packs with implicit acceptance of licenses. This command builds all projects, target-types, and build-types. Using [`--context`](build-overview.md#context) reduces the scope of the build. Using [`--frozen-packs`](build-overview.md#reproducible-builds) uses exactly the packs that are specified in the file `*.cbuild-pack.yml`. diff --git a/docs/images/Layers.png b/docs/images/Layers.png index 2de3e8e..8297112 100644 Binary files a/docs/images/Layers.png and b/docs/images/Layers.png differ diff --git a/docs/images/overview.pptx b/docs/images/overview.pptx index 8cd2a34..55bd79d 100644 Binary files a/docs/images/overview.pptx and b/docs/images/overview.pptx differ diff --git a/docs/index.md b/docs/index.md index 86c42c1..f6c4e5c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,13 +31,16 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for: - [**Pack Creation**](pack-tools.md) describes how to create software packs that optionally include examples and explains the pack creation tools `packchk` (software pack verification) and `svdconv` (SVD file verification and header file generator). +- [**Experimental Features**](Experimental-Features.md) for resource management of multi-project linker scripts, run and debug management. + ## Revision History Version | Description :------------------|:------------------------- -2.6.0 | CMSIS-Toolbox [2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.6.0); extends [pack:](YML-Input-Format.md#pack-name-conventions) version specifier and [C language](YML-Input-Format.md#language-c) support to C17 and C23. Improved is [regions header file generation](CreateApplications.md#regions-header-file) for linker scripts. It adds [trustzone: secure-only](YML-Input-Format.md#processor) for projects without secure entries, [apis](YML-CBuild-Format.md#apis), [messages](YML-CBuild-Format.md#cbuilds), and [PLM status for config files](YML-CBuild-Format.md#files-of-a-component) to cbuild.yml information, and fixes several minor issues. It is no longer possible to specify [compiler](YML-Input-Format.md#compiler) in the [`cdefault.yml`](YML-Input-Format.md#cdefault) file. +2.7.0 | CMSIS-Toolbox [2.7.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.7.0). Adds [C++ language](YML-Input-Format.md#language-cpp): `c++23`, `gnu++23`; [output](YML-Input-Format.md#output) linker MAP file control; [MCUXpresso Config Tool](MCUXpressoConfig.md); [experimental features](Experimental-Features.md) for multi-project linker scripts, debug, and run. Fixed: `components:` now require [Csub](YML-Input-Format.md#component-name-conventions) specifier; LLVM/Clang 19 compatibility; handling of [group options](YML-Input-Format.md#groups). See here for [more details](https://github.com/orgs/Open-CMSIS-Pack/projects/13). +2.6.0 | CMSIS-Toolbox [2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.6.0); extends [pack:](YML-Input-Format.md#pack-name-conventions) version specifier and [C language](YML-Input-Format.md#language-c) support to C17 and C23. Improved is [regions header file generation](CreateApplications.md#regions-header-file) for linker scripts. It adds [trustzone: secure-only](YML-Input-Format.md#processor) for projects without secure entries, [apis](YML-CBuild-Format.md#apis), [messages](YML-CBuild-Format.md#cbuilds), and [PLM status for config files](YML-CBuild-Format.md#files-of-a-component) to cbuild.yml information, and fixes several minor issues. It is no longer possible to specify [compiler](YML-Input-Format.md#compiler) in the [`cdefault.yml`](YML-Input-Format.md#cdefault) file. See here for [more details](https://github.com/orgs/Open-CMSIS-Pack/projects/14). 2.5.0 | CMSIS-Toolbox [2.5.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.5.0); direct CMake interface is now default, [`tmpdir:`](YML-Input-Format.md#output-dirs) controls location of interim files, adds [`add-path-asm:`](YML-Input-Format.md#add-path-asm), adds [`define-asm`](YML-Input-Format.md#define-asm), adds [regular expression](YML-Input-Format.md#regular-expressions) search to `for-context:`/`not-for-context`, and contains several corrections. 2.4.0 | CMSIS-Toolbox [2.4.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.4.0); adds [CubeMX integration](CubeMX.md), [pre/post-build steps](YML-Input-Format.md#prepost-build-steps), simplifies the [generator integration](build-operation.md#generator-integration), and contains several corrections. 2.3.0 | CMSIS-Toolbox [2.3.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.3.0) adds in the csolution project files [component instances](YML-Input-Format.md#instances) and [optimize: debug](YML-Input-Format.md#optimize). Tools are extended with [cbuild setup command](build-operation.md#details-of-the-setup-mode), [--frozen-pack option](build-overview.md#reproducible-builds). Refer to [release information](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.3.0) for more details. 2.2.0 | CMSIS-Toolbox [2.2.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) adds [generator integration](build-operation.md#generator-integration), extends [translation controls](YML-Input-Format.md#translation-control), adds [context set](build-overview.md#working-with-context-set), adds [pack locking](YML-CBuild-Format.md#pack-locking), and improves [linker script management](build-overview.md#linker-script-management). Refer to [release information](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) for more details. -2.0.0 | Initial release for CMSIS-Toolbox [2.0.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.0.0) \ No newline at end of file +2.0.0 | Initial release for CMSIS-Toolbox [2.0.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.0.0) diff --git a/docs/installation.md b/docs/installation.md index c3e71cb..973064f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -136,7 +136,8 @@ export CMSIS_COMPILER_ROOT=/opt/cmsis-toolbox/etc export PATH=/opt/cmsis-toolbox/bin:$PATH ``` -Note: The command `printenv` should list these environment variables. +!!! Note + The command `printenv` should list these environment variables. #### Setup macOS @@ -176,8 +177,6 @@ The command to install and enable `vcpkg` depends on the shell. ```bat curl -LO https://aka.ms/vcpkg-init.cmd && .\vcpkg-init.cmd -``` -```bat %USERPROFILE%\.vcpkg\vcpkg-init.cmd ``` @@ -185,8 +184,6 @@ curl -LO https://aka.ms/vcpkg-init.cmd && .\vcpkg-init.cmd ```ps1 iex (iwr -useb https://aka.ms/vcpkg-init.ps1) -``` -```ps1 . ~/.vcpkg/vcpkg-init.ps1 ``` @@ -194,8 +191,6 @@ iex (iwr -useb https://aka.ms/vcpkg-init.ps1) ```sh . <(curl https://aka.ms/vcpkg-init.sh -L) -``` -```sh . ~/.vcpkg/vcpkg-init ``` diff --git a/docs/migration.md b/docs/migration.md index 73670d7..0a15430 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -48,7 +48,8 @@ in `output-dirs`: - `gendir` (replaced by `generators` node) - `rtedir` (replaced by `rte` node in `*.cproject.yml`) ->Note: RTE files belonging to components specified in `*.clayer.yml` files remain next to such `*.clayer.yml.` +!!! Note + RTE files belonging to components specified in `*.clayer.yml` files remain next to such `*.clayer.yml.` in [`processor`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#processor): @@ -63,7 +64,9 @@ in [`cdefault:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs **The cdefault enablement has changed:** The [`cdefault:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#default) empty node must be added to *.csolution.yml to activate its use. ->Note: the file must be named `cdefault.yml` or `cdefault.yaml` without leading dot. + +!!! Note + The file must be named `cdefault.yml` or `cdefault.yaml` without leading dot. **The following [Access Sequences](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#access-sequences) were removed:** diff --git a/docs/pack-tools.md b/docs/pack-tools.md index f48e71a..21b8a7b 100644 --- a/docs/pack-tools.md +++ b/docs/pack-tools.md @@ -98,8 +98,7 @@ solution: A *template project* does not define a [`device:`](YML-Input-Format.md#device) or [`board:`](YML-Input-Format.md#board) in the `*.csolution.yml` file. When a IDE starts such an *template* the `device:` and/or `board:` information along with `pack:` information is added depending on user selection. The [`target-types:`](YML-Input-Format.md#target-types) contains a `Name` that may be replaced by a descriptive target name. !!! Note - -A *template project* should not specify the DFP or BSP with a `pack:` node as this gets added by the IDE during project start. + A *template project* should not specify the DFP or BSP with a `pack:` node as this gets added by the IDE during project start. **Simple Template:** @@ -147,8 +146,7 @@ project: ``` !!! Note - -*Templates* should compile when the above information is added to the `*.csolution.yml` file. The exception is when *templates* require parts of the code provided by a generator. + *Templates* should compile when the above information is added to the `*.csolution.yml` file. The exception is when *templates* require parts of the code provided by a generator. **Register Template in PDSC File:** @@ -266,8 +264,7 @@ solution: ``` !!! Note - -The [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples) contains several *reference applications* that exemplify the overall structure. + The [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware/tree/main/Examples) contains several *reference applications* that exemplify the overall structure. **Register *Reference Applications* in PDSC File:** @@ -299,8 +296,7 @@ The [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware/tree/main/Ex ``` !!! Note - -Several [STM32 Board Support Packs (BSP)](https://github.com/Open-CMSIS-Pack#stm32-packs-with-generator-support) contain *layers* that are pre-configured for certain applications. For example, the *layer* in the [ST_NUCLEO-F756ZG_BSP](https://github.com/Open-CMSIS-Pack/ST_NUCLEO-F756ZG_BSP/tree/main/Layers/Default) supports applications that require Ethernet, USB Device, UART, or I2C interfaces. + Several [STM32 Board Support Packs (BSP)](https://github.com/Open-CMSIS-Pack#stm32-packs-with-generator-support) contain *layers* that are pre-configured for certain applications. For example, the *layer* in the [ST_NUCLEO-F756ZG_BSP](https://github.com/Open-CMSIS-Pack/ST_NUCLEO-F756ZG_BSP/tree/main/Layers/Default) supports applications that require Ethernet, USB Device, UART, or I2C interfaces. ## Code Templates @@ -323,8 +319,20 @@ Several [STM32 Board Support Packs (BSP)](https://github.com/Open-CMSIS-Pack#stm ``` !!! Note + The [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) and [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware) pack contains several *code templates* that exemplify the overall structure. + +## Pack Generation + +Packs should be generated using scripts. Several scripts are available on [github.com/open-cmsis-pack](https://github.com/open-cmsis-pack): + +- [gen-pack](https://github.com/Open-CMSIS-Pack/gen-pack) is library for scripts creating software packs. +- [gen-pack-action](https://github.com/Open-CMSIS-Pack/gen-pack-action) is a GitHub workflow action generating documentation and software packs. + +To start a pack, add a [`*.PDSC` file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/packFormat.html) with meta information and configure the above scripts. -The [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) and [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware) pack contains several *code templates* that exemplify the overall structure. +!!! Tip + - Arm uses GitHub actions to create packs. Review this process under the `workflow` directory on the projects available on [github.com/arm-software](https://github.com/arm-software) or [github.com/open-cmsis-pack](https://github.com/open-cmsis-pack). + - A good simple pack project is the [CMSIS-Driver pack](https://github.com/arm-software/cmsis-driver). Once this pack is published it is available for software developers using pack managers or [web portals](https://www.keil.arm.com/packs/cmsis-driver-arm/overview/). ## Pack Examples diff --git a/mkdocs.yml b/mkdocs.yml index e229a0c..0da5f29 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ nav: - Build Information Files: YML-CBuild-Format.md - Build Operation: build-operation.md - Pack Creation: pack-tools.md + - Experimental Features: Experimental-Features.md theme: name: readthedocs markdown_extensions: