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

   1 /**************************************************************************************************/
   2 /**
   3 \defgroup   compiler_conntrol_gr    Compiler Control
   4 \brief      Compiler agnostic \#define symbols for generic C/C++ source code
   5 \details
   6 The CMSIS-Core provides the header file <b>cmsis_compiler.h</b> with consistent \#define symbols for generate C or C++ source files that should be compiler agnostic.
   7 Each CMSIS compliant compiler should support the functionality described in this section.
   8
   9 The header file <b>cmsis_compiler.h</b> is also included by each \ref device_h_pg so that these definitions are available.
  10 @{
  11 */
  12
  13 /**
  14 \def __ARM_ARCH_6M__
  15 \brief Set to 1 when generating code for Armv6-M (Cortex-M0, Cortex-M1)
  16 \details
  17 The <b>\#define __ARM_ARCH_6M__</b> is set to 1 when generating code for the Armv6-M architecture. This architecture is for example used by the Cortex-M0, Cortex-M0+, and Cortex-M1 processor.
  18 */
  19 #define __ARM_ARCH_6M__
  20
  21 /**
  22 \def __ARM_ARCH_7M__
  23 \brief Set to 1 when generating code for Armv7-M (Cortex-M3)
  24 \details
  25 The <b>\#define __ARM_ARCH_7M__</b> is set to 1 when generating code for the Armv7-M architecture. This architecture is for example used by the Cortex-M3 processor.
  26 */
  27 #define __ARM_ARCH_7M__
  28
  29 /**
  30 \def __ARM_ARCH_7EM__
  31 \brief Set to 1 when generating code for Armv7-M (Cortex-M4) with FPU
  32 \details
  33 The <b>\#define __ARM_ARCH_7EM__</b> is set to 1 when generating code for the Armv7-M architecture with floating point extension. This architecture is for example used by the Cortex-M4 processor with FPU
  34 */
  35 #define __ARM_ARCH_7EM__
  36
  37 /**
  38 \cond (ARMv8M)
  39 */
  40
  41 /**
  42 \def __ARM_ARCH_8M_BASE__
  43 \brief Set to 1 when generating code for Armv8-M Baseline
  44 \details
  45 The <b>\#define __ARM_ARCH_8M_BASE__</b> is set to 1 when generating code for the Armv8-M architecture baseline variant.
  46 */
  47 #define __ARM_ARCH_8M_BASE__
  48
  49 /**
  50 \def __ARM_ARCH_8M_MAIN__
  51 \brief Set to 1 when generating code for Armv8-M Mainline
  52 \details
  53 The <b>\#define __ARM_ARCH_8M_MAIN__</b> is set to 1 when generating code for the Armv8-M architecture mainline variant.
  54 */
  55 #define __ARM_ARCH_8M_MAIN__
  56
  57 /**
  58 \endcond
  59 */
  60
  61
  62 /**************************************************************************************************/
  63 /**
  64 \def __ASM
  65 \brief Pass information from the compiler to the assembler.
  66 \details
  67 The \b __ASM keyword can declare or define an embedded assembly function or incorporate inline assembly into a function
  68 (shown in the code example below).
  69
  70 <b>Code Example:</b>
  71 \code
  72 // Reverse bit order of value
  73
  74 __attribute__( ( always_inline ) ) __STATIC_INLINE uint32_t __RBIT(uint32_t value)
  75 {
  76   uint32_t result;
  77
  78    __ASM volatile ("rbit %0, %1" : "=r" (result) : "r" (value) );
  79    return(result);
  80 }
  81 \endcode
  82
  83 */
  84 #define __ASM
  85
  86 /**************************************************************************************************/
  87 /**
  88 \def __INLINE
  89 \brief Recommend that function should be inlined by the compiler.
  90 \details
  91 Inline functions offer a trade-off between code size and performance. By default, the compiler decides during optimization whether to
  92 inline code or not. The \b __INLINE attribute gives the compiler an hint to inline this function. Still, the compiler may decide not to inline
  93 the function.  As the function is global an callable function is also generated.
  94
  95 <b> Code Example:</b>
  96 \code
  97 const uint32_t led_mask[] = {1U << 4, 1U << 5, 1U << 6, 1U << 7};
  98
  99 /*------------------------------------------------------------------------------
 100   Switch on LEDs
 101  *------------------------------------------------------------------------------*/
 102 __INLINE static void LED_On (uint32_t led) {
 103
 104   PTD->PCOR   = led_mask[led];
 105 }
 106 \endcode
 107
 108 */
 109 #define __INLINE
 110
 111 /**************************************************************************************************/
 112 /**
 113 \def __STATIC_INLINE
 114 \brief Define a static function should be inlined by the compiler.
 115 \details
 116 Defines a static function that may be inlined by the compiler. If the compiler generates inline code for
 117 all calls to this functions, no additional function implementation is generated which may further optimize space.
 118
 119 <b> Code Example:</b>
 120 \code
 121 \\ Get Interrupt Vector
 122 __STATIC_INLINE uint32_t NVIC_GetVector(IRQn_Type IRQn)
 123 {
 124     uint32_t *vectors = (uint32_t *)SCB->VTOR;
 125     return vectors[(int32_t)IRQn + NVIC_USER_IRQ_OFFSET];
 126 }
 127 \endcode
 128
 129 */
 130 #define __STATIC_INLINE
 131
 132 /**************************************************************************************************/
 133 /**
 134 \def __NO_RETURN
 135 \brief Inform the compiler that a function does not return.
 136 \details
 137 Informs the compiler that the function does not return. The compiler can then perform optimizations by
 138 removing code that is never reached.
 139
 140 <b> Code Example:</b>
 141 \code
 142 // OS idle demon (running when no other thread is ready to run).
 143
 144 __NO_RETURN void os_idle_demon (void);
 145 \endcode
 146
 147 */
 148 #define __NO_RETURN
 149
 150 /**************************************************************************************************/
 151 /**
 152 \def __USED
 153 \brief Inform that a variable shall be retained in executable image.
 154 \details
 155 Definitions tagged with \b __USED in the source code should be not removed by the linker when detected as unused.
 156
 157 <b> Code Example:</b>
 158 \code
 159 /* Export following variables for debugging */
 160 __USED uint32_t const CMSIS_RTOS_API_Version = osCMSIS;
 161 __USED uint32_t const CMSIS_RTOS_RTX_Version = osCMSIS_RTX;
 162 __USED uint32_t const os_clockrate = OS_TICK;
 163 __USED uint32_t const os_timernum  = 0;
 164 \endcode
 165
 166 */
 167 #define __USED
 168
 169 /**************************************************************************************************/
 170 /**
 171 \def __WEAK
 172 \brief Export a function or variable weakly to allow overwrites.
 173 \details
 174 Functions defined with \b __WEAK export their symbols weakly. A weakly defined function behaves like a normally defined
 175 function unless a non-weakly defined function of the same name is linked into the same image. If both a non-weakly defined
 176 function and a weakly defined function exist in the same image then all calls to the function resolve to call the non-weak
 177 function.
 178
 179 Functions declared with \b __WEAK and then defined without \b __WEAK behave as non-weak functions.
 180
 181 <b> Code Example:</b>
 182 \code
 183 __WEAK void SystemInit(void)
 184 {
 185   SystemCoreSetup();
 186   SystemCoreClockSetup();
 187 }
 188 \endcode
 189
 190 */
 191 #define __WEAK
 192
 193 /**************************************************************************************************/
 194 /**
 195 \def __PACKED
 196 \brief Request smallest possible alignment.
 197 \details
 198 Specifies that a type must have the smallest possible alignment.
 199
 200 <b> Code Example:</b>
 201 \code
 202 struct foo {
 203   uint8_t  u8;
 204   uint32_t u32[2] __PACKED;
 205 };
 206 \endcode
 207
 208 */
 209 #define __PACKED
 210
 211 /**************************************************************************************************/
 212 /**
 213 \def __PACKED_STRUCT
 214 \brief Request smallest possible alignment for a structure.
 215 \details
 216 Specifies that a structure must have the smallest possible alignment.
 217
 218 <b> Code Example:</b>
 219 \code
 220 __PACKED_STRUCT foo {
 221   uint8_t   u8;
 222   uint32_t  u32;
 223   uint16_t  u16;
 224 };
 225 \endcode
 226
 227 */
 228 #define __PACKED_STRUCT
 229
 230 /**************************************************************************************************/
 231 /**
 232 \def __UNALIGNED_UINT32
 233 \brief Pointer for unaligned access of a uint32_t variable.
 234 \deprecated
 235 Do not use this macro.
 236 It has been superseded by \ref __UNALIGNED_UINT32_READ, \ref __UNALIGNED_UINT32_WRITE and will be removed in the future.
 237 \details
 238 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
 239 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 240 processor core and compiler settings.
 241
 242 <b> Code Example:</b>
 243 \code
 244 uint32_t val32;
 245
 246 void test (uint8_t *ptr) {
 247   __UNALIGNED_UINT32(ptr) = val32;
 248 }
 249 \endcode
 250
 251 */
 252 #define __UNALIGNED_UINT32
 253
 254 /**************************************************************************************************/
 255 /**
 256 \def __UNALIGNED_UINT16_READ
 257 \brief Pointer for unaligned read of a uint16_t variable.
 258 \details
 259 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in read
 260 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 261 processor core and compiler settings.
 262
 263 <b> Code Example:</b>
 264 \code
 265 uint16_t val16;
 266
 267 void test (uint8_t *ptr) {
 268    val16 = __UNALIGNED_UINT16_READ(ptr);
 269 }
 270 \endcode
 271
 272 */
 273 #define __UNALIGNED_UINT16_READ
 274
 275 /**************************************************************************************************/
 276 /**
 277 \def __UNALIGNED_UINT16_WRITE
 278 \brief Pointer for unaligned write of a uint16_t variable.
 279 \details
 280 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in write
 281 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 282 processor core and compiler settings.
 283
 284 <b> Code Example:</b>
 285 \code
 286 uint16_t val16 = 0U;
 287
 288 void test (uint8_t *ptr) {
 289    __UNALIGNED_UINT16_WRITE(ptr, val16);
 290 }
 291 \endcode
 292
 293 */
 294 #define __UNALIGNED_UINT16_WRITE
 295
 296 /**************************************************************************************************/
 297 /**
 298 \def __UNALIGNED_UINT32_READ
 299 \brief Pointer for unaligned read of a uint32_t variable.
 300 \details
 301 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in read
 302 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 303 processor core and compiler settings.
 304
 305 <b> Code Example:</b>
 306 \code
 307 uint32_t val32;
 308
 309 void test (uint8_t *ptr) {
 310    val32 = __UNALIGNED_UINT32_READ(ptr);
 311 }
 312 \endcode
 313
 314 */
 315 #define __UNALIGNED_UINT32_READ
 316
 317 /**************************************************************************************************/
 318 /**
 319 \def __UNALIGNED_UINT32_WRITE
 320 \brief Pointer for unaligned write of a uint32_t variable.
 321 \details
 322 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in write
 323 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 324 processor core and compiler settings.
 325
 326 <b> Code Example:</b>
 327 \code
 328 uint32_t val32 = 0U;
 329
 330 void test (uint8_t *ptr) {
 331    __UNALIGNED_UINT32_WRITE(ptr, val32);
 332 }
 333 \endcode
 334
 335 */
 336 #define __UNALIGNED_UINT32_WRITE
 337
 338 /**************************************************************************************************/
 339 /**
 340 \def __ALIGNED
 341 \brief Minimum alignment for a variable.
 342 \details
 343 Specifies a minimum alignment for a variable or structure field, measured in bytes.
 344
 345 <b> Code Example:</b>
 346 \code
 347 uint32_t stack_space[0x100] __ALIGNED(8);   // 8-byte alignment required
 348 \endcode
 349
 350 */
 351 #define __ALIGNED
 352
 353 /** @} */ /** end of compiler_conntrol_gr **/