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