Experimental Features

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 version 2.7 implements the experimental features for: - Resource Management - Run and Debug Management

Hardening and finalizing of this features is planned for CMSIS-Toolbox version 2.8.

Resource Management

In a multi-processor or multi-project application the target type describes the target hardware. A solution is a collection of related projects and the context-set defines the projects that are deployed to the target hardware. A project uses a subset of resources (called regions at linker level).

The linker script management is extended for multi-processor or multi-project applications with the following features:

When resources: node is specified in one of the *.cproject.yml or *.clayer.yml files of a csolution project:
- The file .\cmsis\<solution-name>+<target-name>.regions.h is generated. This file contains the global region settings of a solution for one target-type.
- The file .\cmsis\<solution-name>+<target-name>.regions.h replaces the regions_<device_or_board>.h that is located in the directory ./RTE/Device/<device>. The regions_<device_or_board>.h is longer generated.
A define: <project-name>_cproject is always added to the linker script pre-processor (also when no resources: node is used).

The following picture explains the extended linker script management for multi-project applications.

Linker Script Management for Multi-Project Applications

`resources:`

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 may get added. Therefore the resources: node is forward looking in the way heap and stack is specified.

  resources:
    regions:
      - region: __ROM0    # region name pre-defined in script template: __ROM0..3
        size: 0x10000     # specifies region size
#       name: ITCM_Flash  - maps to physical memory name(s), if missing use PDSC default memory
#       address:          - absolution address of region; not in scope for 2.7
#       startup:          - locate startup/vectors to this region; not in scope for 2.7
#       align:            - alignment restrictions of the regions; not in scope for 2.7

      - region: __RAM0    # region name pre-defined in script template: __RAM0..3
        size:  0x8000     # specifies region size
        heap:  0x2000     # heap size (only permitted region __RAM0)
        stack: 0x4000     # stack size (only permitted in region __RAM0)
#       name:             - maps to physical memory name(s), if missing use PDSC default memory
#         - SRAM1
#         - SRAM2
#       address:          - absolution address of region; not in scope for 2.7
#       align:            - alignment restrictions of the regions; not in scope for 2.7
#       sections:         - potentially locate sections (requires linker script generation); not in scope for 2.7
#         - .text.function

Example `<solution-name>+<target-name>.regions.h` file

#ifndef USBD_STM32F746G_DISCO_REGIONS_H
#define USBD_STM32F746G_DISCO_REGIONS_H

// *** DO NOT MODIFY THIS FILE! ***
//
// Generated by csolution 2.7.0 based on packs and csolution project resources
// Device Family Pack (DFP):   Keil::STM32F7xx_DFP@3.0.0
// Board Support Pack (BSP):   Keil::STM32F746G-DISCO_BSP@1.0.0

// Available Physical Memory Resources
// rx ROM:   Name: ITCM_Flash (from DFP)  BASE: 0x00200000  SIZE: 0x00100000
// rx ROM:   Name: Flash (from DFP)       BASE: 0x08000000  SIZE: 0x00100000 (default)
// rwx RAM:  Name: DTCM (from DFP)        BASE: 0x20000000  SIZE: 0x00010000
// rwx RAM:  Name: SRAM1 (from DFP)       BASE: 0x20010000  SIZE: 0x00020000 (default)
// rwx RAM:  Name: SRAM2 (from DFP)       BASE: 0x20030000  SIZE: 0x00020000 (default)
// rwx RAM:  Name: BKP_SRAM (from DFP)    BASE: 0x40024000  SIZE: 0x00001000
// rwx RAM:  Name: ITCM (from DFP)        BASE: 0x00000000  SIZE: 0x00004000

//--------------------------------------
#ifdef A_cproject
// Resources allocated in A.cproject.yml

#define __ROM0_BASE  0x08000000      /* Memory Name: Flash */
#define __ROM0_SIZE  0x00010000

#define __RAM0_BASE  0x20010000      /* Memory Name: SRAM1 */
#define __RAM0_SIZE  0x00008000

#define __STACK_SIZE 0x00004000
#define __HEAP_SIZE  0x00002000

#endif /* A_cproject */

//--------------------------------------
#ifdef B_cproject
// Resources allocated in B.cproject.yml

#define __ROM0_BASE  0x08010000      /* Memory Name: Flash */
#define __ROM0_SIZE  0x00030000

#define __RAM0_BASE  0x20018000      /* Memory Name: SRAM1+SRAM2 */
#define __RAM0_SIZE  0x00020000

#define __STACK_SIZE 0x00000200
#define __HEAP_SIZE  0x00000000

#endif  /* B_cproject */

#endif /* USBD_STM32F746G_DISCO_REGIONS_H */

Question

Should the <solution-name>+<target-name>.regions.h file contain also #define symbols for the overall available memory, i.e. for a boot loader?

Adding Memory

Hardware targets may have additional off-chip memory. A memory: node that can be added as additional information to a target type as shown below:

solution:
  :
  target-types:
    - type: MyHardware
      device: STMicroelectronics::STM32F746NGHx
      memory:                                  # Additional memory available in MyHardware
        - name: Ext-Flash                      # Identifier
        - access: rx                           # access permission 
        - start: 0x40000000        
        - size: 0x200000
        - algorithm: Flash/Ext-Flash.flm       # Programming algorithm

Run and Debug Management

The CMSIS-Pack PDSC files contain information about device/board parameters and software components:

Flash algorithms 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 and System Description Files that support more complex Cortex-A/R/M configurations.
CMSIS-SVD System View Description (SVD) files for viewing device peripherals.
CMSIS-View Software Component Viewer Description (SCVD) 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 and the 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 (see Adding Memory).
ToDo: Additional images that should be loaded.
ToDo: Device configuration information.
ToDo: Access information for protected debug ports (i.e. encryption keys).

`<target-name>.cbuild-run.yml`

The <target-name>.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 <target-name>.cbuild-run.yml file provides access to PDSC information and the build output of one target. It also exports the Debug Access Sequences.

Run and Debug Information Management

The <solution-name>+<target-name>.cbuild-run.yml file represents a context-set of a solution.

Content of <target-name>.cbuild-run.yml:

cbuild-run:
  generated-by: csolution version 2.7.0
  solution: CubeMX.csolution.yml
  target-type: MyBoard_ROM
  compiler: AC6
  device: STMicroelectronics::STM32U585AIIx
  device-pack: Keil::STM32U5xx_DFP@3.0.0
  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:
      ...     
    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/<sdf> # 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.

>programmer --csolution MyHardware.cbuild-run.yml

Experimental Features

Resource Management

resources:

Example <solution-name>+<target-name>.regions.h file