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