Overview

The CMSIS-Pack format is used to deliver a software package and is aimed to be scalable for future requirements. It provides a management process and supports a tool independent distribution for:

• Device Support for tool chains and software applications to target a specific device:
  • Information about the processor and it's features.
  • C and assembly files for the device startup and access to the memory mapped peripheral registers.
  • Parameters, technical information, and data sheets about the device family and the specific devices.
  • Device description and available peripherals.
  • Memory layout of internal and external RAM and ROM address ranges.
  • Flash algorithms for programming the device.
  • Debug and trace configurations as well as System View Description files for device specific display of the memory mapped peripheral registers.
• Board Support for rapid development in the prototyping stage:
  • Information about the development board and it's features.
  • Parameters, technical information, and data sheets about the board, the mounted microcontroller and peripheral devices.
  • Drivers for on-board peripheral devices
• Software Components simplify the re-use of software and the management of 3rd party software. They contain:
  • A collection of source modules, header and configuration files as well as libraries.
  • Documentation of the software, including features and APIs.
• Application Programming Interfaces specify one or more APIs for software components that are part of another Software Pack.
• Example Projects can be used as a reference and starting point for similar applications. They contain:
  • Fully defined application projects that work out of the box in the specified build and debug environments.
  • Documentation about the purpose of the example, how to build, configure and execute the application.
• User Code Templates help to understand the basic concepts of a software component better and to give the user a good starting point for implementing his application.

Software Components

A software component encapsulates a set of related functions. Software components can contain C/C++ source files, object code, assembler files, header files, or libraries. The interfaces of software components should be defined with API Interface to make them substitutable by other compatible components at design time. In addition, CMSIS software components should contain documentation for the software component. They may provide user code templates that give a starting point for the application developer, and can have optional debug view descriptions for debuggers.

CMSIS software components can also refer to multiple interfaces of other software components. This could be also a hardware abstraction layer for a device peripheral.

Configuration files contain application specific parameters for a software component. These files are typically copied to the user project workspace; all other files are not modified by the user and can remain in a separate location which avoids that a project workspace is polluted by many source files that should be considered as “black-box” elements by the application programmer.

Technical Details

A component lists the files that belong to it and that are relevant for a project. The component itself or each individual file may refer to a condition that must resolve to true; if it is false, the component or file is not applicable in the given context.

Each software component must have the following attributes that are used to identify the component:

• Component Class (Cclass): A component class which is a top-level component name, for example CMSIS, Device, File System
• Component Group (Cgroup): A component group name, for example CMSIS:RTOS, Device:Startup, File System:CORE
• Component Version (Cversion): the version number of the software component.

Optionally, a software component may have additional attributes:

• Component Sub-Group (Csub): A component sub-group that is used when multiple compatible implementations of a component are be available. For example CMSIS:RTOS:MyRTOS, Device:Driver USBD:Full-speed
• Component Variant (Cvariant): A variant of the software component is typically used when the same implementation has multiple top-level configurations, like debug and release.
• Component Vendor (Cvendor): the supplier of the software component.
• Cbundle: allows to combine multiple software components into a software bundle. For example if a network stack is used, all interfaces must match to that component.
• Instances: allow to deploy multiple instances of a software component. Each instance can have a separate configuration file.

The Cclass, Cgroup, Csub, Cvariant and Cversion attributes are used together with the vendor specified by the pack to identify a component. A component vendor must ensure that the combination Cclass, Cgroup, Csub and Cversion is unique and not used by multiple components within the same Pack. Advertise a set of attributes to be used by other software components using the /package/taxonomy element.

For a list of established Cclasses, refer to Software Component Cclasses.

In case multiple interdependent components (belonging to the same Cclass) form part of a solution, these can be grouped in a so called bundle.

Use the following syntax to reference to software components and APIs:
<Vendor>::<Cclass>:<Cgroup>:<Csub>

Examples:

• ::CMSIS:RTOS (API) - the CMSIS-RTOS API.
• ARM::CMSIS:DSP - the CMSIS-DSP Library.
• ::File System:Drive:NOR - the NOR Flash Drive of a file system.

Here is an example for the display of software components in a development tool:

Display of a software component in development tools

Software Component Files

Each software component consists of a certain number of files. Each file has at least the following attributes:

• name: File path, file name, and file extension in the format path/name.extension. The file path is relative to the root directory of the Pack.
• category: Defines the purpose of the file. Select the predefined value as listed in the table File Categories.

Optionally, every file may have the following attributes:

• attr: Defines the special use and handling of a file. Select a predefined value as defined in the table File Attributes.
• condition: Enter the identifier (attribute id) of a condition. The element is used if the condition resolves to true.
• select: Brief description and purpose of the file. The select attribute is required when attr is set to template or interface. When multiple template files of a component have the same select string, they are treated as a single selectable template. This way, multiple template or interface files can be bundled.
• src: Path information. The path is specified relative to the Pack Description File (PDSC).
• version: File-specific version information. This is used particularly for files copied into the project workspace. Before a file gets copied, a version check avoids unnecessary copy actions. If a file does not have a version, then the component version is used.

File naming

It is good practice to name software component files uniquely. This is especially important for user configuration files that are copied into a project. The CMSIS-Pack run-time environment copies configuration files by <Cclass> into the directory structure. For example, ./RTE/BSP stores all user editable files of the <Cclass> BSP. If the file name is not unique, clashes might occur with other software components of the same <Cclass> (for example when you name the configuration file user_config.h).

Recommended configuration file naming is as follows: <vendor>_<unique_component>_config

Examples

• MyVendor_MyBSP_config.h
• MyVendor_MyNetworkStack_config.h

Note

Please be aware that you also need to make sure that your configuration files need to be uniquely named and versioned if your software component consists of <Cvariants> that differ in the configuration files. Otherwise, it might happen that your toolchain is not able to resolve correctly and users might end up with unconfigurable components, especially when they change the variant while developing the application.

References to other software components

Software components can reference other software components (either within the same pack or in other packs) using conditions:

A condition describes dependencies on:

• a specific device
• a certain processor
• tool attributes
• the presence of other components (pcak internal or external)

Conditions can be used to ensure that specific software components are either present in the system or can prevent that illegal combinations of software components are chosen by the user.

Conditions are used to define AND/OR rules that make components conditional and therefore only available under certain circumstances, for example for specific devices or processors. Conditions are also used to express dependencies between software components.

Each condition has an id that is unique within the scope of a the PDSC file. An id can be referenced in the condition attribute of components, APIs, examples, files and other conditions. All attributes set in a accept, require, or deny element must resolve to true for the element to become true. A condition becomes true when:

• At least one accept element is true, AND
• all require elements are true, AND
• no deny element is true.

If a condition resolves to false during processing, the respective element will be ignored.

Requirements

Packs can require other packs to be available (and can even ask for a specific version of a pack):

There are three different requirement types:

• The packages section lists CMSIS Packs that have been used to configure the project. This includes the specification of a version range to ensure compatibility. If no version is provided, the latest installed version is used. If not yet installed, the latest available version will be installed before resolving the configuration.
• The compilers section specifies the toolchains that are supported by this example. The required compiler version is specified using the version element. If no compiler is specified, it is assumed that any toolchain will work.
• The languages section allows to specify requirements regarding the programming language, for example C99 standard. If no language requirements are set, ANSI C is assumed.

Central API definition

The CMSIS-Pack system allows a central API definition that shares header file information and documentation of an API interface.

This single API interface definition ensures consistency when it is used across multiple implementations that consume the interface. The API interface definition can be distributed separately or as part of the software component that consumes this interface.

An example is the CMSIS-Driver pack that contains various hardware interface drivers that all compatible with the CMSIS-Driver APIs (that are published in the CMSIS Pack).

Inventory header file: RTE_Components.h

Frequently, the behavior or features of a software component depend on the presence of other software components in the application. For example, a network stack can interface to Ethernet or serial PPP (UART). Depending on the presence of interface components, the implementation may behave differently.

To simplify application configuration, the file RTE_Components.h is generated before the project build step. It contains the inventory of all selected components. For each selected software component, it contains #define statements that are specified by the component meta data. The following example shows an RTE_Components.h file:

/* 
   Auto generated Run-Time-Environment Component Configuration File 
          * Do not modify ! *** 
 */ 
 
#ifndef RTE_COMPONENTS_H 
#define RTE_COMPONENTS_H 
 
/* 
   Define the Device Header File: 
 */ 
 
#define CMSIS_device_header "stm32f10x.h" 
 
#define RTE_Network_Interface_ETH_0     /* Network Interface ETH 0 */ 
#define RTE_Network_Socket_BSD          /* Network Socket BSD */ 
#define RTE_Network_Socket_TCP          /* Network Socket TCP */ 
#define RTE_Network_Socket_UDP          /* Network Socket UDP */ 
 
#endif /* RTE_COMPONENTS_H */

Use this information in other header files to control features that depend on the inclusion to other software components. For example:

#include "RTE_Components.h" 
#ifdef  RTE_Network_Interface_ETH_0  // if component is included 
#include "Net_Config_ETH_0.h"        // add related configuration file 
#endif

Combining software components

When using software components, you can use the conditions to automatically resolve dependencies on other components. Use this to combine components for a project in a certain way, while combining them differently for another project. In the following example, a network stack transfers data via Ethernet. The network stack requires a MAC and PHY to do this. The selected device from silicon vendor A that contains an on-chip MAC, thus only requiring a PHY to be selected:

Example with internal MAC

You can copy the project, select a different device from silicon vendor B for example and let the run-time environment manager do the exchange of the components. As the new devices do not have an on-chip MAC, you need to select a different component to fulfill the requirement for the network stack:

Example with external MAC and PHY

This reduces the development time drastically, as the developer does not need to care for the correct dependency between software components, but can concentrate on the implementation of his own application code.

Pack Conventions

A Software Pack is a collection of files located in directories that are archived in a file with the extension *.pack using the standard ZIP file format. The Pack Description file (PDSC) with the file extension *.pdsc contains the meta information, describing the content of a pack based on XML. The PDSC file must be:

• included in the Software Pack
• located in the base folder of the archive
• compliant with the Software Pack file naming convention

Note

• The base folder is defined to be the root folder './' of a zip archive and it is imperative that the whole Software Pack only contains a single PDSC file.
• Future tools shall support this case: if the PDSC file is located in an immediate subdirectory, then the subdirectory becomes the base folder. The Software Pack is installed as if the subdirectory does not exist. All files and directories located in the root folder are ignored and do not get installed.

Pack File Name

A Software Pack must have a unique filename. Therefore it is constructed from vendor, packname and version and the file extension *.pack.

<vendor>.<name>.<version>.pack.

Where:

• <vendor> is the name of the supplier or vendor of the Software Pack.
• <name> is the name of the Software Pack. All packs that are published by a vendor must have a unique pack name.
• <release version="X.Y.Z">specifies the version number of the release for the Software Pack.
• .pack is the file extension identifying a Software Pack.

Note

• The XML elements <vendor>, <name>, and the version attribute of the <release> are specified in the PDSC file. PDSC, Pack filenames are case sensitive and need to match exactly.
• <vendor> and <name> must not contain spaces.
• The PDSC file needs to reside in the base folder of the Pack. All file references are relative to the location of the PDSC file.

Software Component Cclasses

If you add a software component in the PDSC file, you have to specify a component class (CClass), component group (Cgroup), and the component's version number (Cversion). For more information refer to Software Components.

If applicable, try to map the Cclass of your software component to one of the following predefined or already well established classes listed below. These Cclass names are pre-defined in the CMSIS pack using the taxonomy element.

Cclass	Description
Audio	Software components for audio processing
Board Support	Generic interfaces for evaluation and development boards
Board Part *	Drivers that support an external component available on an evaluation board
CMSIS	Common Microcontroller Software Interface Standard components
CMSIS Driver	Unified device drivers compliant to the CMSIS-Driver specification
Compiler	Arm Compiler software extensions
Data Exchange	Data exchange components or data formatter, for example JSON
Device	Startup and system setup components
Extension Board *	Drivers that support an extension boards or shield
File System*	File drive support and file system
Graphics*	Graphical libraries for user interfaces
IoT Client	IoT cloud client connectors
IoT Service	IoT specific services, i.e. device on-boarding
IoT Utility	IoT specific utilities, i.e. a socket interface
Network*	Network stack using Internet protocols
RTOS*	Real-time operating systems
Security*	Encryption for secure communication or storage
USB*	Universal Serial Bus stack
Utility	Generic software utility components

Classes with a * should always be used together with a bundle to avoid conflicts with other software components.

If you wish to standardize a new Cclass, please send an inquiry to cmsis.nosp@m.@arm.nosp@m..com or raise an issue on the public CMSIS GitHub development repository.