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

   1 /**************************************************************************************************/
   2 /**
   3 \defgroup   compiler_conntrol_gr    Compiler Control
   4 \brief      Compiler specific \#defines in CMSIS-Core
   5 \details
   6 CMSIS-Core provides a set of compiler control \#defines that produce a consistent behavior, no matter which compiler is used
   7 to build the application code.
   8 @{
   9 */
  10
  11 /**************************************************************************************************/
  12 /**
  13 \def __ASM
  14 \brief Keyword passing information from the compiler to the assembler.
  15 \details
  16 The \b __ASM keyword can declare or define an embedded assembly function or incorporate inline assembly into a function
  17 (shown in the code example below).
  18
  19 <b>Code Example:</b>
  20 \code
  21 // Reverse bit order of value
  22
  23 __attribute__( ( always_inline ) ) __STATIC_INLINE uint32_t __RBIT(uint32_t value)
  24 {
  25   uint32_t result;
  26
  27    __ASM volatile ("rbit %0, %1" : "=r" (result) : "r" (value) );
  28    return(result);
  29 }
  30 \endcode
  31
  32 */
  33 #define __ASM
  34
  35 /**************************************************************************************************/
  36 /**
  37 \def __INLINE
  38 \brief Keyword suggesting to the compiler that it compiles a C or C++ function inline.
  39 \details
  40 Inline functions offer a trade-off between code size and performance. By default, the compiler decides for itself whether to
  41 inline code or not.
  42
  43 In most circumstances, the decision to inline a particular function is best left to the compiler. However, you can give the
  44 compiler a hint that a function is required to be inlined by using \b __INLINE. Still, the compiler can decide not to inline
  45 the function.
  46
  47 <b> Code Example:</b>
  48 \code
  49 const uint32_t led_mask[] = {1UL << 4, 1UL << 5, 1UL << 6, 1UL << 7};
  50
  51 /*------------------------------------------------------------------------------
  52   Switch on LEDs
  53  *------------------------------------------------------------------------------*/
  54 __INLINE static void LED_On (uint32_t led) {
  55
  56   PTD->PCOR   = led_mask[led];
  57 }
  58 \endcode
  59
  60 */
  61 #define __INLINE
  62
  63 /**************************************************************************************************/
  64 /**
  65 \def __STATIC_INLINE
  66 \brief Keyword suggesting to the compiler that it compiles a C or C++ function statically inline.
  67 \details
  68 As for \ref __INLINE, the compiler may choose to inline the function. In addition, the compiler will add a locally scoped
  69 version of the function in the resulting object file. As you can have one static version of the function per object file, you
  70 may end up with multiple definitions of the same function. This will require more space.
  71
  72 <b> Code Example:</b>
  73 \code
  74 // Set Priority Grouping
  75
  76 __STATIC_INLINE void NVIC_SetPriorityGrouping(uint32_t PriorityGroup)
  77 {
  78   uint32_t reg_value;
  79   uint32_t PriorityGroupTmp = (PriorityGroup & (uint32_t)0x07);               /* only values 0..7 are used          */
  80
  81   reg_value  =  SCB->AIRCR;                                                   /* read old register configuration    */
  82   reg_value &= ~(SCB_AIRCR_VECTKEY_Msk | SCB_AIRCR_PRIGROUP_Msk);             /* clear bits to change               */
  83   reg_value  =  (reg_value                                 |
  84                 ((uint32_t)0x5FA << SCB_AIRCR_VECTKEY_Pos) |
  85                 (PriorityGroupTmp << 8));                                     /* Insert write key and priority group */
  86   SCB->AIRCR =  reg_value;
  87 }
  88 \endcode
  89
  90 */
  91 #define __STATIC_INLINE
  92
  93 /**************************************************************************************************/
  94 /**
  95 \def __NO_RETURN
  96 \brief Informs the compiler that the function does not return.
  97 \details
  98 The compiler can perform optimizations by removing code that is never reached. If the function reaches an explicit or
  99 implicit return, \b __NO_RETURN is ignored and the compiler generates a warning.
 100
 101 <b> Code Example:</b>
 102 \code
 103 // OS idle demon (running when no other thread is ready to run).
 104
 105 __NO_RETURN void os_idle_demon (void);
 106 \endcode
 107
 108 */
 109 #define __NO_RETURN
 110
 111 /**************************************************************************************************/
 112 /**
 113 \def __USED
 114 \brief Informs the compiler that a static variable is to be retained in the object file.
 115 \details
 116 Data marked with \b __USED is tagged in the object file to avoid removal by linker unused section removal. Static variables
 117 marked as used are emitted to a single section, in the order they are declared.
 118
 119 <b> Code Example:</b>
 120 \code
 121 /* Export following defines to debugger. */
 122 __USED uint32_t const CMSIS_RTOS_API_Version = osCMSIS;
 123 __USED uint32_t const CMSIS_RTOS_RTX_Version = osCMSIS_RTX;
 124 __USED uint32_t const os_clockrate = OS_TICK;
 125 __USED uint32_t const os_timernum  = 0;
 126 \endcode
 127
 128 */
 129 #define __USED
 130
 131 /**************************************************************************************************/
 132 /**
 133 \def __WEAK
 134 \brief Keyword instructing the compiler to export a function or variable weakly.
 135 \details
 136 Functions defined with \b __WEAK export their symbols weakly. A weakly defined function behaves like a normally defined
 137 function unless a non-weakly defined function of the same name is linked into the same image. If both a non-weakly defined
 138 function and a weakly defined function exist in the same image then all calls to the function resolve to call the non-weak
 139 function.
 140
 141 Functions declared with \b __WEAK and then defined without \b __WEAK behave as non-weak functions.
 142
 143 <b> Code Example:</b>
 144 \code
 145 __WEAK void SystemInit(void)
 146 {
 147   SystemCoreSetup();
 148   SystemCoreClockSetup();
 149 }
 150 \endcode
 151
 152 */
 153 #define __WEAK
 154
 155 /**************************************************************************************************/
 156 /**
 157 \def __UNALIGNED_UINT32
 158 \brief Pointer to unaligned uint32_t variable.
 159 \details
 160 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in read/write
 161 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying ARM
 162 processor core and compiler settings.
 163
 164 <b> Code Example:</b>
 165 \code
 166 uint32_t val32;
 167
 168 void test (uint8_t *ptr) {
 169   __UNALIGNED_UINT32(ptr) = val32;
 170 }
 171 \endcode
 172
 173 */
 174 #define __UNALIGNED_UINT32
 175
 176 /**************************************************************************************************/
 177 /**
 178 \def __ALIGNED
 179 \brief Alignment of a variable.
 180 \details
 181 Specifies a minimum alignment for a variable or structure field, measured in bytes.
 182
 183 <b> Code Example:</b>
 184 \code
 185 uint32_t val32 __ALIGNED(4);
 186 \endcode
 187
 188 */
 189 #define __ALIGNED
 190
 191 /**************************************************************************************************/
 192 /**
 193 \def __PACKED
 194 \brief Smallest possible alignment.
 195 \details
 196 Specifies that a type must have the smallest possible alignment.
 197
 198 <b> Code Example:</b>
 199 \code
 200 struct __PACKED {
 201   uint8_t  len;
 202   uint8_t  type;
 203   uint16_t langid;
 204 } desc_langid;
 205 \endcode
 206
 207 */
 208 #define __PACKED
 209
 210 /** @} */ /** end of compiler_conntrol_gr **/