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

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