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
 243     \param [in]  value  Value to be saturated
 244     \param [in]    sat  Bit position to saturate to [1..32]
 245     \return             Saturated value
 246  */
 247 int32_t __SSAT(int32_t value, uint32_t sat);
 248
 249
 250 /**************************************************************************************************/
 251 /** \brief  Unsigned Saturate [not for Cortex-M0, Cortex-M0+, or SC000]
 252
 253     This function saturates an unsigned value [not for Cortex-M0, Cortex-M0+, or SC000].
 254
 255     \param [in]  value  Value to be saturated
 256     \param [in]    sat  Bit position to saturate to [0..31]
 257     \return             Saturated value
 258  */
 259 uint32_t __USAT(uint32_t value, uint32_t sat);
 260
 261
 262 /**************************************************************************************************/
 263 /** \brief  Count leading zeros
 264
 265     This function counts the number of leading zeros of a data value.
 266
 267     On Armv6-M (Cortex-M0, Cortex-M0+, and SC000) this function is not available as a core instruction
 268     instruction and thus __CLZ is implemented in software.
 269
 270     \param [in]  value  Value to count the leading zeros
 271     \return             number of leading zeros in value
 272  */
 273 uint8_t __CLZ(uint32_t value);
 274
 275
 276 /**************************************************************************************************/
 277 /** \brief  Rotate Right with Extend (32 bit)
 278
 279     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.
 280
 281     \param [in]    value  Value to rotate
 282     \return               Rotated value
 283  */
 284 uint32_t __RRX(uint32_t value);
 285
 286
 287 /**************************************************************************************************/
 288 /** \brief  LDRT Unprivileged (8 bit)
 289
 290     This function executed an Unprivileged LDRT command for 8 bit value.
 291
 292     \param [in]    ptr  Pointer to data
 293     \return             value of type uint8_t at (*ptr)
 294  */
 295 uint8_t  __LDRBT(uint8_t ptr);
 296
 297
 298 /**************************************************************************************************/
 299 /** \brief  LDRT Unprivileged (16 bit)
 300
 301     This function executed an Unprivileged LDRT command for 16 bit values.
 302
 303     \param [in]    ptr  Pointer to data
 304     \return        value of type uint16_t at (*ptr)
 305  */
 306 uint16_t  __LDRHT(uint16_t ptr);
 307
 308
 309 /**************************************************************************************************/
 310 /** \brief  LDRT Unprivileged (32 bit)
 311
 312     This function executed an Unprivileged LDRT command for 32 bit values.
 313
 314     \param [in]    ptr  Pointer to data
 315     \return        value of type uint32_t at (*ptr)
 316  */
 317 uint32_t  __LDRT(uint32_t ptr);
 318
 319
 320 /**************************************************************************************************/
 321 /** \brief  STRT Unprivileged (8 bit)
 322
 323     This function executed an Unprivileged STRT command for 8 bit values.
 324
 325     \param [in]  value  Value to store
 326     \param [in]    ptr  Pointer to location
 327  */
 328 void __STRBT(uint8_t value, uint8_t ptr);
 329
 330
 331 /**************************************************************************************************/
 332 /** \brief  STRT Unprivileged (16 bit)
 333
 334     This function executed an Unprivileged STRT command for 16 bit values.
 335
 336     \param [in]  value  Value to store
 337     \param [in]    ptr  Pointer to location
 338  */
 339 void __STRHT(uint16_t value, uint16_t ptr);
 340
 341
 342 /**************************************************************************************************/
 343 /** \brief  STRT Unprivileged (32 bit)
 344
 345     This function executed an Unprivileged STRT command for 32 bit values.
 346
 347     \param [in]  value  Value to store
 348     \param [in]    ptr  Pointer to location
 349  */
 350 void __STRT(uint32_t value, uint32_t ptr);
 351
 352
 353 /**
 354 \cond (ARMv8M)
 355 */
 356
 357 /**
 358   \brief   Load-Acquire (8 bit)
 359   \details Executes a LDAB instruction for 8 bit value.
 360   \param [in]    ptr  Pointer to data
 361   \return             value of type uint8_t at (*ptr)
 362   \note    Only availabe for Armv8-M Architecture.
 363  */
 364 uint8_t __LDAB(volatile uint8_t *ptr);
 365
 366 /**
 367   \brief   Load-Acquire (16 bit)
 368   \details Executes a LDAH instruction for 16 bit values.
 369   \param [in]    ptr  Pointer to data
 370   \return        value of type uint16_t at (*ptr)
 371   \note    Only availabe for Armv8-M Architecture.
 372  */
 373 uint16_t __LDAH(volatile uint16_t *ptr);
 374
 375 /**
 376   \brief   Load-Acquire (32 bit)
 377   \details Executes a LDA instruction for 32 bit values.
 378   \param [in]    ptr  Pointer to data
 379   \return        value of type uint32_t at (*ptr)
 380   \note    Only availabe for Armv8-M Architecture.
 381  */
 382 uint32_t __LDA(volatile uint32_t *ptr);
 383
 384 /**
 385   \brief   Store-Release (8 bit)
 386   \details Executes a STLB instruction for 8 bit values.
 387   \param [in]  value  Value to store
 388   \param [in]    ptr  Pointer to location
 389   \note    Only availabe for Armv8-M Architecture.
 390  */
 391 void __STLB(uint8_t value, volatile uint8_t *ptr);
 392
 393 /**
 394   \brief   Store-Release (16 bit)
 395   \details Executes a STLH instruction for 16 bit values.
 396   \param [in]  value  Value to store
 397   \param [in]    ptr  Pointer to location
 398   \note    Only availabe for Armv8-M Architecture.
 399  */
 400 void __STLH(uint16_t value, volatile uint16_t *ptr);
 401
 402 /**
 403   \brief   Store-Release (32 bit)
 404   \details Executes a STL instruction for 32 bit values.
 405   \param [in]  value  Value to store
 406   \param [in]    ptr  Pointer to location
 407   \note    Only availabe for Armv8-M Architecture.
 408  */
 409 void __STL(uint32_t value, volatile uint32_t *ptr);
 410
 411 /**
 412   \brief   Load-Acquire Exclusive (8 bit)
 413   \details Executes a LDAB exclusive instruction for 8 bit value.
 414   \param [in]    ptr  Pointer to data
 415   \return             value of type uint8_t at (*ptr)
 416   \note    Only availabe for Armv8-M Architecture.
 417  */
 418 uint8_t __LDAEXB(volatile uint32_t *ptr);
 419
 420 /**
 421   \brief   Load-Acquire Exclusive (16 bit)
 422   \details Executes a LDAH exclusive instruction for 16 bit values.
 423   \param [in]    ptr  Pointer to data
 424   \return        value of type uint16_t at (*ptr)
 425   \note    Only availabe for Armv8-M Architecture.
 426  */
 427 uint16_t __LDAEXH(volatile uint32_t *ptr);
 428
 429 /**
 430   \brief   Load-Acquire Exclusive (32 bit)
 431   \details Executes a LDA exclusive instruction for 32 bit values.
 432   \param [in]    ptr  Pointer to data
 433   \return        value of type uint32_t at (*ptr)
 434   \note    Only availabe for Armv8-M Architecture.
 435  */
 436 uint32_t __LDAEX(volatile uint32_t *ptr);
 437
 438 /**
 439   \brief   Store-Release Exclusive (8 bit)
 440   \details Executes a STLB exclusive instruction for 8 bit values.
 441   \param [in]  value  Value to store
 442   \param [in]    ptr  Pointer to location
 443   \return          0  Function succeeded
 444   \return          1  Function failed
 445   \note    Only availabe for Armv8-M Architecture.
 446  */
 447 uint32_t __STLEXB(uint8_t value, volatile uint8_t *ptr);
 448
 449 /**
 450   \brief   Store-Release Exclusive (16 bit)
 451   \details Executes a STLH exclusive instruction for 16 bit values.
 452   \param [in]  value  Value to store
 453   \param [in]    ptr  Pointer to location
 454   \return          0  Function succeeded
 455   \return          1  Function failed
 456   \note    Only availabe for Armv8-M Architecture.
 457  */
 458 uint32_t __STLEXH(uint16_t value, volatile uint16_t *ptr);
 459
 460 /**
 461   \brief   Store-Release Exclusive (32 bit)
 462   \details Executes a STL exclusive instruction for 32 bit values.
 463   \param [in]  value  Value to store
 464   \param [in]    ptr  Pointer to location
 465   \return          0  Function succeeded
 466   \return          1  Function failed
 467   \note    Only availabe for Armv8-M Architecture.
 468  */
 469 uint32_t __STLEX(uint32_t value, volatile uint32_t *ptr);
 470
 471 /**
 472 \endcond
 473 */
 474
 475 /*@}*/ /* end of group Intrisic_CPU */
 476
 477