Pack Creation

This chapter describes how to create software packs and explains the tools packchk (software pack verification) and svdconv (SVD file converter).

Pack Creation Tools

The following tools support the creation of Software Packs in CMSIS-Pack format:

Tool	Description
packchk	Pack Validation: installs and manages software packs in the local development environment.
svdconv	SVD Check / Convert: validate and/or convert System View Description (SVD) files.

Scripts

Several tools and scripts help to automate the pack creation.

Hands-on Tutorials

These scripts are in several hands-on tutorials.

Hands-on Tutorial	Description
DFP-Pack-HandsOn	Explains the structure and creation of a Device Family Pack (DFP).
BSP-Pack-HandsOn	Explains the structure and creation of a Board Support Pack (BSP).
SW-Pack-HandsOn	Explains the steps to create a simple software pack using the Open-CMSIS-Pack technology.
Create-Scaleable-SW	Explains how to structure complex middleware stacks.

Hints for Pack Creation

• Use C startup files that allows to use a DFP with any toolchain.
• For elements use a brief description text with less than 128 characters to explain the purpose. When possible link to documentation with detailed information.
  • Example: A component Device:HAL:ENET should not have description ENET HAL Driver, use Ethernet HAL driver instead.
• Consider adding project templates to help get started with more complex projects.
  • This is useful when devices are are configured using generators or provide multiple linker scripts (i.e. RAM/ROM execution).
• To distribute toolchain agnostic examples as part of packs:
  • Consider to use select-compiler to make projects toolchain independent.
  • To avoid that examples need updates with every pack release, specify the minium pack version required.
  • Use CI workflows to validate that projects compile correctly.
• Add an overview.md file that describes the overall usage of the software pack. These files are displayed on www.keil.arm.com/packs and index by Web search engines.

Project Examples

Project examples help to get started with new devices, boards, and middleware software components. The CMSIS-Pack format supports therefore different types of project examples:

• Template Projects are stub projects that help to get started. Some software packs may contain device specific templates.
• Examples are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals.
• Reference Applications are hardware agnostic project examples that required layers to add the hardware abstraction of a target (typically a board).

In addition packs may contain:

• Layers are pre-configured software components or source code that can be shared across multiple projects.
• Code Templates are stub source files for middleware components that can be incorporated into user code.

The picture below shows the different packs that are used to publish project examples. These examples are available for software developers on web pages and can be directly accessed from IDEs that are for example enabled with the VS Code Arm CMSIS Solution extension.

The following section explains how the different types of project examples are structured and registered within a CMSIS-Pack.

Support Multiple Compilers

To make project examples independent of a specific compiler toolchain, the *.csolution.yml file should include the select-compiler: node with a list of tested compilers. When a user or IDE starts such an example, the compiler: node that selects the compiler gets added.

Example:

solution:
  description: <brief description of the project example>
  created-for: CMSIS-Toolbox@2.6.0
  cdefault:

  select-compiler:  # list of tested compilers that can be selected
    - compiler: AC6
    - compiler: GCC
    - compiler: IAR
    - compiler: CLANG
      :

Related Examples

The *.csolution.yml file may contain several related projects that share the same target-types: and build-types:.

Example:

solution:
      :
  projects:
    - project: BSD_Server/BSD_Server.cproject.yml
    - project: FTP_Server/FTP_Server.cproject.yml
    - project: HTTP_Server/HTTP_Server.cproject.yml

Template Projects

A template project does not define a device: or 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: contains a Name that may be replaced by a descriptive target name.

Simple Template:

A simple template only defines one target.

solution:
      :
  target-types:
    - type: Name
#     board:            # added during creation of solution
#     device:           # added during creation of solution
      :

Multi-Target Template:

A multi-target template may contain different configurations for the same target, for example a configuration that executes from ROM and another that executes from RAM. The example below shows how this could be achieved using variables:.

solution:
      :
  target-types:
    - type: Name-ROM
#     board:           # added during creation of solution
#     device:          # added during creation of solution
      variables:
        - regions_header: path/region_ROM.h 

    - type: Name-RAM
#     board:           # added during creation of solution
#     device:          # added during creation of solution
      variables:
        - regions_header: path/region_RAM.h 
      :

In the example above, projects can use the linker: node in the *.cproject.yml file to reference the regions header file of the selected target.

project:

  linker:
    - regions:  $regions_header$

Register Template in PDSC File:

Templates are published using the <csolution> element in the PDSC file. Device-specific Templates should be part of the DFP. Board-specific templates should be part of the BSP.

  <csolution> 
    <template name="Simple Device project" path="/device/Simple" file="Simple.csolution.yml" condition="Device_Spec">
      <description>Single-core project with empty main function configured for device</description>
    </template>
    <template name="Simple Board project" path="/board/Simple" file="Simple.csolution.yml" condition="Board_Spec">
      <description>Single-core project with empty main function configured for board</description>
    </template>
  </csolution>

Examples

Examples are complete projects that typically run on a board. They should therefore specify a target-type with board: and list the packs: that are used, specifically the DFP and BSP.

To minimize maintenance of Examples that are part of a pack, consider these rules:

• IMPORTANT: Store all files that are part of the ./RTE directory. These files store configuration and are important for PLM.
• Use select-compiler: when the Example works with several toolchains. Do not specify compiler:.
• Specify minimum pack version. Do not store *.cbuild-pack.yml.
• The tool selects first target-type and first build-type when cbuild-set.yml is missing. For simple projects do not store *.cbuild-set.yml.
• For simple projects, rely on the cdefault.yml file that is provided with CMSIS-Toolbox.

Examples that work with several compiler toolchains should use select-compiler: and not define compiler: explicit. The compiler: node of the available toolchain is added when the Example is loaded into the IDE.

When minimum pack versions are specified, the semantic versioning of packs should ensure that newer pack versions work also. As the *.cbuild-pack.yml file fixes pack versions, this file should be not stored in the pack.

Examples may contain in the *.csolution.yml file multiple related projects that for example cover different aspects of a peripheral or middleware. For such Examples it is not required to store the *.cbuild-set.yml file as the tools select the first target-type and build-type of the *.csolution.yml file.

Examples that do not require special compiler controls may rely on the cdefault.yml file that is provided with CMSIS-Toolbox as this file contains reasonable default settings. For more complex Examples, provide a local copy of the cdefault.yml file in the same directory as the *.csolution.yml file.

Refer to Toolchain Agnostic Project for further information.

csolution.yml file of an Example:

solution:
# Optional: Add a brief description line (recommendation less than 128 characters)
  description: Example that shows the usage of Fault component on an Cortex-M33 with TrustZone

  created-for: CMSIS-Toolbox@2.6.0          # minimum CMSIS-Toolbox version, newer versions will work also
  cdefault:

  select-compiler:
    - compiler: GCC               # GCC is supported
    - compiler: AC6               # AC6 is supported
    - compiler: IAR               # IAR is supported

  packs:
    - pack: Keil::STM32U5xx_DFP@^2.1.0      # minimum compatible pack version
    - pack: Keil::B-U585I-IOT02A_BSP@^1.0.0

  target-types:
    - type: B-U585I-IOT02A
      board: STMicroelectronics::B-U585I-IOT02A
      device: STMicroelectronics::STM32U585AIIx

  build-types:
    - type: Debug
      debug: on
      optimize: debug

    - type: Release
      debug: off
      optimize: balanced

  projects:
    - project: ./Secure/Fault_S.cproject.yml
    - project: ./NonSecure/Fault_NS.cproject.yml

Register Examples in PDSC File:

Examples can be part of any pack and are published using the <examples> element in the PDSC file. Note that it is possible to register multiple project formats to support different tool environments.

  <examples>
    <example name="Fault example" folder="Examples/Fault/B-U585I-IOT02A" doc="README.md">
      <description>Example that shows the usage of Fault component on an Cortex-M33 with TrustZone</description>
      <board name="B-U585I-IOT02A" vendor="STMicroelectronics"/>
      <project>
        <environment name="csolution" load="Fault.csolution.yml"/>
        <environment name="uv" load="Fault.uvmpw"/>
      </project>
    </example>
  </examples>

Reference Applications

Reference applications can run on many different target hardware boards. Similar to template projects the device: and board: along with the required DFP and BSP pack: is not specified in the *.csolution.yml file.

solution:
  description: IPv4/IPv6 Network examples
  created-for: CMSIS-Toolbox@2.6.0
  cdefault:

  select-compiler:  # list of tested compilers that can be selected
    - compiler: AC6
    - compiler: GCC
    - compiler: IAR
    - compiler: CLANG

  target-types:
    - type: Name
#     board:           # added during creation of solution
#     variables:
#       - Board-Layer: <board_layer>.clayer.yml

Register Reference Applications in PDSC File:

Reference Applications are typically part of a middleware software pack and publish using the <examples> element in the PDSC file. The difference to examples is that no <board> element is used as the reference application is hardware agnostic.

  <examples>
    </example>
    <example name="Network" doc="README.md" folder="Examples/Network">
      <description>MDK-Middleware: IPv4/IPv6 Client and Server applications via Ethernet</description>
      <project>
        <environment name="csolution" load="Network.csolution.yml"/>
      </project>
    </example>

Layers

Layers with connections are used to by Reference Applications to target hardware. These layers are added when a reference application is configured for a board:, typically in the IDE.

Register Layers in PDSC File:

Layers are part of a BSP and published using the <csolution> element in the PDSC file.

  <csolution>
    <clayer type="Board" path="Layers/Default" file="Board.clayer.yml" copy-to="Board/MyBoard" condition="Board-Spec"/>
  </csolution>

Code Templates

Code templates are part of the components files in the PDSC file and can be manually added by the user to a software project. Code templates show how a software component is used and the source code can be directly adapted to the requirements of the application program.

Register Code Templates in PDSC File:

Code Templates are part of a software component and published using the <components> element using attr="template" in the PDSC file.

  <component Cgroup="Socket" Csub="UDP" condition="Network Interface">
    :
    <files>
      <file category="doc"    name="Documentation/html/Network/group__netUDP__Func.html"/>
      <file category="header" name="Components/Network/Config/Net_Config_UDP.h" attr="config" version="5.1.1"/>
      <file category="source" name="Components/Network/Template/UDP_Socket.c" attr="template" select="UDP Socket"/>
      <!-- Library source files -->
      <file category="source" name="Components/Network/Source/net_udp.c"/>
    </files>

Pack Generation

Packs should be generated using scripts. Several scripts are available on github.com/open-cmsis-pack:

• gen-pack is library for scripts creating software packs.
• gen-pack-action is a GitHub workflow action generating documentation and software packs.

To start a pack, add a *.PDSC file with meta information and configure the above scripts.

Pack Examples

Several pack examples available on github.com/Open-CMSIS-Pack exemplify how to create software packs. Other packs that are a good reference are the various Arm CMSIS packs or the MDK Middleware pack. The source of these packs is available on Github/Arm-software.