begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core_A/src/Using.txt

   1 /**
   2 \page using_pg Using CMSIS in Embedded Applications
   3
   4
   5 \details
   6
   7 To use the CMSIS-Core-A the following files are added to the embedded application:
   8  - \ref startup_c_pg with reset handler and exception vectors.
   9  - \ref system_c_pg with general device configuration (i.e. for clock and bus setup).
  10  - \ref device_h_pg gives access to processor core and all peripherals.
  11  - \ref mem_h_pg contains basic memory configurations.
  12  - \ref mmu_c_pg contains the memory management unit setup.
  13
  14 \note The files \ref startup_c_pg, \ref system_c_pg, \ref mem_h_pg, and \ref mmu_h_pg may require application specific adaptations and therefore should be copied
  15       into the application project folder prior configuration. The \ref device_h_pg is included in all source files that need device access
  16           and can be stored on a central include folder that is generic for all projects.
  17
  18 The \ref ResetHandler defined in \ref startup_c_pg is executed after reset.
  19 The default initialization sequence is
  20  - set the vector base address register (\ref __set_VBAR),
  21  - set stacks for each exception mode (\ref __set_mode, \ref __set_SP),
  22  - call \ref MMU_CreateTranslationTable, and
  23  - call \ref SystemInit.
  24
  25 After the system initialization control is transferred to the C/C++ run-time
  26 library which performs initialization and calls the \b main function in the user code. In addition the \ref startup_c_pg contains a weak default handler
  27 implementation for every exception. It may also contain stack and heap configurations for the user application.
  28
  29 The \ref system_c_pg performs the setup for the processor clock. The variable \ref SystemCoreClock indicates the CPU clock speed.
  30 \ref system_init_gr describes the minimum feature set. In addition the file may contain functions for the memory bus setup and clock re-configuration.
  31
  32 The \ref device_h_pg is the central include file that the application programmer is using in the C/C++ source code. It provides the following features:
  33  - \ref peripheral_gr provides a standardized register layout for all peripherals. Optionally functions for device-specific peripherals may be available.
  34  - \ref GIC_gr can be accessed with standardized symbols and functions for the General Interrupt Controller (GIC) are provided.
  35  - \ref intrinsic_CPU_gr allow to access special instructions, for example for activating sleep mode or the NOP instruction.
  36  - \ref intrinsic_SIMD_gr provide access to the DSP-oriented instructions.
  37  - \ref SysTick_gr function to configure and start a periodic timer interrupt.
  38  - \ref ITM_Debug_gr are functions that allow printf-style I/O via the CoreSight Debug Unit and ITM communication.
  39
  40
  41 \image html "CMSIS_CORE_Files_user.png" "CMSIS-Core-A User Files"
  42
  43 The CMSIS-Core-A are device specific. In addition, the \ref startup_c_pg is also compiler vendor specific.
  44 The various compiler vendor tool chains may provide folders that contain the CMSIS files for each supported device.
  45
  46
  47 For example, the following files are provided in MDK-ARM to support the STM32F10x Connectivity Line device variants:
  48
  49 <table class="cmtable">
  50     <tr>
  51       <th>File</th>
  52       <th>Description</th>
  53     </tr>
  54     <tr>
  55       <td>".\ARM\Startup\ST\STM32F10x\startup_stm32f10x_cl.s"</td>
  56       <td>\ref startup_s_pg for the STM32F10x Connectivity Line device variants.</td>
  57     </tr>
  58     <tr>
  59       <td>".\ARM\Startup\ST\STM32F10x\system_stmf10x.c"</td>
  60       <td>\ref system_c_pg for the STM32F10x device families.</td>
  61     </tr>
  62     <tr>
  63       <td>".\ARM\INC\ST\STM32F10x\stm32f10x.h"</td>
  64       <td>\ref device_h_pg for the STM32F10x device families.</td>
  65     </tr>
  66     <tr>
  67       <td>".\ARM\INC\ST\STM32F10x\system_stm32f10x.h"</td>
  68       <td>\ref system_Device_h_sec for the STM32F10x device families.</td>
  69     </tr>
  70 </table>
  71
  72
  73 \note The silicon vendors create these device-specific CMSIS-Core-M files based on \ref templates_pg provide by ARM.
  74
  75 Thereafter, the functions described under <a href="Modules.html">\b Reference </a> can be used in the application.
  76
  77 \b Examples
  78  - \subpage using_CMSIS is a simple example that shows the usage of the CMSIS layer.
  79  - \subpage using_VTOR_pg shows how to remap the interrupt vector table.
  80  - \subpage using_ARM_pg explains how to use CMSIS-Core-M for ARM processors.
  81
  82
  83 \page using_CMSIS Basic CMSIS Example
  84
  85 A typical example for using the CMSIS layer is provided below. The example is based on a STM32F10x Device.
  86
  87 \code
  88 #include <stm32f10x.h>                           // File name depends on device used
  89
  90 uint32_t volatile msTicks;                       // Counter for millisecond Interval
  91
  92 void SysTick_Handler (void) {                    // SysTick Interrupt Handler
  93   msTicks++;                                     // Increment Counter
  94 }
  95
  96 void WaitForTick (void)  {
  97   uint32_t curTicks;
  98
  99   curTicks = msTicks;                            // Save Current SysTick Value
 100   while (msTicks == curTicks)  {                 // Wait for next SysTick Interrupt
 101     __WFE ();                                    // Power-Down until next Event/Interrupt
 102   }
 103 }
 104
 105 void TIM1_UP_IRQHandler (void) {                 // Timer Interrupt Handler
 106   ;                                              // Add user code here
 107 }
 108
 109 void timer1_init(int frequency) {                // Set up Timer (device specific)
 110   NVIC_SetPriority (TIM1_UP_IRQn, 1);            // Set Timer priority
 111   NVIC_EnableIRQ (TIM1_UP_IRQn);                 // Enable Timer Interrupt
 112 }
 113
 114
 115 void Device_Initialization (void)  {             // Configure & Initialize MCU
 116   if (SysTick_Config (SystemCoreClock / 1000)) { // SysTick 1mSec
 117        : // Handle Error
 118   }
 119   timer1_init ();                                // setup device-specific timer
 120 }
 121
 122
 123 // The processor clock is initialized by CMSIS startup + system file
 124 void main (void) {                                   // user application starts here
 125   Device_Initialization ();                      // Configure & Initialize MCU
 126   while (1)  {                                   // Endless Loop (the Super-Loop)
 127     __disable_irq ();                            // Disable all interrupts
 128     Get_InputValues ();                          // Read Values
 129     __enable_irq ();                             // Enable all interrupts
 130     Calculation_Response ();                     // Calculate Results
 131     Output_Response ();                          // Output Results
 132     WaitForTick ();                              // Synchronize to SysTick Timer
 133   }
 134 }
 135 \endcode
 136
 137 \page using_VTOR_pg Using Interrupt Vector Remap
 138
 139 Most Cortex-M processors provide VTOR register for remapping interrupt vectors. The following example shows
 140 a typical use case where the interrupt vectors are copied to RAM and the SysTick_Handler is replaced.
 141
 142 \code
 143 #include "ARMCM3.h"                     // Device header
 144
 145 /* externals from startup_ARMCM3.s */
 146 extern uint32_t __Vectors[];                             /* vector table ROM  */
 147
 148 #define VECTORTABLE_SIZE        (256)          /* size Cortex-M3 vector table */
 149 #define VECTORTABLE_ALIGNMENT   (0x100ul) /* 16 Cortex + 32 ARMCM3 = 48 words */
 150                                           /* next power of 2 = 256            */
 151
 152 /* new vector table in RAM */
 153 uint32_t vectorTable_RAM[VECTORTABLE_SIZE] __attribute__(( aligned (VECTORTABLE_ALIGNMENT) ));
 154
 155 /*----------------------------------------------------------------------------
 156   SysTick_Handler
 157  *----------------------------------------------------------------------------*/
 158 volatile uint32_t msTicks = 0;                        /* counts 1ms timeTicks */
 159 void SysTick_Handler(void) {
 160   msTicks++;                                             /* increment counter */
 161 }
 162
 163 /*----------------------------------------------------------------------------
 164   SysTick_Handler (RAM)
 165  *----------------------------------------------------------------------------*/
 166 volatile uint32_t msTicks_RAM = 0;                    /* counts 1ms timeTicks */
 167 void SysTick_Handler_RAM(void) {
 168   msTicks_RAM++;                                         /* increment counter */
 169 }
 170
 171 /*----------------------------------------------------------------------------
 172   MAIN function
 173  *----------------------------------------------------------------------------*/
 174 int main (void) {
 175   uint32_t i;
 176
 177   for (i = 0; i < VECTORTABLE_SIZE; i++) {
 178     vectorTable_RAM[i] = __Vectors[i];            /* copy vector table to RAM */
 179   }
 180                                                    /* replace SysTick Handler */
 181   vectorTable_RAM[SysTick_IRQn + 16] = (uint32_t)SysTick_Handler_RAM;
 182
 183   /* relocate vector table */
 184   __disable_irq();
 185     SCB->VTOR = (uint32_t)&vectorTable_RAM;
 186   __DSB();
 187   __enable_irq();
 188
 189   SystemCoreClockUpdate();                        /* Get Core Clock Frequency */
 190   SysTick_Config(SystemCoreClock / 1000ul); /* Setup SysTick Timer for 1 msec */
 191
 192   while(1);
 193 }
 194 \endcode
 195
 196 \page using_ARM_pg Using CMSIS with generic ARM Processors
 197
 198 ARM provides CMSIS-Core-M files for the supported ARM Processors and for various compiler vendors.
 199 These files can be used when standard ARM processors should be used in a project.
 200 The table below lists the folder and device names of the ARM processors.
 201
 202 <table class="cmtable">
 203     <tr>
 204       <th>Folder</th>
 205       <th>Processor</th>
 206       <th>Description</th>
 207     </tr>
 208     <tr>
 209       <td>".\Device\ARM\ARMCM0"</td>
 210       <td>Cortex-M0</td>
 211       <td>Contains \b Include and \b Source template files configured for the Cortex-M0 processor.
 212               The device name is ARMCM0 and the name of the \ref device_h_pg is <ARMCM0.h>.
 213           </td>
 214     </tr>
 215     <tr>
 216       <td>".\Device\ARM\ARMCM0plus"</td>
 217       <td>Cortex-M0+</td>
 218       <td>Contains \b Include and \b Source template files configured for the Cortex-M0+ processor.
 219               The device name is ARMCM0plus and the name of the \ref device_h_pg is <ARMCM0plus.h>.
 220           </td>
 221     </tr>
 222     <tr>
 223       <td>".\Device\ARM\ARMCM3"</td>
 224       <td>Cortex-M3</td>
 225       <td>Contains \b Include and \b Source template files configured for the Cortex-M3 processor.
 226               The device name is ARMCM3 and the name of the \ref device_h_pg is <ARMCM3.h>.
 227           </td>
 228     </tr>
 229     <tr>
 230       <td>".\Device\ARM\ARMCM4"</td>
 231       <td>Cortex-M4</td>
 232       <td>Contains \b Include and \b Source template files configured for the Cortex-M4 processor.
 233               The device name is ARMCM4 and the name of the \ref device_h_pg is <ARMCM4.h>.
 234           </td>
 235     </tr>
 236     <tr>
 237       <td>".\Device\ARM\ARMCM7"</td>
 238       <td>Cortex-M7</td>
 239       <td>Contains \b Include and \b Source template files configured for the Cortex-M7 processor.
 240               The device name is ARMCM7 and the name of the \ref device_h_pg is <ARMCM7.h>.
 241           </td>
 242     </tr>
 243     <tr>
 244       <td>".\Device\ARM\ARMSC000"</td>
 245       <td>SecurCore SC000</td>
 246       <td>Contains \b Include and \b Source template files configured for the SecurCore SC000 processor.
 247               The device name is ARMSC000 and the name of the \ref device_h_pg is <ARMSC000.h>.
 248           </td>
 249     </tr>
 250     <tr>
 251       <td>".\Device\ARM\ARMSC300"</td>
 252       <td>SecurCore SC300</td>
 253       <td>Contains \b Include and \b Source template files configured for the SecurCore SC300 processor.
 254               The device name is ARMSC300 and the name of the \ref device_h_pg is <ARMSC300.h>.
 255           </td>
 256     </tr>
 257 </table>
 258
 259 \section using_ARM_Lib_sec Create generic Libraries with CMSIS
 260
 261 The CMSIS Processor and Core Peripheral files allow also to create generic libraries.
 262 The <a href="../../DSP/html/index.html">\b CMSIS-DSP </a> Libraries are an example for such a generic library.
 263
 264 To build a generic Library set the define \b __CMSIS_GENERIC and include the relevant <b>core_<cpu>.h</b> CMSIS CPU & Core Access header file for the processor.
 265 The define <b>__CMSIS_GENERIC</b> disables device-dependent features such as the <b>SysTick</b> timer and the <b>Interrupt System</b>.
 266 Refer to \ref core_config_sect for a list of the available <b>core_<cpu>.h</b> header files.
 267
 268 \b Example:
 269
 270 The following code section shows the usage of the <b>core_&lt;cpu&gt;.h</b> header files to build a generic library for Cortex-M0, Cortex-M3, Cortex-M4, or Cortex-M7.  To
 271 select the processor, the source code uses the define \b CORTEX_M7, \b CORTEX_M4, \b CORTEX_M3, \b CORTEX_M0, or \b CORTEX_M0PLUS. By using this header file, the source code can access
 272 the functions for \ref Core_Register_gr, \ref intrinsic_CPU_gr, \ref intrinsic_SIMD_gr, and \ref ITM_Debug_gr.
 273
 274
 275 \code
 276 #define __CMSIS_GENERIC              /* disable NVIC and Systick functions */
 277
 278 #if defined (CORTEX_M7)
 279   #include "core_cm7.h"
 280 #if defined (CORTEX_M4)
 281   #include "core_cm4.h"
 282 #elif defined (CORTEX_M3)
 283   #include "core_cm3.h"
 284 #elif defined (CORTEX_M0)
 285   #include "core_cm0.h"
 286 #elif defined (CORTEX_M0PLUS)
 287   #include "core_cm0plus.h"
 288 #else
 289   #error "Processor not specified or unsupported."
 290 #endif
 291
 292 \endcode
 293
 294
 295 */