summaryrefslogtreecommitdiff
path: root/docs/Pack/html/createPackBoard.html
blob: 33aa415b6ffa6040151d1e7feb21441b49627a7c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<!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>