1/**
2\defgroup intrinsic_CPU_gr Intrinsic Functions for CPU Instructions
3@{
4\brief Functions that generate specific Cortex-M CPU Instructions.
5\details
6The following functions generate specific Cortex-M instructions that cannot be directly accessed by the C/C++ Compiler.
7Refer to the \ref ref_man_sec "Cortex-M Generic User Guides" for detailed information about these Cortex-M instructions.
8
9\note
10When using the <b>Arm Compiler Version 5 Toolchain</b> the following \ref intrinsic_CPU_gr are implemented using the Embedded Assembler.
11As 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)
12it 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*/
24void __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*/
35void __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*/
53void __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*/
61void __SEV(void);
62
63
64/**************************************************************************************************/
65/** \brief  Set Breakpoint
66
67This function causes the processor to enter Debug state.
68Debug 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*/
72void __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*/
82void __ISB(void);
83
84
85/**************************************************************************************************/
86/** \brief  Data Synchronization Barrier
87
88\details
89This function acts as a special kind of Data Memory Barrier.
90It completes when all explicit memory accesses before this instruction complete.
91*/
92void __DSB(void);
93
94
95/**************************************************************************************************/
96/** \brief  Data Memory Barrier
97
98\details
99This function ensures the apparent order of the explicit memory operations before
100and after the instruction, without ensuring their completion.
101*/
102void __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*/
112uint32_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*/
122uint32_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*/
132int16_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*/
141uint32_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*/
154uint32_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*/
165uint8_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*/
176uint16_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*/
187uint32_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*/
200uint32_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*/
213uint32_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*/
226uint32_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*/
235void __CLREX(void);
236
237
238/**************************************************************************************************/
239/** \brief  Signed Saturate
240
241    This function saturates a signed value.
242    The Q bit is set if saturation occurs [not for Cortex-M0, Cortex-M0+, or SC000].
243
244    On Armv6-M (Cortex-M0, Cortex-M0+, and SC000) this function is not available as a core instruction
245    instruction and thus __SSAT is implemented in software.
246
247    \param [in]  value  Value to be saturated
248    \param [in]    sat  Bit position to saturate to [1..32]
249    \return             Saturated value
250*/
251int32_t __SSAT(int32_t value, uint32_t sat);
252
253
254/**************************************************************************************************/
255/** \brief  Unsigned Saturate
256
257    This function saturates an unsigned value.
258    The Q bit is set if saturation occurs [not for Cortex-M0, Cortex-M0+, or SC000].
259
260    On Armv6-M (Cortex-M0, Cortex-M0+, and SC000) this function is not available as a core instruction
261    instruction and thus __USAT is implemented in software.
262
263    \param [in]  value  Value to be saturated
264    \param [in]    sat  Bit position to saturate to [0..31]
265    \return             Saturated value
266*/
267uint32_t __USAT(int32_t value, uint32_t sat);
268
269
270/**************************************************************************************************/
271/** \brief  Count leading zeros
272
273    This function counts the number of leading zeros of a data value.
274
275    On Armv6-M (Cortex-M0, Cortex-M0+, and SC000) this function is not available as a core instruction
276    instruction and thus __CLZ is implemented in software.
277
278    \param [in]  value  Value to count the leading zeros
279    \return             number of leading zeros in value
280*/
281uint8_t __CLZ(uint32_t value);
282
283
284/**************************************************************************************************/
285/** \brief  Rotate Right with Extend (32 bit)
286
287    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.
288
289    \param [in]    value  Value to rotate
290    \return               Rotated value
291*/
292uint32_t __RRX(uint32_t value);
293
294
295/**************************************************************************************************/
296/** \brief  LDRT Unprivileged (8 bit)
297
298    This function executed an Unprivileged LDRT command for 8 bit value.
299
300    \param [in]    ptr  Pointer to data
301    \return             value of type uint8_t at (*ptr)
302*/
303uint8_t  __LDRBT(uint8_t ptr);
304
305
306/**************************************************************************************************/
307/** \brief  LDRT Unprivileged (16 bit)
308
309    This function executed an Unprivileged LDRT command for 16 bit values.
310
311    \param [in]    ptr  Pointer to data
312    \return        value of type uint16_t at (*ptr)
313*/
314uint16_t  __LDRHT(uint16_t ptr);
315
316
317/**************************************************************************************************/
318/** \brief  LDRT Unprivileged (32 bit)
319
320    This function executed an Unprivileged LDRT command for 32 bit values.
321
322    \param [in]    ptr  Pointer to data
323    \return        value of type uint32_t at (*ptr)
324*/
325uint32_t  __LDRT(uint32_t ptr);
326
327
328/**************************************************************************************************/
329/** \brief  STRT Unprivileged (8 bit)
330
331    This function executed an Unprivileged STRT command for 8 bit values.
332
333    \param [in]  value  Value to store
334    \param [in]    ptr  Pointer to location
335*/
336void __STRBT(uint8_t value, uint8_t ptr);
337
338
339/**************************************************************************************************/
340/** \brief  STRT Unprivileged (16 bit)
341
342    This function executed an Unprivileged STRT command for 16 bit values.
343
344    \param [in]  value  Value to store
345    \param [in]    ptr  Pointer to location
346*/
347void __STRHT(uint16_t value, uint16_t ptr);
348
349
350/**************************************************************************************************/
351/** \brief  STRT Unprivileged (32 bit)
352
353    This function executed an Unprivileged STRT command for 32 bit values.
354
355    \param [in]  value  Value to store
356    \param [in]    ptr  Pointer to location
357*/
358void __STRT(uint32_t value, uint32_t ptr);
359
360
361/**
362\cond (ARMv8M)
363*/
364
365/**
366  \brief   Load-Acquire (8 bit)
367  \details Executes a LDAB instruction for 8 bit value.
368  \param [in]    ptr  Pointer to data
369  \return             value of type uint8_t at (*ptr)
370  \note    Only available for Armv8-M Architecture.
371*/
372uint8_t __LDAB(volatile uint8_t *ptr);
373
374/**
375  \brief   Load-Acquire (16 bit)
376  \details Executes a LDAH instruction for 16 bit values.
377  \param [in]    ptr  Pointer to data
378  \return        value of type uint16_t at (*ptr)
379  \note    Only available for Armv8-M Architecture.
380*/
381uint16_t __LDAH(volatile uint16_t *ptr);
382
383/**
384  \brief   Load-Acquire (32 bit)
385  \details Executes a LDA instruction for 32 bit values.
386  \param [in]    ptr  Pointer to data
387  \return        value of type uint32_t at (*ptr)
388  \note    Only available for Armv8-M Architecture.
389*/
390uint32_t __LDA(volatile uint32_t *ptr);
391
392/**
393  \brief   Store-Release (8 bit)
394  \details Executes a STLB instruction for 8 bit values.
395  \param [in]  value  Value to store
396  \param [in]    ptr  Pointer to location
397  \note    Only available for Armv8-M Architecture.
398*/
399void __STLB(uint8_t value, volatile uint8_t *ptr);
400
401/**
402  \brief   Store-Release (16 bit)
403  \details Executes a STLH instruction for 16 bit values.
404  \param [in]  value  Value to store
405  \param [in]    ptr  Pointer to location
406  \note    Only available for Armv8-M Architecture.
407*/
408void __STLH(uint16_t value, volatile uint16_t *ptr);
409
410/**
411  \brief   Store-Release (32 bit)
412  \details Executes a STL instruction for 32 bit values.
413  \param [in]  value  Value to store
414  \param [in]    ptr  Pointer to location
415  \note    Only available for Armv8-M Architecture.
416*/
417void __STL(uint32_t value, volatile uint32_t *ptr);
418
419/**
420  \brief   Load-Acquire Exclusive (8 bit)
421  \details Executes a LDAB exclusive instruction for 8 bit value.
422  \param [in]    ptr  Pointer to data
423  \return             value of type uint8_t at (*ptr)
424  \note    Only available for Armv8-M Architecture.
425*/
426uint8_t __LDAEXB(volatile uint32_t *ptr);
427
428/**
429  \brief   Load-Acquire Exclusive (16 bit)
430  \details Executes a LDAH exclusive instruction for 16 bit values.
431  \param [in]    ptr  Pointer to data
432  \return        value of type uint16_t at (*ptr)
433  \note    Only available for Armv8-M Architecture.
434*/
435uint16_t __LDAEXH(volatile uint32_t *ptr);
436
437/**
438  \brief   Load-Acquire Exclusive (32 bit)
439  \details Executes a LDA exclusive instruction for 32 bit values.
440  \param [in]    ptr  Pointer to data
441  \return        value of type uint32_t at (*ptr)
442  \note    Only available for Armv8-M Architecture.
443*/
444uint32_t __LDAEX(volatile uint32_t *ptr);
445
446/**
447  \brief   Store-Release Exclusive (8 bit)
448  \details Executes a STLB exclusive instruction for 8 bit values.
449  \param [in]  value  Value to store
450  \param [in]    ptr  Pointer to location
451  \return          0  Function succeeded
452  \return          1  Function failed
453  \note    Only available for Armv8-M Architecture.
454*/
455uint32_t __STLEXB(uint8_t value, volatile uint8_t *ptr);
456
457/**
458  \brief   Store-Release Exclusive (16 bit)
459  \details Executes a STLH exclusive instruction for 16 bit values.
460  \param [in]  value  Value to store
461  \param [in]    ptr  Pointer to location
462  \return          0  Function succeeded
463  \return          1  Function failed
464  \note    Only available for Armv8-M Architecture.
465*/
466uint32_t __STLEXH(uint16_t value, volatile uint16_t *ptr);
467
468/**
469  \brief   Store-Release Exclusive (32 bit)
470  \details Executes a STL exclusive instruction for 32 bit values.
471  \param [in]  value  Value to store
472  \param [in]    ptr  Pointer to location
473  \return          0  Function succeeded
474  \return          1  Function failed
475  \note    Only available for Armv8-M Architecture.
476*/
477uint32_t __STLEX(uint32_t value, volatile uint32_t *ptr);
478
479/**
480\endcond
481*/
482
483/** @}*/ /* end of group Intrisic_CPU*/
484
485
486