1 | /* |
---|
2 | * thread.h - Thread and related operations definition. |
---|
3 | * |
---|
4 | * Author Ghassan Almaless (2008,2009,2010,2011,2012) |
---|
5 | * Mohamed Lamine Karaoui (2015) |
---|
6 | * Alain Greiner (2016) |
---|
7 | * |
---|
8 | * Copyright (c) UPMC Sorbonne Universites |
---|
9 | * |
---|
10 | * This file is part of ALMOS-MKH. |
---|
11 | * |
---|
12 | * ALMOS-MKH is free software; you can redistribute it and/or modify it |
---|
13 | * under the terms of the GNU General Public License as published by |
---|
14 | * the Free Software Foundation; version 2.0 of the License. |
---|
15 | * |
---|
16 | * ALMOS-MKH is distributed in the hope that it will be useful, but |
---|
17 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
19 | * General Public License for more details. |
---|
20 | * |
---|
21 | * You should have received a copy of the GNU General Public License |
---|
22 | * along with ALMOS-MKH; if not, write to the Free Software Foundation, |
---|
23 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
---|
24 | */ |
---|
25 | |
---|
26 | #ifndef _THREAD_H_ |
---|
27 | #define _THREAD_H_ |
---|
28 | |
---|
29 | #include <hal_types.h> |
---|
30 | #include <hal_special.h> |
---|
31 | #include <xlist.h> |
---|
32 | #include <list.h> |
---|
33 | #include <hal_context.h> |
---|
34 | #include <spinlock.h> |
---|
35 | #include <core.h> |
---|
36 | #include <cluster.h> |
---|
37 | #include <process.h> |
---|
38 | #include <dev_ioc.h> |
---|
39 | #include <dev_nic.h> |
---|
40 | #include <dev_txt.h> |
---|
41 | #include <dev_mmc.h> |
---|
42 | #include <dev_dma.h> |
---|
43 | |
---|
44 | /*************************************************************************************** |
---|
45 | * This defines the various pthread_attr_t flags. |
---|
46 | **************************************************************************************/ |
---|
47 | |
---|
48 | #define PT_FLAG_DETACH 0x001 // user defined not joinable |
---|
49 | #define PT_FLAG_CLUSTER_DEFINED 0x002 // user defined target cluster |
---|
50 | #define PT_FLAG_CORE_DEFINED 0x004 // user defined core cluster |
---|
51 | |
---|
52 | /*************************************************************************************** |
---|
53 | * This structure defines the input argument of the pthread_create() system call. |
---|
54 | * It contains all informations required to initialize an user thread, and is passed |
---|
55 | * as input argument to the thread_user_create() function. |
---|
56 | * It is partly set by the kernel, partly set by the user application itself, |
---|
57 | * using the pthread_attr_***() functions. |
---|
58 | **************************************************************************************/ |
---|
59 | |
---|
60 | typedef struct pthread_attr_s |
---|
61 | { |
---|
62 | pid_t pid; /*! owner process identifier */ |
---|
63 | void * entry_func; /*! pointer on entry function */ |
---|
64 | void * entry_args; /*! pointer on entry function arguments */ |
---|
65 | uint32_t flags; /*! pthread flags (entirely user specified) */ |
---|
66 | cxy_t cxy; /*! target cluster (can be user specified) */ |
---|
67 | lid_t lid; /*! target core (can be user specified) */ |
---|
68 | } |
---|
69 | pthread_attr_t; |
---|
70 | |
---|
71 | |
---|
72 | /*************************************************************************************** |
---|
73 | * This enum defines the thread types. |
---|
74 | **************************************************************************************/ |
---|
75 | |
---|
76 | typedef enum |
---|
77 | { |
---|
78 | THREAD_USER = 0, /*! user thread (pthread) */ |
---|
79 | THREAD_RPC = 1, /*! kernel thread executing pending RPCs */ |
---|
80 | THREAD_DEV = 2, /*! kernel thread executing I/O device commands */ |
---|
81 | THREAD_KERNEL = 3, /*! other kernel thread */ |
---|
82 | THREAD_IDLE = 4, /*! kernel idle thread */ |
---|
83 | THREAD_TYPES_NR |
---|
84 | } |
---|
85 | thread_type_t; |
---|
86 | |
---|
87 | /*************************************************************************************** |
---|
88 | * This defines the masks associated to the thread flags. |
---|
89 | **************************************************************************************/ |
---|
90 | |
---|
91 | #define THREAD_FLAG_LOADABLE 0x0001 /*! This thread has not been executed yet */ |
---|
92 | #define THREAD_FLAG_DETACHED 0x0002 /*! This user thread is detached from parent */ |
---|
93 | |
---|
94 | /*************************************************************************************** |
---|
95 | * This defines the masks associated to the thread signals. |
---|
96 | **************************************************************************************/ |
---|
97 | |
---|
98 | #define THREAD_SIG_KILL 0x0001 /*! This thread must be destroyed ASAP */ |
---|
99 | |
---|
100 | /*************************************************************************************** |
---|
101 | * This defines the masks associated to the blocking causes. |
---|
102 | **************************************************************************************/ |
---|
103 | |
---|
104 | #define THREAD_BLOCKED_GLOBAL 0x0001 /*! thread global blocking */ |
---|
105 | #define THREAD_BLOCKED_IO 0x0002 /*! thread wait IO operation completion */ |
---|
106 | #define THREAD_BLOCKED_MAPPER 0x0004 /*! thread wait mapper */ |
---|
107 | #define THREAD_BLOCKED_EXIT 0x0010 /*! thread requested exit */ |
---|
108 | #define THREAD_BLOCKED_KILL 0x0020 /*! thread received kill signal */ |
---|
109 | #define THREAD_BLOCKED_SEM 0x0040 /*! thread wait semaphore */ |
---|
110 | #define THREAD_BLOCKED_PAGE 0x0080 /*! thread wait page access */ |
---|
111 | #define THREAD_BLOCKED_IDLE 0x1000 /*! thread RPC wait activation */ |
---|
112 | #define THREAD_BLOCKED_DEV_QUEUE 0x2000 /*! thread DEV wait queue */ |
---|
113 | #define THREAD_BLOCKED_DEV_ISR 0x4000 /*! thread DEV wait ISR */ |
---|
114 | |
---|
115 | /*************************************************************************************** |
---|
116 | * This structure defines thread instrumentation informations. |
---|
117 | **************************************************************************************/ |
---|
118 | |
---|
119 | typedef struct thread_info_s |
---|
120 | { |
---|
121 | uint32_t pgfault_nr; /*! cumulated number of page fault */ |
---|
122 | uint32_t sched_nr; /*! TODO ??? [AG] */ |
---|
123 | uint32_t u_err_nr; /*! TODO ??? [AG] */ |
---|
124 | uint32_t m_err_nr; /*! TODO ??? [AG] */ |
---|
125 | uint32_t tm_tmp; /*! temp date to compute execution duration */ |
---|
126 | uint32_t tm_exec; /*! TODO ??? [AG] */ |
---|
127 | uint32_t tm_create; /*! date of the creation */ |
---|
128 | uint32_t tm_born; /*! date of the thread loading */ |
---|
129 | uint32_t tm_dead; /*! date of the death */ |
---|
130 | clock_t tm_sleep; /*! TODO ??? [AG] */ |
---|
131 | clock_t tm_wait; /*! TODO ??? [AG] */ |
---|
132 | clock_t tm_usr; /*! user execution duration */ |
---|
133 | clock_t tm_sys; /*! system execution duration */ |
---|
134 | } |
---|
135 | thread_info_t; |
---|
136 | |
---|
137 | /*************************************************************************************** |
---|
138 | * This structure defines a thread descriptor. |
---|
139 | * It is used for both the user threads and the kernel threads. |
---|
140 | * In a process, an user thread is identified by a unique TRDID (thread identifier), |
---|
141 | * that is returned by the kernel to the user: |
---|
142 | * - The TRDID 16 LSB bits contain the LTID (Local Thread Index). |
---|
143 | * - The TRDID 16 MSB bits contain the owner cluster CXY. |
---|
144 | * - The LTID is used to index the th_tbl[] array in the local process descriptor. |
---|
145 | * This TRDID is computed by the process_register_thread() function, when the user |
---|
146 | * thread is registerd in the local copy of the process descriptor. |
---|
147 | **************************************************************************************/ |
---|
148 | |
---|
149 | #define THREAD_SIGNATURE 0xDEADBEEF |
---|
150 | |
---|
151 | typedef struct thread_s |
---|
152 | { |
---|
153 | uint32_t trdid; /*! thread index (in THTBL) */ |
---|
154 | thread_type_t type; /*! thread type */ |
---|
155 | uint32_t quantum; /*! number of clock ticks given to thread */ |
---|
156 | uint32_t ticks_nr; /*! number of ticks used */ |
---|
157 | uint32_t time_last_check; /*! last cpu_time_stamp */ |
---|
158 | core_t * core; /*! pointer to the owner core */ |
---|
159 | process_t * process; /*! pointer on local process descriptor */ |
---|
160 | |
---|
161 | uint32_t local_locks; /*! number of local locks owned by thread */ |
---|
162 | list_entry_t locks_root; /*! root of local locks list */ |
---|
163 | |
---|
164 | uint32_t remote_locks; /*! number of local locks owned by thread */ |
---|
165 | xlist_entry_t xlocks_root; /*! root of remote locks list */ |
---|
166 | |
---|
167 | intptr_t u_stack_base; /*! user stack base address */ |
---|
168 | uint32_t u_stack_size; /*! user stack size (bytes) */ |
---|
169 | intptr_t k_stack_base; /*! kernel stack base address */ |
---|
170 | uint32_t k_stack_size; /*! kernel stack size (bytes) */ |
---|
171 | |
---|
172 | void * entry_func; /*! pointer on entry function */ |
---|
173 | void * entry_args; /*! pointer on entry function arguments */ |
---|
174 | |
---|
175 | uint32_t flags; /*! bit vector of flags */ |
---|
176 | uint32_t blocked; /*! bit vector of blocking causes */ |
---|
177 | uint32_t signals; /*! bit vector of signals */ |
---|
178 | |
---|
179 | error_t errno; /*! errno value of last system call */ |
---|
180 | |
---|
181 | bool_t fork_user; /*! user defined placement for next fork() */ |
---|
182 | cxy_t fork_cxy; /*! target cluster for next fork() */ |
---|
183 | |
---|
184 | xlist_entry_t children_root; /*! root of list of attached children */ |
---|
185 | uint32_t children_nr; /*! number of attached children threads */ |
---|
186 | remote_spinlock_t * children_lock; /*! lock protecting the children list */ |
---|
187 | |
---|
188 | xlist_entry_t brothers_list; /*! member of threads with same parent */ |
---|
189 | |
---|
190 | list_entry_t sched_list; /*! member of threads attached to same core */ |
---|
191 | |
---|
192 | uint32_t dev_channel; /*! device channel for a DEV thread */ |
---|
193 | union /*! embedded command for a DEV thread */ |
---|
194 | { |
---|
195 | ioc_command_t ioc; /*! IOC device generic command */ |
---|
196 | txt_command_t txt; /*! TXT device generic command */ |
---|
197 | nic_command_t nic; /*! NIC device generic command */ |
---|
198 | mmc_command_t mmc; /*! MMC device generic command */ |
---|
199 | dma_command_t dma; /*! DMA device generic command */ |
---|
200 | } |
---|
201 | command; |
---|
202 | |
---|
203 | cxy_t rpc_client_cxy; /*! client cluster index (for a RPC thread) */ |
---|
204 | |
---|
205 | xlist_entry_t wait_list; /*! member of threads blocked on same cond */ |
---|
206 | |
---|
207 | void * fpu_context; /*! pointer on FPU context */ |
---|
208 | void * cpu_context; /*! pointer on CPU context */ |
---|
209 | |
---|
210 | thread_info_t info; /*! embedded thread_info_t */ |
---|
211 | |
---|
212 | uint32_t signature; /*! for kernel stack overflow detection */ |
---|
213 | } |
---|
214 | thread_t; |
---|
215 | |
---|
216 | /*************************************************************************************** |
---|
217 | * This macro returns a pointer on the calling thread from the core hardware register. |
---|
218 | **************************************************************************************/ |
---|
219 | |
---|
220 | #define CURRENT_THREAD (hal_get_current_thread()) |
---|
221 | |
---|
222 | /*************************************************************************************** |
---|
223 | * This function allocates memory for an user thread descriptor in the local cluster, |
---|
224 | * and initializes it from information contained in the "attr" argument. |
---|
225 | * It is used by the pthread_create system call, the CPU context is initialised from |
---|
226 | * scratch, and the "loadable" field is set. |
---|
227 | * The new thread is attached to the core specified in the "attr" argument. |
---|
228 | * It is registered in the local process descriptor for the process specified in "attr". |
---|
229 | * The thread descriptor pointer is returned to allow the parent thread to register it |
---|
230 | * in its children list. |
---|
231 | * The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start. |
---|
232 | *************************************************************************************** |
---|
233 | * @ new_thread : address of buffer for new thread descriptor pointer. |
---|
234 | * @ attr : pointer on pthread attributes descriptor. |
---|
235 | * @ u_stack_base : actual user stack size. |
---|
236 | * @ u_stack_size : actual user stack base. |
---|
237 | * @ returns 0 if success / returns ENOMEM if error. |
---|
238 | **************************************************************************************/ |
---|
239 | error_t thread_user_create( thread_t ** new_thread, |
---|
240 | pthread_attr_t * attr, |
---|
241 | intptr_t u_stack_base, |
---|
242 | uint32_t u_stack_size ); |
---|
243 | |
---|
244 | /*************************************************************************************** |
---|
245 | * This function allocates memory for an user thread descriptor in the local cluster, |
---|
246 | * and initialises it from informations contained in the calling thread descriptor. |
---|
247 | * It is used by the fork() system call to create the child process main thread. |
---|
248 | * The new thread is attached to the core with the lowest load. |
---|
249 | * It is registered in the process descriptor defined by the "process" argument. |
---|
250 | * This new thread inherits its execution context from the calling thread, |
---|
251 | * and the "loadable" field is NOT set. |
---|
252 | * The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start. |
---|
253 | *************************************************************************************** |
---|
254 | * @ new_thread : address of buffer for new thread descriptor pointer. |
---|
255 | * @ process : local pointer on owner process descriptor. |
---|
256 | * @ u_stack_base : actual user stack size. |
---|
257 | * @ u_stack_size : actual user stack base. |
---|
258 | * @ returns 0 if success / returns ENOMEM if error. |
---|
259 | **************************************************************************************/ |
---|
260 | error_t thread_user_fork( thread_t ** new_thread, |
---|
261 | process_t * process, |
---|
262 | intptr_t u_stack_base, |
---|
263 | uint32_t u_stack_size ); |
---|
264 | |
---|
265 | /*************************************************************************************** |
---|
266 | * This function allocates memory for a kernel thread descriptor in the local cluster, |
---|
267 | * and initialise it from arguments values, calling the thread_kernel_init() function, |
---|
268 | * that also allocates and initializes the CPU context. |
---|
269 | * The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start. |
---|
270 | *************************************************************************************** |
---|
271 | * @ new_thread : address of buffer for new thread pointer. |
---|
272 | * @ type : kernel thread type. |
---|
273 | * @ func : pointer on function. |
---|
274 | * @ args : function arguments. |
---|
275 | * @ core_lid : local core index. |
---|
276 | * @ returns 0 if success / returns ENOMEM if error |
---|
277 | **************************************************************************************/ |
---|
278 | error_t thread_kernel_create( thread_t ** new_thread, |
---|
279 | thread_type_t type, |
---|
280 | void * func, |
---|
281 | void * args, |
---|
282 | lid_t core_lid ); |
---|
283 | |
---|
284 | /*************************************************************************************** |
---|
285 | * This function initialises an existing kernel thread descriptor from arguments values. |
---|
286 | * The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start. |
---|
287 | *************************************************************************************** |
---|
288 | * @ thread : pointer on existing thread descriptor. |
---|
289 | * @ type : kernel thread type. |
---|
290 | * @ func : pointer on function. |
---|
291 | * @ args : function arguments. |
---|
292 | * @ core_lid : local core index. |
---|
293 | * @ returns 0 if success / returns EINVAL if error |
---|
294 | **************************************************************************************/ |
---|
295 | error_t thread_kernel_init( thread_t * thread, |
---|
296 | thread_type_t type, |
---|
297 | void * func, |
---|
298 | void * args, |
---|
299 | lid_t core_lid ); |
---|
300 | |
---|
301 | /*************************************************************************************** |
---|
302 | * This function releases the physical memory allocated for a thread descriptor |
---|
303 | * in the local cluster. It can be used for both an user and a kernel thread. |
---|
304 | * The physical memory dynamically allocated in the HEAP or MMAP zones by an user |
---|
305 | * thread will be released when the process is killed, and the page table flushed. |
---|
306 | *************************************************************************************** |
---|
307 | * @ thread : pointer on the thread descriptor to release. |
---|
308 | **************************************************************************************/ |
---|
309 | void thread_destroy( thread_t * thread ); |
---|
310 | |
---|
311 | /*************************************************************************************** |
---|
312 | * This function defines the code of the thread executed by all cores after kernel_init, |
---|
313 | * or when no other thread is runnable for a given core. |
---|
314 | * |
---|
315 | * TODO: In the TSAR architecture, it enters an infinite loop, in wich it forces |
---|
316 | * the core in sleep (low-power) mode. Any IRQ will force the core to exit this sleep |
---|
317 | * mode, but no ISR is executed. |
---|
318 | * TODO: We must analyse if we have the same behaviour for I86 architectures... |
---|
319 | **************************************************************************************/ |
---|
320 | void thread_idle_func(); |
---|
321 | |
---|
322 | /*************************************************************************************** |
---|
323 | * This function registers a child thread in the global list of attached |
---|
324 | * children threads of a parent thread. |
---|
325 | * It does NOT take a lock, as this function is allways called by the parent thread. |
---|
326 | *************************************************************************************** |
---|
327 | * @ xp_parent : extended pointer on the parent thread descriptor. |
---|
328 | * @ xp_child : extended pointer on the child thread descriptor. |
---|
329 | **************************************************************************************/ |
---|
330 | void thread_child_parent_link( xptr_t xp_parent, |
---|
331 | xptr_t xp_child ); |
---|
332 | |
---|
333 | /*************************************************************************************** |
---|
334 | * This function removes an user thread from the parent thread global list |
---|
335 | * of attached children threads. |
---|
336 | * It does take the lock, as this function can be called by the child thread. |
---|
337 | * In this case, it uses the extended pointer on the parent thread contained |
---|
338 | * in the pthread_attr_t embedded in the child thread descriptor. |
---|
339 | *************************************************************************************** |
---|
340 | * @ xp_parent : extended pointer on the parent thread descriptor. |
---|
341 | * @ xp_child : extended pointer on the child thread descriptor. |
---|
342 | **************************************************************************************/ |
---|
343 | void thread_child_parent_unlink( xptr_t xp_parent, |
---|
344 | xptr_t xp_child ); |
---|
345 | |
---|
346 | |
---|
347 | /*************************************************************************************** |
---|
348 | * This function atomically set a signal in a thread descriptor. |
---|
349 | *************************************************************************************** |
---|
350 | * @ thread : local pointer on target thread. |
---|
351 | * @ mask : mask on selected signal. |
---|
352 | **************************************************************************************/ |
---|
353 | inline void thread_set_signal( thread_t * thread, |
---|
354 | uint32_t mask ); |
---|
355 | |
---|
356 | /*************************************************************************************** |
---|
357 | * This function reset a signal in a thread descriptor. |
---|
358 | *************************************************************************************** |
---|
359 | * @ thread : local pointer on target thread. |
---|
360 | * @ mask : mask on selected signal. |
---|
361 | **************************************************************************************/ |
---|
362 | inline void thread_reset_signal( thread_t * thread, |
---|
363 | uint32_t mask ); |
---|
364 | |
---|
365 | /*************************************************************************************** |
---|
366 | * This function returns true if the calling thread is attached to its parent thread. |
---|
367 | **************************************************************************************/ |
---|
368 | inline bool_t thread_is_joinable(); |
---|
369 | |
---|
370 | /*************************************************************************************** |
---|
371 | * This function returns true if the calling thread is not blocked. |
---|
372 | **************************************************************************************/ |
---|
373 | inline bool_t thread_is_runnable(); |
---|
374 | |
---|
375 | /*************************************************************************************** |
---|
376 | * This function cheks if the calling thread can deschedule. |
---|
377 | *************************************************************************************** |
---|
378 | * @ returns true if no locks taken. |
---|
379 | **************************************************************************************/ |
---|
380 | inline bool_t thread_can_yield(); |
---|
381 | |
---|
382 | /*************************************************************************************** |
---|
383 | * This function checks if the calling thread must be descheduled. |
---|
384 | *************************************************************************************** |
---|
385 | * @ returns true if no locks taken, and elapsed time. |
---|
386 | **************************************************************************************/ |
---|
387 | bool_t thread_check_sched(); |
---|
388 | |
---|
389 | /*************************************************************************************** |
---|
390 | * This function can be used by the calling thread to suicide. |
---|
391 | * All locks must be previouly released. |
---|
392 | * The scenario depends on the attached/detached flag : |
---|
393 | * - if detached, it set the SIG_KILL signal in the "signals" bit_vector, registers |
---|
394 | * the BLOCKED_EXIT bit in the "blocked" bit_vector, and deschedule. |
---|
395 | * - if attached, it simply set the BLOCKED_EXIT bit in the "blocked" bit vector |
---|
396 | * and deschedule. The SIG_KILL signal will be set by the parent thread when |
---|
397 | * executing the pthread_join(). |
---|
398 | *************************************************************************************** |
---|
399 | * @ returns 0 if success / returns EINVAL if locks_count is not zero. |
---|
400 | **************************************************************************************/ |
---|
401 | error_t thread_exit(); |
---|
402 | |
---|
403 | /*************************************************************************************** |
---|
404 | * This function registers a blocking cause in the target thread "blocked" bit vector. |
---|
405 | * Warning : this function does not deschedule the calling thread. |
---|
406 | * The descheduling can be forced by a sched_yield(). |
---|
407 | *************************************************************************************** |
---|
408 | * @ thread : local pointer on target thread. |
---|
409 | * @ cause : mask defining the cause (one hot). |
---|
410 | **************************************************************************************/ |
---|
411 | void thread_block( thread_t * thread, |
---|
412 | uint32_t cause ); |
---|
413 | |
---|
414 | /*************************************************************************************** |
---|
415 | * This function reset the bit identified by the cause argument in the "blocked" |
---|
416 | * bit vector of a remote thread descriptor. |
---|
417 | * We need an extended pointer, because the client thread of an I/O operation on a |
---|
418 | * given device is not in the same cluster as the associated device descriptor. |
---|
419 | * Warning : this function does not reschedule the remote thread. |
---|
420 | * The scheduling can be forced by sending an IPI to the core running the remote thread. |
---|
421 | *************************************************************************************** |
---|
422 | * @ thread : extended pointer on the remote thread. |
---|
423 | * @ cause : mask defining the cause (one hot). |
---|
424 | **************************************************************************************/ |
---|
425 | void thread_unblock( xptr_t thread, |
---|
426 | uint32_t cause ); |
---|
427 | |
---|
428 | /*************************************************************************************** |
---|
429 | * This function kills a target thread, identified by its local pointer. |
---|
430 | * It is generally called by the local process_destroy() function. |
---|
431 | * - it forces the global blocked bit in target thread descriptor. |
---|
432 | * - it set the SIG_KILL signal in target thread. |
---|
433 | * - it send an IPI_SCHED_REQUEST to the target thread core. |
---|
434 | *************************************************************************************** |
---|
435 | * @ thread : local pointer on the target thread. |
---|
436 | * @ returns 0 if success / returns EINVAL if locks_count is not zero. |
---|
437 | **************************************************************************************/ |
---|
438 | void thread_kill( thread_t * thread ); |
---|
439 | |
---|
440 | #endif /* _THREAD_H_ */ |
---|