-
Notifications
You must be signed in to change notification settings - Fork 3
/
README_svd2regbits.html
222 lines (153 loc) · 19.1 KB
/
README_svd2regbits.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
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
<h1 id="readmeforsvd2regbits.py">README for svd2regbits.py</h1>
<p><strong>svd2regbits.py</strong> is a tool to convert CMSIS System View Description (SVD) files into <a href="README.md">regbits</a> C++ header files.</p>
<h2 id="copyrightanamecopyrighta">Copyright <a name="copyright"></a ></h2>
<p>regbits: C++ templates for type-safe bit manipulation
Copyright (C) 2019,2020 Mark R. Rubin</p>
<p>This file is part of regbits.</p>
<p>The regbits program is free software: you can redistribute it
and/or modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.</p>
<p>The regbits program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.</p>
<p>You should have received a copy of the GNU General Public License
(LICENSE.txt) along with the regbits program. If not, see
<a href="https://www.gnu.org/licenses/gpl.html">https://www.gnu.org/licenses/gpl.html</a>.</p>
<h2 id="contentsanamecontentsa">Contents <a name="contents"></a></h2>
<ul>
<li><a href="#copyright">Copyright</a></li>
<li><a href="#svd_and_svd2regbits.py">SVD and svd2regbits.py</a>
<ul>
<li><a href="#disclosure">Disclosure</a></li>
<li><a href="#design_and_documentation">Design and documentation</a></li>
<li><a href="#svd2regbits_py">svd2regbits.py</a></li>
<li><a href="#dim_vs_dim_index"><code><dim></code>/<code>[%s]</code> arrays vs <code><dimIndex></code>/<code>%s</code> lists vs <code><derivedFrom></code></a></li>
<li><a href="#svd2regbits.py_`<derivedFrom>`_limitations">svd2regbits.py <code><derivedFrom></code> limitations</a></li>
<li><a href="#Missing_`<headerStructName>`_tags">Missing <code><headerStructName></code> tags</a></li>
<li><a href="#unconvertible_svd_constructs">Unconvertible SVD constructs</a></li>
<li><a href="#size_and_alignment_errors">Size and alignment errors</a></li>
<li><a href="#svds_file_quality">SVDs file “quality”</a></li>
</ul></li>
<li><a href="#credits">Credits</a></li>
</ul>
<h2 id="svdandsvd2regbits.pyanamesvd_and_svd2regbits.pya">SVD and svd2regbits.py <a name="svd_and_svd2regbits.py"></a></h2>
<p><a name="disclosure"></a></p>
<h4 id="disclosure">Disclosure</h4>
<p>This document includes highly opinionated comments and occasional criticisms regarding the design of the SVD standard and its implementation in many existing SVD file implementations. All statements are strictly the author’s opinion and do not in any way reflect the views of the individuals and organizations listed <a href="#credits">below</a>.</p>
<p><a name="design_and_documentation"></a></p>
<h3 id="designanddocumentation">Design and documentation</h3>
<p>The design of the SVD file format, and its related documentation, is in general highly commendable. The design is exceptionally complete and general, covering a wide range of disparate use cases. Likewise,the documentation is among the best <a href="#footnote_1"><sup>1</sup></a> that exists in the realm of embedded software.</p>
<p>That said, neither are perfect. The documentation is unclear and/or ambiguous several places. That, and more importantly, the complexity of the format almost guarantees that many creators of SVD files will make serious mistakes <a href="#footnote_2"><sup>2</sup></a>. Such files are frequently semantically incorrect or at minimum “clumsy” and non-optimal, and often even syntactically malformed on some level.</p>
<h3 id="svd2regbits.pyanamesvd2regbits_pya">svd2regbits.py <a name="svd2regbits_py"></a></h3>
<p>The current <a href="svd2regbits.py">svd2regbits.py</a> program should be considered an early beta release. It is missing several important capabilities, and likewise doesn’t handle (or handles poorly) several SVD features. The intent is that many of these failings will be addressed in future releases, although not all (see <a href="#unconvertible_svd_constructs">below</a>).</p>
<p>The general intent, both currently and for the future, is to “fix” incorrect and/or untranslatable SVD file features when strictly necessary, but to “drop” all others (malformed, or other elements that svd2regbits.py cannot handle, will not appear in the regbits .hxx file output). Warning messages will be printed in both cases. Specifically, constructs which the author (rightly or wrongly) considers in violation of the documented SVD file format will be removed. Several examples of these are described in the following sections.</p>
<p>In terms of testing, the current svd2regbits.py successfully converts all SVD examples in the <a href="https://github.com/posborne/cmsis-svd/tree/master/data">posborne/cmsis-dvd/data</a> repository (see <a href="#credits">Credits</a>, below) as of this writing, and all compile with the exception of two which contain “svd2regbits-will-not-attempt-to-fix” typos <a href="#footnote_3"><sup>3</sup></a>. Whether or not the resulting regbits .hxx files contain correct addresses, offsets, register layouts, and/or bitfield descriptions is another question entirely.</p>
<p><a name="dim_vs_dim_index"></a></p>
<h3 id="dimsarraysvsdimindexslistsvsderivedfrom"><code><dim></code>/<code>[%s]</code> arrays vs <code><dimIndex></code>/<code>%s</code> lists vs <code><derivedFrom></code></h3>
<p>This is the most frequent misuse/misinterpretation of the complex SVD format. The documentation clearly states (for <code><cluster></code>, <code><register></code>, and <code><field</code>> elements):</p>
<p><em>name:</em> … <em>You can use the placeholder %s, which is replaced by the dimIndex substring. Use the placeholder [%s] only at the end of the identifier to generate arrays in the header file. The placeholder [%s] cannot be used together with dimIndex.</em></p>
<p>and:</p>
<p><em>dimIndex: Specify the substrings that replaces the %s placeholder within name and displayName. By default, the index is a decimal value starting with 0 for the first register. dimIndex should not be used together with the placeholder [%s], but rather with %s.</em></p>
<p>Despite this clarity, many existent SVD files contain elements with <code><name></code> tags containing <code>%s</code> but no corresponding <code><dimIndex></code>, and vice-versa (<code>[%s]</code> with <code><dimIndex></code>). Also <code>%s</code> with <code><dim></code> in addition to <code><dimIndex></code> (which is the correct size? <code><dim></code> or the number of the <code><dimIndex></code> values?) and other such horrors.</p>
<p>In addition, there is almost universal “misuse” of <code>%s</code> with e.g. <code><dimIndex>0,1,2,3</dimIndex></code> which conceptually should be replaced (in this example) with <code>[%s]</code> and <code><dim>4</dim></code>. Admittedly this is both a question of style (whether individually-named elements vs a singly-named array is desired), and also somewhat regbits specific where e.g. <code>ARRAY[2]</code> is safely range-checked at compile time without any impact on executable code size or speed compared to <code>NAME_2</code>.</p>
<p>Also note that <code><peripheral></code> elements are clearly documented as only allowing <code>[%s]</code>, not <code>%s</code> <a href="#footnote_4"><sup>4</sup></a>.</p>
<p>Partly due to current limitations <a href="#footnote_5"><sup>5</sup></a> of regbits, the problems are handled as follows:</p>
<ul>
<li><code><peripheral></code>: Illegal <code>%s</code> and/or missing <code><dim></code> or <code><dimIncrement></code> ignored/removed, otherwise handled correctly.</li>
<li><code><cluster></code> and <code><register></code>: Ignored if more than one <code>%s</code> and/or <code>[%s]</code> <a href="#footnote_6"><sup>6</sup></a>. If <code>[%s]</code> and <code><dimIndex></code>, <code>[%s]</code> changed to <code>%s</code> and <code><dimIndex></code> used. Ignored if <code>%s</code> without <code>dimIndex</code>. Otherwise handled correctly by expanding <code>%s</code>/<code><dimIndex></code> as separately-named elements, or <code>[%s]</code>/<code><dim></code> as array.</li>
<li><code><field></code>: Always expanded as separate <code>%s</code>/<code><dimIndex></code> names (including implicit rewrite of <code>[%s]</code>/<code><dim></code> to <code>%s</code>/<code><dimIndex></code> if the former) due to current regbits limitation <a href="#footnote_5"><sup>5</sup></a>.</li>
</ul>
<p><a name="svd2regbits.py_`<derivedFrom>`_limitations"></a></p>
<h3 id="svd2regbits.pyderivedfromlimitations">svd2regbits.py <code><derivedFrom></code> limitations</h3>
<p>The current svd2regbits.py converter intentionally misinterprets <code><derivedFrom></code> tags in <code><peripheral></code>, <code><cluster></code>, and <code><register></code> elements, effectively treating them as “clonedFrom” or “copyOf”, i.e. without modification or overriding. (It also completely ignores <code><derivedFrom></code> in <code><field></code> and <code><enumeratedValue></code> elements.)</p>
<p>The <code><derivedFrom></code> tag adds useful the capabilities to the design of SVD format, but is very difficult to implement fully in an SVD-to-C/C++ converter. This is especially true if the converter attempts to create single struct/object definitions for multiple SVD elements which are identical instead of blindly expanding a possibly deep <code><derivedFrom></code> tree without analysis of what, if anything, is being added/overridden.</p>
<p>Future releases of svd2regbits.py should have improvements regarding the issue.</p>
<p>In addition, svd2regbits.py cannot handle “retrograde” <code><derivedFrom></code> addresses. C++ (and C) peripheral structs must have their registers/clusters in address order because they must know the type of each sub-object as it is instantiated (forward declaration does not work in this situation). For example, if an SVD file has:</p>
<pre><code> <peripheral>
<name>SOME_PERIPHERAL</name>
<register>
<name>FIRST_OF_THIS_TYPE</name>
<addressOffset>0x20</addressOffset>
...
</register>
...
<register derivedFrom FIRST_OF_THIS_TYPE>
<name>SECOND_OF_THIS_TYPE</name>
<addressOffset>0x10</addressOffset>
...
</register>
</peripheral>
</code></pre>
<p>the converted regbits .hxx file will fail to compile:</p>
<pre><code> struct SomePeripheral {
first_of_this_type_t secondOfThisType;
// ...
struct FirstOfThisType {
// ...
};
using first_of_this_type_t = Reg<uint32_t, FirstOfThisType>;
first_of_this_type_t first_of_this_type;
};
</code></pre>
<p>Again, this could be corrected by a “virtual” reordering of the SVD file at conversion time, but the difficulty of doing so will likely remain out of the scope of this converter for the conceivable future, regardless that the problem is specific to svd2regbits.py and does not affect SVD-to-CMSIS converters. (I contend that such SVD files are conceptually misleading and should be
changed anyway – if the ordering is not in fact a typo in the first place.)</p>
<p>Note that the above is a separate issue from the order in the SVD file (although it would also be nice if SVD writers respected address order, thus allowing linear “stream” parsing of the files).</p>
<p><a name="Missing_`<headerStructName>`_tags"></a></p>
<h3 id="missingheaderstructnametags">Missing <code><headerStructName></code> tags</h3>
<p>A problem with many existing SVD files (not the SVD standard itself) is the lack of <code><headerStructName></code> tags, particularly in <code><derivedFrom></code> peripherals where they would be most useful. The SVD documentation clearly states:</p>
<p><em>headerStructName: Specify the base name of C structures. The headerfile generator uses the name of a peripheral as the base name for the C structure type. If <headerStructName> element is specfied, then this string is used instead of the peripheral name; useful when multiple peripherals get derived and a generic type name should be used.</em></p>
<p>Failure to include meaningful <code><headerStructName></code> tags results in C/C++ pointers in converted files with confusingly inaccurate types, such the following in a regbits/C++/.hxx file:</p>
<pre><code> static volatile GenTim2* gen_tim_4 = reinterpret_cast<volatile GenTim2*>(TIM4_BASE);
</code></pre>
<p>or the equivalent in a CMSIS .h header file:</p>
<pre><code> #define TIM4 ((TIM2_TypeDef *)TIM4_BASE)
</code></pre>
<p>Note that, ironically, the <code><groupName></code> tag <em>is</em> often included but cannot be used as a substitute for <code><headerStructName></code> as it is frequently more “generic” (e.g. all timers being given <code><groupName>TIMER</groupname></code> tags despite the various timers belonging to conceptually and C/C++ struct/class different sub-types).</p>
<p><a name="unconvertible_svd_constructs"></a></p>
<h3 id="unconvertiblesvdconstructs">Unconvertible SVD constructs</h3>
<p>The SVD file format allows the description of elements that while syntactically and semantically correct cannot be converted into C/C++ structs without extensive reinterpretation. For example, consider the following pathological case:</p>
<pre><code> <register>
<name>A[%s]</name>
<addressOffset>0x20</addressOffset>
<size>32</size>
<dim>4</dim>
<dimIncrement>8</dimIncrement>
...
</register>
<register>
<name>B[%s]</name>
<addressOffset>0x24</addressOffset>
<size>32</size>
<dim>4</dim>
<dimIncrement>8</dimIncrement>
...
</register>
</code></pre>
<p>Of course these interleaved registers should be more properly written as a <code><cluster></code> containing “A” and “B” and <code><dim>4</dim></code>, but while the above is perfectly legal SVD, it cannot be converted without an A.I.-level analysis and implicit rewrite.</p>
<p><a name="size_and_alignment_errors"></a></p>
<h3 id="sizeandalignmenterrors">Size and alignment errors</h3>
<p>Many existent SVD files contain obvious alignment and/or size errors, such as 16, 32, 64 bit registers with <code><addressOffset></code> values that are not 2, 4, 8 bit aligned. I understand that some ARM (and other) CPUs can handle misaligned data, but other evidence in the files imply that the misalignments are in fact typos or misunderstandings.</p>
<p><a name="svds_file_quality"></a></p>
<h3 id="svdsfilequality">SVDs file “quality”</h3>
<p>As noted in the SVD documentation, the “quality” of an SVD file is a separate issue from its correctness. An SVD file can be syntactically and semantically correct but if it is missing <code><field></code> and/or <code><enumeratedValue></code> elements it will likely be of little use, both in and of itself and after conversion to a usable format such as CMSIS header or regbits .hxx file <a href="#footnote_7"><sup>7</sup></a>. “Garbage in, garbage out” as the saying from the dawn of computing goes.</p>
<h2 id="creditsanamecreditsa">Credits <a name="credits"></a></h2>
<p>Many thanks to:</p>
<ul>
<li><a href="https://github.com/gzigzigzeo">gzigzigzeo</a> for informing me about the existence of SVD files (<a href="https://github.com/thanks4opensource/regbits_stm/issues/1">Generate RegBits definitions from SVD #1</a>)</li>
<li><a href="https://github.com/posborne">posborne</a> for his excellent work creating and maintaining his <a href="https://github.com/posborne/cmsis-svd/">CMSIS-SVD Repository and Parsers</a></li>
<li><a href="https://www.arm.com/">Arm Limited</a> and/or <a href="https://www.keil.com/">armKeil</a> <a href="#footnote_8"><sup>8</sup></a> for creating and making publicly available <a href="#footnote_9"><sup>9</sup></a> SVD and its documentation (<a href="https://arm-software.github.io/CMSIS_5/SVD/html/index.html">System View Description</a>, <a href="https://www.keil.com/pack/doc/CMSIS/SVD/html/index.html">System View Description</a>).</li>
</ul>
<h2 id="footnotes">Footnotes</h2>
<ol>
<li><a name="footnote_1"></a> Given the quality level of most embedded documentation, this is unfortunately a very low hurdle to clear.</li>
<li><a name="footnote_2"></a> And they do. Lots of them.</li>
<li><a name="footnote_3"></a> Not to name any names, but a company whose initials begin with “S” and “T” and end with “M” shouldn’t include multiple <code><interrupt></code> elements with the same <code><name></code> but different <code><value></code> values. To be fair, these obvious typos affect only two of the 87 STM SVD examples tested.</li>
<li><a name="footnote_4"></a> I have not seen any examples that violate this rule, nor in fact any arrays of <code><peripheral></code> at all. Once again the possibility that the SVD standard is more complex than necessary, in this case with <code><peripheral></code> arrays being a subset of the <code><derivedFrom></code> semantics.</li>
<li><a name="footnote_5"></a> Which will be addressed in an upcoming release.</li>
<li><a name="footnote_6"></a> What does having both <code>%s</code> and <code>[%s]</code> in a <code><cluster></code> or <code><register></code> name mean? Multiple <code><dimIndex></code>-replaced names each being a <code><dim></code> array, or an array of <code><dimIndex></code> names in an implicit <code><cluster></code>?</li>
<li><a name="footnote_7"></a> I find it ironic that STM, which does a fair job of <code>#define</code>-ing field values in its CMSIS headers (although only for single bit fields, completely giving up on multiple regardless of whether wide and semantically an integer vs. narrow with a small number of enumerated encoded values) (and likewise has no <code><enumeratedValue></code> tags in its SVD files), while NXP which at least in the CMSIS headers for the older, low-end LPC series chips I’ve seen has no field descriptions at all nevertheless supplies <code><field></code> tags with <code><description></code> and <code><enumeratedValue></code> elements in its SVDs. (Their CMSIS headers aren’t generated from the SVDs?)</li>
<li><a name="footnote_8"></a> The creation, history, and ownership of SVD is unclear to me.</li>
<li><a name="footnote_9"></a> Likewise its licensing terms, other than the Apache license in the published <a href="https://arm-software.github.io/CMSIS_5/SVD/html/schema_1_2_gr.html">CMSIS-SVD Schema File</a>, <a href="https://www.keil.com/pack/doc/CMSIS/SVD/html/schema_1_2_gr.html">CMSIS-SVD Schema File</a></li>
</ol>