blob: 33aa415b6ffa6040151d1e7feb21441b49627a7c [file] [log] [blame]
<!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 Board Support</title>
<title>CMSIS-Pack: Pack with Board Support</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
&#160;<span id="projectnumber">Version 1.6.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&#160;Page</span></a></li>
<li class="current"><a href="pages.html"><span>Usage&#160;and&#160;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('createPackBoard.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">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</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 Board Support </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>A <a class="el" href="cp_SWComponents.html">Software Pack</a> that contains a <a class="el" href="pdsc_boards_pg.html">&lt;board&gt;</a> element is called Board Support Pack (BSP). A BSP may contain additional <b>Software Components</b>, <b>Example Projects</b>, as well as <b>Code Templates</b>. The typical content of a BSP is:</p>
<ul>
<li>Source code, libraries, header/configuration files for the underlying hardware and documentation (for example user manuals, getting started guides, and schematics).</li>
<li><a class="el" href="cp_SWComponents.html#cp_Examples">Example Projects</a> that show the usage of the development board and its peripherals.</li>
<li><a class="el" href="cp_SWComponents.html#cp_CodeTemplates">User Code Templates</a> that can be used as a starting point for using the development board or the mounted device.</li>
</ul>
<p>This section is a tutorial that explains how to create a BSP. Initially the PDSC file in the BSP only describes an evaluation board. This BSP is then extended to contain also software components that interface with the hardware of the board. Example projects and code templates may be added as described in the section <a class="el" href="cp_SWComponents.html">Pack with Software Components</a>.</p>
<h2>BSP Use Cases </h2>
<p>A BSP is typically provided by a Board Vendor and is used to <b>extend development tools</b> with support for development boards. In general, the BSP enables Board Vendors to distribute tool independent board support for their development platforms.<br/>
BSPs can also be used to provide information for the display on <b>web sites</b>. One example is the new boards page on <a href="http://www.keil.com/boards2/" class="el" target="_blank">www.keil.com/boards2/</a>:</p>
<div class="image">
<img src="BoardsSectionMCB1500.png" alt="BoardsSectionMCB1500.png"/>
<div class="caption">
Board information on a web site extracted from a BSP</div></div>
<h1><a class="anchor" id="cp_SpecDevBoard"></a>
Specify a Development Board</h1>
<p><b>Preparations</b></p>
<ol type="1">
<li>Install the Software Pack <a href="http://www.keil.com/dd2/arm/armcm3/" class="el" target="_blank">Keil::ARMCortex_DFP</a> as this will be required for the BSP to function properly.</li>
<li>Create a working directory on your PC, for example <b>C:\temp\working_bsp</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_Board_Support.zip</b>.</li>
<li>Copy the <em>content</em> of the ZIP file's <b>01_Specify_Dev_Board</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>
<li>Open the <b>MyVendor.MyBSP.pdsc</b> file in an editor.</li>
</ol>
<p><b>Code Example</b> </p>
<ol>
<li>
Add a <a class="el" href="pdsc_boards_pg.html#element_boards">&lt;boards&gt;</a> section in the PDSC file with the following: <div class="fragment"><div class="line">&lt;boards&gt;</div>
<div class="line"> &lt;board vendor=<span class="stringliteral">&quot;MyVendor&quot;</span> name=<span class="stringliteral">&quot;MyDevBoard&quot;</span> revision=<span class="stringliteral">&quot;V1&quot;</span> salesContact=<span class="stringliteral">&quot;sales@keil.com&quot;</span> orderForm=<span class="stringliteral">&quot;http://www.keil.com&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;MyVendor MyDevBoard Board Description&lt;/description&gt;</div>
<div class="line"> &lt;image small=<span class="stringliteral">&quot;Images/MyDevBoard_small.png&quot;</span> large=<span class="stringliteral">&quot;Images/MyDevBoard_large.png&quot;</span>/&gt;</div>
<div class="line"> &lt;book category=<span class="stringliteral">&quot;setup&quot;</span> name=<span class="stringliteral">&quot;Docs/MyDevBoard/MyDevBoard_setup.pdf&quot;</span> title=<span class="stringliteral">&quot;Getting Started&quot;</span>/&gt;</div>
<div class="line"> &lt;book category=<span class="stringliteral">&quot;schematic&quot;</span> name=<span class="stringliteral">&quot;Docs/MyDevBoard/MyDevBoard_schematics.pdf&quot;</span> title=<span class="stringliteral">&quot;Schematics&quot;</span>/&gt;</div>
<div class="line"> &lt;book category=<span class="stringliteral">&quot;manual&quot;</span> name=<span class="stringliteral">&quot;Docs/MyDevBoard/MyDevBoard_um.pdf&quot;</span> title=<span class="stringliteral">&quot;User Manual&quot;</span>/&gt;</div>
<div class="line"> &lt;mountedDevice deviceIndex=<span class="stringliteral">&quot;0&quot;</span> Dvendor=<span class="stringliteral">&quot;ARM:82&quot;</span> Dname=<span class="stringliteral">&quot;ARMCM3&quot;</span>/&gt;</div>
<div class="line"> &lt;compatibleDevice deviceIndex=<span class="stringliteral">&quot;0&quot;</span> Dvendor=<span class="stringliteral">&quot;ARM:82&quot;</span> Dfamily=<span class="stringliteral">&quot;ARM Cortex M3&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;ODbg&quot;</span> n=<span class="stringliteral">&quot;1&quot;</span> name=<span class="stringliteral">&quot;On-board J-LINK Lite&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;PWR&quot;</span> n=<span class="stringliteral">&quot;5&quot;</span> name=<span class="stringliteral">&quot;USB Powered&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;DIO&quot;</span> n=<span class="stringliteral">&quot;8&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;SPI&quot;</span> n=<span class="stringliteral">&quot;1&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;LED&quot;</span> n=<span class="stringliteral">&quot;6&quot;</span> name=<span class="stringliteral">&quot;User LEDs&quot;</span>/&gt;</div>
<div class="line"> &lt;feature type=<span class="stringliteral">&quot;ArduinoFF&quot;</span> n=<span class="stringliteral">&quot;1&quot;</span>/&gt;</div>
<div class="line"> &lt;debugInterface adapter=<span class="stringliteral">&quot;J-Link Lite&quot;</span> connector=<span class="stringliteral">&quot;Mini-USB&quot;</span>/&gt;</div>
<div class="line"> &lt;/board&gt;</div>
<div class="line">&lt;/boards&gt;</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_Specify_Dev_Board</b> directory. </dd></dl>
</li>
<li>
<p class="startli">Finally, save the PDSC file and generate 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.</p>
<div class="image">
<img src="DevBoardDisplay.png" alt="DevBoardDisplay.png"/>
<div class="caption">
Display of development boards in development tools</div></div>
</li>
</ol>
<dl class="section note"><dt>Note</dt><dd>packChk.exe will display <b>M346</b> informations: <pre class="fragment">*** WARNING M346: .\Files\MyVendor.MyBSP.pdsc (Line 29)
Referenced device(s) in 'MyDevBoard' not found: 'ARMCM3'
*** WARNING M346: .\Files\MyVendor.MyBSP.pdsc (Line 29)
Referenced device(s) in 'MyDevBoard' not found: 'ARM Cortex M3'
</pre> This is because this BSP does not contain a device section with the mentioned devices. To work aroung this problem, you might add the ARM:CMSIS PDSC file to the checking process.</dd></dl>
<h1><a class="anchor" id="cp_BundleExample"></a>
Create a BSP Bundle</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>Copy the <em>content</em> of the <b>02_BSP_Bundle</b> directory of the <b>Pack_with_Board_Support.zip</b> file to the <b>Files</b> directory in your working environment: </p>
<ol>
<li>
Add a <code>&lt;conditions&gt;</code> section in your PDSC with the following (the <a class="el" href="cp_SWComponents.html#cp_Conditions">conditions</a> section provides more information on this step): <div class="fragment"><div class="line">&lt;condition <span class="keywordtype">id</span>=<span class="stringliteral">&quot;ARM Cortex M3 Series&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;ARM Cortex M3 device required&lt;/description&gt;</div>
<div class="line"> &lt;require Dfamily=<span class="stringliteral">&quot;ARM Cortex M3&quot;</span> Dvendor=<span class="stringliteral">&quot;ARM:82&quot;</span>/&gt;</div>
<div class="line">&lt;/condition&gt;</div>
<div class="line">&lt;condition <span class="keywordtype">id</span>=<span class="stringliteral">&quot;MyDevBoard Board Setup&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;Board Setup Code required&lt;/description&gt;</div>
<div class="line"> &lt;require condition=<span class="stringliteral">&quot;ARM Cortex M3 Series&quot;</span>/&gt;</div>
<div class="line"> &lt;require Cclass=<span class="stringliteral">&quot;Board Support&quot;</span> Cgroup=<span class="stringliteral">&quot;Board Setup&quot;</span>/&gt;</div>
<div class="line">&lt;/condition&gt;</div>
</div><!-- fragment --> </li>
<li>
Add a <code>&lt;components&gt;</code> section in your PDSC with the following (the <a class="el" href="cp_SWComponents.html#cp_Components">components</a> section provides more information on this step): <div class="fragment"><div class="line">&lt;bundle Cbundle=<span class="stringliteral">&quot;MyDevBoardSupport&quot;</span> Cclass=<span class="stringliteral">&quot;Board Support&quot;</span> Cversion=<span class="stringliteral">&quot;1.0.1&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;MyDevBoard custom board support package&lt;/description&gt;</div>
<div class="line"> &lt;doc&gt;Docs/BSP/MyBSP.htm&lt;/doc&gt;</div>
<div class="line"> &lt;component Cgroup=<span class="stringliteral">&quot;Board Setup&quot;</span> condition=<span class="stringliteral">&quot;ARM Cortex M3 Series&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;Custom board setup code&lt;/description&gt;</div>
<div class="line"> &lt;files&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;doc&quot;</span> name=<span class="stringliteral">&quot;Docs/BSP/Setup.htm&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;header&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Include/setup.h&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;source&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Source/setup.c&quot;</span>/&gt;</div>
<div class="line"> &lt;/files&gt;</div>
<div class="line"> &lt;/component&gt;</div>
<div class="line"> &lt;component Cgroup=<span class="stringliteral">&quot;I/O&quot;</span> Csub=<span class="stringliteral">&quot;LED&quot;</span> condition=<span class="stringliteral">&quot;MyDevBoard Board Setup&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;LED code <span class="keywordflow">for</span> custom board&lt;/description&gt;</div>
<div class="line"> &lt;files&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;doc&quot;</span> name=<span class="stringliteral">&quot;Docs/BSP/LED.htm&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;header&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Include/led.h&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;header&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Include/config_led.h&quot;</span> attr=<span class="stringliteral">&quot;config&quot;</span> version=<span class="stringliteral">&quot;1.0.0&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;source&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Source/led.c&quot;</span>/&gt;</div>
<div class="line"> &lt;/files&gt;</div>
<div class="line"> &lt;/component&gt;</div>
<div class="line"> &lt;component Cgroup=<span class="stringliteral">&quot;I/O&quot;</span> Csub=<span class="stringliteral">&quot;GPIO&quot;</span> condition=<span class="stringliteral">&quot;MyDevBoard Board Setup&quot;</span>&gt;</div>
<div class="line"> &lt;description&gt;GPIO code <span class="keywordflow">for</span> custom board&lt;/description&gt;</div>
<div class="line"> &lt;files&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;doc&quot;</span> name=<span class="stringliteral">&quot;Docs/BSP/GPIO.htm&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;header&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Include/gpio.h&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;header&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Include/config_gpio.h&quot;</span> attr=<span class="stringliteral">&quot;config&quot;</span> version=<span class="stringliteral">&quot;1.0.0&quot;</span>/&gt;</div>
<div class="line"> &lt;file category=<span class="stringliteral">&quot;source&quot;</span> name=<span class="stringliteral">&quot;MySWComp/Source/gpio.c&quot;</span>/&gt;</div>
<div class="line"> &lt;/files&gt;</div>
<div class="line"> &lt;/component&gt;</div>
<div class="line">&lt;/bundle&gt;</div>
</div><!-- fragment --> </li>
<li>
Add a new version number: <div class="fragment"><div class="line">&lt;release version=<span class="stringliteral">&quot;1.0.1&quot;</span>&gt;</div>
<div class="line"> Board support bundle added</div>
<div class="line">&lt;/release&gt;</div>
</div><!-- fragment --> </li>
<li>
<p class="startli">Finally, save the PDSC file and regenerate the Pack file using the <a class="el" href="cp_SWComponents.html#cp_GeneratePack">gen_pack.bat</a> script. Afterwards, install the Pack in your development tool and observe the differences to version 1.0.0.</p>
<div class="image">
<img src="BSPBundleDisplay.png" alt="BSPBundleDisplay.png"/>
<div class="caption">
BSP bundle display in development tools</div></div>
</li>
</ol>
</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 Jul 10 2019 15:21:00 for CMSIS-Pack Version 1.6.0 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>