General.txt

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\mainpage Overview

<b>Open-CMSIS-Pack</b> describes a delivery mechanism for software components, device parameters, and evaluation board
support. The XML-based package description (PDSC) file describes the content of a software pack (file collection) that
includes:
 -  Source code, header files, and software libraries
 -  Documentation and source code templates
 -  Device parameters along with startup code and programming algorithms
 -  Example projects

The complete file collection along with the PDSC file is shipped in ZIP-format (renamed to *.pack). The PDSC file is designed
for software development environments and describes the user and device relevant context for the files supplied within such
a pack file. This information can also be used for display on web sites (refer to \ref createPackPublish).

The CMSIS-Pack system solves several problems:

- It provides meta-data of files that relate to a software component. All files that belong to a software component can be
  identified and information about the original provider is preserved.
- It enables consistent software component upgrade and identifies incompatible configuration files that may be part of the
  user application.
- Software component providers can specify the interfaces and relationship to other software components.
- The meta-data of a software component can include dependency information for toolchains, devices, and processors which
  simplifies the integration into application programs.

After installing a software pack, all included software components are available to the development
tools. Software components are a collection of source modules, header and configuration files as well as
libraries. Packs containing software components can also include \ref pdsc_examples_pg "examples" and user code templates.

The \subpage pack_revisionHistory lists the main changes between versions.


\section SWPackVariants Software pack use cases

A software pack can be used to deliver:

- \b Device \b support: a so called <i>Device Family Pack (DFP)</i> contains CMSIS system/startup files, drivers, and flash
  algorithms for a microcontroller device family.
- \b Board \b support: a <i>Board Support Pack (BSP)</i> contains documentation, schematics, and drivers for a certain
  development board.
- \b Software \b components: a pure <i>software pack</i> can contain source code, libraries, and documentation for:
  - \b middleware \b stacks for public availability.
  - \b in-house \b software for distribution within a company and/or engineering group.

All these pack types can contain in addition:

- example projects,
- code templates,
- reference applications.

As shown in the image below, a software pack can address multiple use cases at the same time! The
\ref packFormat "XML elements" in the PDSC file determine the use case(s).
<a class="el" href="https://arm-software.github.io/CMSIS_6/latest/General/index.html#cmsis_components" target="_blank">CMSIS</a>
itself is distributed in various software packs (CORE, DSP library, RTOS implementation, etc.) and is supplied by Arm.

\image html pack_trinity.png "Major use cases of software packs"

The following sections provide more information:

 - In the \ref cp_Packs, learn the basics and the required steps for creating a pack.
 - \ref packFormat describes all XML elements that can be used in a package description file.
 - \ref configWizard can be used to create GUI-like elements in development tools for configuration files.
 - \ref flashAlgorithm algorithms are used to erase or download applications to Flash devices.
 - \ref coresight_setup allows to create tool-agnostic debug and trace configurations.
 - \ref sdf_pg describes all XML elements that can be used in a system description file for debugging.

\note
The <a href="https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools/">CMSIS-Toolbox documentation</a> provides in-depth
documentation about how to create a CMSIS-Pack. It contains links to pack tutorial repos (for DFP, BSP, and generic software
packs) and provides useful tips when creating a pack.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page pack_revisionHistory Revision history

<table class="cmtable" summary="Revision History">
  <tr>
    <th>Version</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>1.7.49</td>
    <td>
      - deprecate values 'DP' and 'ACCESS_AP' from 'type' attribute in element 'datapatch' 
    </td>
  </tr>
  <tr>
    <td>1.7.48</td>
    <td>
      - add 'HPROT' and 'SPROT' attributes to 'accessportV1' and 'accessportV2' element
    <td>
  </tr>
  <tr>
    <td>1.7.47</td>
    <td>
      - removed optional 'Pname' attribute from 'debugvars' element
    </td>
  </tr>
  <tr>
    <td>1.7.46</td>
    <td>
      - added XYD vendor
    </td>
  </tr>
    <td>1.7.45</td>
    <td>
      - added 'CLANG_TI' to 'CompilerEnumType'
      - documentation: removed "Pack Tutorials" section and added link to CMSIS-Toolbox documentation
    </td>
  </tr>
  <tr>
    <td>1.7.44</td>
    <td>
      - added optional 'environments' section below package element to hold environment-specific information pertaining to the package as a whole
    </td>
  </tr>
  <tr>
    <td>1.7.43</td>
    <td>
      - added optional 'ECCN' section for EU and US export control classification numbers
    </td>
  </tr>
  <tr>
    <td>1.7.42</td>
    <td>
      - added 'mode' attribute ExeGeneratorArgumentType
    </td>
  </tr>
  <tr>
    <td>1.7.41</td>
    <td>
      - changed remaining 'public' attributes to all have default value 'true' if not specified.
    </td>
  </tr>
  <tr>
    <td>1.7.40</td>
    <td>
      - added 'Secure-only' to \ref DsecureEnum "DsecureEnum" to specify a secure software model without provisions for a non-secure partition
    </td>
  </tr>
  <tr>
    <td>1.7.39</td>
    <td>
      - modified default 'DebugPortStart' debug sequence to clear DP sticky error bits
    </td>
  </tr>
  <tr>
    <td>1.7.38</td>
    <td>
      - The \ref createPackPublish "pack publishing process" has been rewritten completely
      - removed the old tutorials that have been superseded by the online versions on GitHub
    </td>
  </tr>
  <tr>
    <td>1.7.37</td>
    <td>
      - added 'Nationstech:184' to \ref DeviceVendorEnum "DeviceVendorEnum"
      - added 'NSING:185' to \ref DeviceVendorEnum "DeviceVendorEnum"
      - added Cortex A35 and Cortex A55 support in PACK.xsd
    </td>
  </tr>
  <tr>
    <td>1.7.36</td>
    <td>
      - added \ref pdsc_csolution_pg for \ref element_clayer "clayer.yml files" and \ref element_cs_template "project templates".
      - added \ref element_targets to specify that a pack applies to specific devices only.
      - added to \ref configWizard the item `<y>` to support symbol or value entries.
    </td>
  </tr>
  <tr>
    <td>1.7.35</td>
    <td>
     - made board element optional in example element
     - added attribute overview to package description element
     - fixed 'BOYAMICRO' vendor value in \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.34</td>
    <td>
     - added 'Watech:183' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.33</td>
    <td>
     - added 'BOYAMICRO:182' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.32</td>
    <td>
     - FileScopeAttributeType 'private' and 'public' also used for header files.
     - attribute select also permitted for component files type header.
     - description text size limit documented with BriefDescType.
    </td>
  </tr>
  <tr>
    <td>1.7.31</td>
    <td>
     - added new processor Cortex-M52
    </td>
  </tr>  
  <tr>
    <td>1.7.30</td>
    <td>
     - renamed componentExts as extensions in the schema.
    </td>
  </tr>  
  <tr>
    <td>1.7.29</td>
    <td>
     - added \ref element_part_image "image" child element to \ref element_part element
    </td>
  </tr>
  <tr>
    <td>1.7.28</td>
    <td>
     - changed capitalization from 'changeLogs' to 'changelogs' to align with documentation
    </td>
  </tr>
  <tr>
    <td>1.7.27</td>
    <td>
     - changed capitalization from 'Clang' to 'CLANG' in 'CompilerEnumType' to align with CMSIS-Toolbox
     - added 'MinebeaMitsumi:181' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.26</td>
    <td>
     - added 'YTMicro:180' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.25</td>
    <td>
     - added 'Sinemicro:179' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.24</td>
    <td>
     - added \ref element_environment "environment" element as child element of \ref element_board "/package/boards/board" and \ref element_component_environments "/package/components/.../component/environments"
    </td>
  </tr>
  <tr>
    <td>1.7.23</td>
    <td>
     - specified that url to a website in book element is allowed
     - aligned \<book> element occurrence in \ref element_board "board" table to XSD schema
    </td>
  </tr>
  <tr>
    <td>1.7.22</td>
    <td>
     - added 'Hvendor' and 'Hname' as attributes of the \ref element_accept "accept", \ref element_require "require" and \ref element_deny "deny" elements
     - redefined 'Hvendor' as xs:string
    </td>
  </tr>
  <tr>
    <td>1.7.21</td>
    <td>
     - added 'Himax:178' to \ref DeviceVendorEnum "DeviceVendorEnum"
     - added 'Renesas' to CompilerEnumType
    </td>
  </tr>
  <tr>
    <td>1.7.20</td>
    <td>
     - added \<clayers> section for distributing layers in software packs. This is renamed to \<csolution> in 1.7.36 as it was not used before.
    </td>
  </tr>
  <tr>
    <td>1.7.19</td>
    <td>
     - added generator specific component file types: 'genSource', 'genHeader', 'genParams', 'genAsset' to 'FileCategoryType' of the files element
    </td>
  </tr>
  <tr>
    <td>1.7.18</td>
    <td>
     - added 'NO_VENDOR:0' to \ref DeviceVendorEnum "DeviceVendorEnum"
    </td>
  </tr>
  <tr>
    <td>1.7.17</td>
    <td>
     - added Hclass and Hgroup predefined values for \ref element_part "\<part>" element classification
     - added \ref element_part-taxonomy "\<part-taxonomy>" element to list description elements defining part classes and part group names
    </td>
  </tr>
  <tr>
    <td>1.7.16</td>
    <td>
     - added 'bottom' and 'perspective' attributes to \ref element_board_image "\<image>" element
     - revert extension from v1.7.10 and replace using attributes for 'language' and 'scope' in 'FileType'
     - added 'Clang' to 'CompilerEnumType'.
     - added '3PEAK' Dvendor ID.
    </td>
  </tr>
  <tr>
    <td>1.7.15</td>
    <td>
     - added 'projectpath' attribute which can be used by IDE to construct file location folder in IDE project explorer view of workspace.
    </td>
  </tr>
  <tr>
    <td>1.7.14</td>
    <td>
     - added 'changelog' element providing references to change log files by component, api and bundle elements
     - added 'Puya' Dvendor ID.
     - added 'view' attribute to component element with predefined values define by 'ViewType'
    </td>
  </tr>
  <tr>
    <td>1.7.13</td>
    <td>
     - added VirtualHW as a new board type in support of the Arm Virtual Hardware initiative
     - added \<parts> element and its child elements for describing and packaging the parts (devices other than the MCU).
     - added \<mountedPart> element, as child element of the \<board> element, for describing the parts (devices other than the MCU)
       mounted on the development board.
    </td>
  </tr>
  <tr>
    <td>1.7.12</td>
    <td>
     - added 'Linkedsemi' Dvendor ID.
    </td>
  </tr>
  <tr>
    <td>1.7.11</td>
    <td>
     - added 'uuid' to boards element to indicate a 128-bit universal ID in the debug firmware of the board
     - added 'memory' and 'algorithm' child elements to the boards element to describe board-specific memory
     - added 'Bvendor', 'Bname', 'Brevision' attribute to conditions element to allow board specific filtering.
    </td>
  </tr>
  <tr>
    <td>1.7.10</td>
    <td>
     - added 'includeAsm', 'includeC', 'includeCpp', 'includeLd' to FileCategoryType of the components element
     - added 'headerAsm', 'includeC', 'headerCpp', 'headerLd' to FileCategoryType of the components element
    </td>
  </tr>
  <tr>
    <td>1.7.9</td>
    <td>
     - added new section \<licenseSets> supporting association of multiple license
       files with one or more component
    </td>
  </tr>
  <tr>
    <td>1.7.8</td>
    <td>
     - added extension points description for components
    </td>
  </tr>
  <tr>
    <td>1.7.7</td>
    <td>
     - added 'Cortex-M85' to DcoreEnum
     - added 'Dpacbti' attribute to Processor
     - added 'Dpacbti' attribute to Condition
     - added 'DpacbtiEnum'
    </td>
  </tr>
  <tr>
    <td>1.7.6</td>
    <td>
     - type of n and m attributes of BoardFeatureType and Pname becomes xs:string
    </td>
  </tr>
  <tr>
    <td>1.7.5</td>
    <td>
     - Rename DcoreEnum 'Star' to 'Star-MC1'
    </td>
  </tr>
  <tr>
    <td>1.7.4</td>
    <td>
     - clarified the usage of the "public" attribute and set public="true" as default.
    </td>
  </tr>
  <tr>
    <td>1.7.3</td>
    <td>
     - added 'Star' to DcoreEnum
    </td>
  </tr>
  <tr>
    <td>1.7.2</td>
    <td>
     - added 'XC' to CompilerEnumType to enable use of Microchip XC32 compiler
    </td>
  </tr>
  <tr>
    <td>1.7.1</td>
    <td>
      - undo removing deprecated attributes as they are still used in latest pdsc file versions:
        DeviceVendorEnum: Lapis Semiconductor, DeviceVendorEnum: Pname, BoardReferenceType: Dvendor, Dname
      - added condition attribute to TaxonomyDescriptionType supporting context specific taxonomies (e.g. vendor or device specific)
    </td>
  </tr>
  <tr>
    <td>1.7.0</td>
    <td>
      - added processor attribute Dcdecp for implemented Custom Datapath Extension Coprocessors (Cortex-M33)
      - extended BoardType added DebugProbeType and FlashAlgorithm.
      - removed types and references used by deprecated cprj format.
    </td>
  </tr>
  <tr>
    <td>1.6.3</td>
    <td>
- removed CMSIS Project Description format (cpdsc) from CMSIS-Pack. Format has been superseeded by new format specification located in the CMSIS
  <a href="https://arm-software.github.io/CMSIS_5/develop/Build/html/cprjFormat_pg.html"><b>Build</b></a> tab.
- added \ref dbg_setup_tutorial "debug setup tutorial" to the documentation.
- updated documentation of PackChk "errors and warnings".
- updated documentation to reflect switch from 'http' to 'https'.
- added 'folder' attribute to example's \ref element_example_project_env "\<environment>" element.
- added 'ACCESS_AP' to \ref DataPatchAccessTypeEnum "DataPatchAccessTypeEnum".
- added 'Cortex-M55' to \ref DcoreEnum "DcoreEnum".
- added 'uninit' attribute to \ref element_memory "\<memory>" element to replace deprecated 'init' attribute.
- updated \ref DmveEnum 'DmveEnum' specification.
- updated minimum length of \<Cclass>, \<Cgroup> and \<Cvariant> attributes in \ref element_component "\<component>" from 3 to 2.
- removed all types specific to cpdsc format. Cpdsc is replaced by Cprj with dedicated schema.
    </td>
  </tr>
  <tr>
    <td>1.6.2</td>
    <td>Modifications compared to Version 1.6.1
  - added \ref element_accessportV1 "\<accessportV1>" and \ref element_accessportV2 "\<accessportV2>" to describe CoreSight access port parameters.
  - added attribute '__apid' to \ref element_debug "\<debug>" and \ref element_dbg_datapatch "\<datapatch>" to reference \<accessportV1> and \<accessportV2> elements.
  - added attribute 'dormant' to \ref element_debugconfig "\<debugconfig>" element.
    </td>
  </tr>
  <tr>
    <td>1.6.1</td>
    <td>Modifications compared to Version 1.6.0
- added a Bash script to support pack generation on Linux or Windows.
- added \b custom attribute to \ref element_component "component element".
- added \b TrustZone-disabled value to \ref DsecureEnum "software model selection".
- added \ref dbg_setup_tutorial in CMSIS-Pack documentation.
    </td>
  </tr>
  <tr>
    <td>1.6.0</td>
    <td>Modifications compared to Version 1.5.0
- added Armv8.1-M MVE processor feature attribute 'Dmve'.
- added local and global pre-include section \ref Pre_Include_Local_Component_h, \ref Pre_Include_Global_h.
- added file categories 'preIncludeLocal' and 'preIncludeGlobal' to the \ref FileCategoryEnum.
- added file attribute 'path' for file category 'header' to add support for relative include paths.
- added to \ref element_package "package" element the possibility to restrict the usage of the with attributes Dcore, Dname, Dvendor, and Tcompiler.
- added \ref element_dominate "dominate" element to overwrites identical \ref element_devices "devices", \ref element_apis "APIs", or \ref element_components "components".
- added attribute 'condition' to the \ref element_api "api" element so that an API can be excluded based on a condition.
- added new \ref pack_Cclass : "Audio", "Board Part", "Data Exchange", "Extension Board", "IoT Client", "IoT Utility", "Security", "Utility".
    </td>
  </tr>
  <tr>
    <td>1.5.0</td>
    <td>Modifications compared to Version 1.4.9
- added \ref sdf_pg
- updates to \ref DeviceVendorEnum "Device Vendor"
- removed usage of DP CTRL/STAT CDBGRSTREQ from \ref debugPortStart default sequence
- added \ref element_flashinfo "flashinfo" with children \<block\> and \<gap\> to describe flash devices for sequence-based flash download
- new \ref DebugFunctions "debug access functions" and \ref DebugVars "global debug variables" for sequence-based flash download
- added \ref element_repository "repository" element for specifying origin of public repositories
- added attributes to \ref element_release "release" element specifying repository tag and url for downloading repository content
- added new processor Cortex-M35P
    </td>
  </tr>
  <tr>
    <td>1.4.9</td>
    <td>Modifications compared to Version 1.4.8
- added Toptions attribute for use in conditions
- updated documentation for generator section to reflect new exe, web, and eclipse sections
    </td>
  </tr>
  <tr>
    <td>1.4.8</td>
    <td>Modifications compared to Version 1.4.7
- added support for semantic versioning quality information in ConditionVersionType
- updated Pack schema file making some elements optional
- added Pack Index File Specification and schema file
    </td>
  </tr>
  <tr>
    <td>1.4.7</td>
    <td>Modifications compared to Version 1.4.6
- added multiple version types to tighten the schema checking depending on context
- added new generator sections for exe, web and eclipse based generators in &lt;generator&gt;
- added new processor attributes Dtz = Trustzone and Ddsp = DSP instructions for Armv8-M
- added new attributes Dtz, Ddsp, Dsecure to conditions &lt;require&gt;, &lt;deny&gt;, &lt;accept&gt;
- added new processors Cortex-M23 and Cortex-M33 and other in DcoreEnum
- added new attribute public to books and images to indicate public use of documents and board images
    </td>
  </tr>
  <tr>
    <td>1.4.6</td>
    <td>Modifications compared to Version 1.4.5
- refined Dname string pattern restriction (RestrictedStringDname)
    </td>
  </tr>
  <tr>
    <td>1.4.5</td>
    <td>Modifications compared to Version 1.4.4
- added: Punits to ProcessorType
- added: Punit to DebugType
    </td>
  </tr>
  <tr>
    <td>1.4.4</td>
    <td>Modifications compared to Version 1.4.3
- added: attribute defaultResetSequence to DebugType.
- added: &lt;requirements&gt; section:
    - &lt;packages&gt; defining dependencies between packs
    - &lt;languages&gt; defining required language support e.g. C99
    - &lt;compiler&gt; defining required toolchains
- added: &lt;create&gt; section used for tool independent project description
    - attributes: name, documentation, condition
    - &lt;target&gt; specifies the board and device targeted by the project
    - &lt;options&gt;
    - &lt;files&gt; specifies the grouped files
- updated: &lt;algorith&gt; element
    - added attributes: style, parameter and endian
- updated: &lt;memory&gt; element
    - added attributes: name, access and alias
    - deprecating attribute: id (replaced by name + access)
    </td>
  </tr>
  <tr>
    <td>1.4.3</td>
    <td>Modifications compared to Version 1.4.1
- Adding attribute "sdf" to debugconfig element within section &lt;devices&gt;
    </td>
  </tr>
  <tr>
    <td>1.4.1</td>
    <td>Modifications compared to Version 1.4.0
- pName, Dname, Dvariant type changed from xs:string to RestrictedString
    </td>
  </tr>
  <tr>
    <td>1.4.0</td>
    <td>Modifications compared to Version 1.3.3:
- device section <em>memory</em> specification redefined, deprecating <em>id</em> attribute
- device section <em>algorithm</em> support multiple flash programming algorithm styles
- device section <em>debug</em> adding CJTAG debug port type
    </td>
  </tr>
  <tr>
    <td>1.3.3</td>
    <td>Modifications compared to Version 1.3.1:
- Schema Version remains unchanged, since no incompatible update
- <em>Added</em> generator section can specify a target GPDSC file that it will generate
- <em>Added</em> A component can be linked to a generator and the generator's GPDSC file will be
  automatically included in the project as part of the component.
- <em>Added</em> A generator command is optionally extended by a separate description of arguments
- <em>Updated</em> Vendor list
- <em>Updated</em> Utility packChk.exe to Version 1.3.0.0:
  - detect redefinitions of boards
  - check presence of board image files
  - check for duplicate device features
  - check for duplicate device definitions
  - check for
  - minor bug fixes
    </td>
  </tr>
  <tr>
    <td>1.3.1</td>
    <td>Modifications compared to Version 1.3:
- Schema Version remains unchanged, since no incompatible update
- <em>Added</em> Cortex-M7 to the predefined list of processors
- <em>Updated</em> Vendor list
- <em>Added</em> File version attribute to debugvars element of device description
- <em>Updated</em> XML file header encoding tag set to capital "UTF8"
- <em>Deprecated</em> init attribute of &lt;memory&gt; element in &lt;devices&gt; section deprecated
    </td>
  </tr>
  <tr>
    <td>1.3</td>
    <td>Modifications compared to Version 1.2:
 - <em>Added</em> attributes to release tag for managing deprecation and changing Pack IDs
 - <em>Removed</em> external RAMn and ROMn memory IDs in memory tag
 - <em>Added</em> FileCategoryTypes in &lt;file&gt; element for C, C++, Assembler, Linker
 - <em>Extended</em> specification of &lt;require&gt;, &lt;accept&gt; and &lt;deny&gt; with Cversion and Capiversion ranges
 - <em>Added</em> \ref createPackUtil and packchk for Pack validation
 - <em>Added</em> documentation for the Example Pack based on LPC1800 Device Family
 - <em>Refined</em> &lt;debug&gt; element description
 - Many clarifications in the documentation along with examples
    </td>
  </tr>
  <tr>
    <td>1.2</td>
    <td>Clarifications for release.</td>
  </tr>
  <tr>
    <td>1.1 - Preliminary</td>
    <td>Update release for review:
 - <em>new</em> Boards description
 - <em>new</em> Debug description
 - <em>revised</em> Device Feature capture
 - <em>new</em> Generator description
 - <em>new</em> Flash Algorithm Specification
 - <em>new</em> Configuration Wizard Annotation Specification</td>
  </tr>
  <tr>
    <td>1.0 - Preliminary</td>
    <td>Preliminary release for review</td>
  </tr>
  <tr>
    <td>0.10</td>
    <td>Release for beta review</td>
  </tr>
</table>
*/