GenDataModel.txt 16.3 KB
Newer Older
1
2
3
4
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page GenDataModel Generator Data Model 

5
6
7
The <b>Generator Data Model</b> defines the resource and partition data structure for code generators.
This data structure is connected to a FreeMarker template engine and file templates allow to generate
various files that can be used to configure development tools or hardware components.
8
9
10

\image html generator.png "FreeMarker Template Engine"

11
12
\section fp_toplevel FreeMarker top-level format

13
14
\subpage fm_system provides memory layout and TrustZone configuration of the complete system. 
\subpage fm_zone setup information of a zone (or system partition) along with related peripherals.
15

16
17
18
19
20
21
22
23
24
25
26
27
\section fm_basics FreeMarker basics

The variable types relevant for CMSIS-Zone are:

\b scalar: variable that stores a single value of a scalar type
scalar-types:
- string
- int
- bool

\b hash: variable that that stores one or more variables with a unique lookup name

28
\b sequence: variable that stores sub-variables without names but instead are selected via index (myVariable[index])
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

A variable is accessed using the dollar character followed by a variable or expression in brackets:
\code
${...}
\endcode
Output the name of the zone:
\code
${zone.name}
\endcode

A sequence gets iterated:
\code
<#list zone.memory as mem>
   Memory region name $mem.name
</#list

Printing a sorted list of all available memory entries by start address
\code
<#list zone.memory?sort_by("start") as mem>
  ${mem.start} ${mem.name}
</#list>
\endcode



\page fm_system system element

The \ref fm_system provides the memory layout and the TrustZone configuration of the complete system. 
57
58
This information can be used for example, to create a linker script that defines the memory setup of the SoC system.

59
<table class="cmtable" summary="Element: system">
60
61
62
63
64
65
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
66
67
68
    <td>\subpage fm_memory ".memory"</td>
    <td>A sequence of all memory regions available in the system resource file.</td>
    <td>sequence</td>
69
70
71
72
73
74
  </tr>
  <tr>
    <td>\subpage fm_peripheral ".peripheral"</td>
    <td>A sequence of all peripherals available in the system resource file.</td>
    <td>sequence</td>
  </tr>
75
76
77
78
79
  <tr>
    <td>\subpage fm_sau ".sau"</td>
    <td>A sequence of all SAU regions for initialization.</td>
    <td>sequence</td>
  </tr>
80
  <tr>
81
82
83
    <td>\subpage fm_interrupt ".interrupt"</td>
    <td>A sequence of all interrupt sources available.</td>
    <td>sequence</td>
84
  </tr>
reinhardkeil's avatar
reinhardkeil committed
85
86
87
88
89
  <tr>
    <td>\subpage fm_mpc_setup ".mpc_setup"</td>
    <td>Contains the device specific configuration registers for the setup of the Memory Protection Controller (MPC).</td>
    <td>sequence</td>
  </tr>
90
  <tr>
91
92
    <td>\subpage fm_reg_setup ".reg_setup"</td>
    <td>Contains the device specific configuration registers for the setup of the peripherals.</td>
93
    <td>sequence</td>
94
95
96
  </tr>
</table>
  
97
\page fm_zone zone element
98
99
100
101
102
103
104
105
106
107
108
109
110
111

The \ref fm_zone provides the setup information of a zone (or system partition) along with related peripherals.
This information can be used for example, to create the MPU setup that is required for various execution zones along with
the related linker setup.

<table class="cmtable" summary="Element: zone">
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
    <td>.name</td>
    <td>The name of the zone (or system partition).</td>
112
    <td>string</td>
113
114
  </tr>
  <tr>
115
    <td>\subpage fm_memory ".memory"</td>
116
117
    <td>A sequence of all memory regions that are accessible in the zone (or system partition).</td>
    <td>sequence</td>
118
119
  </tr>
  <tr>
120
121
122
    <td>\subpage fm_peripheral ".peripheral"</td>
    <td>A sequence of all peripherals that are accessible in the zone (or system partition).</td>
    <td>sequence</td>
123
124
125
  </tr>
  <tr>
    <td>\subpage fm_mpu_setup ".mpu_setup"</td>
126
127
    <td>A sequence of configuration information for the Memory Protection Unit (MPU).</td>
    <td>sequence</td>
128
129
130
  </tr>
</table>

131

132
133
134
135
136
*/


/**************************************************************************************************/
/**
137
\page fm_memory ../memory[n] sequence element
138

139
The \ref fm_memory provides a sequence of memory information.
140

141
<table class="cmtable" summary="Element: memory[n]">
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
    <td>\ref fm_system "system"</td>
    <td colspan=3>\ref fm_system</td>
  </tr>
  <tr>
    <td>\ref fm_zone "zone"</td>
    <td colspan=3>\ref fm_zone</td>
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
    <td>.memory[<i>n</i>]</td>
161
162
    <td>Sequence of memory region information.</td>
    <td>sequence</td>
163
164
165
166
167
168
169
170
171
  </tr>
  <tr>
    <td>.memory[<i>n</i>].name</td>
    <td>The name of this memory region.</td>
    <td>xs:string</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].type</td>
    <td>The type of memory in this region ("RAM" or "ROM").</td>
172
    <td>MemoryTypeEnum/xs:string</td>
173
174
175
176
  </tr>
  <tr>
    <td>.memory[<i>n</i>].start</td>
    <td>The logical start address of the memory region in the address map.</td>
177
    <td>NonNegativeInteger</td>
178
179
180
181
  </tr>
  <tr>
    <td>.memory[<i>n</i>].size</td>
    <td>The size (in bytes) of the memory region.</td>
182
    <td>NonNegativeInteger</td>
183
184
185
186
  </tr>
  <tr>
    <td>.memory[<i>n</i>].security</td>
    <td>The \ref security "security" setting for this memory region.</td>
187
    <td>SecurityTypeEnum/xs:string</td>
188
  </tr>
189
190
191
192
193
  <tr>
    <td>.memory[<i>n</i>].security.c</td>
    <td>Memory has non-secure callable attribute set.</td>
    <td>xs:boolean</td>
  </tr>
194
195
196
197
198
199
200
201
202
203
  <tr>
    <td>.memory[<i>n</i>].security.s</td>
    <td>Memory is access from \em "secure" state.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].security.n</td>
    <td>Memory is access from \em "non-secure" state.</td>
    <td>xs:boolean</td>
  </tr>
204
205
206
  <tr>
    <td>.memory[<i>n</i>].access</td>
    <td>The \ref access "access" permissions for this memory region in the following separate fields.</td>
207
    <td>AccessType</td>
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
  </tr>
  <tr>
    <td>.memory[<i>n</i>].access.r</td>
    <td>The \em read \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].access.w</td>
    <td>The \em write \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].access.x</td>
    <td>The \em execution \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].access.p</td>
    <td>The \em peripheral \ref access "access" information.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.memory[<i>n</i>].info</td>
    <td>Brief description of the memory region.</td>
    <td>xs:string</td>
  </tr>
</table>
*/

/**************************************************************************************************/
/**
239
\page fm_sau sau[n] sequence element
240

241
242
243
244
245
246
The \ref fm_sau lists all SAU regions for initialization in this system.

It lists all SAU regions that require either non-secure access or non-secure callable attribute.
The SAU region list is generated from:
  - setup information from \ref xml_si_region
  - memory regions that are assigned to zones with non-secure domain.
247
  - memory regions that are configured as secure, non-secure callable.
248

249
<table class="cmtable" summary="Element: sau[n]">
250
251
252
253
254
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
255
256
    <td>\ref fm_system "system"</td>
    <td colspan=3>\ref fm_system</td>
257
258
259
260
261
262
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
263
  <tr>
264
    <td>.sau[<i>n</i>].start</td>
265
266
267
268
    <td>The logical start address for the region.</td>
    <td>xs:string</td>
  </tr>
  <tr>
269
    <td>.sau[<i>n</i>].end</td>
270
271
272
273
    <td>The logical end address for the region.</td>
    <td>xs:string</td>
  </tr>
  <tr>
274
    <td>.sau[<i>n</i>].nsc</td>
275
276
277
278
    <td>If set to 1 the region is secure, non-secure callable.</td>
    <td>SecurityTypeEnum/xs:string</td>
  </tr>
  <tr>
279
    <td>.sau[<i>n</i>].info</td>
280
281
282
283
284
285
286
287
288
    <td>List of memory regions or info from \ref xml_si_region.</td>
    <td>xs:string</td>
  </tr>
</table>
*/


/**************************************************************************************************/
/**
289
\page fm_interrupt interrupt[n] sequence element
290
291
292
293
294
295
296
297
298

The \ref fm_interrupt lists all interrupt sources available in the system.

<table class="cmtable" summary="Element: interrupt[n]">
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
299
300
    <td>\ref fm_system "system"</td>
    <td colspan=3>\ref fm_system</td>
301
302
303
304
305
306
  </tr>s
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
307
  <tr>
308
    <td>.interrupt[<i>n</i>].name</td>
309
310
311
312
    <td>The name of this interrupt.</td>
    <td>xs:string</td>
  </tr>
  <tr>
313
    <td>.interrupt[<i>n</i>].irqn</td>
314
    <td>The interrupt number.</td>
315
    <td>NonNegativeInteger</td>
316
317
  </tr>
  <tr>
318
    <td>.interrupt[<i>n</i>].security</td>
319
    <td>The \ref security "security" setting for this interrupt.</td>
320
    <td>SecurityTypeEnum/xs:string</td>
321
322
  </tr>
  <tr>
323
324
325
326
327
328
329
330
331
332
333
    <td>.interrupt[<i>n</i>].security.s</td>
    <td>Peripheral with related interrupt is assigned to \em "secure" state.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.interrupt[<i>n</i>].security.n</td>
    <td>Peripheral with related interrupt is assigned to \em "non-secure" state.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.interrupt[<i>n</i>].info</td>
334
335
336
337
338
    <td>Brief description of the interrupt source.</td>
    <td>xs:string</td>
  </tr>
</table>
*/
339

reinhardkeil's avatar
reinhardkeil committed
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
/**************************************************************************************************/
/**
\page fm_mpc_setup mpc_setup[n] element

The \ref fm_mpc_setup contains a sequence of device specific configuration for the setup of the Memory Protection Controller (MPC).

<table class="cmtable" summary="Element: mpc_setup[n]">
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
    <td>\ref fm_system "system"</td>
    <td colspan=3>\ref fm_system</td>
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
    <td>.mpc_setup[<i>n</i>].name</td>
    <td>The name of the base register that controls the MPC.</td>
    <td>xs:string</td>
  </tr>
  <tr>
    <td>.reg_setup[<i>n</i>].memory</td>
    <td>The name of the physical memory region that is connected via the MPC.</td>
    <td>xs:string</td>
  </tr>
  <tr>
371
372
    <td>.reg_setup[<i>n</i>].blk_size</td>
    <td>The block size information that CMSIS-Zone used for LUT generation.</td>
reinhardkeil's avatar
reinhardkeil committed
373
374
375
    <td>NonNegativeInteger</td>
  </tr>
  <tr>
376
377
378
379
380
381
382
383
384
385
386
387
    <td>.reg_setup[<i>n</i>].S_lut[<i>m</i>]</td>
    <td>The look-up table (LUT) bit values for Secure attribute.</td>
    <td>NonNegativeInteger</td>
  </tr>
  <tr>
    <td>.reg_setup[<i>n</i>].P_lut[<i>m</i>]</td>
    <td>The look-up table (LUT) bit values for Privileged attribute.</td>
    <td>NonNegativeInteger</td>
  </tr>
  <tr>
    <td>.reg_setup[<i>n</i>].lut[<i>m</i>]</td>
    <td>The look-up table (LUT) bit values for a combined Secure and Privileged attribute (\ref xml_rmpc - \b format attribute specifies the format of the LUT).</td>
reinhardkeil's avatar
reinhardkeil committed
388
389
390
391
392
393
394
395
396
397
    <td>NonNegativeInteger</td>
  </tr>
  <tr>
    <td>.reg_setup[<i>n</i>].lut_comment[<i>m</i>]</td>
    <td>The region information for source code comments of the BLK_LUT values.</td>
    <td>xs:string</td>
  </tr>
</table>
*/

398
399
/**************************************************************************************************/
/**
400
\page fm_reg_setup reg_setup[n] element
401

402
The \ref fm_reg_setup contains a sequence of device specific configuration for the setup of the interrupts.
403

404
<table class="cmtable" summary="Element: reg_setup[n]">
405
406
407
408
409
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
410
411
    <td>\ref fm_system "system"</td>
    <td colspan=3>\ref fm_system</td>
412
413
414
415
416
417
418
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
419
    <td>.reg_setup[<i>n</i>].name</td>
420
421
422
423
    <td>The name of the register or array that holds the configuration information.</td>
    <td>xs:string</td>
  </tr>
  <tr>
424
    <td>.reg_setup[<i>n</i>].index</td>
425
    <td>The index value for the register array.</td>
426
    <td>NonNegativeInteger</td>
427
428
  </tr>
  <tr>
429
430
    <td>.reg_setup[<i>n</i>].value[<i>m</i>]</td>
    <td>An array with register setup values (corresponds to .peripheral[<i>m</i>] below.</td>
431
    <td>NonNegativeInteger</td>
432
433
  </tr>
  <tr>
434
    <td>.reg_setup[<i>n</i>].peripheral[<i>m</i>]</td>
435
436
    <td>An array with the peripheral names that setup belongs too.</td>
    <td>xs:string</td>
437
438
439
  </tr>
</table>
*/
440
441


442
443
/**************************************************************************************************/
/**
444
\page fm_peripheral ../peripheral[n] element
445

446
The \ref fm_peripheral contains a sequence of all peripherals that are accessible in the zone (or system partition).
447

448
<table class="cmtable" summary="Element: peripheral[n]">
449
450
451
452
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
453
454
455
456
  <tr>
    <td>\ref fm_system "system"</td>
    <td colspan=2>\ref fm_system</td>
  </tr>
457
458
459
460
461
462
463
464
465
466
  <tr>
    <td>\ref fm_zone "zone"</td>
    <td colspan=2>\ref fm_zone</td>
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
467
    <td>.peripheral[<i>n</i>].name</td>
468
469
470
471
    <td>The name of the peripheral.</td>
    <td>xs:string</td>
  </tr>
  <tr>
472
    <td>.peripheral[<i>n</i>].group</td>
473
474
475
476
    <td>The name of the peripheral group that this peripheral belongs too.</td>
    <td>xs:string</td>
  </tr>
  <tr>
477
    <td>.peripheral[<i>n</i>].start</td>
478
    <td>The logical start address of the peripheral in the address map.</td>
479
    <td>NonNegativeInteger</td>
480
481
482
483
  </tr>
  <tr>
    <td>.peripheral[<i>n</i>].size</td>
    <td>The size (in bytes) of the peripheral.</td>
484
    <td>NonNegativeInteger</td>
485
486
  </tr>
  <tr>
487
    <td>.peripheral[<i>n</i>].security</td>
488
    <td>The \ref security "security" setting for this peripheral.</td>
489
    <td>SecurityTypeEnum/xs:string</td>
490
491
  </tr>
  <tr>
492
493
494
495
496
497
498
499
500
501
502
    <td>.peripheral[<i>n</i>].security.s</td>
    <td>Peripheral is assigned to \em "secure" state.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.peripheral[<i>n</i>].security.n</td>
    <td>Peripheral is assigned to \em "non-secure" state.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
    <td>.peripheral[<i>n</i>].access</td>
503
    <td>The \ref access "access" permissions for this peripheral in the following separate fields.</td>
504
    <td>N/A</td>
505
506
  </tr>
  <tr>
507
    <td>.peripheral[<i>n</i>].access.r</td>
508
509
510
511
    <td>The \em read \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
512
    <td>.peripheral[<i>n</i>].access.w</td>
513
514
515
    <td>The \em write \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
516
  <tr>
517
    <td>.peripheral[<i>n</i>].access.x</td>
518
519
520
521
    <td>The \em execution \ref access "access" permission.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
522
    <td>.peripheral[<i>n</i>].access.p</td>
523
524
525
526
    <td>The \em peripheral \ref access "access" information.</td>
    <td>xs:boolean</td>
  </tr>
  <tr>
527
    <td>.peripheral[<i>n</i>].info</td>
528
529
    <td>Brief description of the peripheral region.</td>
    <td>xs:string</td>
530
531
  </tr>
</table>
532
*/
533

534
535
/**************************************************************************************************/
/**
536
\page fm_mpu_setup mpu_setup element
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554

The \ref fm_mpu_setup contains the configuration information for the Memory Protection Unit (MPU).

<table class="cmtable" summary="Element: mpu_setup">
  <tr>
    <th>Parent Element</th>
    <th colspan="2">Element Chain</th>
  </tr>
  <tr>
    <td>\ref fm_system "zone"</td>
    <td colspan=3>\ref fm_zone</td>
  </tr>
  <tr>
    <th>Child Elements</th>
    <th>Description</th>
    <th>Type</th>
  </tr>
  <tr>
555
    <td>mpu_setup.type</td>
556
557
558
559
    <td>Implementation of the MPU ("v7M" or "v8M").</td>
    <td>xs:string</td>
  </tr>
  <tr>
560
    <td>mpu_setup.region[<i>n</i>]</td>
561
562
    <td>Sequenc of MPU region settings.</td>
    <td>sequence</td>
563
564
  </tr>
  <tr>
565
    <td>mpu_setup.region[<i>n</i>].no</td>
566
567
568
569
    <td>Number of the region.</td>
    <td>xs:string</td>
  </tr>
  <tr>
570
    <td>mpu_setup.region[<i>n</i>].BaseAddress</td>
571
572
573
574
    <td>The base address of the region.</td>
    <td>xs:string</td>
  </tr>
  <tr>
575
    <td>mpu_setup.region[<i>n</i>].RASR</td>
576
577
578
579
    <td>The MPU region attribute and size register value.</td>
    <td>xs:string</td>
  </tr>
</table>
580
*/