Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
tfm_thread.h
1 /*
2  * Copyright (c) 2018-2019, 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 "tfm_arch_v8m.h"
11 #include "cmsis_compiler.h"
12 
13 /* Status code */
14 #define THRD_STAT_CREATING 0
15 #define THRD_STAT_RUNNING 1
16 #define THRD_STAT_BLOCK 2
17 #define THRD_STAT_DETACH 3
18 #define THRD_STAT_INVALID 4
19 
20 /* Security attribute - default as security */
21 #define THRD_ATTR_SECURE_OFFSET 16
22 #define THRD_ATTR_SECURE (0)
23 #define THRD_ATTR_NON_SECURE (1 << THRD_ATTR_SECURE_OFFSET)
24 
25 /* Lower value has higher priority */
26 #define THRD_PRIOR_MASK 0xFF
27 #define THRD_PRIOR_HIGHEST 0x0
28 #define THRD_PRIOR_MEDIUM 0x7F
29 #define THRD_PRIOR_LOWEST 0xFF
30 
31 /* Error code */
32 #define THRD_SUCCESS 0
33 #define THRD_ERR_INVALID_PARAM 1
34 
35 /* Thread entry function type */
36 typedef void *(*tfm_thrd_func_t)(void *);
37 
38 /* Thread context */
39 struct tfm_thrd_ctx {
40  tfm_thrd_func_t pfn; /* entry function */
41  void *param; /* entry parameter */
42  uint8_t *sp_base; /* stack bottom */
43  uint8_t *sp_top; /* stack top */
44  uint32_t prior; /* priority */
45  uint32_t status; /* status */
46 
47  struct tfm_state_context state_ctx; /* State context */
48  struct tfm_thrd_ctx *next; /* next thread in list */
49 };
50 
51 /*
52  * Initialize a thread context with the necessary info.
53  *
54  * Parameters :
55  * pth - pointer of caller provided thread context
56  * pfn - thread entry function
57  * param - thread entry function parameter
58  * sp_base - stack pointer base (higher address)
59  * sp_top - stack pointer top (lower address)
60  *
61  * Notes :
62  * Thread contex rely on caller allocated memory; initialize members in
63  * context. This function does not insert thread into schedulable list.
64  */
65 void tfm_thrd_init(struct tfm_thrd_ctx *pth,
66  tfm_thrd_func_t pfn, void *param,
67  uint8_t *sp_base, uint8_t *sp_top);
68 
69 /* Set thread priority.
70  *
71  * Parameters :
72  * pth - pointer of thread context
73  * prior - priority value (0~255)
74  *
75  * Notes :
76  * Set thread priority. Priority is set to THRD_PRIOR_MEDIUM in
77  * tfm_thrd_init().
78  */
79 void __STATIC_INLINE tfm_thrd_priority(struct tfm_thrd_ctx *pth,
80  uint32_t prior)
81 {
82  pth->prior &= ~THRD_PRIOR_MASK;
83  pth->prior |= prior & THRD_PRIOR_MASK;
84 }
85 
86 /*
87  * Set thread security attribute.
88  *
89  * Parameters :
90  * pth - pointer of thread context
91  * attr_secure - THRD_ATTR_SECURE or THRD_ATTR_NON_SECURE
92  *
93  * Notes
94  * Reuse prior of thread context to shift down non-secure thread priority.
95  */
96 void __STATIC_INLINE tfm_thrd_secure(struct tfm_thrd_ctx *pth,
97  uint32_t attr_secure)
98 {
99  pth->prior &= ~THRD_ATTR_NON_SECURE;
100  pth->prior |= attr_secure;
101 }
102 
103 /*
104  * Set thread status.
105  *
106  * Parameters :
107  * pth - pointer of thread context
108  * new_status - new status of thread
109  *
110  * Return :
111  * None
112  *
113  * Notes :
114  * Thread status is not changed if invalid status value inputed.
115  */
116 void tfm_thrd_set_status(struct tfm_thrd_ctx *pth, uint32_t new_status);
117 
118 /*
119  * Get thread status.
120  *
121  * Parameters :
122  * pth - pointer of thread context
123  *
124  * Return :
125  * Status of thread
126  */
127 uint32_t __STATIC_INLINE tfm_thrd_get_status(struct tfm_thrd_ctx *pth)
128 {
129  return pth->status;
130 }
131 
132 /*
133  * Set thread state return value.
134  *
135  * Parameters :
136  * pth - pointer of thread context
137  * retval - return value to be set for thread state
138  *
139  * Notes :
140  * This API is useful for blocked syscall blocking thread. Syscall
141  * could set its return value to the caller before caller goes.
142  */
143 void __STATIC_INLINE tfm_thrd_set_retval(struct tfm_thrd_ctx *pth,
144  uint32_t retval)
145 {
146  TFM_STATE_RET_VAL(&pth->state_ctx) = retval;
147 }
148 
149 /*
150  * Validate thread context and insert it into schedulable list.
151  *
152  * Parameters :
153  * pth - pointer of thread context
154  *
155  * Return :
156  * THRD_SUCCESS for success. Or an error is returned.
157  *
158  * Notes :
159  * This function validates thread info. It returns error if thread info
160  * is not correct. Thread is avaliable after successful tfm_thrd_start().
161  */
162 uint32_t tfm_thrd_start(struct tfm_thrd_ctx *pth);
163 
164 /*
165  * Get current running thread.
166  *
167  * Return :
168  * Current running thread context pointer.
169  */
170 struct tfm_thrd_ctx *tfm_thrd_curr_thread(void);
171 
172 /*
173  * Get next running thread in list.
174  *
175  * Return :
176  * Pointer of next thread to be run.
177  */
178 struct tfm_thrd_ctx *tfm_thrd_next_thread(void);
179 
180 /*
181  * Start scheduler for existing threads
182  *
183  * Parameters:
184  * pth - pointer of the caller context collecting thread
185  *
186  * Notes :
187  * This function should be called only ONCE to start the scheduler.
188  * Caller needs to provide a thread object to collect current context.
189  * The usage of the collected context is caller defined.
190  */
191 void tfm_thrd_start_scheduler(struct tfm_thrd_ctx *pth);
192 
193 /*
194  * Activate a scheduling action after exception.
195  *
196  * Notes :
197  * This function could be called multiple times before scheduling.
198  */
199 void tfm_thrd_activate_schedule(void);
200 
201 /*
202  * Save current context into 'prev' thread and switch to 'next'.
203  *
204  * Parameters :
205  * ctxb - latest caller context
206  * prev - previous thread to be switched out
207  * next - thread to be run
208  *
209  * Notes :
210  * This function could be called multiple times before scheduling.
211  */
212 void tfm_thrd_context_switch(struct tfm_state_context_ext *ctxb,
213  struct tfm_thrd_ctx *prev,
214  struct tfm_thrd_ctx *next);
215 
216 /*
217  * Svcall to exit current running thread.
218  *
219  * Notes :
220  * Remove current thread out of schedulable list.
221  */
222 void tfm_svcall_thrd_exit(void);
223 
224 /*
225  * Exit current running thread for client.
226  *
227  * Notes:
228  * Must be called in thread mode.
229  */
230 void tfm_thrd_exit(void);
231 
232 #endif
tfm_thrd_ctx
Definition: tfm_thread.h:39
tfm_state_context_ext
Definition: tfm_arch_v8m.h:27
tfm_state_context
Definition: tfm_arch_v8m.h:42
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.