begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/core_startup_c.md

   1 # Startup File startup_\<Device\>.c {#startup_c_pg}
   2
   3 The startup file defines device exceptions and interrupts, and provides their initial (weak) handler functions. The file has a naming convention `startup_<Device>.c` where `<Device>` corresponds to the device name.
   4
   5 Specifically, following functionalities are provided in the startup file:
   6  - The reset handler `Reset_Handler` which is executed upon CPU reset and typically calls the `SystemInit()` function. After the system init the control is transferred to the C/C++ run-time library which performs initialization and calls the `main` function in the user code.
   7  - The setup values for the Main Stack Pointer (MSP).
   8  - Exception vectors of the Cortex-M Processor with weak functions that implement default routines.
   9  - Interrupt vectors that are device specific with weak functions that implement default routines.
  10
  11 To adapt the file to a specific device only the interrupt vector table needs to be extended with the device-specific interrupt handlers. The naming convention for the interrupt handler names is `<interrupt_name>_IRQHandler`. This table needs to be consistent with \ref IRQn_Type that defines all the IRQ numbers for each interrupt.
  12
  13 Additional application-specific adaptations may be required in the startup code and therefore so the startup file shall be located in the application project. \ref cmsis_files_dfps explains how this can be achieved when device support is provided in [CMSIS pack format](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html).
  14
  15 **Example:**
  16
  17 The following example shows the extension of the interrupt vector table for the LPC1100 device family.
  18
  19 ```c
  20 /*----------------------------------------------------------------------------
  21   Exception / Interrupt Handler
  22  *----------------------------------------------------------------------------*/
  23 /* Exceptions */
  24 void WAKEUP0_IRQHandler     (void) __attribute__ ((weak, alias("Default_Handler")));
  25 void WAKEUP1_IRQHandler     (void) __attribute__ ((weak, alias("Default_Handler")));
  26 void WAKEUP2_IRQHandler     (void) __attribute__ ((weak, alias("Default_Handler")));
  27 // :
  28 // :
  29 void EINT1_IRQHandler       (void) __attribute__ ((weak, alias("Default_Handler")));
  30 void EINT2_IRQHandler       (void) __attribute__ ((weak, alias("Default_Handler")));
  31 // :
  32 // :
  33
  34 /*----------------------------------------------------------------------------
  35   Exception / Interrupt Vector table
  36  *----------------------------------------------------------------------------*/
  37 extern const pFunc __VECTOR_TABLE[240];
  38        const pFunc __VECTOR_TABLE[240] __VECTOR_TABLE_ATTRIBUTE = {
  39   (pFunc)(&__INITIAL_SP),                   /*     Initial Stack Pointer */
  40   Reset_Handler,                            /*     Reset Handler */
  41   NMI_Handler,                              /* -14 NMI Handler */
  42   HardFault_Handler,                        /* -13 Hard Fault Handler */
  43   MemManage_Handler,                        /* -12 MPU Fault Handler */
  44   BusFault_Handler,                         /* -11 Bus Fault Handler */
  45   UsageFault_Handler,                       /* -10 Usage Fault Handler */
  46   0,                                        /*     Reserved */
  47   0,                                        /*     Reserved */
  48   0,                                        /*     Reserved */
  49   0,                                        /*     Reserved */
  50   SVC_Handler,                              /*  -5 SVC Handler */
  51   DebugMon_Handler,                         /*  -4 Debug Monitor Handler */
  52   0,                                        /*     Reserved */
  53   PendSV_Handler,                           /*  -2 PendSV Handler */
  54   SysTick_Handler,                          /*  -1 SysTick Handler */
  55
  56   /* Interrupts */
  57   WAKEUP0_IRQHandler,                       /*   0 Wakeup PIO0.0 */
  58   WAKEUP1_IRQHandler,                       /*   1 Wakeup PIO0.1 */
  59   WAKEUP2_IRQHandler,                       /*   2 Wakeup PIO0.2 */
  60   // :
  61   // :
  62   EINT1_IRQHandler,                         /*  30 PIO INT1 */
  63   EINT2_IRQHandler,                         /*  31 PIO INT2 */
  64   // :
  65   // :
  66 };
  67 ```
  68
  69 ## startup_Device.c Template File {#startup_c_sec}
  70
  71 CMSIS-Core \ref cmsis_template_files include a `startup_Device.c` file that can be used as a starting point for chip vendors to implement own device-specific startup file.
  72
  73 The C startup file relys on certain compiler specific preprocessor defines specified in CMSIS compiler headers:
  74  - \ref __INITIAL_SP
  75  - \ref __STACK_LIMIT
  76  - \ref __PROGRAM_START
  77  - \ref __VECTOR_TABLE
  78  - \ref __VECTOR_TABLE_ATTRIBUTE
  79  - \ref __STACK_SEAL (for Armv8-M/v8.1-M)
  80  - \ref __TZ_set_STACKSEAL_S (for Armv8-M/v8.1-M)
  81
  82 The stack sealing and the initialization for the Stack Limit register is done in function ` Reset_Handler(void)`:
  83
  84 ```c
  85 /*----------------------------------------------------------------------------
  86   Reset Handler called on controller reset
  87  *----------------------------------------------------------------------------*/
  88 __NO_RETURN void Reset_Handler(void)
  89 {
  90   __set_PSP((uint32_t)(&__INITIAL_SP));
  91
  92   __set_MSPLIM((uint32_t)(&__STACK_LIMIT));
  93   __set_PSPLIM((uint32_t)(&__STACK_LIMIT));
  94
  95 #if defined (__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3U)
  96   __TZ_set_STACKSEAL_S((uint32_t *)(&__STACK_SEAL));
  97 #endif
  98
  99   SystemInit();                             /* CMSIS System Initialization */
 100   __PROGRAM_START();                        /* Enter PreMain (C library entry point) */
 101 }
 102 ```
 103
 104 \note Stack Sealing also requires the application project to use a scatter file (or a linker script) as explained in \ref RTOS_TrustZone_stacksealing section.