1/**
2\cond (ARMv8M)
3*/
4
5/**
6\defgroup trustzone_functions TrustZone for Armv8-M/v8.1-M
7\brief Functions that related to optional Armv8-M and Armv8.1-M security extension
8  @{
9\details
10The Armv8-M architecture has optional Armv8-M security extension based on Arm TrustZone technology.
11To access Arm TrustZone extensions for Armv8-M additional CMSIS functions are provided:
12 - \ref coreregister_trustzone_functions
13 - \ref nvic_trustzone_functions
14 - \ref systick_trustzone_functions
15 - \ref sau_trustzone_functions
16 - \ref stacksealing_support_trustzone_functions
17 - \ref context_trustzone_functions
18*/
19
20/**
21  \defgroup coreregister_trustzone_functions Core Register Access Functions
22  \brief Core register Access functions related to TrustZone for Armv8-M.
23  @{
24*/
25
26/**
27  \brief   Get Control register (non-secure)
28  \details Returns the content of the non-secure Control register when in secure mode.
29  \return               non-secure Control register value
30  \sa
31    - \ref __get_CONTROL; CONTROL_Type
32 */
33uint32_t __TZ_get_CONTROL_NS(void);
34
35/**
36  \brief   Set Control register (non-secure)
37  \details Writes the given value to the non-secure Control register when in secure state.
38  \param [in]    control  Control register value to set
39  \sa
40    - \ref __set_CONTROL; CONTROL_Type
41 */
42void __TZ_set_CONTROL_NS(uint32_t control);
43
44/**
45  \brief   Get Process Stack Pointer (non-secure)
46  \details Returns the current value of the non-secure Process Stack Pointer (PSP) when in secure state.
47  \return               PSP register value
48  \sa
49    - \ref __get_PSP
50 */
51uint32_t __TZ_get_PSP_NS(void);
52
53/**
54  \brief   Set Process Stack Pointer (non-secure)
55  \details Assigns the given value to the non-secure Process Stack Pointer (PSP) when in secure state.
56  \param [in]    topOfProcStack  Process Stack Pointer value to set
57  \sa
58    - \ref __set_PSP
59 */
60void __TZ_set_PSP_NS(uint32_t topOfProcStack);
61
62/**
63  \brief   Get Main Stack Pointer (non-secure)
64  \details Returns the current value of the non-secure Main Stack Pointer (MSP) when in secure state.
65  \return               MSP register value
66  \sa
67    - \ref __get_MSP
68 */
69uint32_t __TZ_get_MSP_NS(void);
70
71/**
72  \brief   Set Main Stack Pointer (non-secure)
73  \details Assigns the given value to the non-secure Main Stack Pointer (MSP) when in secure state.
74  \param [in]    topOfMainStack  Main Stack Pointer value to set
75  \sa
76    - \ref __set_MSP
77 */
78void __TZ_set_MSP_NS(uint32_t topOfMainStack);
79
80/**
81  \brief   Get Stack Pointer (non-secure)
82  \details Returns the current value of the non-secure Stack Pointer (SP) when in secure state.
83  \return               SP register value
84 */
85uint32_t __TZ_get_SP_NS(void);
86
87/**
88  \brief   Set Stack Pointer (non-secure)
89  \details Assigns the given value to the non-secure Stack Pointer (SP) when in secure state.
90  \param [in]    topOfStack  Stack Pointer value to set
91 */
92void __TZ_set_SP_NS(uint32_t topOfStack);
93
94/**
95  \brief   Get Priority Mask (non-secure)
96  \details Returns the current state of the non-secure priority mask bit from the Priority Mask register when in secure state.
97  \return               Priority Mask value
98  \sa
99    - \ref __get_PRIMASK
100 */
101uint32_t __TZ_get_PRIMASK_NS(void);
102
103/**
104  \brief   Set Priority Mask (non-secure)
105  \details Assigns the given value to the non-secure Priority Mask register when in secure state.
106  \param [in]    priMask  Priority Mask
107  \sa
108    - \ref __set_PRIMASK
109 */
110void __TZ_set_PRIMASK_NS(uint32_t priMask);
111
112/**
113  \brief   Get Base Priority (non-secure)
114  \details Returns the current value of the non-secure Base Priority register when in secure state.
115  \return               Base Priority register value
116  \sa
117    - \ref __get_BASEPRI
118 */
119uint32_t __TZ_get_BASEPRI_NS(void);
120
121/**
122  \brief   Set Base Priority (non-secure)
123  \details Assigns the given value to the non-secure Base Priority register when in secure state.
124  \param [in]    basePri  Base Priority value to set
125  \sa
126    - \ref __set_BASEPRI
127 */
128void __TZ_set_BASEPRI_NS(uint32_t basePri);
129
130/**
131  \brief   Get Fault Mask (non-secure)
132  \details Returns the current value of the non-secure Fault Mask register when in secure state.
133  \return               Fault Mask register value
134  \sa
135    - \ref __get_FAULTMASK
136 */
137uint32_t __TZ_get_FAULTMASK_NS(void);
138
139/**
140  \brief   Set Fault Mask (non-secure)
141  \details Assigns the given value to the non-secure Fault Mask register when in secure state.
142  \param [in]    faultMask  Fault Mask value to set
143  \sa
144    - \ref __set_FAULTMASK
145 */
146void __TZ_set_FAULTMASK_NS(uint32_t faultMask);
147
148/**
149  \brief   Get Process Stack Pointer Limit (non-secure)
150  Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
151  Stack Pointer Limit register hence zero is returned always.
152
153  \details Returns the current value of the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
154  \return               PSPLIM register value
155 */
156uint32_t __TZ_get_PSPLIM_NS(void);
157
158/**
159  \brief   Set Process Stack Pointer (non-secure)
160  Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
161  Stack Pointer Limit register hence zero is returned always.
162
163  \details Assigns the given value to the non-secure Process Stack Pointer Limit (PSPLIM) when in secure state.
164  \param [in]    ProcStackPtrLimit  Process Stack Pointer Limit value to set
165 */
166void __TZ_set_PSPLIM_NS(uint32_t ProcStackPtrLimit);
167
168/**
169  \brief   Get Main Stack Pointer Limit (non-secure)
170  Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
171  Stack Pointer Limit register hence zero is returned always.
172
173  \details Returns the current value of the non-secure Main Stack Pointer Limit(MSPLIM) when in secure state.
174  \return               MSPLIM register value
175 */
176uint32_t __TZ_get_MSPLIM_NS(void);
177
178/**
179  \brief   Set Main Stack Pointer Limit (non-secure)
180  Devices without Armv8-M Main Extensions (i.e. Cortex-M23) lack the non-secure
181  Stack Pointer Limit register hence zero is returned always.
182
183  \details Assigns the given value to the non-secure Main Stack Pointer Limit (MSPLIM) when in secure state.
184  \param [in]    MainStackPtrLimit  Main Stack Pointer value to set
185 */
186void __TZ_set_MSPLIM_NS(uint32_t MainStackPtrLimit);
187
188/** close coreregister_trustzone_functions
189  @}
190*/
191
192/**
193  \defgroup nvic_trustzone_functions NVIC Functions
194  \brief Nested Vector Interrupt Controller (NVIC) functions related to TrustZone for Armv8-M
195  @{
196*/
197
198/**
199  \brief   Set Priority Grouping (non-secure)
200  \details Sets the non-secure priority grouping field when in secure state using the required unlock sequence.
201           The parameter PriorityGroup is assigned to the field SCB->AIRCR [10:8] PRIGROUP field.
202           Only values from 0..7 are used.
203           In case of a conflict between priority grouping and available
204           priority bits (__NVIC_PRIO_BITS), the smallest possible priority group is set.
205  \param [in]      PriorityGroup  Priority grouping field.
206  \note    Only available for Armv8-M Mainline.
207  \sa
208    - \ref NVIC_SetPriorityGrouping
209 */
210void TZ_NVIC_SetPriorityGrouping_NS(uint32_t PriorityGroup);
211
212/**
213  \brief   Get Priority Grouping (non-secure)
214  \details Reads the priority grouping field from the non-secure NVIC when in secure state.
215  \return                Priority grouping field (SCB->AIRCR [10:8] PRIGROUP field).
216  \note    Only available for Armv8-M Mainline.
217  \sa
218    - \ref NVIC_GetPriorityGrouping
219 */
220uint32_t TZ_NVIC_GetPriorityGrouping_NS(void);
221
222/**
223  \brief   Enable External Interrupt (non-secure)
224  \details Enables a device-specific interrupt in the non-secure NVIC when in secure state.
225  \param [in]      IRQn  External interrupt number. Value cannot be negative.
226  \sa
227    - \ref NVIC_EnableIRQ
228 */
229void TZ_NVIC_EnableIRQ_NS(IRQn_Type IRQn);
230
231
232/**
233  \brief   Get Interrupt Enable status (non-secure)
234  \details Returns a device specific interrupt enable status from the non-secure NVIC interrupt controller when in secure state.
235  \param [in]      IRQn  Interrupt number.
236  \return             0  Interrupt is not enabled.
237  \return             1  Interrupt is enabled.
238  \sa
239    - \ref NVIC_EnableIRQ; NVIC_DisableIRQ;
240 */
241uint32_t TZ_NVIC_GetEnableIRQ_NS(IRQn_Type IRQn);
242
243/**
244  \brief   Disable External Interrupt (non-secure)
245  \details Disables a device-specific interrupt in the non-secure NVIC when in secure state.
246  \param [in]      IRQn  External interrupt number. Value cannot be negative.
247  \sa
248    - \ref NVIC_DisableIRQ
249 */
250void TZ_NVIC_DisableIRQ_NS(IRQn_Type IRQn);
251
252/**
253  \brief   Get Pending Interrupt (non-secure)
254  \details Reads the pending register in the non-secure NVIC when in secure state and returns the pending bit for the specified interrupt.
255  \param [in]      IRQn  Interrupt number.
256  \return             0  Interrupt status is not pending.
257  \return             1  Interrupt status is pending.
258  \sa
259    - \ref NVIC_GetPendingIRQ
260 */
261uint32_t TZ_NVIC_GetPendingIRQ_NS(IRQn_Type IRQn);
262
263/**
264  \brief   Set Pending Interrupt (non-secure)
265  \details Sets the pending bit of an non-secure external interrupt when in secure state.
266  \param [in]      IRQn  Interrupt number. Value cannot be negative.
267  \sa
268    - \ref NVIC_SetPendingIRQ
269 */
270void TZ_NVIC_SetPendingIRQ_NS(IRQn_Type IRQn);
271
272/**
273  \brief   Clear Pending Interrupt (non-secure)
274  \details Clears the pending bit of an non-secure external interrupt when in secure state.
275  \param [in]      IRQn  External interrupt number. Value cannot be negative.
276  \sa
277    - \ref NVIC_ClearPendingIRQ
278 */
279void TZ_NVIC_ClearPendingIRQ_NS(IRQn_Type IRQn);
280
281/**
282  \brief   Get Active Interrupt (non-secure)
283  \details Reads the active register in non-secure NVIC when in secure state and returns the active bit.
284  \param [in]      IRQn  Interrupt number.
285  \return             0  Interrupt status is not active.
286  \return             1  Interrupt status is active.
287  \sa
288    - \ref NVIC_GetActive
289 */
290uint32_t TZ_NVIC_GetActive_NS(IRQn_Type IRQn);
291
292/**
293  \brief   Set Interrupt Priority (non-secure)
294  \details Sets the priority of an non-secure interrupt when in secure state.
295  \note    The priority cannot be set for every core interrupt.
296  \param [in]      IRQn  Interrupt number.
297  \param [in]  priority  Priority to set.
298  \sa
299    - \ref NVIC_SetPriority
300 */
301void TZ_NVIC_SetPriority_NS(IRQn_Type IRQn, uint32_t priority);
302
303/**
304  \brief   Get Interrupt Priority (non-secure)
305  \details Reads the priority of an non-secure interrupt when in secure state.
306           The interrupt number can be positive to specify an external (device specific) interrupt,
307           or negative to specify an internal (core) interrupt.
308  \param [in]   IRQn  Interrupt number.
309  \return             Interrupt Priority. Value is aligned automatically to the implemented priority bits of the microcontroller.
310  \sa
311    - \ref NVIC_GetPriority
312 */
313uint32_t TZ_NVIC_GetPriority_NS(IRQn_Type IRQn);
314
315/** close nvic_trustzone_functions
316  @}
317*/
318
319
320/**
321  \defgroup systick_trustzone_functions SysTick Functions
322  \brief SysTick functions related to TrustZone for Armv8-M.
323  @{
324*/
325
326/**
327  \brief   System Tick Configuration (non-secure)
328  \details Initializes the non-secure System Timer and its interrupt when in secure state, and starts the System Tick Timer.
329           Counter is in free running mode to generate periodic interrupts.
330  \param [in]  ticks  Number of ticks between two interrupts.
331  \return          0  Function succeeded.
332  \return          1  Function failed.
333  \note    When the variable <b>__Vendor_SysTickConfig</b> is set to 1, then the
334           function <b>TZ_SysTick_Config_NS</b> is not included. In this case, the file <b><i>device</i>.h</b>
335           must contain a vendor-specific implementation of this function.
336  \sa
337    - \ref SysTick_Config
338 */
339uint32_t TZ_SysTick_Config_NS(uint32_t ticks);
340
341/** close systick_trustzone_functions
342  @}
343*/
344
345
346/**
347  \defgroup sau_trustzone_functions SAU Functions
348  \brief Secure Attribution Unit (SAU) functions related to TrustZone for Armv8-M.
349  @{
350\details
351The Secure Attribution Unit (SAU) functions SAU
352
353\note
354A SAU is always present if the security extension is available.
355The functionality differs if the SAU contains SAU regions.
356If SAU regions are available is configured with the macro __SAUREGION_PRESENT (see \ref core_config_sect).
357
358 */
359
360/**
361\brief   Setup Secure Attribute Unit (SAU) and non-secure interrupts
362\details
363The function \ref TZ_SAU_Setup uses the settings in the \ref partition_h_pg to initialize
364the Secure Attribute Unit (SAU) and define non-secure interrupts.  It is called from
365the function \ref SystemInit.
366 */
367void TZ_SAU_Setup (void);
368
369/**
370  \brief   Enable Security Attribution Unit (SAU)
371  \details Enables the Security Attribution Unit (SAU).
372 */
373void TZ_SAU_Enable(void);
374
375/**
376  \brief   Disable Security Attribution Unit (SAU)
377  \details Disables the Security Attribution Unit (SAU).
378 */
379void TZ_SAU_Disable(void);
380
381/** close sau_trustzone_functions
382  @}
383*/
384
385
386/**
387  \defgroup stacksealing_support_trustzone_functions Stack Sealing Support Functions
388  \brief Stack sealing macros and helper functions.
389  @{
390\details
391See \ref RTOS_TrustZone_stacksealing for details on stack sealing technique.
392
393 */
394
395/**
396  \brief   Set stack seal at given address (secure)
397  \details Writes the stack seal values (2 x 0xFEF5EDA5U) to the given address when in secure state.
398  \param [in]    stackTop  address to write stackseal
399 */
400void __TZ_set_STACKSEAL_S (uint32_t *stackTop);
401
402/**
403\def __STACK_SEAL
404\brief Compiler/linker symbol specifying the location of the stack seal.
405\details
406The address of the specified symbol is used to set the stack seal during low level init.
407This is compiler/linker specific. CMSIS specifies common default for supported compilers.
408
409\note This define is only intended to be used by the \ref startup_c_pg.
410*/
411#define __STACK_SEAL
412
413/** close stacksealing_support_trustzone_functions
414  @}
415*/
416
417
418/**
419  \defgroup context_trustzone_functions RTOS Context Management
420  \brief RTOS Thread Context Management for Armv8-M TrustZone.
421  @{
422  \details The CMSIS-Core provides the file <b>tz_context.h</b> which defines an API to standardize the context memory system for real-time operating systems. For more information refer to \ref RTOS_TrustZone.
423*/
424
425/**
426  \brief Initialize secure context memory system
427  \details Initializes the memory allocation management for the secure memory regions. As a minimum the secure thread mode stack will be provided.
428  \return execution status (1: success, 0: error)
429 */
430uint32_t TZ_InitContextSystem_S (void);
431
432/**
433  \brief Allocate context memory for calling secure software modules in TrustZone
434  \details
435    Allocates the secure memory regions for thread execution. The parameter \em module describes
436    the set of secure functions that are called by the non-secure thread.
437    Set \em module to zero if no secure calls are used/allowed. This leads to no secure memory to be assigned
438    which results in zero being returned as memory id as well.
439    This function should be called by an RTOS kernel at the start of a thread.
440  \param[in]  module   A non-zero value identifies software modules called from non-secure mode. zero is used if no secure calls are used/allowed.
441  \return value != 0 id TrustZone memory slot identify
442  \return value 0    no memory available or internal error
443 */
444TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module);
445
446/**
447  \brief Free context memory that was previously allocated with \ref TZ_AllocModuleContext_S
448  \details
449    De-allocates the secure memory regions.
450    The parameter \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S.
451    This function should be called by an RTOS kernel at the termination of a thread.
452  \param[in]  id  TrustZone memory slot identifier
453  \return execution status (1: success, 0: error)
454 */
455uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id);
456
457/**
458  \brief Load secure context (called on RTOS thread context switch)
459  \details
460    Prepare the secure context for execution so that a thread in the non-secure state can
461    call secure library modules. The parameter \em id refers to a TrustZone memory slot that has been
462    obtained with \ref TZ_AllocModuleContext_S which might be zero if not used.
463    This function should be called by an RTOS kernel at thread context switch before running a thread.
464  \param[in]  id  TrustZone memory slot identifier
465  \return execution status (1: success, 0: error)
466 */
467uint32_t TZ_LoadContext_S (TZ_MemoryId_t id);
468
469/**
470  \brief Store secure context (called on RTOS thread context switch)
471  \details
472    Free the secure context that has been previously loaded with \ref TZ_LoadContext_S. The parameter
473    \em id refers to a TrustZone memory slot that has been obtained with \ref TZ_AllocModuleContext_S
474    which might be zero if not used.
475    This function should be called by an RTOS kernel at thread context switch after running a thread.
476  \param[in]  id  TrustZone memory slot identifier
477  \return execution status (1: success, 0: error)
478 */
479uint32_t TZ_StoreContext_S (TZ_MemoryId_t id);
480
481
482/** close context_trustzone_functions
483  @}
484*/
485
486
487/** close trustzone_functions
488@}
489*/
490
491/**
492\endcond
493*/