![]() |
CMSIS-Pack
Version 1.3.3
Delivery Mechanism for Software Packs
|
This section is a tutorial that explains how to create a Software Pack. Initially, a Software Pack with a simple PDSC file is created that contains only one software component. This Software Pack is then extended to show the various features for describing software components.
Preparations
Open the file vendor.pack_name.pdsc in an editor and change it like this:
snippets.xml
file in the 01_Create_PDSC directory.A PDSC file starts with information on the XML version and the encoding. The <package> element declares the version of the schema file and the XSD file that is used to validate the PDSC file (hence the copy of the PACK.xsd file into the working directory):
<url>file:///c:/temp/working</url>
Add release information and keywords:
The information from the <releases> section will be used for:
<keywords> may be used for better visibility for search engines.
gen_pack.bat
). The batch file will:Install the Pack by double-clicking it. Depending on the development software that is used, the display of the Pack contents may differ:
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 components must have the following attributes that are used to identify the component:
Cclass
): examples are CMSIS, Device, File System Cgroup
): examples are CMSIS:RTOS, Device:Startup, File System:CORE Cversion
): the version number of the software component.Optionally, a software component may have additional attributes:
Csub
): examples are CMSIS:RTOS:MyRTOS, Device:Driver USBD:Full-speed Cvariant
): a variant of the software component.Cvendor
): the supplier of the software component.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.
The following Cclass
names have a special meaning:
Cgroup
API entries (for example Ethernet (API))Other Cclass
names can be freely assigned to software components.
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:
Here is an example for the display of software components in a development tool:
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.A condition describes dependencies on:
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:
If a condition resolves to false during processing, the respective element will be ignored.
Let's modify the example from the Create PDSC File section by adding the requirement for a CMSIS-RTOS and libraries that are specific to a certain Cortex-M class core:
mylib_cm0.lib
for use with a Cortex-M0 and Cortex-M0+ processormylib_cm3.lib
for use with a Cortex-M3 processormylib_cm4.lib
for use with a Cortex-M4 or Cortex-M7 processorCopy the content of the 02_Conditions directory of the Pack_with_Software_Components.zip file to the Files directory in your working environment:
Finally, save the PDSC file and regenerate the Pack file using the gen_pack.bat script. See Generate a Pack for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.0.
*** WARNING M362: (Line 82) Not all Component Dependencies for 'Cclass=MyClass, Cgroup=MyGroup, Csub=MySubGroup, Cversion=1.0.1, Capiversion=' can be resolved. RTE Model reports: No component is installed.This is because it cannot resolve and check dependencies on components that are not part of this Pack (in this case the CMSIS components). You can either safely ignore this warning or add the ARM:CMSIS PDSC to the checking process, so that the dependencies can be correctly examined.
Software components may have variants, for example:
Variants are mutually exclusive (only one variant can be chosen at a time). Cvariant
is an optional part of the component ID. The variant specifier is a brief string (e.g. release
, debug
).
The following example introduces a new component to the Pack in two variants: debug
and release
. Copy the content of the 03_Variants directory of the Pack_with_Software_Components.zip file to the Files directory in your working environment.
Finally, save the PDSC file and regenerate the Pack file using the gen_pack.bat script. See Generate a Pack for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.1.
Sometimes, software components need to know of other components. Depending on the availability or configuration of another component, certain settings may be required. A distinct header file is available to make components aware of each other: RTE_Components.h. To add a line of C code to this header file, simply add this to your component:
<RTE_Components_h> #define RTE_MyVariant_Debug /* MyVariant Debug Version */ </RTE_Components_h>
The #define
can be checked by other components in a project.
A bundle is basically a variant on the Cclass
level. It specifies the attributes Cclass
, Cversion
and optionally Cgroup
and Cvendor
for a collection of interdependent components. Components within a bundle inherit the attributes set by the bundle and must not set these attributes again. Bundles ensure consistency of attributes across multiple interworking components and restrict the mix and match of components within a Cclass
from different solutions. In addition to components, a bundle has the mandatory elements description
and doc
(for documentation).
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.
Some software components allow several instances. This is useful if more than one peripheral can be connected.
Finally, save the PDSC file and regenerate the Pack file using the gen_pack.bat script. See Generate a Pack for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.2. When selecting a certain number of instances of the component, causes the development tool to copy the required configuration files multiple times into the project. This ensures that each component instance can be configured separately.
An API is a special form of a software component that only defines a C/C++ Application Programming Interface (API). An API does not contain the actual implementation (usually provided by source code or library files) and cannot be selected in a development tool. One example is the CMSIS-RTOS API, which is specified as part of CMSIS. However, the actual RTOS implementation is provided by different vendors. An API consists of a name, a brief description as well as one or more header files, and a document containing a detailed specification of the API.
Copy the content of the 05_APIs directory of the Pack_with_Software_Components.zip file to the Files directory in your working environment:
User code templates provide a quick start for implementing an application. To add user code templates, add source files with the attribute attr=“template”
in a <component>
. The select
attribute is used to identify template files. Template files with the same select
attribute will be added to a project simultaneously.
Copy the content of the 06_User_Code_Templates directory of the Pack_with_Software_Components.zip file to the Files directory in your working environment:
debug
and release
) of the ::MyVariant:MyGroup component: Finally, save the PDSC file and regenerate the Pack file using the gen_pack.bat script. See Generate a Pack for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.4.
Example projects help to understand a certain MCU or development board better. An example and each individual file of it may refer to a condition that must resolve to true; if it is false, the example or file will be ignored. The board element is used to reference to one or more board descriptions using the board vendor and name an example is targeted for. Each example can specify attributes listing related components using Cclass
, Cgroup
, Csub
and Cversion
. The <project> element contains the names of the supported development tools and the project files to be loaded.
Copy the content of the 07_Example_Projects directory of the Pack_with_Software_Components.zip file to the Files directory in your working environment:
Finally, save the PDSC file and regenerate the Pack file using the gen_pack.bat script. See Generate a Pack for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.5.
Example projects rely on a development board to be present (as the code needs to run on real hardware). In the code above you will notice that a development board called "MyDevBoard" was specified. Pack with Board Support explains how to integrate boards into a Pack.