CMSIS/Documentation/SVD/html/group__cluster_level__gr.html


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

<!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>Cluster Level</title>
<title>CMSIS-SVD: Cluster Level</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);
</script>
<link href="stylsheetf" rel="stylesheet" type="text/css" />
</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-SVD
   &#160;<span id="projectnumber">Version 1.3.1</span>
   </div>
   <div id="projectbrief">CMSIS System View Description</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.2 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
      <li><a href="modules.html"><span>Reference</span></a></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('group__cluster_level__gr.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Cluster Level</div>  </div>
<div class="ingroups"><a class="el" href="group__svd___format__1__1__gr.html">SVD Extensions</a></div></div><!--header-->
<div class="contents">
<p><b>Cluster</b> adds an optional sub-level within the CMSIS SVD <em>registers</em> level. A cluster describes a sequence of neighboring registers within a peripheral. A cluster specifies the <em>addressOffset</em> relative to the <em>baseAddress</em> of the peripheral. All <em>register</em> elements within a cluster specify their <em>addressOffset</em> relative to the cluster base address (<em>peripheral:baseAddress + cluster:addressOffset</em>). Multiple <em>&lt;register/&gt;</em> and <em>&lt;cluster&gt;</em> sections may occur in any order. Since version 1.3 of the specification the nesting of <em>&lt;cluster&gt;</em> elements is supported. This means, that within a <em>&lt;cluster&gt;</em> section any number of <em>&lt;register&gt;</em> and <em>&lt;cluster&gt;</em> sections may occur. Nested cluster express hierarchical structures of registers. It is predominantely targeted at the generation of device header files where it allows to create C data structure within the peripheral structure type instead of a flat list of registers. Note that you can also specify an array of a cluster using the <em>&lt;dim&gt;</em> element.</p>
<hr/>
<pre>
<span class="mand"><b>&lt;registers&gt;</b> </span></pre><pre><span class="mand">    <b>&lt;cluster<span class="opt">derivedFrom=<em>identifierType</em></span>&gt;</b>
    <span class="opt">
        <em>&lt;!-- dimElementGroup --&gt; </em>
        &lt;dim&gt;<em>scaledNonNegativeInteger</em>&lt;/dim&gt;
        &lt;dimIncrement&gt;<em>scaledNonNegativeInteger</em>&lt;/dimIncrement&gt;
        &lt;dimIndex&gt;<em>dimIndexType</em>&lt;/dimIndex&gt;
        <em>&lt;!-- end of dimElementGroup --&gt; </em>
    </span>
        &lt;name&gt;<em>identifierType</em>&lt;/name&gt;
        &lt;description&gt;<em>xs:string</em>&lt;/description&gt;
    <span class="opt">
        &lt;headerStructName&gt;<em>identifierType</em>&lt;/headerStructName&gt;
        &lt;alternateCluster&gt;<em>identifierType</em>&lt;/alternateCluster&gt;
    </span>
        &lt;addressOffset&gt;<em>scaledNonNegativeInteger</em>&lt;/addressOffset&gt;</span></pre><pre><span class="mand">        &lt;cluster&gt; ... &lt;/cluster&gt;
        &lt;register&gt; ... &lt;/register&gt;
            ...
    <b>&lt;/cluster&gt;</b>
    <span class="opt">...
    &lt;register&gt;
        ...
    &lt;/register&gt;
    &lt;cluster&gt;
        ...
    &lt;/cluster&gt;
     </span>
<b>&lt;registers&gt;</b> </span>
</pre><table  class="cmtable" summary="Cluster Level Schema">
<tr>
<th>Attribute Name </th><th>Description </th><th>Type </th><th>Occurrence  </th></tr>
<tr>
<td>derivedFrom </td><td>Specifies the name of the cluster from which to inherit the data. Elements being specified underneath will override the inherited values. <br/>
<b>Remarks:</b> When deriving a cluster, it is mandatory to specify at least the name, the description, and the addressOffset. </td><td>registerType </td><td>0..1  </td></tr>
<tr>
<th>Element Name </th><th>Description </th><th>Type </th><th>Occurrence  </th></tr>
<tr class="group1">
<td colspan="4">See <a class="el" href="group__dim_element_group__gr.html">dimElementGroup</a> for details.  </td></tr>
<tr class="group1">
<td align="left">dim </td><td>The value defines the number of elements in an array of clusters.  </td><td>scaledNonNegativeInteger  </td><td>1..1   </td></tr>
<tr class="group1">
<td align="left">dimIncrement </td><td>If <em>dim</em> is specified, this element becomes mandatory. The element specifies the address increment in between two neighboring clusters of the cluster array in the address map. </td><td>scaledNonNegativeInteger  </td><td>1..1   </td></tr>
<tr class="group1">
<td align="left">dimIndex </td><td>Specifies the substrings that replaces the <em>[%s]</em> placeholder within the cluster name. By default, the index is a decimal value starting with 0 for the first cluster element.  </td><td>dimIndexType  </td><td>0..1   </td></tr>
<tr>
<td>name </td><td>String that identifies the cluster. Register names are required to be unique within the scope of a peripheral. Specify <em>[%s]</em> for generating an array in the device header file. </td><td>identifierType  </td><td>1..1   </td></tr>
<tr>
<td>description </td><td>String describing the details of the register. </td><td>xs:string  </td><td>0..1   </td></tr>
<tr>
<td>alternateCluster  </td><td>This tag needs to specify the name of the original description of the register sequence if this cluster provides an alternative description. Otherwise the SVDConv will issue errors. </td><td>identifierType </td><td>0..1   </td></tr>
<tr>
<td>headerStructName  </td><td>This tag specifies the struct type name in the device header file. If not specified, then the name of the cluster will be used. </td><td>identifierType </td><td>0..1   </td></tr>
<tr>
<td>addressOffset </td><td>Value defining the cluster address relative to the <em>baseAddress</em> defined by the peripheral of the register. </td><td>scaledNonNegativeInteger </td><td>1..1   </td></tr>
<tr>
<td>register </td><td>register description </td><td>registerType </td><td>0..*   </td></tr>
<tr>
<td>cluster </td><td>cluster description </td><td>clusterType </td><td>0..*   </td></tr>
</table>
<h1><a class="anchor" id="clusterSection_ex"></a>
Example:</h1>
<div class="fragment"><div class="line">&lt;cluster&gt;</div>
<div class="line">    &lt;dim&gt;4&lt;/dim&gt;</div>
<div class="line">    &lt;dimIncrement&gt;8&lt;/dimIncrement&gt;</div>
<div class="line">    &lt;dimIndex&gt;0-3&lt;/dimIndex&gt;</div>
<div class="line">    &lt;name&gt;TX[%s]&lt;/name&gt;</div>
<div class="line">    &lt;description&gt;Grouping of Transfer data and address&lt;/description&gt;</div>
<div class="line">    &lt;addressOffset&gt;0x40&lt;/addressOffset&gt;</div>
<div class="line">    &lt;<span class="keyword">register</span>&gt;</div>
<div class="line">       &lt;name&gt;TX_DATA&lt;/name&gt;</div>
<div class="line">        ...</div>
<div class="line">       &lt;addressOffset&gt;0x0&lt;/addressOffset&gt;</div>
<div class="line">        ...</div>
<div class="line">    &lt;/<span class="keyword">register</span>&gt;</div>
<div class="line">    &lt;<span class="keyword">register</span>&gt;</div>
<div class="line">        &lt;name&gt;TX_ADDR&lt;/name&gt;</div>
<div class="line">        ...</div>
<div class="line">        &lt;addressOffset&gt;0x4&lt;/addressOffset&gt;</div>
<div class="line">        ...</div>
<div class="line">    &lt;/<span class="keyword">register</span>&gt;</div>
<div class="line">&lt;/cluster&gt;</div>
</div><!-- fragment --><p>The example above describes an array of type TX with 4 elements. TX is a cluster of two consecutive registers with 4 elements. The device header file looks like this:</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line">    ...</div>
<div class="line">    <span class="keyword">struct </span>{</div>
<div class="line">       __IO uint32_t  TX_DATA;</div>
<div class="line">       __IO uint32_t  TX_ADDR;</div>
<div class="line">    } TX[4];</div>
<div class="line">    ...</div>
<div class="line">} ..._Type;</div>
</div><!-- fragment --> </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 Tue Oct 27 2015 14:35:46 for CMSIS-SVD 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.2 
	-->
	</li>
  </ul>
</div>
</body>
</html>