From 96d6da4e252b06dcfdc041e7df23e86161c33007 Mon Sep 17 00:00:00 2001 From: rihab kouki Date: Tue, 28 Jul 2020 11:24:49 +0100 Subject: Official ARM version: v5.6.0 --- docs/Pack/html/cp_Packs.html | 255 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 209 insertions(+), 46 deletions(-) (limited to 'docs/Pack/html/cp_Packs.html') diff --git a/docs/Pack/html/cp_Packs.html b/docs/Pack/html/cp_Packs.html index d730a8f..30ab87c 100644 --- a/docs/Pack/html/cp_Packs.html +++ b/docs/Pack/html/cp_Packs.html @@ -3,8 +3,8 @@ -Software Packs Overview -CMSIS-Pack: Software Packs Overview +Overview +CMSIS-Pack: Overview @@ -32,7 +32,7 @@ Logo
CMSIS-Pack -  Version 1.5.0 +  Version 1.6.0
Delivery Mechanism for Software Packs
@@ -107,10 +107,10 @@ $(document).ready(function(){initNavTree('cp_Packs.html','');});
-
Software Packs Overview
+
Overview
-

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

+

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.
      • @@ -141,6 +141,171 @@ $(document).ready(function(){initNavTree('cp_Packs.html','');});
    • 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 APIheaders" 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.

    +
    +software_component.png +
    +

    +

    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:

    +
    +ComponentDisplay.png +
    +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.
      • +
    +

    +References to other software components

    +

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

    +
    +conditions.png +
    +

    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):

    +
    +requirements.png +
    +

    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.

    +
    +api.png +
    +

    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:

    +
    +internal_mac_example.png +
    +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:

    +
    +external_mac_example.png +
    +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.

    +

    +Steps to Create a Pack

    +

    The following image shows the basic steps that are required to create a Software Pack:

    +
    +PackCreateSteps.png +
    +
      +
    1. Produce input: Create the files that will be delivered with the Pack.
      2. +
    2. Organize files: Use directories to separate the content of the Pack.
      3. +
    3. Create PDSC file: The XML based PDSC file can be created using any text editor. Editors that can validate XML code against a schema file help to find bugs early in the Pack development stage.
      4. +
    4. Generate Pack: Any compression tool supporting the ZIP format can be used to create a Pack file. packChk.exe is helpful for the validation of the contents of a Pack.
      5. +
    +

    The following pages will show how to create a Software Pack from scratch. The page Pack with Software Components will start with a simple Pack containing only the PDSC file and a single software component and will then explain further elements of a Pack in more detail. The page Pack with Device Support adds information on the additional requirements that a DFP has, while Pack with Board Support will elaborate on the content specific to a BSP.

    +

    +Pack Tutorial

    +

    The ARM::CMSIS Pack contains tutorials that are explained on the following pages. In the \CMSIS\Pack\Tutorials directory the following three ZIP files are available:

    + + + + + + + + + +
    ZIP File Documentation
    Pack_with_Software_Components.zip Pack with Software Components
    Pack_with_Device_Support.zip Pack with Device Support
    Pack_with_Board_Support.zip Pack with Board Support

    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:

    @@ -161,7 +326,7 @@ Pack File Name

    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 packname.
      • +
    • <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.
    @@ -174,57 +339,55 @@ Pack File Name

    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:

    -
      -
    • Board Support: Generic interfaces for evaluation and development boards
      • -
    • CMSIS: Cortex Microcontroller Software Interface Standard components
      • -
    • CMSIS Driver: Unified device drivers compliant to the CMSIS-Driver specification
      • -
    • Compiler: Arm Compiler software extensions
      • -
    • Data Exchange: Software components for data exchange
      • -
    • Device: Startup and system setup components
      • -
    • File System*: File drive support and file system
      • -
    • Graphics*: Graphical libraries for user interfaces
      • -
    • Network*: Network stack using Internet protocols
      • -
    • RTOS*: Real-time operating systems
      • -
    • Safety: Components for testing application software against safety standards
      • -
    • Security*: Encryption for secure communication or storage
      • -
    • USB*: Universal Serial Bus stack
      • -
    • Wireless*: Communication stacks such as Bluetooth, WiFi, and ZigBee
      • -
    -

    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.

    -

    -Steps to Create a Pack

    -

    The following image shows the basic steps that are required to create a Software Pack:

    -
    -PackCreateSteps.png -
    -
      -
    1. Produce input: Create the files that will be delivered with the Pack.
      2. -
    2. Organize files: Use directories to separate the content of the Pack.
      3. -
    3. Create PDSC file: The XML based PDSC file can be created using any text editor. Editors that can validate XML code against a schema file help to find bugs early in the Pack development stage.
      4. -
    4. Generate Pack: Any compression tool supporting the ZIP format can be used to create a Pack file. packChk.exe is helpful for the validation of the contents of a Pack.
      5. -
    -

    The following pages will show how to create a Software Pack from scratch. The page Pack with Software Components will start with a simple Pack containing only the PDSC file and a single software component and will then explain further elements of a Pack in more detail. The page Pack with Device Support adds information on the additional requirements that a DFP has, while Pack with Board Support will elaborate on the content specific to a BSP.

    -

    -Pack Tutorial

    -

    The ARM::CMSIS Pack contains tutorials that are explained on the following pages. In the \CMSIS\Pack\Tutorials directory the following three ZIP files are available:

    +

    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.

    - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ZIP File Documentation
    Cclass Description
    Pack_with_Software_Components.zip Pack with Software Components
    Audio Software components for audio processing
    Pack_with_Device_Support.zip Pack with Device Support
    Board Support Generic interfaces for evaluation and development boards
    Pack_with_Board_Support.zip Pack with Board Support
    Board Part * Drivers that support an external component available on an evaluation board
    CMSIS Cortex 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 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.