xref: /Kernel-v10.6.2/portable/IAR/ARM_CM33/secure/secure_context.h (revision ef7b253b56c9788077f5ecd6c9deb4021923d646) 
1 /*
2  * FreeRTOS Kernel V10.6.2
3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
4  *
5  * SPDX-License-Identifier: MIT
6  *
7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
8  * this software and associated documentation files (the "Software"), to deal in
9  * the Software without restriction, including without limitation the rights to
10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11  * the Software, and to permit persons to whom the Software is furnished to do so,
12  * subject to the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be included in all
15  * copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  *
24  * https://www.FreeRTOS.org
25  * https://github.com/FreeRTOS
26  *
27  */
28 
29 #ifndef __SECURE_CONTEXT_H__
30 #define __SECURE_CONTEXT_H__
31 
32 /* Standard includes. */
33 #include <stdint.h>
34 
35 /* FreeRTOS includes. */
36 #include "FreeRTOSConfig.h"
37 
38 /**
39  * @brief PSP value when no secure context is loaded.
40  */
41 #define securecontextNO_STACK               0x0
42 
43 /**
44  * @brief Invalid context ID.
45  */
46 #define securecontextINVALID_CONTEXT_ID     0UL
47 /*-----------------------------------------------------------*/
48 
49 /**
50  * @brief Structure to represent a secure context.
51  *
52  * @note Since stack grows down, pucStackStart is the highest address while
53  * pucStackLimit is the first address of the allocated memory.
54  */
55 typedef struct SecureContext
56 {
57     uint8_t * pucCurrentStackPointer; /**< Current value of stack pointer (PSP). */
58     uint8_t * pucStackLimit;          /**< Last location of the stack memory (PSPLIM). */
59     uint8_t * pucStackStart;          /**< First location of the stack memory. */
60     void * pvTaskHandle;              /**< Task handle of the task this context is associated with. */
61 } SecureContext_t;
62 /*-----------------------------------------------------------*/
63 
64 /**
65  * @brief Opaque handle for a secure context.
66  */
67 typedef uint32_t SecureContextHandle_t;
68 /*-----------------------------------------------------------*/
69 
70 /**
71  * @brief Initializes the secure context management system.
72  *
73  * PSP is set to NULL and therefore a task must allocate and load a context
74  * before calling any secure side function in the thread mode.
75  *
76  * @note This function must be called in the handler mode. It is no-op if called
77  * in the thread mode.
78  */
79 void SecureContext_Init( void );
80 
81 /**
82  * @brief Allocates a context on the secure side.
83  *
84  * @note This function must be called in the handler mode. It is no-op if called
85  * in the thread mode.
86  *
87  * @param[in] ulSecureStackSize Size of the stack to allocate on secure side.
88  * @param[in] ulIsTaskPrivileged 1 if the calling task is privileged, 0 otherwise.
89  *
90  * @return Opaque context handle if context is successfully allocated, NULL
91  * otherwise.
92  */
93 #if ( configENABLE_MPU == 1 )
94     SecureContextHandle_t SecureContext_AllocateContext( uint32_t ulSecureStackSize,
95                                                          uint32_t ulIsTaskPrivileged,
96                                                          void * pvTaskHandle );
97 #else /* configENABLE_MPU */
98     SecureContextHandle_t SecureContext_AllocateContext( uint32_t ulSecureStackSize,
99                                                          void * pvTaskHandle );
100 #endif /* configENABLE_MPU */
101 
102 /**
103  * @brief Frees the given context.
104  *
105  * @note This function must be called in the handler mode. It is no-op if called
106  * in the thread mode.
107  *
108  * @param[in] xSecureContextHandle Context handle corresponding to the
109  * context to be freed.
110  */
111 void SecureContext_FreeContext( SecureContextHandle_t xSecureContextHandle, void * pvTaskHandle );
112 
113 /**
114  * @brief Loads the given context.
115  *
116  * @note This function must be called in the handler mode. It is no-op if called
117  * in the thread mode.
118  *
119  * @param[in] xSecureContextHandle Context handle corresponding to the context
120  * to be loaded.
121  */
122 void SecureContext_LoadContext( SecureContextHandle_t xSecureContextHandle, void * pvTaskHandle );
123 
124 /**
125  * @brief Saves the given context.
126  *
127  * @note This function must be called in the handler mode. It is no-op if called
128  * in the thread mode.
129  *
130  * @param[in] xSecureContextHandle Context handle corresponding to the context
131  * to be saved.
132  */
133 void SecureContext_SaveContext( SecureContextHandle_t xSecureContextHandle, void * pvTaskHandle );
134 
135 #endif /* __SECURE_CONTEXT_H__ */
136