CMSIS-Pack: /package/components element

| CMSIS-Pack Version 1.5.0 Delivery Mechanism for Software Packs

- Main Page
- Usage and Description

All Pages
/package/components element

The element /package/components describes software components contained in the PACK. A component lists the files that belong to a component 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 component must have a Class (Cclass=), a Group (Cgroup=), and a Version (Cversion=) which is used to identify the component. Optionally a component may have a Sub-Group (Csub=) and Variant (Cvariant=) to add further categories. The Class, Group, Sub-Group, Variant and Version is used together with the vendor specified by the PACK, to identify a component. A component vendor must ensure that the combination Class, Group, Sub-Group and Version is unique and not used by multiple components.

Example

<package>
...
<components>
<!-- component has dependency described by "CMSIS Core" condition -->
<component Cclass="CMSIS" Cgroup="Core" Cversion="3.1.0" condition="CMSIS Core">
<description>CMSIS-Core (Cortex-M) for Cortex-M, SC000, and SC300 processor.</description>
<files>
<!-- CPU independent -->
<file category="doc" name="CMSIS/Documentation/Core/html/index.html"/>
<file category="header" name="CMSIS/Include/core_cmFunc.h"/>
<file category="header" name="CMSIS/Include/core_cmInstr.h"/>
<!-- CPU dependent -->
<file category="header" condition="CM0" name="CMSIS/Include/core_cm0.h"/>
<file category="header" condition="CM0+" name="CMSIS/Include/core_cm0plus.h"/>
<file category="header" condition="CM3" name="CMSIS/Include/core_cm3.h"/>
<file category="header" condition="CM4" name="CMSIS/Include/core_cm4.h"/>
<file category="header" condition="CM4" name="CMSIS/Include/core_cm4_simd.h"/>
<file category="header" condition="SC000" name="CMSIS/Include/core_sc000.h"/>
<file category="header" condition="SC300" name="CMSIS/Include/core_sc300.h"/>
</files>
</component>
<component Cclass="CMSIS" Cgroup="DSP" Cversion="1.1.0" condition="CMSIS DSP">
<description>CMSIS-DSP Library for Cortex-M0, Cortex-M3 and Cortex-M4 as well as SC000 and SC300 processor based devices</description>
<files>
<!-- CPU independent -->
<file category="doc" name="CMSIS/Documentation/DSP/html/index.html"/>
<file category="header" name="CMSIS/Include/arm_math.h"/>
<!-- CPU and Compiler dependent -->
<!-- ARMCC -->
<file category="library" condition="CM0_LE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM0l_math.lib"/>
<file category="library" condition="CM0_BE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM0b_math.lib"/>
<file category="library" condition="CM3_LE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM3l_math.lib"/>
<file category="library" condition="CM3_BE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM3b_math.lib"/>
<file category="library" condition="CM4_LE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM4l_math.lib"/>
<file category="library" condition="CM4_BE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM4b_math.lib"/>
<file category="library" condition="CM4F_LE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM4lf_math.lib"/>
<file category="library" condition="CM4F_BE_ARMCC" name="CMSIS/Lib/ARM/arm_cortexM4bf_math.lib"/>
<!-- GCC -->
<file category="library" condition="CM0_LE_GCC" name="CMSIS/Lib/GCC/libarm_cortexM0l_math.a"/>
<file category="library" condition="CM3_LE_GCC" name="CMSIS/Lib/GCC/libarm_cortexM3l_math.a"/>
<file category="library" condition="CM4_LE_GCC" name="CMSIS/Lib/GCC/libarm_cortexM4l_math.a"/>
<file category="library" condition="CM4F_LE_GCC" name="CMSIS/Lib/GCC/libarm_cortexM4lf_math.a"/>
<!-- G++ -->
<file category="library" condition="CM0_LE_G++" name="CMSIS/Lib/G++/libarm_cortexM0l_math.a"/>
<file category="library" condition="CM3_LE_G++" name="CMSIS/Lib/G++/libarm_cortexM3l_math.a"/>
<file category="library" condition="CM4_LE_G++" name="CMSIS/Lib/G++/libarm_cortexM4l_math.a"/>
<file category="library" condition="CM4F_LE_G++" name="CMSIS/Lib/G++/libarm_cortexM4lf_math.a"/>
</files>
</component>
<component condition="ARM_CM0" Cclass="Device" Cgroup="Startup" Cversion="3.1.1">
<description>System Startup for generic ARM Cortex-M0 device</description>
<files>
<file category="header" name="Device/ARM/ARMCM0/Include/ARMCM0.h"/>
<file category="header" name="Device/ARM/ARMCM0/Include/system_ARMCM0.h"/>
<file category="source" condition="Compiler_ARM" name="Device/ARM/ARMCM0/Source/ARM/startup_ARMCM0.s"/>
<file category="source" condition="Compiler_GCC" name="Device/ARM/ARMCM0/Source/GCC/startup_ARMCM0.S"/>
<file category="source" condition="Compiler_G++" name="Device/ARM/ARMCM0/Source/G++/startup_ARMCM0.S"/>
<file category="source" condition="Compiler_IAR" name="Device/ARM/ARMCM0/Source/IAR/startup_ARMCM0.s"/>
<file category="source" name="Device/ARM/ARMCM0/Source/system_ARMCM0.c" attr="template"/>
</files>
</component>
</components>
...
</package>

# Component Bundle

In case multiple inter-dependent components that belong to the same Cclass form part of a solution, these can be grouped into a bundle. A bundle specifies identical attributes Cclass, Cversion and optionally Cgroup and Cvendor for several components. Components within a bundle inherit these attributes set by the bundle and cannot alter these attributes. Bundles ensure consistency of attributes across multiple interworking components and restrict the mix and match of components within a Cclass from different Software Packs.

An example of a bundle is shown in the Create a BSP Bundle section where the bundle is used to deliver board support files for a certain development platform.

# Component Files

The files of a Software Component will be used in development tool-chains to build an application. Depending on the attributes, the files are handled differently:

- Libraries, source, and header files without an attribute cannot be modified. These files are stored in the folders of the Software Component and get directly included from this location into the project.
- Source and header files that have the attribute `"config"` are copied to the project so that they can be edited by the user and tailored to the needs of the application. If a Software Component allows multiple instances of files, they can be copied multiple times to a project and will get a suffix _%Instance% (see Component Instances). Please note that header files that are used with the attribute `"config"` need to be stored separately from other header files (for example in an extra directory) to avoid that due to the include path search order of the compiler, the unmodified header file in the pack repository is found first and used by the compiler (creating unexpected results).
- Source and header files that have the attribute `"template"` are part of User Code Templates and can be added to a project manually by the user.

The following image shows the dependency between the attribute and the display in a development environment:

Display of files of a Software Component in development tools

# Component Instances

Modern microcontrollers often have multiple instances of the same peripheral interface (for example UART, SPI, USB, etc.). To be able to have separate configuration files for each of these instances, Software Components can have multiple instances as well. The attribute maxInstances declares the maximum number of instances that can be used in a project for a certain Software Component.

If the user selects for example two instances of the same component, all files with the attribute `"config"` will be copied twice to the project. The name of the component (for example `config_mylib.h`) will be expanded with an `_%Instance%` number:

1. Instance: config_mylib_0.h
2. Instance: config_mylib_1.h

The availability of instances in a project can be made public in the `RTE_Components.h` file. This can be used to check for the availability of a certain instance in the user application code:

<RTE_Components_h>
<!-- the following content goes into file 'RTE_Components.h' -->
#define RTE_FileSystem_Drive_NOR_%Instance% /* File System NOR Flash Drive %Instance% */
</RTE_Components_h>

Component instances in PDSC file and in development tools

# RTE_Components.h

The build environment should generate a C/C++ include file with the name RTE_Components.h that contains:

- The statements of the related <RTE_Components_h> element for all selected software components.
- The header file name specified in the <compile> element of the /package/devices element.

Example

The following example shows a sample content of a file RTE_Components.h. It contains the statements that are specified with the element RTE_Components_h of four software components.

/*
* 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 */

The typical usage of the RTE_Components.h file is in header files to control for example the inclusion of files that are related to other components for the same Software Pack.

#include "RTE_Components.h"
#ifdef RTE_Network_Interface_ETH_0 // generated when software component Network Interface ETH 0 is included
#include "Net_Config_ETH_0.h" // add the related configuration file for these component
#endif

# /package/components

Grouping element containing a choice of at least one bundle or component. No more than one element components can exist in a PACK.

Parent | Element Chain
--- | ---
package | /package
Attributes | Description | Type | Use
generator | Specifies the generator ID of the generator that has been used to generate all components within this section. | xs:string | optional
Child Elements | Description | Type | Occurrence
bundle | Grouping element for a collection of inter-operable components belonging to the same Cclass | ComponentType | 1..*
component | Grouping element for components | ComponentType | 1..*

# /package/components/bundle

A bundle describes a named collection of inter-operable components of the identical Cvendor, Cclass and Cversion. Components enclosed in a bundle must not specify any of the following attributes Cvendor, Cclass and Cversion.

Parent | Element Chain
--- | ---
components | /package/components
Attributes | Description | Type | Use
Cbundle | Defines the name of the bundle. It becomes a mandatory part of the component ID. | xs:string | required
Cvendor | Defines the component vendor all components of this bundle belong to. If not explicitly set the component vendor is derived from the package vendor. The component vendor is a mandatory part of the component ID. | xs:string | optional
Cclass | Defines the component class to which all components in the bundle belong. Is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Classes. | CclassType | required
Cversion | Defines the version of all components contained in the bundle. The component version is a mandatory part of the component ID. The version format is described in Version Type. | VersionType | required
Child Elements | Description | Type | Occurrence
description | Brief description of the bundle | xs:string | 1..1
doc | Documentation for the bundle: 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. | xs:string | 1..1
component | Grouping element for components. | ComponentType | 1..*

# /package/components/.../component

A component describes a collection of files (source, header, configuration, library) that can be versioned and categorized.

Parent | Element Chain
--- | ---
components | /package/components
components | /package/components/bundle
Attributes | Description | Type | Use
Cvendor | Defines the component vendor this component is shipped by. It is a mandatory part of the component ID and will be inherited from the package vendor if not specified. Must not be specified for a component within a bundle. | xs:string | optional
Cclass | Defines the component class to which the component belongs. This is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Classes. Must not be specified for a component within a bundle. | CclassType | required
Cgroup | Defines the component group to whoch the component belongs. Is a mandatory part of the component ID. Predefined values can be used as listed in the table Component Groups. | CgroupType | required
Csub | Defines the component subgroup. Is an optional part of the component ID. The type is described in Component Subgroups. | CsubType | optional
Cvariant | Defines a variant of a component. Is an optional part of the component ID. The variant specifier is a brief string (for example: release, debug). | xs:string [3..32] | optional
Cversion | Defines the version of this component. Is a mandatory part of the component ID. The version format is described in Version Type. Must not be specified for a component within a bundle. | VersionType | required
Capiversion | For components that are based on an API, it defines the version of the API used by this component. It ensures that the API header file with this or any higher version is acceptable for using that component. The version format is described in Version Type. | VersionType | optional
condition | Enter the id of a condition. The component is available and can be selected when the condition is true. | xs:string | optional
maxInstances | Maximum allowed instances of a component in a project. Default is 1 for one instance. The range is [1..10]. | xs:integer | optional
isDefaultVariant | Identifies this component variant to be the preferred variant for tool driven selection [Version 1.4.0] | xs:boolean | optional
generator | This links the component with a generator description located in the same file. If this component is selected by the run time configuration, the tool will test whether the configured gpdsc file does already exist or not. If the file is not present, then the command specified by the referenced generator section, will be invoked. If the gpdsc file already exists it will be included into the project | xs:string | optional
Child Elements | Description | Type | Occurrence
deprecated | When set to true, then the component is deprecated and no longer maintained. Default is false to indicate an actively maintained component. | xs:boolean | 0..1
description | Brief description of the component. | xs:string | 1..1
RTE_Components_h | Source code that is copied into the file RTE_Components.h when the component is included into a software project. | xs:string | 0..1
files | Grouping element for all files that are part of this component. | group | 1

Component Subgroups

Component Subgroups are specified by the element Csub, and create subcategories within Component Classes (Cclass) and Component Groups (Cgroup). A Csub name is of type xs:string with a length between 3 and 32 characters. No Csub names have been predefined.

Subgroups exists in the elements:

- /package/conditions/condition/accept
- /package/conditions/condition/require
- /package/conditions/condition/deny
- /package/components/.../component
- /package/examples/example/attributes/component

Example:

<... Csub="MyRTOS" Cgroup="RTOS" Cclass="CMSIS"...>

# /package/.../files

The group files can appear in various PACK elements. This group is the frame for defining individual file properties.

Example:

<package>
...
<apis>
<api Cclass="Device" Cgroup="Driver UART" exclusive="0">
<files>
...
</files>
</api>
</apis>
...
<components>
<component Cclass="Device" Cgroup="Startup" Cversion="3.1.1" >
<files>
...
</files>
</component>
</components>
...
</package>

Parents | Element Chain
--- | ---
api | /package/apis/api
component | /package/components/component
component | /package/components/bundle/component
Child Elements | Description | Type | Occurrence
file | Frame for the individual file of a component. | group | 1..*

# /package/.../files/file

The element file is the mechanism to attach files to the software. The file purpose is defined through the category attribute. The name attribute identifies the file.

Example:

<package>
...
<apis>
<api Cclass="Device" Cgroup="Driver UART" exclusive="0">
<files>
<file category="doc" name="Driver/Doc/UART/html/index.html"/>
<file category="header" name="Driver/Include/Driver_UART.h"/>
</files>
</api>
</apis>
...
<components>
<component Cclass="Device" Cgroup="Startup" Cversion="3.1.1" >
<files>
<file category="header" name="Device/Include/system_stm32f2xx.h"/>
<file category="source" name="Device/Source/ARM/startup_stm32f2xx.s" attr="template"/>
<file category="source" name="Device/Source/system_stm32f2xx.c" attr="template"/>
</files>
</component>
</components>
...
</package>

Parents | Element Chain
--- | ---
files | /package/apis/api/files
files | /package/components/component/files
files | /package/components/bundle/component/files
files | /package/generators/generator/project_files
Attributes | Description | Type | Use
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. | xs:string | required
category | Defines the purpose of the file. Select the predefined value as listed in the table File Categories. | FileCategoryEnum | required
attr | Defines the special use and handling of a file. Select a predefined value as defined in the table File Attributes. | FileAttributeEnum | optional
condition | Enter the identifier (attribute id) of a condition. The element is used if the condition resolves to true. If the condition resolves to false, then the element will be ignored. For example, a library might be specific for a certain toolchain or processor instruction set. | xs:string | optional
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. | xs:string | optional
src | Path information. The path is specified relative to the PACK Description File. If category is set to library, then the src string can contain a list of directory paths separated by semicolons. A debugger will search those paths for locating the source files of the modules archived in the library supporting the debugging of library code. | xs:string | optional
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. The version format is described in Version Type. | VersionType | optional

Table: File Attributes

The file attribute defines the special handling in the project when being used as configuration, template, or interface file. The table lists the values available as a file attribute.

attr= | Description
--- | ---
config | The file is a configuration file of the component. It is expected that only configuration options are modified. The file is managed as part of the component, as a project-specific file typically copied into the component section of the project.
template | The file is used as a source code template file. It is expected to be edited and extended by the software developer. The file can be copied into a user section of the project.

Note
  Header files with the attribute config must be located in a directory within the pack that is not otherwise specified as an "include folder" of this or any other component's files of the category "header" or "include". For example:

      <file category="header"  name="src/config/user_config.h" attr="config" version="1.0.0" />

  Config files are copied into the project folder and are adopted specifically for that project. Due to the include path search order of the compiler, chances exist that the unmodified header file in the pack repository is found first and used by the compiler (creating unexpected results).

Table: File Categories

File category types define the use of component files within the application. Typically, these files are added to the project and processed by the build tools.

File categories are used in the following elements:

- /package/.../files/file
- /package/generators/generator/files/file
- /package/create/project/select/component/file

The table lists the predefined values for a file category.

category= | Description
--- | ---
doc | Documentation
header | Header file used in the component. Sets an include file path.
include | Sets an include file path.
library | Library file
object | Object file that can be added to the application
source | Startup-, system-, and other C/C++, assembler, etc. source files
sourceC | C source file
sourceCpp | C++ source file
sourceAsm | Assembly source file
linkerScript | linker script file that can be selected by tool-chains
utility | a command line tool that can be configured for pre- or post-processing during the build process
image | Files of image type are marked for special processing into a File System Image embedded into the application. This category requires the attr being set to template.
other | Other file types not covered in the list above