begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/Ref_cmInstr.txt

   1 /**
   2 \defgroup intrinsic_CPU_gr Intrinsic Functions for CPU Instructions
   3 @{
   4 \brief Functions that generate specific Cortex-M CPU Instructions.
   5 \details
   6 The following functions generate specific Cortex-M instructions that cannot be directly accessed by the C/C++ Compiler.
   7 Refer to the \ref ref_man_sec for detailed information about these Cortex-M instructions.
   8
   9 \note
  10 When using the <b>Arm Compiler Version 5 Toolchain</b> the following \ref intrinsic_CPU_gr are implemented using the Embedded Assembler.
  11 As the Embedded Assembler may cause side effects (Refer to <b>Arm Compiler v5.xx User Guide - Using the Inline and Embedded Assemblers of the Arm Compiler</b> for more information)
  12 it is possible to disable the following intrinsic functions and therefore the usage of the Embedded Assembler with the <b><i>define __NO_EMBEDDED_ASM</i></b>:
  13  - \ref __REV16
  14  - \ref __REVSH
  15  - \ref __RRX
  16
  17
  18 */
  19 /**************************************************************************************************/
  20 /** \brief  No Operation
  21
  22     This function does nothing. This instruction can be used for code alignment purposes.
  23  */
  24 void __NOP(void);
  25
  26
  27 /**************************************************************************************************/
  28 /** \brief  Wait For Interrupt
  29
  30     WFI is a hint instruction that suspends execution until one of the following events occurs:
  31     - A non-masked interrupt occurs and is taken.
  32     - An interrupt masked by PRIMASK becomes pending.
  33     - A Debug Entry request.
  34  */
  35 void __WFI(void);
  36
  37
  38 /**************************************************************************************************/
  39 /** \brief  Wait For Event
  40
  41     Wait For Event is a hint instruction that permits the processor to enter
  42     a low-power state until an events occurs:
  43     \li If the <b>event register is 0</b>, then WFE suspends execution until one of the following events occurs:
  44     - An exception, unless masked by the exception mask registers or the current priority level.
  45     - An exception enters the Pending state, if SEVONPEND in the System Control Register is set.
  46     - A Debug Entry request, if Debug is enabled.
  47     - An event signaled by a peripheral or another processor in a multiprocessor system using
  48     the SEV instruction.
  49
  50     \li If the <b>event register is 1</b>, then WFE clears it to 0 and returns immediately.
  51
  52  */
  53 void __WFE(void);
  54
  55
  56 /**************************************************************************************************/
  57 /** \brief  Send Event
  58
  59     Send Event is a hint instruction. It causes an event to be signaled to the CPU.
  60  */
  61 void __SEV(void);
  62
  63
  64 /**************************************************************************************************/
  65 /** \brief  Set Breakpoint
  66
  67 This function causes the processor to enter Debug state.
  68 Debug tools can use this to investigate system state when the instruction at a particular address is reached.
  69
  70 \param [in]    value  is ignored by the processor. If required, a debugger can use it to obtain additional information about the breakpoint.
  71 */
  72 void __BKPT(uint8_t value);
  73
  74
  75 /**************************************************************************************************/
  76 /** \brief  Instruction Synchronization Barrier
  77
  78     Instruction Synchronization Barrier flushes the pipeline in the processor,
  79     so that all instructions following the ISB are fetched from cache or
  80     memory, after the instruction has been completed.
  81  */
  82 void __ISB(void);
  83
  84
  85 /**************************************************************************************************/
  86 /** \brief  Data Synchronization Barrier
  87
  88 \details
  89 This function acts as a special kind of Data Memory Barrier.
  90 It completes when all explicit memory accesses before this instruction complete.
  91  */
  92 void __DSB(void);
  93
  94
  95 /**************************************************************************************************/
  96 /** \brief  Data Memory Barrier
  97
  98 \details
  99 This function ensures the apparent order of the explicit memory operations before
 100 and after the instruction, without ensuring their completion.
 101  */
 102 void __DMB(void);
 103
 104
 105 /**************************************************************************************************/
 106 /**
 107   \brief   Reverse byte order (32 bit)
 108   \details Reverses the byte order in unsigned integer value. For example, 0x12345678 becomes 0x78563412.
 109   \param [in]    value  Value to reverse
 110   \return               Reversed value
 111  */
 112 uint32_t __REV(uint32_t value);
 113
 114
 115 /**************************************************************************************************/
 116 /**
 117   \brief   Reverse byte order (16 bit)
 118   \details Reverses the byte order within each halfword of a word. For example, 0x12345678 becomes 0x34127856.
 119   \param [in]    value  Value to reverse
 120   \return               Reversed value
 121  */
 122 uint32_t __REV16(uint32_t value);
 123
 124
 125 /**************************************************************************************************/
 126 /**
 127   \brief   Reverse byte order (16 bit)
 128   \details Reverses the byte order in a 16-bit value and returns the signed 16-bit result. For example, 0x0080 becomes 0x8000.
 129   \param [in]    value  Value to reverse
 130   \return               Reversed value
 131  */
 132 int16_t __REVSH(int16_t value);
 133
 134
 135 /**************************************************************************************************/
 136 /**
 137   \brief   Reverse bit order of value
 138   \param [in]    value  Value to reverse
 139   \return               Reversed value
 140  */
 141 uint32_t __RBIT(uint32_t value);
 142
 143
 144 /**************************************************************************************************/
 145 /** \brief  Rotate a value right by a number of bits
 146
 147     This function rotates a value right by a specified number of bits.
 148
 149     \param [in]    value  Value to be shifted right
 150     \param [in]    shift  Number of bits in the range [1..31]
 151     \return               Rotated value
 152
 153  */
 154 uint32_t __ROR(uint32_t value, uint32_t shift);
 155
 156
 157 /**************************************************************************************************/
 158 /** \brief  LDR Exclusive (8 bit) [not for Cortex-M0, Cortex-M0+, or SC000]
 159
 160     This function executed an exclusive LDR command for 8 bit value [not for Cortex-M0, Cortex-M0+, or SC000].
 161
 162     \param [in]    *addr  Pointer to data
 163     \return             value of type uint8_t at (*addr)
 164  */
 165 uint8_t __LDREXB(volatile uint8_t *addr);
 166
 167
 168 /**************************************************************************************************/
 169 /** \brief  LDR Exclusive (16 bit) [not for Cortex-M0, Cortex-M0+, or SC000]
 170
 171     This function executed an exclusive LDR command for 16 bit values [not for Cortex-M0, Cortex-M0+, or SC000].
 172
 173     \param [in]    *addr  Pointer to data
 174     \return        value of type uint16_t at (*addr)
 175  */
 176 uint16_t __LDREXH(volatile uint16_t *addr);
 177
 178
 179 /**************************************************************************************************/
 180 /** \brief  LDR Exclusive (32 bit) [not for Cortex-M0, Cortex-M0+, or SC000]
 181
 182     This function executed an exclusive LDR command for 32 bit values [not for Cortex-M0, Cortex-M0+, or SC000].
 183
 184     \param [in]    *addr  Pointer to data
 185     \return        value of type uint32_t at (*addr)
 186  */
 187 uint32_t __LDREXW(volatile uint32_t *addr);
 188
 189
 190 /**************************************************************************************************/
 191 /** \brief  STR Exclusive (8 bit) [not for Cortex-M0, Cortex-M0+, or SC000]
 192
 193     This function executed an exclusive STR command for 8 bit values [not for Cortex-M0, Cortex-M0+, or SC000].
 194
 195     \param [in]  value  Value to store
 196     \param [in]  *addr  Pointer to location
 197     \return          0  Function succeeded
 198     \return          1  Function failed
 199  */
 200 uint32_t __STREXB(uint8_t value, volatile uint8_t *addr);
 201
 202
 203 /**************************************************************************************************/
 204 /** \brief  STR Exclusive (16 bit) [not for Cortex-M0, Cortex-M0+, or SC000]
 205
 206     This function executed an exclusive STR command for 16 bit values [not for Cortex-M0, Cortex-M0+, or SC000].
 207
 208     \param [in]  value  Value to store
 209     \param [in]  *addr  Pointer to location
 210     \return          0  Function succeeded
 211     \return          1  Function failed
 212  */
 213 uint32_t __STREXH(uint16_t value, volatile uint16_t *addr);
 214
 215
 216 /**************************************************************************************************/
 217 /** \brief  STR Exclusive (32 bit)  [not for Cortex-M0, Cortex-M0+, or SC000]
 218
 219     This function executed an exclusive STR command for 32 bit values [not for Cortex-M0, Cortex-M0+, or SC000].
 220
 221     \param [in]  value  Value to store
 222     \param [in]  *addr  Pointer to location
 223     \return          0  Function succeeded
 224     \return          1  Function failed
 225  */
 226 uint32_t __STREXW(uint32_t value, volatile uint32_t *addr);
 227
 228
 229 /**************************************************************************************************/
 230 /** \brief  Remove the exclusive lock [not for Cortex-M0, Cortex-M0+, or SC000]
 231
 232     This function removes the exclusive lock which is created by LDREX [not for Cortex-M0, Cortex-M0+, or SC000].
 233
 234  */
 235 void __CLREX(void);
 236
 237
 238 /**************************************************************************************************/
 239 /** \brief  Signed Saturate [not for Cortex-M0, Cortex-M0+, or SC000]
 240
 241     This function saturates a signed value [not for Cortex-M0, Cortex-M0+, or SC000].
 242     The Q bit is set if saturation occurs.
 243
 244     \param [in]  value  Value to be saturated
 245     \param [in]    sat  Bit position to saturate to [1..32]
 246     \return             Saturated value
 247  */
 248 int32_t __SSAT(int32_t value, uint32_t sat);
 249
 250
 251 /**************************************************************************************************/
 252 /** \brief  Unsigned Saturate [not for Cortex-M0, Cortex-M0+, or SC000]
 253
 254     This function saturates an unsigned value [not for Cortex-M0, Cortex-M0+, or SC000].
 255     The Q bit is set if saturation occurs.
 256
 257     \param [in]  value  Value to be saturated
 258     \param [in]    sat  Bit position to saturate to [0..31]
 259     \return             Saturated value
 260  */
 261 uint32_t __USAT(uint32_t value, uint32_t sat);
 262
 263
 264 /**************************************************************************************************/
 265 /** \brief  Count leading zeros
 266
 267     This function counts the number of leading zeros of a data value.
 268
 269     On Armv6-M (Cortex-M0, Cortex-M0+, and SC000) this function is not available as a core instruction
 270     instruction and thus __CLZ is implemented in software.
 271
 272     \param [in]  value  Value to count the leading zeros
 273     \return             number of leading zeros in value
 274  */
 275 uint8_t __CLZ(uint32_t value);
 276
 277
 278 /**************************************************************************************************/
 279 /** \brief  Rotate Right with Extend (32 bit)
 280
 281     This function moves each bit of a bitstring right by one bit. The carry input is shifted in at the left end of the bitstring.
 282
 283     \param [in]    value  Value to rotate
 284     \return               Rotated value
 285  */
 286 uint32_t __RRX(uint32_t value);
 287
 288
 289 /**************************************************************************************************/
 290 /** \brief  LDRT Unprivileged (8 bit)
 291
 292     This function executed an Unprivileged LDRT command for 8 bit value.
 293
 294     \param [in]    ptr  Pointer to data
 295     \return             value of type uint8_t at (*ptr)
 296  */
 297 uint8_t  __LDRBT(uint8_t ptr);
 298
 299
 300 /**************************************************************************************************/
 301 /** \brief  LDRT Unprivileged (16 bit)
 302
 303     This function executed an Unprivileged LDRT command for 16 bit values.
 304
 305     \param [in]    ptr  Pointer to data
 306     \return        value of type uint16_t at (*ptr)
 307  */
 308 uint16_t  __LDRHT(uint16_t ptr);
 309
 310
 311 /**************************************************************************************************/
 312 /** \brief  LDRT Unprivileged (32 bit)
 313
 314     This function executed an Unprivileged LDRT command for 32 bit values.
 315
 316     \param [in]    ptr  Pointer to data
 317     \return        value of type uint32_t at (*ptr)
 318  */
 319 uint32_t  __LDRT(uint32_t ptr);
 320
 321
 322 /**************************************************************************************************/
 323 /** \brief  STRT Unprivileged (8 bit)
 324
 325     This function executed an Unprivileged STRT command for 8 bit values.
 326
 327     \param [in]  value  Value to store
 328     \param [in]    ptr  Pointer to location
 329  */
 330 void __STRBT(uint8_t value, uint8_t ptr);
 331
 332
 333 /**************************************************************************************************/
 334 /** \brief  STRT Unprivileged (16 bit)
 335
 336     This function executed an Unprivileged STRT command for 16 bit values.
 337
 338     \param [in]  value  Value to store
 339     \param [in]    ptr  Pointer to location
 340  */
 341 void __STRHT(uint16_t value, uint16_t ptr);
 342
 343
 344 /**************************************************************************************************/
 345 /** \brief  STRT Unprivileged (32 bit)
 346
 347     This function executed an Unprivileged STRT command for 32 bit values.
 348
 349     \param [in]  value  Value to store
 350     \param [in]    ptr  Pointer to location
 351  */
 352 void __STRT(uint32_t value, uint32_t ptr);
 353
 354
 355 /**
 356 \cond (ARMv8M)
 357 */
 358
 359 /**
 360   \brief   Load-Acquire (8 bit)
 361   \details Executes a LDAB instruction for 8 bit value.
 362   \param [in]    ptr  Pointer to data
 363   \return             value of type uint8_t at (*ptr)
 364   \note    Only availabe for Armv8-M Architecture.
 365  */
 366 uint8_t __LDAB(volatile uint8_t *ptr);
 367
 368 /**
 369   \brief   Load-Acquire (16 bit)
 370   \details Executes a LDAH instruction for 16 bit values.
 371   \param [in]    ptr  Pointer to data
 372   \return        value of type uint16_t at (*ptr)
 373   \note    Only availabe for Armv8-M Architecture.
 374  */
 375 uint16_t __LDAH(volatile uint16_t *ptr);
 376
 377 /**
 378   \brief   Load-Acquire (32 bit)
 379   \details Executes a LDA instruction for 32 bit values.
 380   \param [in]    ptr  Pointer to data
 381   \return        value of type uint32_t at (*ptr)
 382   \note    Only availabe for Armv8-M Architecture.
 383  */
 384 uint32_t __LDA(volatile uint32_t *ptr);
 385
 386 /**
 387   \brief   Store-Release (8 bit)
 388   \details Executes a STLB instruction for 8 bit values.
 389   \param [in]  value  Value to store
 390   \param [in]    ptr  Pointer to location
 391   \note    Only availabe for Armv8-M Architecture.
 392  */
 393 void __STLB(uint8_t value, volatile uint8_t *ptr);
 394
 395 /**
 396   \brief   Store-Release (16 bit)
 397   \details Executes a STLH instruction for 16 bit values.
 398   \param [in]  value  Value to store
 399   \param [in]    ptr  Pointer to location
 400   \note    Only availabe for Armv8-M Architecture.
 401  */
 402 void __STLH(uint16_t value, volatile uint16_t *ptr);
 403
 404 /**
 405   \brief   Store-Release (32 bit)
 406   \details Executes a STL instruction for 32 bit values.
 407   \param [in]  value  Value to store
 408   \param [in]    ptr  Pointer to location
 409   \note    Only availabe for Armv8-M Architecture.
 410  */
 411 void __STL(uint32_t value, volatile uint32_t *ptr);
 412
 413 /**
 414   \brief   Load-Acquire Exclusive (8 bit)
 415   \details Executes a LDAB exclusive instruction for 8 bit value.
 416   \param [in]    ptr  Pointer to data
 417   \return             value of type uint8_t at (*ptr)
 418   \note    Only availabe for Armv8-M Architecture.
 419  */
 420 uint8_t __LDAEXB(volatile uint32_t *ptr);
 421
 422 /**
 423   \brief   Load-Acquire Exclusive (16 bit)
 424   \details Executes a LDAH exclusive instruction for 16 bit values.
 425   \param [in]    ptr  Pointer to data
 426   \return        value of type uint16_t at (*ptr)
 427   \note    Only availabe for Armv8-M Architecture.
 428  */
 429 uint16_t __LDAEXH(volatile uint32_t *ptr);
 430
 431 /**
 432   \brief   Load-Acquire Exclusive (32 bit)
 433   \details Executes a LDA exclusive instruction for 32 bit values.
 434   \param [in]    ptr  Pointer to data
 435   \return        value of type uint32_t at (*ptr)
 436   \note    Only availabe for Armv8-M Architecture.
 437  */
 438 uint32_t __LDAEX(volatile uint32_t *ptr);
 439
 440 /**
 441   \brief   Store-Release Exclusive (8 bit)
 442   \details Executes a STLB exclusive instruction for 8 bit values.
 443   \param [in]  value  Value to store
 444   \param [in]    ptr  Pointer to location
 445   \return          0  Function succeeded
 446   \return          1  Function failed
 447   \note    Only availabe for Armv8-M Architecture.
 448  */
 449 uint32_t __STLEXB(uint8_t value, volatile uint8_t *ptr);
 450
 451 /**
 452   \brief   Store-Release Exclusive (16 bit)
 453   \details Executes a STLH exclusive instruction for 16 bit values.
 454   \param [in]  value  Value to store
 455   \param [in]    ptr  Pointer to location
 456   \return          0  Function succeeded
 457   \return          1  Function failed
 458   \note    Only availabe for Armv8-M Architecture.
 459  */
 460 uint32_t __STLEXH(uint16_t value, volatile uint16_t *ptr);
 461
 462 /**
 463   \brief   Store-Release Exclusive (32 bit)
 464   \details Executes a STL exclusive instruction for 32 bit values.
 465   \param [in]  value  Value to store
 466   \param [in]    ptr  Pointer to location
 467   \return          0  Function succeeded
 468   \return          1  Function failed
 469   \note    Only availabe for Armv8-M Architecture.
 470  */
 471 uint32_t __STLEX(uint32_t value, volatile uint32_t *ptr);
 472
 473 /**
 474 \endcond
 475 */
 476
 477 /*@}*/ /* end of group Intrisic_CPU */
 478
 479