begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/Template.txt

   1 /**
   2 \page Templates_pg Template Files
   3
   4 \details
   5
   6 ARM supplies CMSIS-CORE template files for the all supported Cortex-M processors and various compiler vendors.
   7 Refer to the list of \ref tested_tools_sec for compliance.
   8 These template files include the following:
   9  - Register names of the Core Peripherals and names of the Core Exception Vectors.
  10  - Functions to access core peripherals, special CPU instructions and SIMD instructions (for Cortex-M4 and Cortex-M7)
  11  - Generic startup code and system configuration code.
  12
  13 The detailed file structure of the CMSIS-CORE is shown in the following picture.
  14
  15 \image html "CMSIS_CORE_Files.png" "CMSIS-CORE File Structure"
  16
  17
  18 \section template_files_sec Template Files
  19
  20 The CMSIS-CORE template files should be extended by the silicon vendor to reflect the actual device and device peripherals.
  21 Silicon vendors add in this context the:
  22  - <b>Device Peripheral Access Layer</b> that provides definitions for device-specific peripherals.
  23  - <b>Access Functions for Peripherals</b> (optional) that provides additional helper functions to access device-specific peripherals.
  24  - <b>Interrupt vectors</b> in the startup file that are device specific.
  25
  26 <table class="cmtable">
  27     <tr>
  28       <th>Template File</th>
  29       <th>Description</th>
  30     </tr>
  31     <tr>
  32       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Source\\ARM\\startup_Device.s</td>
  33       <td>Startup file template for ARM C/C++ Compiler.</td>
  34     </tr>
  35     <tr>
  36       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Source\\GCC\\startup_Device.s</td>
  37       <td>Startup file template for GNU GCC ARM Embedded Compiler.</td>
  38     </tr>
  39     <tr>
  40       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Source\\IAR\\startup_Device.s</td>
  41       <td>Startup file template for IAR C/C++ Compiler.</td>
  42     </tr>
  43     <tr>
  44       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Source\\system_Device.c</td>
  45       <td>Generic system_Device.c file for system configuration (i.e. processor clock and memory bus system).</td>
  46     </tr>
  47     <tr>
  48       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Include\\Device.h</td>
  49       <td>Generic device header file. Needs to be extended with the device-specific peripheral registers. Optionally functions that access the peripherals
  50       can be part of that file.</td>
  51     </tr>
  52     <tr>
  53       <td>.\\Device\\\_Template_Vendor\\Vendor\\Device\\Include\\system_Device.h</td>
  54       <td>Generic system device configuration include file.</td>
  55     </tr>
  56 </table>
  57
  58
  59 In addition ARM provides the following core header files that do not need any modifications.
  60
  61 <table class="cmtable">
  62     <tr>
  63       <th>Core Header Files</th>
  64       <th>Description</th>
  65     </tr>
  66     <tr>
  67       <td><b>core_&lt;cpu&gt;.h</b></td>
  68       <td>Defines the core peripherals and provides helper functions that access the core registers. This file is available for all supported processors:
  69              - core_cm0.h: for the Cortex-M0 processor
  70              - core_cm0plus.h: for the Cortex-M0+ processor
  71              - core_cm3.h: for the Cortex-M3 processor
  72              - core_cm4.h: for the Cortex-M4 processor
  73              - core_cm7.h: for the Cortex-M7 processor
  74              - core_sc000.h: for the SecurCore SC000 processor
  75              - core_sc300.h: for the SecurCore SC300 processor
  76              - core_armv8mbl.h: for the ARMv8-M Baseline processor
  77              - core_armv8mml.h: for the ARMv8-M Mainline processor
  78           </td>
  79     </tr>
  80     <tr>
  81       <td><b>core_cminstr.h</b></td>
  82       <td>Defines intrinsic functions to access special Cortex-M instructions.</td>
  83     </tr>
  84     <tr>
  85       <td><b>core_cmiunc.h</b></td>
  86       <td>Defines functions to access the Cortex-M core peripherals.</td>
  87     </tr>
  88     <tr>
  89       <td><b>core_cmsimd.h</b></td>
  90       <td>Defines intrinsic functions to access the SIMD instructions for Cortex-M4, Cortex-M7 and ARMv8MML.</td>
  91     </tr>
  92 </table>
  93
  94
  95 \section adapt_template_files_sec Adaption of Template Files to Devices
  96
  97 Copy the complete folder including files and replace:
  98   - folder name 'Vendor' with the abbreviation for the device vendor  e.g.: NXP.
  99   - folder name 'Device' with the specific device name e.g.: LPC17xx.
 100   - in the filenames 'Device' with the specific device name e.g.: LPC17xx.
 101
 102 Each template file contains comments that start with \b ToDo: that describe a required modification.
 103 The template files contain placeholders:
 104
 105 <table class="cmtable">
 106     <tr>
 107       <th>Placeholder</th>
 108       <th>Replaced with</th>
 109     </tr>
 110     <tr>
 111       <td>&lt;Device&gt;</td>
 112       <td>the specific device name or device family name; i.e. LPC17xx.</td>
 113     </tr>
 114     <tr>
 115       <td>&lt;DeviceInterrupt&gt;</td>
 116       <td>a specific interrupt name of the device; i.e. TIM1 for Timer 1.</td>
 117     <tr>
 118       <td>&lt;DeviceAbbreviation&gt;</td>
 119       <td>short name or abbreviation of the device family; i.e. LPC.</td>
 120     </tr>
 121     <tr>
 122       <td>Cortex-M#</td>
 123       <td>the specific Cortex-M processor name; i.e. Cortex-M3.</td>
 124     </tr>
 125 </table>
 126
 127
 128 The adaption of the template files is described in detail on the following pages:
 129   - \subpage startup_s_pg
 130   - \subpage system_c_pg
 131   - \subpage device_h_pg
 132   - \subpage partition_h_pg
 133 */
 134
 135 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 136 /**
 137 \page startup_s_pg Startup File startup_<device>.s
 138
 139 The \ref startup_s_pg contains:
 140  - The reset handler which is executed after CPU reset and typically calls the \ref SystemInit function.
 141  - The setup values for the Main Stack Pointer (MSP).
 142  - Exception vectors of the Cortex-M Processor with weak functions that implement default routines.
 143  - Interrupt vectors that are device specific with weak functions that implement default routines.
 144
 145 The file exists for each supported toolchain and is the only tool-chain specific CMSIS file.
 146
 147 To adapt the file to a new device only the interrupt vector table needs to be extended with
 148 the device-specific interrupt handlers. The naming convention for the interrupt handler names are
 149 &lt;interrupt_name&gt;_IRQHandler.  This table needs to be consistent with \ref IRQn_Type that defines all the
 150 IRQ numbers for each interrupt.
 151
 152 \b Example:
 153
 154 The following example shows the extension of the interrupt vector table for the LPC1100 device family.
 155
 156 \code
 157                 ; External Interrupts
 158                 DCD     WAKEUP0_IRQHandler       ; 16+ 0: Wakeup PIO0.0
 159                 DCD     WAKEUP1_IRQHandler       ; 16+ 1: Wakeup PIO0.1
 160                 DCD     WAKEUP2_IRQHandler       ; 16+ 2: Wakeup PIO0.2
 161                  :       :
 162                  :       :
 163                 DCD     EINT1_IRQHandler         ; 16+30: PIO INT1
 164                 DCD     EINT0_IRQHandler         ; 16+31: PIO INT0
 165          :
 166          :
 167                 EXPORT  WAKEUP0_IRQHandler       [WEAK]
 168                 EXPORT  WAKEUP1_IRQHandler       [WEAK]
 169                 EXPORT  WAKEUP2_IRQHandler       [WEAK]
 170                  :       :
 171                  :       :
 172                 EXPORT  EINT1_IRQHandler         [WEAK]
 173                 EXPORT  EINT0_IRQHandler         [WEAK]
 174
 175 WAKEUP0_IRQHandler
 176 WAKEUP1_IRQHandler
 177 WAKEUP1_IRQHandler
 178       :
 179       :
 180 EINT1_IRQHandler
 181 EINT0_IRQHandler
 182                 B       .
 183
 184 \endcode
 185
 186 \section startup_s_sec startup_Device.s Template File
 187
 188 An ARM Compiler \ref startup_s_sec for an ARMv7-M processor like Cortex-M3 is shown below.
 189 The files for other compiler vendors differ slightly in the syntax, but not in the overall structure.
 190
 191 \verbinclude "Source\ARM\startup_Device.s"
 192 */
 193
 194 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 195 /**
 196 \page system_c_pg System Configuration Files system_<device>.c and system_<device>.h
 197
 198 The \ref system_c_pg provides as a minimum the functions described under \ref system_init_gr.
 199 These functions are device specific and need adaptations. In addition, the file might have
 200 configuration settings for the device such as XTAL frequency or PLL prescaler settings.
 201
 202 For devices with external memory BUS the system_<device>.c also configures the BUS system.
 203
 204 The silicon vendor might expose other functions (i.e. for power configuration) in the system_<device>.c file.
 205 In case of additional features the function prototypes need to be added to the system_<device>.h header file.
 206
 207 \section system_Device_sec system_Device.c Template File
 208
 209 The \ref system_Device_sec for the Cortex-M3 is shown below.
 210
 211 \verbinclude "Source\system_Device.c"
 212
 213 \section system_Device_h_sec system_Device.h Template File
 214
 215 The system_<device>.h header file contains prototypes to access the public functions in the system_<device>.c file.
 216 The \ref system_Device_h_sec is shown below.
 217
 218 \verbinclude "Include\system_Device.h"
 219
 220 */
 221
 222 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 223 /**
 224 \page device_h_pg Device Header File <device.h>
 225
 226 The \ref device_h_pg contains the following sections that are device specific:
 227
 228   - \ref interrupt_number_sec provides interrupt numbers (IRQn) for all exceptions and interrupts of the device.
 229   - \ref core_config_sect reflect the features of the device.
 230   - \ref device_access provides definitions for the \ref peripheral_gr to all device peripherals. It contains all data structures and the address mapping for device-specific peripherals.
 231   - <b>Access Functions for Peripherals (optional)</b> provide additional helper functions for peripherals that are useful for programming of these peripherals. Access Functions may be provided as inline functions or can be extern references to a device-specific library provided by the silicon vendor.
 232
 233 <a href="Modules.html">\b Reference </a> describes the standard features and functions of the \ref device_h_pg in detail.
 234
 235 \section interrupt_number_sec Interrupt Number Definition
 236
 237 \ref device_h_pg contains the enumeration \ref IRQn_Type that defines all exceptions and interrupts of the device.
 238   - Negative IRQn values represent processor core exceptions (internal interrupts).
 239   - Positive IRQn values represent device-specific exceptions (external interrupts). The first device-specific interrupt has the IRQn value 0.
 240     The IRQn values needs extension to reflect the device-specific interrupt vector table in the \ref startup_s_pg.
 241
 242 \b Example:
 243
 244 The following example shows the extension of the interrupt vector table for the LPC1100 device family.
 245
 246 \code
 247 typedef enum IRQn
 248 {
 249 /******  Cortex-M0 Processor Exceptions Numbers ***************************************************/
 250   NonMaskableInt_IRQn           = -14,      /*!< 2 Non Maskable Interrupt                         */
 251   HardFault_IRQn                = -13,      /*!< 3 Cortex-M0 Hard Fault Interrupt                 */
 252   SVCall_IRQn                   = -5,       /*!< 11 Cortex-M0 SV Call Interrupt                   */
 253   PendSV_IRQn                   = -2,       /*!< 14 Cortex-M0 Pend SV Interrupt                   */
 254   SysTick_IRQn                  = -1,       /*!< 15 Cortex-M0 System Tick Interrupt               */
 255
 256 /******  LPC11xx/LPC11Cxx Specific Interrupt Numbers **********************************************/
 257   WAKEUP0_IRQn                  = 0,        /*!< All I/O pins can be used as wakeup source.       */
 258   WAKEUP1_IRQn                  = 1,        /*!< There are 13 pins in total for LPC11xx           */
 259   WAKEUP2_IRQn                  = 2,
 260                  :       :
 261                  :       :
 262   EINT1_IRQn                    = 30,       /*!< External Interrupt 1 Interrupt                   */
 263   EINT0_IRQn                    = 31,       /*!< External Interrupt 0 Interrupt                   */
 264 } IRQn_Type;
 265 \endcode
 266
 267 \section core_config_sect Configuration of the Processor and Core Peripherals
 268
 269 The \ref device_h_pg  configures the Cortex-M or SecurCore processor and the core peripherals with <i>\#defines</i>
 270 that are set prior to including the file <b>core_<cpu>.h</b>.
 271
 272 The following tables list the <i>\#defines</i> along with the possible values for each processor core.
 273 If these <i>\#defines</i> are missing default values are used.
 274
 275 \b core_cm0.h
 276 <table class="cmtable">
 277     <tr>
 278       <th>\#define</th>
 279       <th>Value Range</th>
 280       <th>Default</th>
 281       <th>Description</th>
 282     </tr>
 283     <tr>
 284       <td>__CM0_REV</td>
 285       <td>0x0000</td>
 286       <td>0x0000</td>
 287       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 288     </tr>
 289     <tr>
 290       <td>__NVIC_PRIO_BITS</td>
 291       <td>2</td>
 292       <td>2</td>
 293       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 294     </tr>
 295     <tr>
 296       <td>__Vendor_SysTickConfig</td>
 297       <td>0 .. 1</td>
 298       <td>0</td>
 299       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 300                 is excluded. In this case, the file <i><b>device.h</b></i>
 301                 must contain a vendor specific implementation of this function.</td>
 302     </tr>
 303 </table>
 304
 305 \b core_cm0plus.h
 306 <table class="cmtable">
 307     <tr>
 308       <th>\#define</th>
 309       <th>Value Range</th>
 310       <th>Default</th>
 311       <th>Description</th>
 312     </tr>
 313     <tr>
 314       <td>__CM0PLUS_REV</td>
 315       <td>0x0000</td>
 316       <td>0x0000</td>
 317       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 318     </tr>
 319     <tr>
 320       <td>__NVIC_PRIO_BITS</td>
 321       <td>2</td>
 322       <td>2</td>
 323       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 324     </tr>
 325     <tr>
 326       <td>__Vendor_SysTickConfig</td>
 327       <td>0 .. 1</td>
 328       <td>0</td>
 329       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 330                 is excluded. In this case, the file <i><b>device.h</b></i>
 331                 must contain a vendor specific implementation of this function.</td>
 332     </tr>
 333 </table>
 334
 335 \b core_cm3.h
 336 <table class="cmtable">
 337     <tr>
 338       <th>\#define</th>
 339       <th>Value Range</th>
 340       <th>Default</th>
 341       <th>Description</th>
 342     </tr>
 343     <tr>
 344       <td>__CM3_REV</td>
 345       <td>0x0101 | 0x0200</td>
 346       <td>0x0200</td>
 347       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 348     </tr>
 349     <tr>
 350       <td>__NVIC_PRIO_BITS</td>
 351       <td>2 .. 8</td>
 352       <td>4</td>
 353       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 354     </tr>
 355     <tr>
 356       <td>__MPU_PRESENT</td>
 357       <td>0 .. 1</td>
 358       <td>0</td>
 359       <td>Defines if a MPU is present or not</td>
 360     </tr>
 361     <tr>
 362       <td>__Vendor_SysTickConfig</td>
 363       <td>0 .. 1</td>
 364       <td>0</td>
 365       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 366                 is excluded. In this case, the file <i><b>device.h</b></i>
 367                 must contain a vendor specific implementation of this function.</td>
 368     </tr>
 369 </table>
 370
 371 \b core_cm4.h
 372 <table class="cmtable">
 373     <tr>
 374       <th>\#define</th>
 375       <th>Value Range</th>
 376       <th>Default</th>
 377       <th>Description</th>
 378     </tr>
 379     <tr>
 380       <td>__CM4_REV</td>
 381       <td>0x0000</td>
 382       <td>0x0000</td>
 383       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 384     </tr>
 385     <tr>
 386       <td>__NVIC_PRIO_BITS</td>
 387       <td>2 .. 8</td>
 388       <td>4</td>
 389       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 390     </tr>
 391     <tr>
 392       <td>__MPU_PRESENT</td>
 393       <td>0 .. 1</td>
 394       <td>0</td>
 395       <td>Defines if a MPU is present or not</td>
 396     </tr>
 397     <tr>
 398       <td>__FPU_PRESENT</td>
 399       <td>0 .. 1</td>
 400       <td>0</td>
 401       <td>Defines if a FPU is present or not</td>
 402     </tr>
 403     <tr>
 404       <td>__Vendor_SysTickConfig</td>
 405       <td>0 .. 1</td>
 406       <td>0</td>
 407       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 408                 is excluded. In this case, the file <i><b>device.h</b></i>
 409                 must contain a vendor specific implementation of this function.</td>
 410     </tr>
 411 </table>
 412
 413 \b core_cm7.h
 414 <table class="cmtable" summary="">
 415     <tr>
 416       <th>\#define</th>
 417       <th>Value Range</th>
 418       <th>Default</th>
 419       <th>Description</th>
 420     </tr>
 421     <tr>
 422       <td>__CM7_REV</td>
 423       <td>0x0000</td>
 424       <td>0x0000</td>
 425       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 426     </tr>
 427     <tr>
 428       <td>__MPU_PRESENT</td>
 429       <td>0 .. 1</td>
 430       <td>0</td>
 431       <td>Defines if a MPU is present or not</td>
 432     </tr>
 433     <tr>
 434       <td>__NVIC_PRIO_BITS</td>
 435       <td>2 .. 8</td>
 436       <td>4</td>
 437       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 438     </tr>
 439     <tr>
 440       <td>__Vendor_SysTickConfig</td>
 441       <td>0 .. 1</td>
 442       <td>0</td>
 443       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 444                 is excluded. In this case, the file <i><b>device.h</b></i>
 445                 must contain a vendor specific implementation of this function.</td>
 446     </tr>
 447     <tr>
 448       <td>__FPU_PRESENT</td>
 449       <td>0 .. 1</td>
 450       <td>0</td>
 451       <td>Defines if a FPU is present or not. See <b>__FPU_DP</b> description below.</td>
 452     </tr>
 453     <tr>
 454       <td>__FPU_DP</td>
 455       <td>0 .. 1</td>
 456       <td>0</td>
 457       <td>The combination of the defines <b>__FPU_PRESENT</b> and <b>__FPU_DP</b>
 458          determine the whether the FPU is with single or double precision as shown in the table below.
 459              \n\n
 460              <table class="cmtable" summary="">
 461                  <tr  bgcolor="cyan">
 462            <td><b>__FPU_PRESENT</b></td>
 463                    <td><b>__FPU_DP</b></td>
 464                    <td><b>Description</b></td>
 465                  </tr>
 466                  <tr>
 467                    <td align="center">0</td>
 468                    <td align="center"><i>ignored</i></td>
 469                    <td>Processor has no FPU. The value set for <b>__FPU_DP</b> has no influence. </td>
 470                  </tr>
 471                  <tr>
 472                    <td align="center">1</td>
 473                    <td align="center">0</td>
 474                    <td>Processor with FPU with single precision. The file <b>ARMCM7_SP.h</b> has preconfigured settings for this combination.</td>
 475                  </tr>
 476                  <tr>
 477                    <td align="center">1</td>
 478                    <td align="center">1</td>
 479            <td>Processor with FPU with double precision. The file <b>ARMCM7_DP.h</b> has preconfigured settings for this combination.</td>
 480                  </tr>
 481                  </table>
 482           </td>
 483     </tr>
 484     <tr>
 485       <td>__ICACHE_PRESENT</td>
 486       <td>0 .. 1</td>
 487       <td>1</td>
 488       <td>Instruction Chache present or not</td>
 489     </tr>
 490     <tr>
 491       <td>__DCACHE_PRESENT</td>
 492       <td>0 .. 1</td>
 493       <td>1</td>
 494       <td>Data Chache present or not</td>
 495     </tr>
 496     <tr>
 497       <td>__DTCM_PRESENT</td>
 498       <td>0 .. 1</td>
 499       <td>1</td>
 500       <td>Data Tightly Coupled Memory is present or not</td>
 501     </tr>
 502 </table>
 503
 504 \b core_sc000.h
 505 <table class="cmtable">
 506     <tr>
 507       <th>\#define</th>
 508       <th>Value Range</th>
 509       <th>Default</th>
 510       <th>Description</th>
 511     </tr>
 512     <tr>
 513       <td>__SC000_REV</td>
 514       <td>0x0000</td>
 515       <td>0x0000</td>
 516       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 517     </tr>
 518     <tr>
 519       <td>__NVIC_PRIO_BITS</td>
 520       <td>2</td>
 521       <td>2</td>
 522       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 523     </tr>
 524     <tr>
 525       <td>__MPU_PRESENT</td>
 526       <td>0 .. 1</td>
 527       <td>0</td>
 528       <td>Defines if a MPU is present or not</td>
 529     </tr>
 530     <tr>
 531       <td>__Vendor_SysTickConfig</td>
 532       <td>0 .. 1</td>
 533       <td>0</td>
 534       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 535                 is excluded. In this case, the file <i><b>device.h</b></i>
 536                 must contain a vendor specific implementation of this function.</td>
 537     </tr>
 538 </table>
 539
 540 \b core_sc300.h
 541 <table class="cmtable">
 542     <tr>
 543       <th>\#define</th>
 544       <th>Value Range</th>
 545       <th>Default</th>
 546       <th>Description</th>
 547     </tr>
 548     <tr>
 549       <td>__SC300_REV</td>
 550       <td>0x0000</td>
 551       <td>0x0000</td>
 552       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 553     </tr>
 554     <tr>
 555       <td>__NVIC_PRIO_BITS</td>
 556       <td>2 .. 8</td>
 557       <td>4</td>
 558       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 559     </tr>
 560     <tr>
 561       <td>__MPU_PRESENT</td>
 562       <td>0 .. 1</td>
 563       <td>0</td>
 564       <td>Defines if a MPU is present or not</td>
 565     </tr>
 566     <tr>
 567       <td>__Vendor_SysTickConfig</td>
 568       <td>0 .. 1</td>
 569       <td>0</td>
 570       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 571                 is excluded. In this case, the file <i><b>device.h</b></i>
 572                 must contain a vendor specific implementation of this function.</td>
 573     </tr>
 574 </table>
 575
 576 \b core_ARMv8MBL.h
 577 <table class="cmtable">
 578     <tr>
 579       <th>\#define</th>
 580       <th>Value Range</th>
 581       <th>Default</th>
 582       <th>Description</th>
 583     </tr>
 584     <tr>
 585       <td>__ARMv8MBL_REV</td>
 586       <td>0x0000</td>
 587       <td>0x0000</td>
 588       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 589     </tr>
 590     <tr>
 591       <td>__MPU_PRESENT</td>
 592       <td>0 .. 1</td>
 593       <td>0</td>
 594       <td>Defines if a MPU is present or not</td>
 595     </tr>
 596     <tr>
 597       <td>__SAUREGION_PRESENT</td>
 598       <td>0 .. 1</td>
 599       <td>0</td>
 600       <td>Defines if SAU regions are present or not</td>
 601     </tr>
 602     <tr>
 603       <td>__VTOR_PRESENT</td>
 604       <td>0 .. 1</td>
 605       <td>0</td>
 606       <td>Defines if a VTOR register is present or not</td>
 607     </tr>
 608     <tr>
 609       <td>__NVIC_PRIO_BITS</td>
 610       <td>2</td>
 611       <td>2</td>
 612       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 613     </tr>
 614     <tr>
 615       <td>__Vendor_SysTickConfig</td>
 616       <td>0 .. 1</td>
 617       <td>0</td>
 618       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 619                 is excluded. In this case, the file <i><b>device.h</b></i>
 620                 must contain a vendor specific implementation of this function.</td>
 621     </tr>
 622 </table>
 623
 624 \b core_ARMv8MML.h
 625 <table class="cmtable">
 626     <tr>
 627       <th>\#define</th>
 628       <th>Value Range</th>
 629       <th>Default</th>
 630       <th>Description</th>
 631     </tr>
 632     <tr>
 633       <td>__ARMv8MML_REV</td>
 634       <td>0x0000</td>
 635       <td>0x0000</td>
 636       <td>Core revision number ([15:8] revision number, [7:0] patch number)</td>
 637     </tr>
 638     <tr>
 639       <td>__MPU_PRESENT</td>
 640       <td>0 .. 1</td>
 641       <td>0</td>
 642       <td>Defines if a MPU is present or not</td>
 643     </tr>
 644     <tr>
 645       <td>__SAUREGION_PRESENT</td>
 646       <td>0 .. 1</td>
 647       <td>0</td>
 648       <td>Defines if SAU regions are present or not</td>
 649     </tr>
 650     <tr>
 651       <td>__FPU_PRESENT</td>
 652       <td>0 .. 1</td>
 653       <td>0</td>
 654       <td>Defines if a FPU is present or not</td>
 655     </tr>
 656     <tr>
 657       <td>__NVIC_PRIO_BITS</td>
 658       <td>2 .. 8</td>
 659       <td>3</td>
 660       <td>Number of priority bits implemented in the NVIC (device specific)</td>
 661     </tr>
 662     <tr>
 663       <td>__Vendor_SysTickConfig</td>
 664       <td>0 .. 1</td>
 665       <td>0</td>
 666       <td>If this define is set to 1, then the default <b>SysTick_Config</b> function
 667                 is excluded. In this case, the file <i><b>device.h</b></i>
 668                 must contain a vendor specific implementation of this function.</td>
 669     </tr>
 670 </table>
 671
 672 \b Example
 673
 674 The following code exemplifies the configuration of the Cortex-M4 Processor and Core Peripherals.
 675
 676 \code
 677 #define __CM4_REV                 0x0001    /* Core revision r0p1                                 */
 678 #define __MPU_PRESENT             1         /* MPU present or not                                 */
 679 #define __NVIC_PRIO_BITS          3         /* Number of Bits used for Priority Levels            */
 680 #define __Vendor_SysTickConfig    0         /* Set to 1 if different SysTick Config is used       */
 681 #define __FPU_PRESENT             1         /* FPU present or not                                 */
 682 .
 683 .
 684 #include <core_cm4.h>                       /* Cortex-M4 processor and core peripherals           */
 685 \endcode
 686
 687
 688 \section core_version_sect   CMSIS Version and Processor Information
 689
 690 Defines in the core_<i>cpu</i>.h file identify the version of the CMSIS-CORE and the processor used.
 691 The following shows the defines in the various core_<i>cpu</i>.h files that may be used in the \ref device_h_pg
 692 to verify a minimum version or ensure that the right processor core is used.
 693
 694 \b core_cm0.h
 695 \code
 696 #define __CM0_CMSIS_VERSION_MAIN  (5U)                                 /* [31:16] CMSIS HAL main version */
 697 #define __CM0_CMSIS_VERSION_SUB   (0U)                                 /* [15:0]  CMSIS HAL sub version */
 698 #define __CM0_CMSIS_VERSION       ((__CM0_CMSIS_VERSION_MAIN << 16U) | \
 699                                     __CM0_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 700
 701 #define __CORTEX_M                (0U)                                 /* Cortex-M Core */
 702 \endcode
 703
 704
 705 \b core_cm0plus.h
 706 \code
 707 #define __CM0PLUS_CMSIS_VERSION_MAIN  (5U)                                  /* [31:16] CMSIS HAL main version */
 708 #define __CM0PLUS_CMSIS_VERSION_SUB   (0U)                                  /* [15:0]  CMSIS HAL sub version */
 709 #define __CM0PLUS_CMSIS_VERSION       ((__CM0P_CMSIS_VERSION_MAIN << 16U) | \
 710                                         __CM0P_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 711
 712 #define __CORTEX_M                    (0U)                                  /* Cortex-M Core */
 713 \endcode
 714
 715
 716 \b core_cm3.h
 717 \code
 718 #define __CM3_CMSIS_VERSION_MAIN  (5U)                                 /* [31:16] CMSIS HAL main version */
 719 #define __CM3_CMSIS_VERSION_SUB   (0U)                                 /* [15:0]  CMSIS HAL sub version */
 720 #define __CM3_CMSIS_VERSION       ((__CM3_CMSIS_VERSION_MAIN << 16U) | \
 721                                     __CM3_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 722
 723 #define __CORTEX_M                (3U)                                 /* Cortex-M Core */
 724 \endcode
 725
 726 \b core_cm4.h
 727 \code
 728 #define __CM4_CMSIS_VERSION_MAIN  (5U)                                 /* [31:16] CMSIS HAL main version */
 729 #define __CM4_CMSIS_VERSION_SUB   (0U)                                 /* [15:0]  CMSIS HAL sub version */
 730 #define __CM4_CMSIS_VERSION       ((__CM4_CMSIS_VERSION_MAIN << 16U) | \
 731                                     __CM4_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 732
 733 #define __CORTEX_M                (4U)                                 /* Cortex-M Core */
 734 \endcode
 735
 736 \b core_cm7.h
 737 \code
 738 #define __CM7_CMSIS_VERSION_MAIN  (5U)                                 /* [31:16] CMSIS HAL main version */
 739 #define __CM7_CMSIS_VERSION_SUB   (0U)                                 /* [15:0]  CMSIS HAL sub version */
 740 #define __CM7_CMSIS_VERSION       ((__CM7_CMSIS_VERSION_MAIN << 16U) | \
 741                                     __CM7_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 742
 743 #define __CORTEX_M                (7U)                                 /* Cortex-M Core */
 744 \endcode
 745
 746 \b core_sc000.h
 747 \code
 748 #define __SC000_CMSIS_VERSION_MAIN  (5U)                                   /* [31:16] CMSIS HAL main version */
 749 #define __SC000_CMSIS_VERSION_SUB   (0U)                                   /* [15:0]  CMSIS HAL sub version */
 750 #define __SC000_CMSIS_VERSION       ((__SC000_CMSIS_VERSION_MAIN << 16U) | \
 751                                       __SC000_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 752
 753 #define __CORTEX_SC                 (0U)                                   /* Cortex secure core */
 754 \endcode
 755
 756 \b core_sc300.h
 757 \code
 758 #define __SC300_CMSIS_VERSION_MAIN  (5U)                                   /* [31:16] CMSIS HAL main version */
 759 #define __SC300_CMSIS_VERSION_SUB   (0U)                                   /* [15:0]  CMSIS HAL sub version */
 760 #define __SC300_CMSIS_VERSION       ((__SC300_CMSIS_VERSION_MAIN << 16U) | \
 761                                       __SC300_CMSIS_VERSION_SUB          ) /* CMSIS HAL version number */
 762
 763 #define __CORTEX_SC                 (300U)                                 /* Cortex secure core */
 764 \endcode
 765
 766 \b core_ARMv8MBL.h
 767 \code
 768 #define __ARMv8MBL_CMSIS_VERSION_MAIN  (5U)                                       /* [31:16] CMSIS HAL main version */
 769 #define __ARMv8MBL_CMSIS_VERSION_SUB   (0U)                                       /* [15:0]  CMSIS HAL sub version */
 770 #define __ARMv8MBL_CMSIS_VERSION       ((__ARMv8MBL_CMSIS_VERSION_MAIN << 16U) | \
 771                                          __ARMv8MBL_CMSIS_VERSION_SUB           ) /* CMSIS HAL version number */
 772
 773 #define __CORTEX_M                     (tbd)                                      /* Cortex secure core */
 774 \endcode
 775
 776 \b core_ARMv8MML.h
 777 \code
 778 #define __ARMv8MML_CMSIS_VERSION_MAIN  (5U)                                       /* [31:16] CMSIS HAL main version */
 779 #define __ARMv8MML_CMSIS_VERSION_SUB   (0U)                                       /* [15:0]  CMSIS HAL sub version */
 780 #define __ARMv8MML_CMSIS_VERSION       ((__ARMv8MML_CMSIS_VERSION_MAIN << 16U) | \
 781                                          __ARMv8MML_CMSIS_VERSION_SUB           ) /* CMSIS HAL version number */
 782
 783 #define __CORTEX_M                     (tbd)                                      /* Cortex secure core */
 784 \endcode
 785
 786
 787 \section device_access Device Peripheral Access Layer
 788
 789 The \ref device_h_pg contains for each peripheral:
 790  - Register Layout Typedef
 791  - Base Address
 792  - Access Definitions
 793
 794 The section \ref peripheral_gr shows examples for peripheral definitions.
 795
 796 \section device_h_sec Device.h Template File
 797
 798 The silicon vendor needs to extend the Device.h template file with the CMSIS features described above.
 799 In addition the \ref device_h_pg may contain functions to access device-specific peripherals.
 800 The \ref system_Device_h_sec which is provided as part of the CMSIS specification is shown below.
 801
 802 \verbinclude "Include\Device.h"
 803
 804 */
 805
 806
 807
 808 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 809 /**
 810 \page partition_h_pg System Partition Header File partition_<device>.h
 811
 812 The \ref partition_h_pg contains the initial setup of the TrustZone hardware in an ARMv8-M system.
 813 The function \ref TZ_SAU_Setup is call from \ref SystemInit and uses the settings in this file to
 814 initialize the Secure Attribute Unit (SAU) and define non-secure interrupts (register NVIC_INIT_ITNS).
 815 The following initializations are performed:
 816
 817   - \ref sau_ctrlregister_sec provides settings for the SAU CTRL register.
 818   - \ref sau_regions_sect provides configuration of the SAU Address Regions.
 819   - \ref sau_sleepexception_sec provides device-specific deepsleep and exception settings.
 820   - \ref sau_interrupttarget_sec provides device-specific interrupt target settings.
 821
 822 \section sau_ctrlregister_sec  SAU CTRL register settings
 823 <table class="cmtable">
 824     <tr>
 825       <th>\#define</th>
 826       <th>Value Range</th>
 827       <th>Default</th>
 828       <th>Description</th>
 829     </tr>
 830     <tr>
 831       <td>SAU_INIT_CTRL</td>
 832       <td>0 .. 1</td>
 833       <td>0</td>
 834       <td>Initialize SAU CTRL register or not
 835            - 0: do not initialize SAU CTRL register
 836            - 1: initialize SAU CTRL register</td>
 837     </tr>
 838     <tr>
 839       <td>SAU_INIT_CTRL_ENABLE</td>
 840       <td>0 .. 1</td>
 841       <td>0</td>
 842       <td>enable/disable the SAU
 843            - 0: disable SAU
 844            - 1: enable SAU</td>
 845     </tr>
 846     <tr>
 847       <td>SAU_INIT_CTRL_ALLNS</td>
 848       <td>0 .. 1</td>
 849       <td>0</td>
 850       <td>value for SAU_CTRL register bit ALLNS
 851            - 0: all Memory is Secure
 852            - 1: all Memory is Non-Secure</td>
 853     </tr>
 854 </table>
 855
 856 \section sau_regions_sect  Configuration of the SAU Address Regions
 857 <table class="cmtable">
 858     <tr>
 859       <th>\#define</th>
 860       <th>Value Range</th>
 861       <th>Default</th>
 862       <th>Description</th>
 863     </tr>
 864     <tr>
 865       <td>SAU_REGIONS_MAX</td>
 866       <td>0 .. tbd</td>
 867       <td>8</td>
 868       <td>maximum number of SAU regions</td>
 869     </tr>
 870     <tr>
 871       <td>SAU_INIT_REGION<number></td>
 872       <td>0 .. 1</td>
 873       <td>0</td>
 874       <td>initialize SAU region or not
 875            - 0: do not initialize SAU region
 876            - 1: initialize SAU region</td>
 877     </tr>
 878     <tr>
 879       <td>SAU_INIT_START<number></td>
 880       <td>0x00000000 .. 0xFFFFFFE0\n
 881           [in steps of 32]</td>
 882       <td>0x00000000</td>
 883       <td>region start address</td>
 884     </tr>
 885     <tr>
 886       <td>SAU_INIT_END<number></td>
 887       <td>0x00000000 .. 0xFFFFFFE0\n
 888           [in steps of 32]</td>
 889       <td>0x00000000</td>
 890       <td>region start address</td>
 891     </tr>
 892     <tr>
 893       <td>SAU_INIT_NSC<number></td>
 894       <td>0 .. 1</td>
 895       <td>0</td>
 896       <td>SAU region attribute
 897            - 0: Non-Secure
 898            - 1: Secure, Non-Secure callable</td>
 899     </tr>
 900 </table>
 901
 902 The range of \<number\> is from 0 .. SAU_REGIONS_MAX.
 903 A set of these macros must exist for each \<number\>.
 904
 905 The following example shows a set of SAU region macros.
 906
 907 \code
 908 #define SAU_REGIONS_MAX   8                 /* Max. number of SAU regions */
 909
 910 #define SAU_INIT_REGION0    1
 911 #define SAU_INIT_START0     0x00000000      /* start address of SAU region 0 */
 912 #define SAU_INIT_END0       0x001FFFE0      /* end address of SAU region 0 */
 913 #define SAU_INIT_NSC0       1
 914
 915 #define SAU_INIT_REGION1    1
 916 #define SAU_INIT_START1     0x00200000      /* start address of SAU region 1 */
 917 #define SAU_INIT_END1       0x003FFFE0      /* end address of SAU region 1 */
 918 #define SAU_INIT_NSC1       0
 919
 920 #define SAU_INIT_REGION2    1
 921 #define SAU_INIT_START2     0x20200000      /* start address of SAU region 2 */
 922 #define SAU_INIT_END2       0x203FFFE0      /* end address of SAU region 2 */
 923 #define SAU_INIT_NSC2       0
 924
 925 #define SAU_INIT_REGION3    1
 926 #define SAU_INIT_START3     0x40000000      /* start address of SAU region 3 */
 927 #define SAU_INIT_END3       0x40040000      /* end address of SAU region 3 */
 928 #define SAU_INIT_NSC3       0
 929
 930 #define SAU_INIT_REGION4    0
 931 #define SAU_INIT_START4     0x00000000      /* start address of SAU region 4 */
 932 #define SAU_INIT_END4       0x00000000      /* end address of SAU region 4 */
 933 #define SAU_INIT_NSC4       0
 934
 935 #define SAU_INIT_REGION5    0
 936 #define SAU_INIT_START5     0x00000000      /* start address of SAU region 5 */
 937 #define SAU_INIT_END5       0x00000000      /* end address of SAU region 5 */
 938 #define SAU_INIT_NSC5       0
 939
 940 #define SAU_INIT_REGION6    0
 941 #define SAU_INIT_START6     0x00000000      /* start address of SAU region 6 */
 942 #define SAU_INIT_END6       0x00000000      /* end address of SAU region 6 */
 943 #define SAU_INIT_NSC6       0
 944
 945 #define SAU_INIT_REGION7    0
 946 #define SAU_INIT_START7     0x00000000      /* start address of SAU region 7 */
 947 #define SAU_INIT_END7       0x00000000      /* end address of SAU region 7 */
 948 #define SAU_INIT_NSC7       0
 949 \endcode
 950
 951
 952 \section sau_sleepexception_sec  Configuration of Sleep and Exception behaviour
 953 <table class="cmtable">
 954     <tr>
 955       <th>\#define</th>
 956       <th>Value Range</th>
 957       <th>Default</th>
 958       <th>Description</th>
 959     </tr>
 960     <tr>
 961       <td>CSR_INIT_DEEPSLEEPS</td>
 962       <td>0 .. 1</td>
 963       <td>0</td>
 964       <td>value for SCB_CSR register bit DEEPSLEEPS
 965            - 0: Deep Sleep can be enabled by Secure and Non-Secure state
 966            - 1: Deep Sleep can be enabled by Secure state only</td>
 967     </tr>
 968     <tr>
 969       <td>AIRCR_INIT_SYSRESETREQS</td>
 970       <td>0 .. 1</td>
 971       <td>0</td>
 972       <td>value for SCB_AIRCR register bit SYSRESETREQS
 973            - 0: System reset request accessible from Secure and Non-Secure state
 974            - 1: System reset request accessible from Secure state only</td>
 975     </tr>
 976     <tr>
 977       <td>AIRCR_INIT_PRIS</td>
 978       <td>0 .. 1</td>
 979       <td>0</td>
 980       <td>value for SCB_AIRCR register bit PRIS
 981            - 0: Priority of Non-Secure exceptions is Not altered
 982            - 1: Priority of Non-Secure exceptions is Lowered to 0x80-0xFF</td>
 983     </tr>
 984     <tr>
 985       <td>AIRCR_INIT_BFHFNMINS</td>
 986       <td>0 .. 1</td>
 987       <td>0</td>
 988       <td>value for SCB_AIRCR register bit BFHFNMINS
 989            - 0: BusFault, HardFault, and NMI target are Secure state
 990            - 1: BusFault, HardFault, and NMI target are Non-Secure state</td>
 991     </tr>
 992 </table>
 993
 994 \section sau_interrupttarget_sec Configuration of Interrupt Target settings
 995
 996 Each interrupt has a configuration bit that defines the execution
 997 in Secure or Non-secure state. The Non-Secure interrupts have a separate
 998 vector table.  Refer to \ref Model_TrustZone for more information.
 999
1000 <table class="cmtable">
1001     <tr>
1002       <th>\#define</th>
1003       <th>Value Range</th>
1004       <th>Default</th>
1005       <th>Description</th>
1006     </tr>
1007     <tr>
1008       <td>NVIC_INIT_ITNS<number></td>
1009       <td>0x00000000 .. 0xFFFFFFFF\n
1010           [each bit represents an interrupt]</td>
1011       <td>0x00000000</td>
1012       <td>Interrupt vector target
1013            - 0: Secure state
1014            - 1: Non-Secure state</td>
1015     </tr>
1016 </table>
1017
1018 The range of \<number\> is 0 .. (\<number of external interrupts\> + 31) / 32.
1019
1020 The following example shows the configuration for a maximum of 64 external interrupts.
1021
1022 \code
1023 #define NVIC_INIT_ITNS0      0x0000122B
1024 #define NVIC_INIT_ITNS1      0x0000003A
1025 \endcode
1026
1027
1028 */
1029
1030 */