begriffs open source - cmsis/blob - CMSIS/Documentation/Doxygen/Core_A/src/Ref_CompilerControl.txt

   1 /**************************************************************************//**
   2  * @file     Ref_CompilerControl.txt
   3  * @brief    CMSIS compiler specific macros, functions, instructions
   4  * @version  V1.00
   5  * @date     22. Feb 2017
   6  ******************************************************************************/
   7 /* CMSIS compiler control architecture macros */
   8 /**
   9 \defgroup comp_cntrl_gr Compiler Control
  10 \brief Compiler agnostic \#define symbols for generic C/C++ source code
  11 \details
  12 The CMSIS-Core provides the header file \b cmsis_compiler.h with consistent \#define symbols to generate C or C++ source files that should be compiler agnostic.
  13 Each CMSIS compliant compiler should support the functionality described in this section.
  14 @{
  15 */
  16
  17 /**
  18 \def __ARMCC_VERSION
  19 */
  20
  21 /**
  22 \def __ARM_ARCH_7A__
  23 \brief Set to 1 when generating code for Armv7-A (Cortex-A7)
  24 \details
  25 The \b \#define __ARM_ARCH_7A__ is set to 1 when generating code for the Armv7-A architecture. This architecture is for example used by the Cortex-A7 processor.
  26 */
  27 #define __ARM_ARCH_7A__
  28
  29 /**
  30 \def __ASM
  31 \brief Pass information from the compiler to the assembler.
  32 \details
  33 The \b __ASM keyword can declare or define an embedded assembly function or incorporate inline assembly into a function
  34 (shown in the code example below).
  35
  36 <b>Code Example:</b>
  37 \code
  38 // Reverse bit order of value
  39
  40 __attribute__( ( always_inline ) ) __STATIC_INLINE uint32_t __RBIT(uint32_t value)
  41 {
  42   uint32_t result;
  43
  44    __ASM volatile ("rbit %0, %1" : "=r" (result) : "r" (value) );
  45    return(result);
  46 }
  47 \endcode
  48 */
  49
  50 /**
  51 \def __INLINE
  52 \brief Recommend that function should be inlined by the compiler.
  53 \details
  54 Inline functions offer a trade-off between code size and performance. By default, the compiler decides during optimization whether to
  55 inline code or not. The \b __INLINE attribute gives the compiler an hint to inline this function.
  56 Still, the compiler may decide not to inline the function. As the function is global an callable function is also generated.
  57
  58 <b> Code Example:</b>
  59 \code
  60 const uint32_t led_mask[] = {1U << 4, 1U << 5, 1U << 6, 1U << 7};
  61
  62 //------------------------------------------------------------------------------
  63 // Switch on LEDs
  64 //------------------------------------------------------------------------------
  65 __INLINE static void LED_On (uint32_t led) {
  66
  67   PTD->PCOR   = led_mask[led];
  68 }
  69 \endcode
  70 */
  71
  72 /**
  73 \def __STATIC_INLINE
  74 \brief Define a static function should be inlined by the compiler.
  75 \details
  76 Defines a static function that may be inlined by the compiler. If the compiler generates inline code for
  77 all calls to this functions, no additional function implementation is generated which may further optimize space.
  78
  79 <b> Code Example:</b>
  80 \code
  81 __STATIC_INLINE uint32_t GIC_GetPriority(IRQn_Type IRQn)
  82 {
  83   return((uint32_t)GICDistributor->D_IPRIORITYR[((uint32_t)(int32_t)IRQn)]);
  84 }
  85 \endcode
  86 */
  87
  88 /**************************************************************************************************/
  89 /**
  90 \def __STATIC_FORCEINLINE
  91 \brief Define a static function that should be always inlined by the compiler.
  92 \details
  93 Defines a static function that should be always inlined by the compiler.
  94
  95 \note
  96 For compilers that do not allow to force function inlining, the macro maps to \ref __STATIC_INLINE.
  97
  98 <b> Code Example:</b>
  99 \code
 100 \\ Get Interrupt Vector
 101 __STATIC_FORCEINLINE uint32_t NVIC_GetVector(IRQn_Type IRQn)
 102 {
 103     uint32_t *vectors = (uint32_t *) ((uintptr_t) SCB->VTOR);
 104     return vectors[(int32_t)IRQn + NVIC_USER_IRQ_OFFSET];
 105 }
 106 \endcode
 107
 108 */
 109 #define __STATIC_FORCEINLINE
 110
 111 /**
 112 \def __NO_RETURN
 113 \brief Inform the compiler that a function does not return.
 114 \details
 115 Informs the compiler that the function does not return. The compiler can then perform optimizations by
 116 removing code that is never reached.
 117
 118 <b> Code Example:</b>
 119 \code
 120 // OS idle demon (running when no other thread is ready to run).
 121
 122 __NO_RETURN void os_idle_demon (void);
 123 \endcode
 124 */
 125
 126 /**
 127 \def __USED
 128 \brief Inform that a variable shall be retained in executable image.
 129 \details
 130 Definitions tagged with \b __USED in the source code should be not removed by the linker when detected as unused.
 131
 132 <b> Code Example:</b>
 133 \code
 134 // Export following variables for debugging
 135 __USED uint32_t const CMSIS_RTOS_API_Version = osCMSIS;
 136 __USED uint32_t const CMSIS_RTOS_RTX_Version = osCMSIS_RTX;
 137 __USED uint32_t const os_clockrate = OS_TICK;
 138 __USED uint32_t const os_timernum  = 0;
 139 \endcode
 140 **/
 141
 142 /**
 143 \def __WEAK
 144 \brief Export a function or variable weakly to allow overwrites.
 145 \details
 146 Functions defined with \b __WEAK export their symbols weakly. A function defined weak behaves like a normal defined
 147 function unless a non-weak function with the same name is linked into the same image. If both a non-weak
 148 function and a weak defined function exist in the same image, then all calls to the function resolve to the non-weak
 149 function.
 150
 151 Functions declared with \b __WEAK and then defined without \b __WEAK behave as non-weak functions.
 152
 153 <b> Code Example:</b>
 154 \code
 155 __WEAK void SystemInit(void)
 156 {
 157   SystemCoreSetup();
 158   SystemCoreClockSetup();
 159 }
 160 \endcode
 161 */
 162
 163 /**
 164 \def __ALIGNED(x)
 165 \brief Minimum alignment for a variable.
 166 \details
 167 Specifies a minimum alignment for a variable or structure field, measured in bytes.
 168
 169 <b> Code Example:</b>
 170 \code
 171 uint32_t stack_space[0x100] __ALIGNED(8);   // 8-byte alignment required
 172 \endcode
 173 */
 174
 175 /**
 176 \def __PACKED
 177 \brief Request smallest possible alignment.
 178 \details
 179 Specifies that a type must have the smallest possible alignment.
 180
 181 <b> Code Example:</b>
 182 \code
 183 struct foo {
 184   uint8_t  u8;
 185   uint32_t u32[2] __PACKED;
 186 };
 187 \endcode
 188 */
 189 /**************************************************************************************************/
 190 /**
 191 \def __PACKED_STRUCT
 192 \brief Request smallest possible alignment for a structure.
 193 \details
 194 Specifies that a structure must have the smallest possible alignment.
 195
 196 <b> Code Example:</b>
 197 \code
 198 __PACKED_STRUCT foo {
 199   uint8_t   u8;
 200   uint32_t  u32;
 201   uint16_t  u16;
 202 };
 203 \endcode
 204
 205 */
 206 #define __PACKED_STRUCT
 207
 208 /**************************************************************************************************/
 209 /**
 210 \def __UNALIGNED_UINT32
 211 \brief Pointer for unaligned access of a uint32_t variable.
 212 \deprecated
 213 Do not use this macro.
 214 It has been superseded by \ref __UNALIGNED_UINT32_READ, \ref __UNALIGNED_UINT32_WRITE and will be removed in the future.
 215 \details
 216 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
 217 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 218 processor core and compiler settings.
 219
 220 <b> Code Example:</b>
 221 \code
 222 uint32_t val32;
 223
 224 void test (uint8_t *ptr) {
 225   __UNALIGNED_UINT32(ptr) = val32;
 226 }
 227 \endcode
 228
 229 */
 230 #define __UNALIGNED_UINT32
 231
 232 /**************************************************************************************************/
 233 /**
 234 \def __UNALIGNED_UINT16_READ
 235 \brief Pointer for unaligned read of a uint16_t variable.
 236 \details
 237 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in read
 238 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 239 processor core and compiler settings.
 240
 241 <b> Code Example:</b>
 242 \code
 243 uint16_t val16;
 244
 245 void test (uint8_t *ptr) {
 246    val16 = __UNALIGNED_UINT16_READ(ptr);
 247 }
 248 \endcode
 249
 250 */
 251 #define __UNALIGNED_UINT16_READ
 252
 253 /**************************************************************************************************/
 254 /**
 255 \def __UNALIGNED_UINT16_WRITE
 256 \brief Pointer for unaligned write of a uint16_t variable.
 257 \details
 258 Defines a pointer to a uint16_t from an address that does not need to be aligned. This can then be used in write
 259 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 260 processor core and compiler settings.
 261
 262 <b> Code Example:</b>
 263 \code
 264 uint16_t val16 = 0U;
 265
 266 void test (uint8_t *ptr) {
 267    __UNALIGNED_UINT16_WRITE(ptr, val16);
 268 }
 269 \endcode
 270
 271 */
 272 #define __UNALIGNED_UINT16_WRITE
 273
 274 /**************************************************************************************************/
 275 /**
 276 \def __UNALIGNED_UINT32_READ
 277 \brief Pointer for unaligned read of a uint32_t variable.
 278 \details
 279 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in read
 280 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 281 processor core and compiler settings.
 282
 283 <b> Code Example:</b>
 284 \code
 285 uint32_t val32;
 286
 287 void test (uint8_t *ptr) {
 288    val32 = __UNALIGNED_UINT32_READ(ptr);
 289 }
 290 \endcode
 291
 292 */
 293 #define __UNALIGNED_UINT32_READ
 294
 295 /**************************************************************************************************/
 296 /**
 297 \def __UNALIGNED_UINT32_WRITE
 298 \brief Pointer for unaligned write of a uint32_t variable.
 299 \details
 300 Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in write
 301 operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying Arm
 302 processor core and compiler settings.
 303
 304 <b> Code Example:</b>
 305 \code
 306 uint32_t val32 = 0U;
 307
 308 void test (uint8_t *ptr) {
 309    __UNALIGNED_UINT32_WRITE(ptr, val32);
 310 }
 311 \endcode
 312
 313 */
 314 #define __UNALIGNED_UINT32_WRITE
 315
 316 /**
 317 @}
 318 */
 319 /* end group comp_cntrl_gr */
 320
 321 /* ##########################  Core Instruction Access  ######################### */
 322 /**
 323 \defgroup CMSIS_Core_InstructionInterface Intrinsic Functions
 324 \brief Functions that generate specific Cortex-A CPU Instructions
 325 @{
 326 */
 327
 328 /**
 329 \def __NOP
 330 \details No Operation does nothing. This instruction can be used for code alignment purposes.
 331
 332
 333 \def __WFI
 334 \details Wait For Interrupt is a hint instruction that suspends execution until one of a number of events occurs.
 335
 336 \def __WFE
 337 \details Wait For Event is a hint instruction that permits the processor to enter
 338
 339 \def __SEV
 340 \details Send Event is a hint instruction. It causes an event to be signaled to the CPU.
 341
 342 \def __ISB()
 343 \details Instruction Synchronization Barrier flushes the pipeline in the processor,
 344            so that all instructions following the ISB are fetched from cache or memory,
 345            after the instruction has been completed.
 346
 347 \def __DSB()
 348 \details Acts as a special kind of Data Memory Barrier.
 349            It completes when all explicit memory accesses before this instruction complete.
 350
 351 \def __DMB()
 352 \details Ensures the apparent order of the explicit memory operations before
 353            and after the instruction, without ensuring their completion.
 354
 355 \def __BKPT(value)
 356 \details Causes the processor to enter Debug state.
 357            Debug tools can use this to investigate system state when the instruction at a particular address is reached.
 358 */
 359
 360 /**
 361   \brief   Reverse byte order (32 bit)
 362   \details Reverses the byte order in unsigned integer value. For example, 0x12345678 becomes 0x78563412.
 363   \param [in]    value  Value to reverse
 364   \return               Reversed value
 365  */
 366 uint32_t __REV(uint32_t value);
 367
 368 /**
 369   \brief   Reverse byte order (16 bit)
 370   \details Reverses the byte order within each halfword of a word. For example, 0x12345678 becomes 0x34127856.
 371   \param [in]    value  Value to reverse
 372   \return               Reversed value
 373  */
 374 uint16_t __REV16(uint16_t value);
 375
 376 /**
 377   \brief   Reverse byte order (16 bit)
 378   \details Reverses the byte order in a 16-bit value and returns the signed 16-bit result. For example, 0x0080 becomes 0x8000.
 379   \param [in]    value  Value to reverse
 380   \return               Reversed value
 381  */
 382 int32_t __REVSH(int32_t value);
 383
 384 /**
 385   \brief   Rotate Right in unsigned value (32 bit)
 386   \details Rotate Right (immediate) provides the value of the contents of a register rotated by a variable number of bits.
 387   \param [in]    op1  Value to rotate
 388   \param [in]    op2  Number of Bits to rotate
 389   \return               Rotated value
 390  */
 391 uint32_t __ROR(uint32_t op1, uint32_t op2);
 392
 393 /**
 394   \brief   Reverse bit order of value
 395   \details Reverses the bit order of the given value.
 396   \param [in]    value  Value to reverse
 397   \return               Reversed value
 398  */
 399 uint32_t __RBIT(uint32_t value);
 400
 401 /**
 402   \brief        Count leading zeros.
 403   \details Counts the number of leading zeros of a data value.
 404   \param [in]    value  Value to count the leading zeros
 405   \return               number of leading zeros in value
 406  */
 407 uint8_t __CLZ(uint32_t value);
 408
 409 /** @}*/
 410 /* end of group CMSIS_Core_InstructionInterface */
 411
 412