begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core_A/src/cmsis_armcc.txt

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