diff options
| author | Ali Labbene <ali.labbene@st.com> | 2019-12-11 08:59:21 +0100 |
|---|---|---|
| committer | Ali Labbene <ali.labbene@st.com> | 2019-12-16 16:35:24 +0100 |
| commit | 9f95ff5b6ba01db09552b84a0ab79607060a2666 (patch) | |
| tree | 8a6e0dda832555c692307869aed49d07ee7facfe /docs/Pack/html/cp_SWComponents.html | |
| parent | 76177aa280494bb36d7a0bcbda1078d4db717020 (diff) | |
| download | st-cmsis-core-lowfat-9f95ff5b6ba01db09552b84a0ab79607060a2666.tar.gz st-cmsis-core-lowfat-9f95ff5b6ba01db09552b84a0ab79607060a2666.tar.bz2 st-cmsis-core-lowfat-9f95ff5b6ba01db09552b84a0ab79607060a2666.zip | |
Official ARM version: v5.4.0
Add CMSIS V5.4.0, please refer to index.html available under \docs folder.
Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure
used in existing projects, and thus avoid projects mass update
Note: the following components have been removed from ARM original delivery (as not used in ST packages)
- CMSIS_EW2018.pdf
- .gitattributes
- .gitignore
- \Device
- \CMSIS
- \CoreValidation
- \DAP
- \Documentation
- \DoxyGen
- \Driver
- \Pack
- \RTOS\CMSIS_RTOS_Tutorial.pdf
- \RTOS\RTX
- \RTOS\Template
- \RTOS2\RTX
- \Utilities
- All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2
Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3
Diffstat (limited to 'docs/Pack/html/cp_SWComponents.html')
| -rw-r--r-- | docs/Pack/html/cp_SWComponents.html | 538 |
1 files changed, 538 insertions, 0 deletions
diff --git a/docs/Pack/html/cp_SWComponents.html b/docs/Pack/html/cp_SWComponents.html new file mode 100644 index 0000000..0783053 --- /dev/null +++ b/docs/Pack/html/cp_SWComponents.html @@ -0,0 +1,538 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<title>Pack with Software Components</title> +<title>CMSIS-Pack: Pack with Software Components</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<link href="cmsis.css" rel="stylesheet" type="text/css" /> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<script type="text/javascript" src="printComponentTabs.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> + $(document).ready(initResizable); + $(window).load(resizeHeight); +</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> + $(document).ready(function() { searchBox.OnSelectItem(0); }); +</script> +</head> +<body> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 46px;"> + <td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td> + <td style="padding-left: 0.5em;"> + <div id="projectname">CMSIS-Pack +  <span id="projectnumber">Version 1.5.0</span> + </div> + <div id="projectbrief">Delivery Mechanism for Software Packs</div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<div id="CMSISnav" class="tabs1"> + <ul class="tablist"> + <script type="text/javascript"> + <!-- + writeComponentTabs.call(this); + //--> + </script> + </ul> +</div> +<!-- Generated by Doxygen 1.8.6 --> +<script type="text/javascript"> +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +</script> + <div id="navrow1" class="tabs"> + <ul class="tablist"> + <li><a href="index.html"><span>Main Page</span></a></li> + <li class="current"><a href="pages.html"><span>Usage and Description</span></a></li> + <li> + <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.png" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> + </span> + </div> + </li> + </ul> + </div> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +$(document).ready(function(){initNavTree('cp_SWComponents.html','');}); +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Pages</a></div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="header"> + <div class="headertitle"> +<div class="title">Pack with Software Components </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p>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.</p> +<p><b>Preparations</b></p> +<ol type="1"> +<li>Create a working directory on you PC, for example <b>C:\temp\working</b>.</li> +<li>Go to the directory <b>\CMSIS\Pack\Tutorials</b> available in the <b>ARM::CMSIS</b> Pack installation. Please consult your development tool's documentation for more information on the Pack installation directory structure. In a standard µVision installation, you will find it below <b>C:\Keil_v5\ARM\Pack\ARM\CMSIS\<em>version</em></b>.</li> +<li>Open the file <b>Pack_with_Software_Components.zip</b>.</li> +<li>Copy the <em>content</em> of the ZIP file's <b>01_Create_PDSC</b> directory into your working directory.</li> +<li>Make sure that files/directories are not write protected (remove read-only flag).</li> +<li>Copy from the directory <b>\CMSIS\Utilities</b> available in the <b>ARM::CMSIS</b> Pack installation the following files into your working directory:<ul> +<li>PackChk.exe</li> +<li>PACK.xsd</li> +</ul> +</li> +</ol> +<h1><a class="anchor" id="cp_CreatePDSC"></a> +Create PDSC File</h1> +<ol> +<li> +<p class="startli">Open the file <b>vendor.pack_name.pdsc</b> in an editor and change it like this: </p> +<div class="fragment"><div class="line"><?xml version=<span class="stringliteral">"1.0"</span> encoding=<span class="stringliteral">"UTF-8"</span>?></div> +<div class="line"><<span class="keyword">package </span>schemaVersion="1.4" xmlns:xs="http:<span class="comment">//www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="PACK.xsd"></span></div> +<div class="line"> <vendor>MyVendor</vendor></div> +<div class="line"> <name>MyPack</name></div> +<div class="line"> <description>Internal Software Pack</description></div> +<div class="line"> <url></url></div> +<div class="line"> <supportContact></supportContact></div> +<div class="line"> <license>Docs/license.txt</license></div> +</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>All code examples in this and the following sections can be found in the <code>snippets.xml</code> file in the <b>01_Create_PDSC</b> directory.</dd></dl> +<p>A PDSC file starts with information on the XML version and the encoding. The <a class="el" href="pdsc_package_pg.html"><package></a> 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):</p> +<ul> +<li><a class="el" href="pdsc_package_pg.html#element_package"><name></a> specifies the name of the Pack and <em>must</em> <em>not</em> contain spaces. <b>Example:</b> <code>MyPack</code> and <code>My_Pack</code> are ok, <code>My</code> <code>Pack</code> is not ok.</li> +<li><a class="el" href="pdsc_package_pg.html#element_package"><description></a> describes the Pack in a few words</li> +<li><a class="el" href="pdsc_package_pg.html#element_package"><vendor></a> states the name of the Pack's vendor and <em>must</em> <em>not</em> contain spaces. <b>Example:</b> <code>ACMECorp</code> and <code>ACME_Corp</code> are OK, <code>ACME</code> <code>Corporation</code> is not OK.</li> +<li><a class="el" href="pdsc_package_pg.html#element_package"><url></a> defines the download URL of the Pack (may be left empty) <dl class="section note"><dt>Note</dt><dd><ul> +<li>In this tutorial, the URL is not specified. This means that the Pack will be marked in Pack Installer as <b>Offline</b> and needs to be updated manually. To resolve this issue, it is possible to specify the file "download" location using a <a href="https://en.wikipedia.org/wiki/File_URI_scheme" target="_blank">file URI</a>. For Windows users, this would look like the following: <pre class="fragment"> <url>file:///c:/temp/working</url></pre></li> +<li>It is important to understand how the <url> element works. If you specify a URL, for example <a href="http://www.keil.com/pack/" target="_blank">http://www.keil.com/pack</a>, then you have to make the PDSC file and the corresponding Pack file(s) available for download at that exact location. The naming of the files follow the standard naming rules. For example, the ARM::CMSIS PDSC and Pack files are available here:<br/> + <a href="http://www.keil.com/pack/ARM.CMSIS.pdsc" target="_blank">http://www.keil.com/pack/ARM.CMSIS.pdsc</a> and <br/> + <a href="http://www.keil.com/pack/ARM.CMSIS.4.3.0.pack" target="_blank">http://www.keil.com/pack/ARM.CMSIS.4.3.0.pack</a> and <br/> + <a href="http://www.keil.com/pack/ARM.CMSIS.4.2.0.pack" target="_blank">http://www.keil.com/pack/ARM.CMSIS.4.2.0.pack</a> and ... <br/> + At the specified location, you need to have one (unversioned) PDSC file and can have multiple versioned Pack files, but at least the latest one.</li> +</ul> +</dd></dl> +</li> +<li><a class="el" href="pdsc_package_pg.html#element_package"><supportContact></a> may provide an email address or web page URL for Pack specific questions/problems</li> +<li><a class="el" href="pdsc_package_pg.html#element_package"><license></a> links to an optional license file that will be shown during the installation of the Pack. The installation in development tools will abort if the license agreement is not accepted. </li> +</ul> +</li> +<li> +<p class="startli">Add release information and keywords: </p> +<div class="fragment"><div class="line"><releases></div> +<div class="line"> <release version=<span class="stringliteral">"1.0.0"</span> date=<span class="stringliteral">"2015-03-09"</span>></div> +<div class="line"> Initial version</div> +<div class="line"> </release></div> +<div class="line"></releases></div> +<div class="line"> </div> +<div class="line"><keywords></div> +<div class="line"> <keyword>MyVendor</keyword></div> +<div class="line"> <keyword>My Software Component</keyword></div> +<div class="line"></keywords></div> +</div><!-- fragment --><p> The information from the <a class="el" href="element_releases.html"><releases></a> section will be used for:</p> +<ul> +<li>Determining the Pack version (required for the file name of the Pack file)</li> +<li>Display of release information</li> +</ul> +<p class="endli"><a class="el" href="element_keywords.html"><keywords></a> may be used for better visibility for search engines. </p> +</li> +<li> +Add a <a class="el" href="pdsc_components_pg.html"><components></a> section with the following: <div class="fragment"><div class="line"><components></div> +<div class="line"> <component Cclass=<span class="stringliteral">"MyClass"</span> Cgroup=<span class="stringliteral">"MyGroup"</span> Csub=<span class="stringliteral">"MySubGroup"</span> Cversion=<span class="stringliteral">"1.0.0"</span>></div> +<div class="line"> <description>MySWComp</description></div> +<div class="line"> <files></div> +<div class="line"> <file category=<span class="stringliteral">"doc"</span> name=<span class="stringliteral">"Docs/MySWComp.htm"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/header_mylib.h"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/config/config_mylib.h"</span> attr=<span class="stringliteral">"config"</span> version=<span class="stringliteral">"1.0.0"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/mylib_one.c"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/mylib_two.c"</span>/></div> +<div class="line"> </files></div> +<div class="line"> </component></div> +<div class="line"></components></div> +</div><!-- fragment --> <dl class="section note"><dt>Note</dt><dd>If you are using a header file with the attribute <span class="XML-Token">config</span>, save it in a separate directory from all other header files as in this example. Configuration files are copied into the project folder and are adopted specifically for that project but chances are 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).</dd></dl> +More information on <b><components></b> will be given in section <a class="el" href="cp_SWComponents.html#cp_Components">Software Components</a>. Save the file and close your editor. In the next section, the generation of a Pack will be explained in detail. </li> +</ol> +<h1><a class="anchor" id="cp_GeneratePack"></a> +Generate a Pack</h1> +<ol> +<li> +Rename the file <b>vendor.pack_name.pdsc</b> to <b>MyVendor.MyPack.pdsc</b>. </li> +<li> +Open the batch file <b>gen_pack.bat</b> from your working directory in a text editor. Check if the following line of code reflects your setup: <div class="fragment"><div class="line"><span class="stringliteral">"C:\Program Files\7-Zip\7z.exe"</span> a %PackName% Files -tzip</div> +</div><!-- fragment --> If you do not have <a href="http://www.7-zip.org/" target="_blank">7-Zip</a> installed on your PC, you can specify any other ZIP tool that supports command line calls. In that case you have to adapt the command line arguments accordingly. </li> +<li> +Having saved <b>gen_pack.bat</b>, you can execute it either by double-clicking or by using the command line which is recommended to see the output of PackChk.exe (open a command window at the location of the files and enter <code>gen_pack.bat</code>). The batch file will:<ul> +<li>Check the availability of the PDSC file</li> +<li>Copy the PDSC file to the <b>Files</b> directory</li> +<li>Run PackChk.exe on the <b>Files</b> directory<br/> +</li> +<li>Create a Pack file in the working directory. It will be called <b>MyVendor.MyPack.1.0.0.pack</b>. </li> +</ul> +</li> +<li> +<p class="startli">Install the Pack by double-clicking it. Depending on the development software that is used, the display of the Pack contents may differ:</p> +<div class="image"> +<img src="simplepack_rte.png" alt="simplepack_rte.png"/> +<div class="caption"> +MyClass:MyGroup:MySubGroup shown in development tool</div></div> + </li> +</ol> +<h1><a class="anchor" id="cp_Components"></a> +Software Components</h1> +<p>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 <a class="el" href="pdsc_conditions_pg.html#element_condition">condition</a> that must resolve to true; if it is false, the component or file is not applicable in the given context.</p> +<p>Each software components must have the following attributes that are used to identify the component:</p> +<ul> +<li>Component Class (<code>Cclass</code>): examples are <b>CMSIS</b>, <b>Device</b>, <b>File</b> <b>System</b> </li> +<li>Component Group (<code>Cgroup</code>): examples are <b>CMSIS:RTOS</b>, <b>Device:Startup</b>, <b>File</b> <b>System:CORE</b> </li> +<li>Component Version (<code>Cversion</code>): the version number of the software component.</li> +</ul> +<p>Optionally, a software component may have additional attributes:</p> +<ul> +<li>Component Sub-Group (<code>Csub</code>): examples are <b>CMSIS:RTOS:MyRTOS</b>, <b>Device:Driver</b> <b>USBD:Full-speed</b> </li> +<li>Component Variant (<code>Cvariant</code>): a variant of the software component.</li> +<li>Component Vendor (<code>Cvendor</code>): the supplier of the software component.</li> +</ul> +<p>The <code>Cclass</code>, <code>Cgroup</code>, <code>Csub</code>, <code>Cvariant</code> and <code>Cversion</code> attributes are used together with the vendor specified by the Pack to identify a component. A component vendor must ensure that the combination <code>Cclass</code>, <code>Cgroup</code>, <code>Csub</code> and <code>Cversion</code> is unique and not used by multiple components within the same Pack.</p> +<p>For a list of established Cclasses, refer to <a class="el" href="cp_Packs.html#pack_Cclass">Software Component Cclasses</a>.</p> +<p>In case multiple interdependent components (belonging to the same <code>Cclass</code>) form part of a solution, these can be grouped in a so called <a class="el" href="cp_SWComponents.html#cp_Bundles">bundle</a>.</p> +<p>Use the following syntax to reference to software components and APIs:<br/> +<b><Vendor>::<Cclass>:<Cgroup>:<Csub></b></p> +<p><b>Examples:</b> </p> +<ul> +<li><b>::CMSIS:RTOS (API)</b> - the CMSIS-RTOS API.</li> +<li><b>ARM::CMSIS:DSP</b> - the CMSIS-DSP Library.</li> +<li><b>::File System:Drive:NOR</b> - the NOR Flash Drive of a file system.</li> +</ul> +<p>Here is an example for the display of software components in a development tool:</p> +<div class="image"> +<img src="ComponentDisplay.png" alt="ComponentDisplay.png"/> +<div class="caption"> +Display of a software component in development tools</div></div> + <h2>Software Component Files </h2> +<p>Each software component consists of a certain number of files. Each file has at least the following attributes:</p> +<ul> +<li><code>name:</code> 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.</li> +<li><code>category:</code> Defines the purpose of the file. Select the predefined value as listed in the table <a class="el" href="pdsc_components_pg.html#FileCategoryEnum">File Categories</a>.</li> +</ul> +<p>Optionally, every file may have the following attributes:</p> +<ul> +<li><code>attr:</code> Defines the special use and handling of a file. Select a predefined value as defined in the table <a class="el" href="pdsc_components_pg.html#FileAttributeEnum">File Attributes</a>.</li> +<li><code>condition:</code> Enter the identifier (attribute <em><b>id</b></em>) of a <a class="el" href="pdsc_conditions_pg.html#element_condition">condition</a>. The element is used if the condition resolves to <span class="XML-Token">true</span>.</li> +<li><code>select:</code> Brief description and purpose of the file. The <b><em>select</em></b> attribute is <b>required</b> when <b><em>attr</em></b> is set to <span class="XML-Token">template</span> or <span class="XML-Token">interface</span>. When multiple template files of a component have the same <b><em>select</em></b> string, they are treated as a single selectable template. This way, multiple template or interface files can be bundled.</li> +<li><code>src:</code> Path information. The path is specified relative to the Pack Description File (PDSC).</li> +<li><code>version:</code> 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.</li> +</ul> +<h1><a class="anchor" id="cp_Conditions"></a> +Conditions</h1> +<p>A condition describes dependencies on:</p> +<ul> +<li>a specific device</li> +<li>a certain processor</li> +<li>tool attributes</li> +<li>the presence of other components</li> +</ul> +<p>Conditions are used to define <b>AND/OR</b> 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.</p> +<p>Each condition has an <b>id</b> that is unique within the scope of a the PDSC file. An id can be referenced in the <code>condition</code> attribute of components, APIs, examples, files and other conditions. All attributes set in a <b>accept</b>, <b>require</b>, or <b>deny</b> element must resolve to true for the element to become true. A condition becomes true when:</p> +<ul> +<li>At least one <b>accept</b> element is true, <em>AND</em> </li> +<li>all <b>require</b> elements are true, <em>AND</em> </li> +<li>no <b>deny</b> element is true.</li> +</ul> +<p>If a condition resolves to false during processing, the respective element will be ignored.</p> +<p>Let's modify the example from the <a class="el" href="cp_SWComponents.html#cp_CreatePDSC">Create PDSC File</a> section by adding the requirement for a CMSIS-RTOS and libraries that are specific to a certain Cortex-M class core:</p> +<ul> +<li><code>mylib_cm0.lib</code> for use with a Cortex-M0 and Cortex-M0+ processor</li> +<li><code>mylib_cm3.lib</code> for use with a Cortex-M3 processor</li> +<li><code>mylib_cm4.lib</code> for use with a Cortex-M4 or Cortex-M7 processor</li> +</ul> +<p>Copy the <em>content</em> of the <b>02_Conditions</b> directory of the <b>Pack_with_Software_Components.zip</b> file to the <b>Files</b> directory in your working environment: </p> +<ol> +<li> +Add a <a class="el" href="pdsc_conditions_pg.html"><conditions></a> section with the following: <div class="fragment"><div class="line"><conditions> </div> +<div class="line"> <condition <span class="keywordtype">id</span>=<span class="stringliteral">"ARM Compiler"</span>></div> +<div class="line"> <require Tcompiler=<span class="stringliteral">"ARMCC"</span>/></div> +<div class="line"> </condition></div> +<div class="line"> <condition <span class="keywordtype">id</span>=<span class="stringliteral">"CM0"</span>></div> +<div class="line"> <description>Cortex-M0 based device</description></div> +<div class="line"> <require condition=<span class="stringliteral">"ARM Compiler"</span>/></div> +<div class="line"> <accept Dcore=<span class="stringliteral">"Cortex-M0"</span>/></div> +<div class="line"> <accept Dcore=<span class="stringliteral">"Cortex-M0+"</span>/></div> +<div class="line"> </condition></div> +<div class="line"> <condition <span class="keywordtype">id</span>=<span class="stringliteral">"CM3"</span>></div> +<div class="line"> <description>Cortex-M3 based device</description></div> +<div class="line"> <require condition=<span class="stringliteral">"ARM Compiler"</span>/></div> +<div class="line"> <accept Dcore=<span class="stringliteral">"Cortex-M3"</span>/></div> +<div class="line"> </condition></div> +<div class="line"> <condition <span class="keywordtype">id</span>=<span class="stringliteral">"CM4_CM7"</span>></div> +<div class="line"> <description>Cortex-M4 based device</description></div> +<div class="line"> <require condition=<span class="stringliteral">"ARM Compiler"</span>/></div> +<div class="line"> <accept Dcore=<span class="stringliteral">"Cortex-M4"</span>/></div> +<div class="line"> <accept Dcore=<span class="stringliteral">"Cortex-M7"</span>/></div> +<div class="line"> </condition></div> +<div class="line"> <condition <span class="keywordtype">id</span>=<span class="stringliteral">"CMSIS Core with RTOS"</span>></div> +<div class="line"> <description>CMSIS Core with RTOS <span class="keywordflow">for</span> Cortex-M processor</description></div> +<div class="line"> <accept condition=<span class="stringliteral">"CM0"</span>/></div> +<div class="line"> <accept condition=<span class="stringliteral">"CM3"</span>/></div> +<div class="line"> <accept condition=<span class="stringliteral">"CM4_CM7"</span>/></div> +<div class="line"> <require Cclass=<span class="stringliteral">"CMSIS"</span> Cgroup=<span class="stringliteral">"Core"</span>/></div> +<div class="line"> <require Cclass=<span class="stringliteral">"CMSIS"</span> Cgroup=<span class="stringliteral">"RTOS"</span>/></div> +<div class="line"> </condition></div> +<div class="line"></conditions></div> +</div><!-- fragment --> </li> +<li> +Change the first line of the already existing <b>component</b> by adding the condition and increasing the version number of the component: <div class="fragment"><div class="line"><component Cclass=<span class="stringliteral">"MyClass"</span> Cgroup=<span class="stringliteral">"MyGroup"</span> Csub=<span class="stringliteral">"MySubGroup"</span> Cversion=<span class="stringliteral">"1.0.1"</span> condition=<span class="stringliteral">"CMSIS Core with RTOS"</span>></div> +</div><!-- fragment --> </li> +<li> +Add the following code to the already existing <b>component</b>: <div class="fragment"><div class="line"><file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM0"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm0.lib"</span>/></div> +<div class="line"><file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM3"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm3.lib"</span>/></div> +<div class="line"><file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM4_CM7"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm4.lib"</span>/></div> +</div><!-- fragment --> Note that library files should always have a condition with regards to a specific C/C++ compiler. To accomplish this, each processor condition has the additional requirement for the Arm C/C++ compiler. </li> +<li> +Add a new version number to the header of the PDSC file so that a Pack with a new version number will be created: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.1"</span>></div> +<div class="line"> Conditions added</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.0.</p> +<div class="image"> +<img src="ConditionsDisplay.png" alt="ConditionsDisplay.png"/> +<div class="caption"> +Display of conditionally added files for a Cortex-M3 device in development tools</div></div> + </li> +</ol> +<dl class="section note"><dt>Note</dt><dd>PackChk.exe will will now display an <b>M362</b> warning: <div class="fragment"><div class="line"> WARNING M362: (Line 80)</div> +<div class="line"> Not all Component Dependencies <span class="keywordflow">for</span> <span class="stringliteral">'Cclass=MyClass, Cgroup=MyGroup, Csub=MySubGroup, Cversion=1.0.1, Capiversion='</span> can be resolved.</div> +<div class="line">M502: RTE Model reports: #error 511: MyVendor::MyClass:MyGroup:MySubGroup : Additional software components required</div> +<div class="line">M504: RTE Model reports: MISSING: -- require CMSIS:CORE</div> +<div class="line">M504: RTE Model reports: MISSING: -- require CMSIS:RTOS</div> +</div><!-- fragment --> This is because it cannot resolve and check dependencies on components that are not part of this Pack (in this case the CMSIS components CORE and RTOS). You can either safely ignore these warnings or include the ARM.CMSIS.pdsc in the checking process, so that the correctness of the references to the CMSIS pack can be validated. <div class="fragment"><div class="line">PackChk.exe <InFile.pdsc> -i <path to installed CMSIS pack>\ARM.CMSIS.pdsc</div> +</div><!-- fragment --></dd></dl> +<h1><a class="anchor" id="cp_Variants"></a> +Variants</h1> +<p>Software components may have <b>variants</b>, for example:</p> +<ul> +<li>Debug version with or release version without diagnostic output</li> +<li>Long/short file names</li> +<li>Fast/slow modes</li> +</ul> +<p>Variants are mutually exclusive (only one variant can be chosen at a time). <code>Cvariant</code> is an optional part of the component ID. The variant specifier is a brief string (e.g. <code>release</code>, <code>debug</code>).</p> +<dl class="section note"><dt>Note</dt><dd>Version management relies on variants to <b>remain unchanged between versions</b>.</dd></dl> +<p>The following example introduces a new component to the Pack in two variants: <code>debug</code> and <code>release</code>. Copy the <em>content</em> of the <b>03_Variants</b> directory of the <b>Pack_with_Software_Components.zip</b> file to the <b>Files</b> directory in your working environment. </p> +<ol> +<li> +Add the following lines to the <b>components</b> section in your PDSC file: <div class="fragment"><div class="line"><component Cclass=<span class="stringliteral">"MyVariant"</span> Cgroup=<span class="stringliteral">"MyGroup"</span> Cvariant=<span class="stringliteral">"Release"</span> Cversion=<span class="stringliteral">"1.0.2"</span> condition=<span class="stringliteral">"CMSIS Core with RTOS"</span>></div> +<div class="line"> <description>Release version of MyVariant</description></div> +<div class="line"> <RTE_Components_h></div> +<div class="line"> <!-- the following content goes into file <span class="stringliteral">'RTE_Components.h'</span> --></div> +<div class="line"> #define RTE_MyVariant_Release <span class="comment">/* MyVariant Release Version */</span></div> +<div class="line"> </RTE_Components_h></div> +<div class="line"> <files></div> +<div class="line"> <file category=<span class="stringliteral">"doc"</span> name=<span class="stringliteral">"Docs/MySWComp.htm"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/header_mylib.h"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/config/config_mylib.h"</span> attr=<span class="stringliteral">"config"</span> version=<span class="stringliteral">"1.0.0"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/mylib_one.c"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/mylib_two.c"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM0"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm0.lib"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM3"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm3.lib"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM4_CM7"</span> name=<span class="stringliteral">"MySWComp/Lib/mylib_cm4.lib"</span>/></div> +<div class="line"> </files></div> +<div class="line"></component></div> +<div class="line"><component Cclass=<span class="stringliteral">"MyVariant"</span> Cgroup=<span class="stringliteral">"MyGroup"</span> Cvariant=<span class="stringliteral">"Debug"</span> Cversion=<span class="stringliteral">"1.0.2"</span> condition=<span class="stringliteral">"CMSIS Core with RTOS"</span>></div> +<div class="line"> <description>Debug version of MyVariant</description></div> +<div class="line"> <RTE_Components_h></div> +<div class="line"> <!-- the following content goes into file <span class="stringliteral">'RTE_Components.h'</span> --></div> +<div class="line"> #define RTE_MyVariant_Debug <span class="comment">/* MyVariant Debug Version */</span></div> +<div class="line"> </RTE_Components_h></div> +<div class="line"> <files></div> +<div class="line"> <file category=<span class="stringliteral">"doc"</span> name=<span class="stringliteral">"Docs/MySWComp.htm"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/header_mylib.h"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"MySWComp/config/debug_config_mylib.h"</span> attr=<span class="stringliteral">"config"</span> version=<span class="stringliteral">"1.0.0"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/debug_mylib_one.c"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/debug_mylib_two.c"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM0"</span> name=<span class="stringliteral">"MySWComp/Lib/debug_mylib_cm0.lib"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM3"</span> name=<span class="stringliteral">"MySWComp/Lib/debug_mylib_cm3.lib"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"library"</span> condition=<span class="stringliteral">"CM4_CM7"</span> name=<span class="stringliteral">"MySWComp/Lib/debug_mylib_cm4.lib"</span>/></div> +<div class="line"> </files></div> +<div class="line"></component></div> +</div><!-- fragment --> </li> +<li> +Add a new revision to reflect the changes in a newly generated Pack: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.2"</span>></div> +<div class="line"> Variants introduced</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.1.</p> +<div class="image"> +<img src="VariantDisplay.png" alt="VariantDisplay.png"/> +<div class="caption"> +Display of MyVariant in development tools</div></div> + </li> +</ol> +<h1><a class="anchor" id="cp_RTEComponents_h"></a> +RTE_Components.h</h1> +<p>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: <b>RTE_Components.h</b>. To add a line of C code to this header file, simply add this to your component:</p> +<pre class="fragment"><RTE_Components_h> + #define RTE_MyVariant_Debug /* MyVariant Debug Version */ +</RTE_Components_h> +</pre><p> The <code>#define</code> can be checked by other components in a project.</p> +<dl class="section note"><dt>Note</dt><dd>The RTE_components.h file needs to be included somewhere in your source files. Refer to <a class="el" href="pdsc_components_pg.html#RTE_Components_h">RTE_Components.h</a> for more information.</dd></dl> +<h1><a class="anchor" id="cp_Bundles"></a> +Bundles</h1> +<p>A bundle is basically a variant on the <code>Cclass</code> level. It specifies the attributes <code>Cclass</code>, <code>Cversion</code> and optionally <code>Cgroup</code> and <code>Cvendor</code> 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 <code>Cclass</code> from different solutions. In addition to components, a bundle has the mandatory elements <code>description</code> and <code>doc</code> (for documentation).</p> +<p>An example of a <b>bundle</b> is shown in the <a class="el" href="createPackBoard.html#cp_BundleExample">Create a BSP Bundle</a> section where the bundle is used to deliver board support files for a certain development platform.</p> +<h1><a class="anchor" id="cp_Instances"></a> +Instances</h1> +<p>Some <a class="el" href="pdsc_components_pg.html">software components</a> allow several instances. This is useful if more than one peripheral can be connected.</p> +<ol> +<li> +Adding the information about a maximum number of instances is easy. Change the first component (::MyClass:MyGroup:MySub) as follows: <div class="fragment"><div class="line"><component Cclass=<span class="stringliteral">"MyClass"</span> Cgroup=<span class="stringliteral">"MyGroup"</span> Csub=<span class="stringliteral">"MySubGroup"</span> Cversion=<span class="stringliteral">"1.0.3"</span> condition=<span class="stringliteral">"CMSIS Core with RTOS"</span> maxInstances=<span class="stringliteral">"3"</span>></div> +</div><!-- fragment --> </li> +<li> +Add a new version number: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.3"</span>></div> +<div class="line"> Maximum number of instances specified</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> 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.</p> +<div class="image"> +<img src="maxInstancesDisplay.png" alt="maxInstancesDisplay.png"/> +<div class="caption"> +Display of component instances in development tools</div></div> + </li> +</ol> +<h1><a class="anchor" id="cp_API"></a> +API Interface</h1> +<p>An <a class="el" href="pdsc_apis_pg.html">API</a> 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.</p> +<p>Copy the <em>content</em> of the <b>05_APIs</b> directory of the <b>Pack_with_Software_Components.zip</b> file to the <b>Files</b> directory in your working environment: </p> +<ol> +<li> +Add a <a class="el" href="pdsc_apis_pg.html"><apis></a> section with the following: <div class="fragment"><div class="line"><api Cclass=<span class="stringliteral">"Device"</span> Cgroup=<span class="stringliteral">"MyAPI"</span> exclusive=<span class="stringliteral">"0"</span>></div> +<div class="line"> <description>API <span class="keywordflow">for</span> MyAPI</description></div> +<div class="line"> <files></div> +<div class="line"> <file category=<span class="stringliteral">"doc"</span> name=<span class="stringliteral">"Docs/API/MyAPI.htm"</span>/></div> +<div class="line"> <file category=<span class="stringliteral">"header"</span> name=<span class="stringliteral">"API/Include/MyAPI.h"</span>/></div> +<div class="line"> </files></div> +<div class="line"> </api></div> +</div><!-- fragment --> </li> +<li> +Add a new version number: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.4"</span>></div> +<div class="line"> MyAPI added</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.3. Most likely, you will see none as APIs are not selectable and are thus not displayed in the tools. </li> +</ol> +<h1><a class="anchor" id="cp_CodeTemplates"></a> +User Code Templates</h1> +<p>User code templates provide a quick start for implementing an application. To add user code templates, add source files with the attribute <code>attr=“template”</code> in a <code><component></code>. The <code>select</code> attribute is used to identify template files. Template files with the same <code>select</code> attribute will be added to a project simultaneously.</p> +<p>Copy the <em>content</em> of the <b>06_User_Code_Templates</b> directory of the <b>Pack_with_Software_Components.zip</b> file to the <b>Files</b> directory in your working environment: </p> +<ol> +<li> +Add the following code to both variants (<code>debug</code> and <code>release</code>) of the ::MyVariant:MyGroup component: <div class="fragment"><div class="line"><file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/Templates/mylib_template1.c"</span> attr=<span class="stringliteral">"template"</span> select=<span class="stringliteral">"Easy Template"</span>/></div> +<div class="line"><file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/Templates/mylib_template2.c"</span> attr=<span class="stringliteral">"template"</span> select=<span class="stringliteral">"Complex Template"</span>/></div> +<div class="line"><file category=<span class="stringliteral">"source"</span> name=<span class="stringliteral">"MySWComp/Templates/mylib_template3.c"</span> attr=<span class="stringliteral">"template"</span> select=<span class="stringliteral">"Complex Template"</span>/></div> +</div><!-- fragment --> </li> +<li> +Add a new version number: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.5"</span>></div> +<div class="line"> User Code Templates added</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.4.</p> +<div class="image"> +<img src="UserCodeTemplatesDisplay.png" alt="UserCodeTemplatesDisplay.png"/> +<div class="caption"> +Display of user code templates in development tools</div></div> + </li> +</ol> +<h1><a class="anchor" id="cp_Examples"></a> +Example Projects</h1> +<p>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 <code>Cclass</code>, <code>Cgroup</code>, <code>Csub</code> and <code>Cversion</code>. The <b><project></b> element contains the names of the supported development tools and the project files to be loaded.</p> +<p>Copy the <em>content</em> of the <b>07_Example_Projects</b> directory of the <b>Pack_with_Software_Components.zip</b> file to the <b>Files</b> directory in your working environment: </p> +<ol> +<li> +Add an <a class="el" href="pdsc_examples_pg.html"><examples></a> section with the following: <div class="fragment"><div class="line"><examples></div> +<div class="line"> <example name=<span class="stringliteral">"MyDevBoard Example"</span> doc=<span class="stringliteral">"Abstract.txt"</span> folder=<span class="stringliteral">"MyPackExample"</span>></div> +<div class="line"> <description>CMSIS-RTOS based example</description></div> +<div class="line"> <board name=<span class="stringliteral">"MyDevBoard"</span> vendor=<span class="stringliteral">"MyVendor"</span>/></div> +<div class="line"> <project></div> +<div class="line"> <environment name=<span class="stringliteral">"uv"</span> load=<span class="stringliteral">"MyPackExample.uvprojx"</span>/></div> +<div class="line"> </project></div> +<div class="line"> <attributes></div> +<div class="line"> <component Cclass=<span class="stringliteral">"CMSIS"</span> Cgroup=<span class="stringliteral">"Core"</span>/></div> +<div class="line"> <component Cclass=<span class="stringliteral">"Device"</span> Cgroup=<span class="stringliteral">"Startup"</span>/></div> +<div class="line"> <component Cclass=<span class="stringliteral">"CMSIS"</span> Cgroup=<span class="stringliteral">"RTOS"</span>/></div> +<div class="line"> <component Cclass=<span class="stringliteral">"MyVariant"</span> Cgroup=<span class="stringliteral">"MyGroup"</span>/></div> +<div class="line"> </attributes></div> +<div class="line"> </example></div> +<div class="line"></examples></div> +</div><!-- fragment --> </li> +<li> +Add a new version number: <div class="fragment"><div class="line"><release version=<span class="stringliteral">"1.0.6"</span>></div> +<div class="line"> Example project added</div> +<div class="line"></release></div> +</div><!-- fragment --> </li> +<li> +<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <b>gen_pack.bat</b> script. See <a class="el" href="cp_SWComponents.html#cp_GeneratePack">Generate a Pack</a> for further details. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.5.</p> +<div class="image"> +<img src="ExampleDisplay.png" alt="ExampleDisplay.png"/> +<div class="caption"> +Display of example projects in development tools</div></div> + </li> +</ol> +<p>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. <a class="el" href="createPackBoard.html">Pack with Board Support</a> explains how to integrate boards into a Pack. </p> +</div></div><!-- contents --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="footer">Generated on Wed Aug 1 2018 17:12:42 for CMSIS-Pack by Arm Ltd. All rights reserved. + <!-- + <a href="http://www.doxygen.org/index.html"> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6 + --> + </li> + </ul> +</div> +</body> +</html> |