TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
tfm_thread.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 #ifndef __TFM_THREAD_H__
8 #define __TFM_THREAD_H__
9 
10 #include <stdint.h>
11 #include <stddef.h>
12 #include "tfm_arch.h"
13 #include "cmsis_compiler.h"
14 
15 /* State code */
16 #define THRD_STATE_CREATING 0
17 #define THRD_STATE_RUNNING 1
18 #define THRD_STATE_BLOCK 2
19 #define THRD_STATE_DETACH 3
20 #define THRD_STATE_INVALID 4
21 
22 /* Security attribute - default as security */
23 #define THRD_ATTR_SECURE_OFFSET 16
24 #define THRD_ATTR_SECURE (0)
25 #define THRD_ATTR_NON_SECURE (1 << THRD_ATTR_SECURE_OFFSET)
26 
27 /* Lower value has higher priority */
28 #define THRD_PRIOR_MASK 0xFF
29 #define THRD_PRIOR_HIGHEST 0x0
30 #define THRD_PRIOR_MEDIUM 0x7F
31 #define THRD_PRIOR_LOWEST 0xFF
32 
33 /* Error code */
34 #define THRD_SUCCESS 0
35 #define THRD_ERR_INVALID_PARAM 1
36 
37 /* Thread entry function type */
38 typedef void *(*tfm_core_thrd_entry_t)(void *);
39 
40 /* Thread context */
42  tfm_core_thrd_entry_t pfn; /* entry function */
43  void *param; /* entry parameter */
44  uintptr_t stk_btm; /* stack bottom (lower address) */
45  uintptr_t stk_top; /* stack top (higher address)*/
46  uint32_t prior; /* priority */
47  uint32_t state; /* state */
48 
49  struct tfm_arch_ctx_t arch_ctx; /* State context */
50  struct tfm_core_thread_t *next; /* next thread in list */
51 };
52 
53 /*
54  * Initialize a thread context with the necessary info.
55  *
56  * Parameters :
57  * pth - pointer of caller provided thread context
58  * pfn - thread entry function
59  * param - thread entry function parameter
60  * stk_top - stack pointer top (higher address)
61  * stk_btm - stack pointer bottom (lower address)
62  *
63  * Notes :
64  * Thread contex rely on caller allocated memory; initialize members in
65  * context. This function does not insert thread into schedulable list.
66  */
67 void tfm_core_thrd_init(struct tfm_core_thread_t *pth,
69  uintptr_t stk_top, uintptr_t stk_btm);
70 
71 /*
72  * Set thread priority.
73  *
74  * Parameters :
75  * pth - pointer of thread context
76  * prior - priority value (0~255)
77  *
78  * Notes :
79  * Set thread priority. Priority is set to THRD_PRIOR_MEDIUM in
80  * tfm_core_thrd_init().
81  */
82 void __STATIC_INLINE tfm_core_thrd_set_priority(struct tfm_core_thread_t *pth,
83  uint32_t prior)
84 {
85  pth->prior &= ~THRD_PRIOR_MASK;
86  pth->prior |= prior & THRD_PRIOR_MASK;
87 }
88 
89 /*
90  * Set thread security attribute.
91  *
92  * Parameters :
93  * pth - pointer of thread context
94  * attr_secure - THRD_ATTR_SECURE or THRD_ATTR_NON_SECURE
95  *
96  * Notes
97  * Reuse prior of thread context to shift down non-secure thread priority.
98  */
99 void __STATIC_INLINE tfm_core_thrd_set_secure(struct tfm_core_thread_t *pth,
100  uint32_t attr_secure)
101 {
102  pth->prior &= ~THRD_ATTR_NON_SECURE;
103  pth->prior |= attr_secure;
104 }
105 
106 /*
107  * Set thread state.
108  *
109  * Parameters :
110  * pth - pointer of thread context
111  * new_state - new state of thread
112  *
113  * Return :
114  * None
115  *
116  * Notes :
117  * Thread state is not changed if invalid state value inputed.
118  */
119 void tfm_core_thrd_set_state(struct tfm_core_thread_t *pth, uint32_t new_state);
120 
121 /*
122  * Get thread state.
123  *
124  * Parameters :
125  * pth - pointer of thread context
126  *
127  * Return :
128  * State of thread
129  */
130 uint32_t __STATIC_INLINE tfm_core_thrd_get_state(struct tfm_core_thread_t *pth)
131 {
132  return pth->state;
133 }
134 
135 /*
136  * Set thread state return value.
137  *
138  * Parameters :
139  * pth - pointer of thread context
140  * retval - return value to be set for thread state
141  *
142  * Notes :
143  * This API is useful for blocked syscall blocking thread. Syscall
144  * could set its return value to the caller before caller goes.
145  */
146 void __STATIC_INLINE tfm_core_thrd_set_retval(struct tfm_core_thread_t *pth,
147  uint32_t retval)
148 {
149  TFM_STATE_RET_VAL(&pth->arch_ctx) = retval;
150 }
151 
152 /*
153  * Validate thread context and insert it into schedulable list.
154  *
155  * Parameters :
156  * pth - pointer of thread context
157  *
158  * Return :
159  * THRD_SUCCESS for success. Or an error is returned.
160  *
161  * Notes :
162  * This function validates thread info. It returns error if thread info
163  * is not correct. Thread is avaliable after successful tfm_core_thrd_start().
164  */
165 uint32_t tfm_core_thrd_start(struct tfm_core_thread_t *pth);
166 
167 /*
168  * Get current running thread.
169  *
170  * Return :
171  * Current running thread context pointer.
172  */
174 
175 /*
176  * Get next running thread in list.
177  *
178  * Return :
179  * Pointer of next thread to be run.
180  */
182 
183 /*
184  * Start scheduler for existing threads
185  *
186  * Parameters:
187  * pth - pointer of the caller context collecting thread
188  *
189  * Notes :
190  * This function should be called only ONCE to start the scheduler.
191  * Caller needs to provide a thread object to collect current context.
192  * The usage of the collected context is caller defined.
193  */
195 
196 /*
197  * Activate a scheduling action after exception.
198  *
199  * Notes :
200  * This function could be called multiple times before scheduling.
201  */
203 
204 /*
205  * Save current architecture context into 'prev' thread and switch to 'next'.
206  *
207  * Parameters :
208  * p_actx - latest caller context
209  * prev - previous thread to be switched out
210  * next - thread to be run
211  *
212  * Notes :
213  * This function could be called multiple times before scheduling.
214  */
215 void tfm_core_thrd_switch_context(struct tfm_arch_ctx_t *p_actx,
216  struct tfm_core_thread_t *prev,
217  struct tfm_core_thread_t *next);
218 
219 #endif
void tfm_core_thrd_init(struct tfm_core_thread_t *pth, tfm_core_thrd_entry_t pfn, void *param, uintptr_t stk_top, uintptr_t stk_btm)
Definition: tfm_thread.c:85
tfm_core_thrd_entry_t pfn
Definition: tfm_thread.h:42
void *(* tfm_core_thrd_entry_t)(void *)
Definition: tfm_thread.h:38
void __STATIC_INLINE tfm_core_thrd_set_retval(struct tfm_core_thread_t *pth, uint32_t retval)
Definition: tfm_thread.h:146
void tfm_core_thrd_start_scheduler(struct tfm_core_thread_t *pth)
Definition: tfm_thread.c:134
#define TFM_STATE_RET_VAL(ctx)
Definition: tfm_arch.h:41
struct tfm_core_thread_t * tfm_core_thrd_get_next_thread(void)
Definition: tfm_thread.c:36
void __STATIC_INLINE tfm_core_thrd_set_priority(struct tfm_core_thread_t *pth, uint32_t prior)
Definition: tfm_thread.h:82
struct tfm_arch_ctx_t arch_ctx
Definition: tfm_thread.h:49
uint32_t tfm_core_thrd_start(struct tfm_core_thread_t *pth)
Definition: tfm_thread.c:97
void tfm_core_thrd_switch_context(struct tfm_arch_ctx_t *p_actx, struct tfm_core_thread_t *prev, struct tfm_core_thread_t *next)
Definition: tfm_thread.c:153
#define THRD_ATTR_NON_SECURE
Definition: tfm_thread.h:25
void __STATIC_INLINE tfm_core_thrd_set_secure(struct tfm_core_thread_t *pth, uint32_t attr_secure)
Definition: tfm_thread.h:99
uint32_t prior
Definition: tfm_thread.h:46
#define THRD_PRIOR_MASK
Definition: tfm_thread.h:28
void tfm_core_thrd_set_state(struct tfm_core_thread_t *pth, uint32_t new_state)
Definition: tfm_thread.c:120
struct tfm_core_thread_t * next
Definition: tfm_thread.h:50
uint32_t __STATIC_INLINE tfm_core_thrd_get_state(struct tfm_core_thread_t *pth)
Definition: tfm_thread.h:130
uintptr_t stk_top
Definition: tfm_thread.h:45
struct tfm_core_thread_t * tfm_core_thrd_get_curr_thread(void)
Definition: tfm_thread.c:46
void tfm_core_thrd_activate_schedule(void)
Definition: tfm_thread.c:129
uintptr_t stk_btm
Definition: tfm_thread.h:44
uint32_t state
Definition: tfm_thread.h:47