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_c_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 Reset_Handler 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 SystemInit.
  23
  24 After the system initialization control is transferred to the C/C++ run-time
  25 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
  26 implementation for every exception. It may also contain stack and heap configurations for the user application.
  27
  28 The \ref system_c_pg performs the setup for the processor clock and the initialization of memory caches, memory management unit, generic interrupt interface
  29 and floating point unit. 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_functions can be accessed with standardized symbols and functions for the General Interrupt Controller (GIC) are provided.
  35  - \ref CMSIS_Core_InstructionInterface allow to access special instructions, for example for activating sleep mode or the NOP instruction.
  36  - \ref PL1_timer_functions "Generic" and \ref PTM_timer_functions "Private" Timer functions to configure and start a periodic timer interrupt.
  37  - \ref L1_cache_functions "Level 1" and \ref L2_cache_functions "Level 2" Cache controller functions to enable, disable, clean and invalidate caches.
  38
  39 CMSIS-Pack provides the <b>\#define CMSIS_header_file</b> in <a href="../../Pack/html/pdsc_components_pg.html#RTE_Components_h"><b>RTE_Components.h</b></a> which gives you access to this <b><i>device</i>.h</b> file.
  40
  41 \image html "CMSIS_CORE_A_Files_user.png" "CMSIS-Core-A User Files"
  42
  43 The CMSIS-Core-A user files 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 \note The silicon vendors create these device-specific CMSIS-Core-A files based on \ref templates_pg provide by Arm.
  47
  48 Thereafter, the functions described under <a href="modules.html">\b Reference </a> can be used in the application.
  49
  50 \b Examples
  51  - \subpage using_CMSIS is a simple example that shows the usage of the CMSIS layer.
  52  - \subpage using_ARM_pg explains how to use CMSIS-Core-M for Arm processors.
  53
  54
  55 \page using_CMSIS Basic CMSIS Example
  56
  57 A typical example for using the CMSIS layer is provided below. The example is based on an unspecific Cortex-A9 Device.
  58
  59 \code
  60 #include <ARMCA9.h>                              // File name depends on device used
  61
  62 static const uint32_t TICK_RATE_HZ = 1000U;
  63
  64 uint32_t volatile msTicks;                       // Counter for millisecond Interval
  65
  66 static void SysTick_Handler( void )
  67 {
  68   msTicks++;                                     // Increment Counter
  69 }
  70
  71 // We use the Private Tiemer (PTIM) of the Cortex-A9 FVP Model here.
  72 // In general the available Timers are highly vendor specific for Cortex-A processors.
  73 void private_timer_init(void) {
  74
  75   PTIM_SetLoadValue ((SystemCoreClock/TICK_RATE_HZ) - 1U);
  76   PTIM_SetControl (PTIM_GetControl() | 7U);
  77
  78   /* Install SysTick_Handler as the interrupt function for PTIM */
  79   IRQ_SetHandler((IRQn_ID_t)PrivTimer_IRQn, SysTick_Handler);
  80
  81   /* Determine number of implemented priority bits */
  82   IRQ_SetPriority ((IRQn_ID_t)PrivTimer_IRQn, IRQ_PRIORITY_Msk);
  83
  84   /* Set lowest priority -1 */
  85   IRQ_SetPriority ((IRQn_ID_t)PrivTimer_IRQn, GIC_GetPriority((IRQn_ID_t)PrivTimer_IRQn)-1);
  86
  87   /* Enable IRQ */
  88   IRQ_Enable ((IRQn_ID_t)PrivTimer_IRQn);
  89 }
  90
  91 /* Delay execution for given amount of ticks */
  92 void Delay(uint32_t ticks)  {
  93   uint32_t tgtTicks = msTicks + ticks;             // target tick count to delay execution to
  94   while (msTicks == tgtTicks)  {
  95     __WFE ();                                      // Power-Down until next Event/Interrupt
  96   }
  97 }
  98
  99 /* main function */
 100 int main(void)
 101 {
 102   /* Initialize device HAL here */
 103   private_timer_init();
 104
 105   static uint8_t ledState = 0;
 106
 107   /* Infinite loop */
 108   while (1)
 109   {
 110     /* Add application code here */
 111     ledState = !ledState;
 112     Delay(500);
 113   }
 114 }
 115 \endcode
 116
 117 CMSIS-Pack provides the <b>\#define CMSIS_header_file</b> in <a href="../../Pack/html/pdsc_components_pg.html#RTE_Components_h"><b>RTE_Components.h</b></a> which gives you access to the <b><i>device</i>.h</b> file
 118 of a project. This allows you to generate generic software components that use the device selected in a project.
 119
 120 \code
 121 #include "RTE_Components.h"     // include information about project configuration
 122 #include CMSIS_device_header    // include <device>.h file
 123 \endcode
 124
 125 \page using_ARM_pg Using CMSIS with generic Arm Processors
 126
 127 Arm provides CMSIS-Core-A files for the supported Arm Processors and for various compiler vendors.
 128 These files can be used when standard Arm processors should be used in a project.
 129 The table below lists the folder and device names of the Arm processors.
 130
 131 <table class="cmtable">
 132   <tr>
 133     <th>Folder</th>
 134     <th>Processor</th>
 135     <th>Description</th>
 136   </tr>
 137   <tr>
 138     <td>".\Device\ARM\ARMCA5"</td>
 139     <td>Cortex-A5</td>
 140     <td>Contains \b Include and \b Source template files configured for the Cortex-A5 processor.
 141         The device name is ARMCA5 and the name of the \ref device_h_pg is <ARMCA5.h>.
 142     </td>
 143   </tr>
 144   <tr>
 145     <td>".\Device\ARM\ARMCA7"</td>
 146     <td>Cortex-A7</td>
 147     <td>Contains \b Include and \b Source template files configured for the Cortex-A7 processor.
 148         The device name is ARMCA7 and the name of the \ref device_h_pg is <ARMCA7.h>.
 149     </td>
 150   </tr>
 151   <tr>
 152     <td>".\Device\ARM\ARMCA9"</td>
 153     <td>Cortex-A9</td>
 154     <td>Contains \b Include and \b Source template files configured for the Cortex-A9 processor.
 155         The device name is ARMCA9 and the name of the \ref device_h_pg is <ARMCA9.h>.
 156     </td>
 157   </tr>
 158 </table>
 159
 160 \note
 161 CMSIS-Pack provides the <b>\#define CMSIS_header_file</b> in <a href="../../Pack/html/pdsc_components_pg.html#RTE_Components_h"><b>RTE_Components.h</b></a> which gives you access to the <b><i>device</i>.h</b> file
 162 of a project. This allows you to generate generic software components that adjust to the device settings.
 163
 164 */