begriffs open source - cmsis/blob - CMSIS/Documentation/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 that may 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 *) ((uintptr_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 __STATIC_FORCEINLINE
 135 \brief Define a static function that should be always inlined by the compiler.
 136 \details
 137 Defines a static function that should be always inlined by the compiler.
 138
 139 \note
 140 For compilers that do not allow to force function inlining, the macro maps to \ref __STATIC_INLINE.
 141
 142 <b>Code Example:</b>
 143 \code
 144 \\ Get Interrupt Vector
 145 __STATIC_FORCEINLINE uint32_t NVIC_GetVector(IRQn_Type IRQn)
 146 {
 147     uint32_t *vectors = (uint32_t *) ((uintptr_t) SCB->VTOR);
 148     return vectors[(int32_t)IRQn + NVIC_USER_IRQ_OFFSET];
 149 }
 150 \endcode
 151
 152 */
 153 #define __STATIC_FORCEINLINE
 154
 155 /**************************************************************************************************/
 156 /**
 157 \def __NO_RETURN
 158 \brief Inform the compiler that a function does not return.
 159 \details
 160 Informs the compiler that the function does not return. The compiler can then perform optimizations by
 161 removing code that is never reached.
 162
 163 <b>Code Example:</b>
 164 \code
 165 // OS idle demon (running when no other thread is ready to run).
 166
 167 __NO_RETURN void os_idle_demon (void);
 168 \endcode
 169
 170 */
 171 #define __NO_RETURN
 172
 173 /**************************************************************************************************/
 174 /**
 175 \def __RESTRICT
 176 \brief restrict pointer qualifier to enable additional optimizations.
 177 \details
 178 The __RESTRICT keyword corresponds to the \b restrict pointer qualifier that has been introduced in C99.
 179 __RESTRICT is a hint to the compiler that enables additional optimizations. It specifies that for the lifetime
 180 of the pointer, only the pointer itself or a value directly derived from it (such as pointer + 1) is used to access
 181 the object. The compiler may therefore ignore potential pointer aliasing effects and perform additional optimizations.
 182
 183 \note
 184 For compilers that do not support the restrict keyword, __RESTRICT is defined as an empty macro and a warning is issued.
 185
 186 <b>Code Example:</b>
 187 \code
 188 __STATIC_INLINE void ARM_MPU_OrderedMemcpy (volatile uint32_t* dst, const uint32_t* __RESTRICT src, uint32_t len)
 189 {
 190   uint32_t i;
 191   for (i = 0U; i < len; ++i)
 192   {
 193     dst[i] = src[i];   // Since src is restrict, the compiler can assume that dst and src are not overlapping may load multiple values at a time
 194   }
 195 }
 196 \endcode
 197
 198 */
 199 #define __RESTRICT
 200
 201 /**************************************************************************************************/
 202 /**
 203 \def __USED
 204 \brief Inform that a variable shall be retained in executable image.
 205 \details
 206 Definitions tagged with \b __USED in the source code should be not removed by the linker when detected as unused.
 207
 208 <b>Code Example:</b>
 209 \code
 210 /* Export following variables for debugging */
 211 __USED uint32_t const CMSIS_RTOS_API_Version = osCMSIS;
 212 __USED uint32_t const CMSIS_RTOS_RTX_Version = osCMSIS_RTX;
 213 __USED uint32_t const os_clockrate = OS_TICK;
 214 __USED uint32_t const os_timernum  = 0;
 215 \endcode
 216
 217 */
 218 #define __USED
 219
 220 /**************************************************************************************************/
 221 /**
 222 \def __WEAK
 223 \brief Export a function or variable weakly to allow overwrites.
 224 \details
 225 Functions defined with \b __WEAK export their symbols weakly. A weakly defined function behaves like a normally defined
 226 function unless a non-weakly defined function of the same name is linked into the same image. If both a non-weakly defined
 227 function and a weakly defined function exist in the same image then all calls to the function resolve to call the non-weak
 228 function.
 229
 230 Functions declared with \b __WEAK and then defined without \b __WEAK behave as non-weak functions.
 231
 232 <b>Code Example:</b>
 233 \code
 234 __WEAK void SystemInit(void)
 235 {
 236   SystemCoreSetup();
 237   SystemCoreClockSetup();
 238 }
 239 \endcode
 240
 241 */
 242 #define __WEAK
 243
 244 /**************************************************************************************************/
 245 /**
 246 \def __PACKED
 247 \brief Request smallest possible alignment.
 248 \details
 249 Specifies that a type must have the smallest possible alignment.
 250
 251 <b>Code Example:</b>
 252 \code
 253 struct foo {
 254   uint8_t  u8;
 255   uint32_t u32[2] __PACKED;
 256 };
 257 \endcode
 258
 259 */
 260 #define __PACKED
 261
 262 /**************************************************************************************************/
 263 /**
 264 \def __PACKED_STRUCT
 265 \brief Request smallest possible alignment for a structure.
 266 \details
 267 Specifies that a structure must have the smallest possible alignment.
 268
 269 <b>Code Example:</b>
 270 \code
 271 __PACKED_STRUCT foo {
 272   uint8_t   u8;
 273   uint32_t  u32;
 274   uint16_t  u16;
 275 };
 276 \endcode
 277
 278 */
 279 #define __PACKED_STRUCT
 280
 281 /**************************************************************************************************/
 282 /**
 283 \def __UNALIGNED_UINT32
 284 \brief Pointer for unaligned access of a uint32_t variable.
 285 \deprecated
 286 Do not use this macro.
 287 It has been superseded by \ref __UNALIGNED_UINT32_READ, \ref __UNALIGNED_UINT32_WRITE and will be removed in the future.
 288 \details
 289 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
 290 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 291 processor core and compiler settings.
 292
 293 <b>Code Example:</b>
 294 \code
 295 uint32_t val32;
 296
 297 void test (uint8_t *ptr) {
 298   __UNALIGNED_UINT32(ptr) = val32;
 299 }
 300 \endcode
 301
 302 */
 303 #define __UNALIGNED_UINT32
 304
 305 /**************************************************************************************************/
 306 /**
 307 \def __UNALIGNED_UINT16_READ
 308 \brief Pointer for unaligned read of a uint16_t variable.
 309 \details
 310 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in read
 311 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 312 processor core and compiler settings.
 313
 314 <b>Code Example:</b>
 315 \code
 316 uint16_t val16;
 317
 318 void test (uint8_t *ptr) {
 319    val16 = __UNALIGNED_UINT16_READ(ptr);
 320 }
 321 \endcode
 322
 323 */
 324 #define __UNALIGNED_UINT16_READ
 325
 326 /**************************************************************************************************/
 327 /**
 328 \def __UNALIGNED_UINT16_WRITE
 329 \brief Pointer for unaligned write of a uint16_t variable.
 330 \details
 331 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in write
 332 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 333 processor core and compiler settings.
 334
 335 <b>Code Example:</b>
 336 \code
 337 uint16_t val16 = 0U;
 338
 339 void test (uint8_t *ptr) {
 340    __UNALIGNED_UINT16_WRITE(ptr, val16);
 341 }
 342 \endcode
 343
 344 */
 345 #define __UNALIGNED_UINT16_WRITE
 346
 347 /**************************************************************************************************/
 348 /**
 349 \def __UNALIGNED_UINT32_READ
 350 \brief Pointer for unaligned read of a uint32_t variable.
 351 \details
 352 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in read
 353 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 354 processor core and compiler settings.
 355
 356 <b>Code Example:</b>
 357 \code
 358 uint32_t val32;
 359
 360 void test (uint8_t *ptr) {
 361    val32 = __UNALIGNED_UINT32_READ(ptr);
 362 }
 363 \endcode
 364
 365 */
 366 #define __UNALIGNED_UINT32_READ
 367
 368 /**************************************************************************************************/
 369 /**
 370 \def __UNALIGNED_UINT32_WRITE
 371 \brief Pointer for unaligned write of a uint32_t variable.
 372 \details
 373 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in write
 374 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 375 processor core and compiler settings.
 376
 377 <b>Code Example:</b>
 378 \code
 379 uint32_t val32 = 0U;
 380
 381 void test (uint8_t *ptr) {
 382    __UNALIGNED_UINT32_WRITE(ptr, val32);
 383 }
 384 \endcode
 385
 386 */
 387 #define __UNALIGNED_UINT32_WRITE
 388
 389 /**************************************************************************************************/
 390 /**
 391 \def __ALIGNED
 392 \brief Minimum alignment for a variable.
 393 \details
 394 Specifies a minimum alignment for a variable or structure field, measured in bytes.
 395
 396 <b>Code Example:</b>
 397 \code
 398 uint32_t stack_space[0x100] __ALIGNED(8);   // 8-byte alignment required
 399 \endcode
 400
 401 */
 402 #define __ALIGNED
 403
 404 /**************************************************************************************************/
 405 /**
 406 \def __COMPILER_BARRIER
 407 \brief Barrier to prevent compiler from reordering instructions.
 408 \details
 409 This barrier limits the compilers reordering optimizations. It prevents the compiler from swapping
 410 instructions resulting from code before and after the barrier.
 411
 412 <b>Code Example:</b>
 413 The assignments in the example are independent. Hence the compiler could choose a different order of
 414 execution, e.g. for a better pipeline utilization. Using the barrier in between prevents this type
 415 of reordering.
 416
 417 \code
 418 void test (uint8_t *ptr) {
 419   var1 = 1;
 420   __COMPILE_BARRIER();
 421   var2 = var3 + 1;
 422 }
 423 \endcode
 424
 425 */
 426 #define __COMPILER_BARRIER
 427
 428 /**************************************************************************************************/
 429 /**
 430 \def __NO_INIT
 431 \brief Force symbol into uninitialized memory section
 432 \details
 433 This puts a symbol (such as a variable) into an uninitialized memory section (e.g, .bss.noinit).
 434
 435 <b>Code Example:</b>
 436 The EventBuffer in the example does not need to be copy- or zero-initialized. By adding
 437 __NO_INIT this variable is allocated into an uninitialized memory section.
 438
 439 \code
 440 static EventRecord_t EventBuffer[EVENT_RECORD_COUNT] __NO_INIT __ALIGNED(16);
 441 \endcode
 442
 443 */
 444 #define __NO_INIT
 445
 446 /**************************************************************************************************/
 447 /**
 448 \def __ALIAS
 449 \brief Creates a symbol as alias to another symbol.
 450
 451 <b>Code Example:</b>
 452 The example declares the function Interrupt0_Handler. By default it is just an alias
 453 pointing to Default_Handler. In combination with __WEAK modifier this allows giving
 454 the function definition at a later point if required.
 455
 456 \code
 457 void Interrupt0_Handler     (void) __WEAK __ALIAS("Default_Handler");
 458 \endcode
 459
 460 */
 461 #define __ALIAS
 462
 463
 464 /**************************************************************************************************/
 465 /**
 466 \def __PROGRAM_START
 467 \brief Entry function into the user application or library startup.
 468 \details
 469 Gives the function to be jumped into right after low level initialization, i.e. SystemInit. This
 470 is compiler and library specific. CMSIS specifies common default for supported compilers.
 471
 472 \note This define is only intended to be used by the \ref startup_c_pg.
 473
 474 <b>Code Example:</b>
 475 \code
 476 void Reset_Handler(void)
 477 {
 478   SystemInit();                             /* CMSIS System Initialization */
 479   __PROGRAM_START();                        /* Enter PreMain (C library entry point) */
 480 }
 481 \endcode
 482 */
 483 #define __PROGRAM_START
 484
 485 /**************************************************************************************************/
 486 /**
 487 \def __INITIAL_SP
 488 \brief Compiler/linker symbol specifying the location of the main stack (MSP).
 489 \details
 490 The address of the specified symbol is used to initialize the main stack pointer (MSP) during low
 491 level init. This is compiler/linker specific. CMSIS specifies common default for supported compilers.
 492
 493 \note This define is only intended to be used by the \ref startup_c_pg.
 494 */
 495 #define __INITIAL_SP
 496
 497 /**************************************************************************************************/
 498 /**
 499 \def __STACK_LIMIT
 500 \brief Compiler/linker symbol specifying the limit of the main stack (MSP).
 501 \details
 502 The address of the specified symbol is used to initialize the main stack pointer limit (MSPLIM on Armv8-M)
 503 during low level init. This is compiler/linker specific. CMSIS specifies common default for supported
 504 compilers.
 505
 506 \note This define is only intended to be used by the \ref startup_c_pg.
 507
 508 <b>Code Example:</b>
 509 \code
 510 void Reset_Handler(void)
 511 {
 512   __set_MSPLIM((uint32_t)(&__STACK_LIMIT));
 513   // :
 514   // :
 515 }
 516 \endcode
 517 */
 518 #define __STACK_LIMIT
 519
 520 /**************************************************************************************************/
 521 /**
 522 \def __VECTOR_TABLE
 523 \brief Symbol name used for the (static) interrupt vector table.
 524 \details
 525 The given name is used for defining the static (compiler time) interrupt vector table. The name
 526 must comply with any compiler/linker conventions, e.g. if used for vector table relocation or debugger
 527 awareness. CMSIS specifies common default for supported compilers.
 528
 529 \note This define is only intended to be used by the \ref startup_c_pg.
 530 */
 531 #define __VECTOR_TABLE
 532
 533 /**************************************************************************************************/
 534 /**
 535 \def __VECTOR_TABLE_ATTRIBUTE
 536 \brief Additional decl specs to be used when defining the (static) interrupt vector table.
 537 \details
 538 The given decl specs are used for defining the static (compiler time) interrupt vector table, e.g.
 539 to mark the table as used and force it into a specific linker section. CMSIS specifies common default
 540 for supported compilers.
 541
 542 \note This define is only intended to be used by the \ref startup_c_pg.
 543 */
 544 #define __VECTOR_TABLE_ATTRIBUTE
 545
 546 /** @} */ /** end of compiler_conntrol_gr **/