 |
Open-CMSIS-Pack
Version 1.7.45
Delivery Mechanism for Software Packs
|
|
Open-CMSIS-Pack
Version 1.7.45
Delivery Mechanism for Software Packs
|
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 bundle (Cbundle=), sub-group (Csub=) and variant (Cvariant=) to add further categories. A component is identified by the class/bundle, group, sub-group, variant and version information together with the vendor specified by the pack or explicitly specifying the (Cvendor=) for a component. The component vendor must ensure that the combination of class/bundle, group, sub-group, version, and variant is unique and not used by multiple components (after evaluating filter conditions).
Note: The selection of multiple variants of the same component is mutually exclusive and must not be supported by tools. Graphical user interfaces may use drop down boxes for selecting a component variant.
Example
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 component bundle is a named set of components that must share identical attributes for Cvendor and Cclass by introducing the attribute Cbundle, which becomes a mandatory part of the component ID. If the attribute Cvendor is not specified in the bundle element, the value is inherited from the pack level vendor element.
The attributes Cvendor, Cclass, Cbundle as well as Cversion are inherited by all component elements within a bundle section. Only the Cversion attribute can be redefined in the component elements.
Components of the same Cclass belonging to a different Cbundle shall not be selected concurrently. In this way bundles ensure interoperability across multiple components and restrict the mix and match of components within a Cclass.
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:
"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)."template" 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:
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:
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:
The build environment should generate a C/C++ include file with the name RTE_Components.h that contains:
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.
The RTE_Components.h file allows to create software that works with any supported device as it gives access to the CMSIS_device_header. The CMSIS_device_header reflects the current selected device and gives you for example access to the processor configuration. Refer to "Device Header File <device.h>" in CMSIS-Core(M) or CMSIS-Core(A) for more information.
Another 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.
The build environment shall generate a C/C++ header file with the name Pre_Include_Global.h from all selected components and add this file to the command line as a pre-include file for the build of all modules in the project. Note: the file shall be generated into the RTE/<target> subdirectory.
results in .../RTE/target_1/Pre_Include_Global.h:
No need to explicitly include this file as it is automatically added as pre-include into the build for all modules.
The build environment shall generate a C/C++ header file with the name Pre_Include_<Cclass>_<component>.h from the selected component and add this file to the command line as a pre-include file for the build of all modules of this component. The same is done for each component containing a "Pre_Include_Local_Component_h" element. Note: files shall be generated into the RTE/<target> subdirectory.
results in .../RTE/target_1/Pre_Include_Other_Alpha.h:
No need to explicitly include this file as it is automatically added as pre-include into the build for all modules of component Other:Alpha.
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. The components section must not be empty. At least one bundle or component is required. | ComponentType | 0..* |
| component | component description element. The components section must not be empty. At least one component or bundle is required. | ComponentType | 0..* |
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 component version inherited by 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. Note: components can redefine their version using the Cversion attribute of the component element. | VersionType | required |
| licenseSet | Reference to the licenseSet with the given identifier ID specified in the licenseSets section of the package description. A licenseSet describes one or more license files which in this case govern all components of this bundle. If the licenseSet is different for different components in the bundle, the licenseSet attribute is required to be assigned on a component level. | xs:string | optional |
| changelog | Reference to the changelog with the given identifier ID specified in the changelogs section of the package description. A changelog references a text file in the pack with a path relative to the pdsc containing changelog information for all components of this bundle. If the changelog files differ for the components in the bundle, the changelog attribute is required to be set on a component level. | xs:string | optional |
| Child Elements | Description | Type | Occurrence |
| description | Brief description of the bundle (maximum 256 characters, recommended 128 characters). | BriefDescType | 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..* |
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). Note: The selection of component variants is mutually exclusive. | xs:string [1..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. | VersionType | required |
| Capiversion | For components that are based on an API header files, it defines the version of the API used by this component. It ensures that the API header file with the same or 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 |
| custom | When set to true, the component requires a custom implementation. This attribute should suppress the automatic component resolver, so it requires always manual selection. | xs:boolean | 0..1 |
| 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 through an automated update algorithm [Version 1.4.0]. If in a new version of a component variants are introduced, the default variant is automatically selected if only the component without variant is specified. This variant is supposed to be the most compatible continuation of the previous component version. Note: It is the component vendor's responsibility to have only a single component variant having this attribute enabled. | 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 |
| licenseSet | Reference to the licenseSet with the given identifier ID specified in the licenseSets section of the package description. A licenseSet describes one or more license files that govern the component. | xs:string | optional |
| view | Defines the user view of this component. A component may be hidden, for example when it is managed by a generator. | ViewType | optional |
| changelog | Reference to the changelog with the given identifier ID specified in the changelogs section of the package description. A changelog references a text file in the pack with a path relative to the pdsc containing changelog information for the component. The content of the referenced changelog file is not required to be exclusively used for a single component. | 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 (maximum 256 characters, recommended 128 characters). | BriefDescType | 1..1 |
| RTE_Components_h | Source code that is copied into the file RTE_Components.h when the component is selected by the run time environment configuration. | xs:string | 0..1 |
| Pre_Include_Global_h | Source code that is copied into the file Pre_Include_Global_h when the component is selected by the run time environment configuration. | xs:string | 0..1 |
| Pre_Include_Local_Component_h | Source code that is copied into the file Pre_Include_Local_Component_h <Cclass>_<Component_name>.h when the component is selected by the run time environment configuration. | xs:string | 0..1 |
| files | Grouping element for all files that are part of this component. | group | 1 |
| extensions | Grouping element for all extensions concerning this component. | group | 1 |
| environments | Grouping element for all environments concerning this component. | group | 0..1 |
The ViewType defines the user view of a component in component selection windows (i.e. Manage Run-Time Environment or Manage Software Components) and command line tools for the component list command.
| ViewType | Description |
|---|---|
| always (default) | Component is always presented to the user. It appears in component selection windows and is listed as available component. |
| never | Component is never presented to the user as it contains supportive files, i.e. for a generator. However it can be explicitly requested by an user, i.e. with the component: node. |
| maskable | It is the choice of the tool to hide this component. A tool may offer an option to show such components. |
Examples:
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:
Example:
The group files can appear in various Pack elements. This group is the frame for defining individual file properties.
Example:
| 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..* |
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:
| 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 |
| path | for category="header" the path attribute explicitly can be used to specify the include path to be added to the commandline of the build tools, specifying an incomplete path. This way the include file requires the specification of the subdirectory (e.g. #include "sub_dir/includeFile.h") which can act as acting as namespace for header files which otherwise have the same name. | xs:string | optional |
| category | Defines the purpose of the file. Select the predefined value as listed in the table File Categories. | FileCategoryEnum | required |
| language | Defines the language of the file category source, header, include. Select one of the predefined value as listed in the table File Language Attribute. If not specified, a source file is identified based on known file extensions, header files and include paths will be applied for all tools. | FileLanguageAttributeType | optional |
| scope | Defines the visibility of header and include. Select one of the predefined value as listed in the table File Scope Attribute. If not specified, a header file or an include path is considered public. | FileScopeAttributeType | optional |
| 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. 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. The select attribute is optional for files with category header to indicate the usage of a header file. | 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 |
| public | Set publishing permissions for the documentation. If <public> is true, then the vendor gives permission to extract the documentation from the pack and publish it on a web-page. Links to web pages are assumed to be public. The default value is true. | xs:boolean | optional |
| projectpath | View location path for a file of component inside IDE project explorer view. When a component is selected into a project, IDE can use it to construct component file view location path inside the IDE project explorer view. It gives component files a better organization view instead of just flat placing them in the project explorer. IDE can also directly ignore this attribute, then all files of the component will be flat placed inside the project explorer view under Cclass. | xs:string | optional |
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.s |
| 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. |
<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).
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:
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 and adds the file name attribute to the list of files to be added to a module using the #include statement. Note: specify only those files as header files that form part of the API of the component, required to use the component |
| include | Sets an include file path. Note: ensure that the name attribute specifies a directory and ends with a '/'. |
| library | Library file |
| object | Object file that can be added to the application |
| source | Startup-, system-, and other C/C++, assembler, etc. source files. Relying on commonly used file extensions. |
| 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. |
| preIncludeGlobal | The specified file is added as a pre-include file to the compiler command line for all modules of the whole project (globally). |
| preIncludeLocal | The specified file is added as a pre-include file to the compiler command line for all modules of the component (locally). |
| genSource | The specified file is a source file which is exclusively used by the generator associated with this component specified by attribute generator. |
| genHeader | The specified file is a header file which is exclusively used by the generator associated with this component specified by attribute generator. |
| genParams | The specified file is a parameter file which is exclusively used by the generator associated with this component specified by attribute generator. |
| genAsset | The specified file is an asset file which is exclusively used by the generator associated with this component specified by attribute generator. it is up to the generator to identify purpose and format of the file by name or file type. |
| other | Other file types not covered in the list above |
Table: File Language Attribute
File language attribute type defines the language for source, header and include file categories. Based on the language the information is used by language specific build tools.
File language attribute is used in the following elements:
The table lists the predefined values for a file language.
| language= | Description |
|---|---|
| asm | The file information is passed to an assembler. |
| c | The file information is passed to a C compiler. |
| cpp | The file information is passed to a C++ compiler. |
| c-cpp | The file information is passed to both C- as well as C++ compiler. |
| link | The file information is passed to a linker. |
File scope attribute type defines the visibility of header file and include path file categories. Based on the specified scope header files or include paths are public or private.
File language attribute is used in the following elements:
The table lists the predefined values for the scope attribute.
| scope= | Description |
|---|---|
| public | Applies only to file elements of category include and category header; ignored otherwise. A public include path is added to the command line for building any modules of the specified language. A public header file is suggested for inclusion by other modules and is considered the contract of the component. |
| private | Applies only to file elements of category include and category header; ignored otherwise. A private include path is added to the command line for building any module of the component for the specified language. A private header file is indicating an internal header file which must not be explicitly included by modules outside of the scope of the component. |
The group extensions can appear in various Pack elements. This group is the frame for defining individual extensions.
Example:
| Parents | Element Chain | ||
|---|---|---|---|
| component | /package/components/component | ||
| component | /package/components/bundle/component | ||
| Child Elements | Description | Type | Occurrence |
| extension | Frame for the individual extension of a component. | group | 1..* |
The element extension is the mechanism to attach additional attributes to the software. This attribute is a key/value pair that is fully defined by the component designer. The possible values are not imposed by this specification.
Example:
| Parents | Element Chain | ||
|---|---|---|---|
| extensions | /package/components/component/extensions | ||
| extensions | /package/components/bundle/component/extensions | ||
| Attributes | Description | Type | Use |
| key | key identifying this extension. This must be unique per component. | xs:string | required |
| value | value associated to the key. | xs:string | optional |
The group environments can appear in component element and in package element. This group is the frame for defining individual environment.
Example #1:
Example #2: describing "tool-x" and "tool-y" custom information applicable to the whole pack:
| Parents | Element Chain | ||
|---|---|---|---|
| component | /package/components/component | ||
| component | /package/components/bundle/component | ||
| package | /package | ||
| Child Elements | Description | Type | Occurrence |
| environment | Specify tool options. | EnvironmentType | 1..* |
See description at /package/devices/family/.../environment.