Context Navigation

source: trunk/kernel/kern/thread.h @ 471

Last change on this file since 471 was 459, checked in by alain, 6 years ago
Introduce the math library, to support the floating point data used by the multi-thread fft application. Fix several bugs regarding the FPU context save/restore. Introduce support for the %f format in printf.
File size: 27.0 KB

Line
1	/*
2	* thread.h - Thread and related operations definition.
3	*
4	* Author Ghassan Almaless (2008,2009,2010,2011,2012)
5	* Alain Greiner (2016)
6	*
7	* Copyright (c) UPMC Sorbonne Universites
8	*
9	* This file is part of ALMOS-MKH.
10	*
11	* ALMOS-MKH is free software; you can redistribute it and/or modify it
12	* under the terms of the GNU General Public License as published by
13	* the Free Software Foundation; version 2.0 of the License.
14	*
15	* ALMOS-MKH is distributed in the hope that it will be useful, but
16	* WITHOUT ANY WARRANTY; without even the implied warranty of
17	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18	* General Public License for more details.
19	*
20	* You should have received a copy of the GNU General Public License
21	* along with ALMOS-MKH; if not, write to the Free Software Foundation,
22	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23	*/
24
25	#ifndef _THREAD_H_
26	#define _THREAD_H_
27
28	#include <hal_kernel_types.h>
29	#include <shared_syscalls.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 <chdev.h>
37	#include <cluster.h>
38	#include <process.h>
39	#include <dev_ioc.h>
40	#include <dev_nic.h>
41	#include <dev_txt.h>
42	#include <dev_mmc.h>
43	#include <dev_dma.h>
44
45	/***************************************************************************************
46	* These macros are used to compose or decompose the global thread identifier (TRDID)
47	* to or from cluster identifier / local thread index (CXY , LTID)
48	**************************************************************************************/
49
50	#define LTID_FROM_TRDID( trdid ) (ltid_t)(trdid & 0x0000FFFF)
51	#define CXY_FROM_TRDID( trdid ) (cxy_t)(trdid >> 16)
52	#define TRDID( cxy , ltid ) (trdid_t)((cxy << 16) \| ltid )
53
54	/***************************************************************************************
55	* This enum defines the thread types.
56	**************************************************************************************/
57
58	typedef enum
59	{
60	THREAD_USER = 0, /! user thread (pthread) /
61	THREAD_RPC = 1, /! kernel thread executing pending RPCs /
62	THREAD_DEV = 2, /! kernel thread executing I/O device commands /
63	THREAD_IDLE = 3, /! kernel idle thread /
64	}
65	thread_type_t;
66
67	/***************************************************************************************
68	* This defines the thread flags bit-vector.
69	**************************************************************************************/
70
71	#define THREAD_FLAG_DETACHED 0x0001 /! This thread is detached from parent /
72	#define THREAD_FLAG_JOIN_DONE 0x0002 /! Parent thread made a join request /
73	#define THREAD_FLAG_KILL_DONE 0x0004 /! This thread received a kill request /
74	#define THREAD_FLAG_SCHED 0x0008 /! Scheduling required for this thread /
75	#define THREAD_FLAG_REQ_ACK 0x0010 /! Acknowledge required from scheduler /
76	#define THREAD_FLAG_REQ_DELETE 0x0020 /! Destruction required from scheduler /
77
78	/***************************************************************************************
79	* This defines the thread blocking causes bit-vector.
80	**************************************************************************************/
81
82	#define THREAD_BLOCKED_GLOBAL 0x0001 /! thread deactivated / wait activation /
83	#define THREAD_BLOCKED_IO 0x0002 /! thread wait IO operation completion /
84	#define THREAD_BLOCKED_MAPPER 0x0004 /! thread wait mapper /
85	#define THREAD_BLOCKED_EXIT 0x0008 /! thread blocked in join / wait exit /
86	#define THREAD_BLOCKED_JOIN 0x0010 /! thread blocked in exit / wait join /
87	#define THREAD_BLOCKED_SEM 0x0020 /! thread wait semaphore /
88	#define THREAD_BLOCKED_PAGE 0x0040 /! thread wait page access /
89	#define THREAD_BLOCKED_IDLE 0x0080 /! thread RPC wait RPC_FIFO non empty /
90	#define THREAD_BLOCKED_USERSYNC 0x0100 /! thread wait (cond/mutex/barrier) /
91	#define THREAD_BLOCKED_RPC 0x0200 /! thread wait RPC completion /
92	#define THREAD_BLOCKED_ISR 0x0400 /! thread DEV wait ISR /
93	#define THREAD_BLOCKED_WAIT 0x0800 /! thread wait child process termination /
94
95	/***************************************************************************************
96	* This structure defines thread instrumentation informations.
97	**************************************************************************************/
98
99	typedef struct thread_info_s
100	{
101	uint32_t pgfault_nr; /! cumulated number of page fault /
102	uint32_t sched_nr; /! TODO ??? [AG] /
103	uint32_t u_err_nr; /! TODO ??? [AG] /
104	uint32_t m_err_nr; /! TODO ??? [AG] /
105	uint32_t tm_tmp; /! temp date to compute execution duration /
106	uint32_t tm_exec; /! TODO ??? [AG] /
107	uint32_t tm_create; /! date of the creation /
108	uint32_t tm_born; /! date of the thread loading /
109	uint32_t tm_dead; /! date of the death /
110	cycle_t tm_sleep; /! TODO ??? [AG] /
111	cycle_t tm_wait; /! TODO ??? [AG] /
112	cycle_t tm_usr; /! user execution duration /
113	cycle_t tm_sys; /! system execution duration /
114	}
115	thread_info_t;
116
117	/***************************************************************************************
118	* This structure defines a thread descriptor.
119	* It is used for both the user threads and the kernel threads.
120	* In a process, a user thread is identified by a unique TRDID (thread identifier):
121	* - The TRDID 16 LSB bits contain the LTID (Local Thread Index).
122	* - The TRDID 16 MSB bits contain the CXY of cluster containing the thread.
123	* The main thread LTID value is always 0.
124	* The LTID is used to index the th_tbl[] array in the local process descriptor.
125	* This TRDID is computed by the process_register_thread() function, when the user
126	* thread is registered in the local copy of the process descriptor.
127	* WARNING : Don't modify the first 4 fields order, as this order is used by the
128	* hal_kentry assembly code for the TSAR architecture.
129	**************************************************************************************/
130
131	#define THREAD_SIGNATURE 0xDEADBEEF
132
133	typedef struct thread_s
134	{
135	void * cpu_context; /! pointer on CPU context switch /
136	void * fpu_context; /! pointer on FPU context switch /
137	void * uzone_current; /! used by hal_do_syscall & hal_do_except /
138	void * uzone_previous; /! used by hal_do_syscall & hal_do_except /
139
140	intptr_t k_stack_base; /! kernel stack base address /
141	uint32_t k_stack_size; /! kernel stack size (bytes) /
142
143	uint32_t trdid; /! thread index (cxy.ltid) /
144	thread_type_t type; /! thread type /
145	uint32_t quantum; /! number of clock ticks given to thread /
146	uint32_t ticks_nr; /! number of ticks used /
147	uint32_t time_last_check; /! last cpu_time_stamp /
148	core_t * core; /! pointer to the owner core /
149	process_t * process; /! pointer on local process descriptor /
150	xptr_t parent; /! extended pointer on parent thread /
151
152	remote_spinlock_t join_lock; /! lock protecting the join/exit /
153	xptr_t join_xp; /! joining/killer thread extended pointer /
154
155	uint32_t * ack_rsp_count; /! pointer on acknowledge response counter /
156
157	intptr_t u_stack_base; /! user stack base address /
158	uint32_t u_stack_size; /! user stack size (bytes) /
159
160	void * entry_func; /! pointer on entry function /
161	void * entry_args; /! pointer on entry function arguments /
162	uint32_t main_argc; /! main thread number of arguments /
163	char ** main_argv; /! main thread array of strings arguments /
164
165	uint32_t flags; /! bit vector of flags /
166	uint32_t blocked; /! bit vector of blocking causes /
167
168	error_t errno; /! errno value set by last system call /
169	uint32_t utls; /! user thread local storage /
170
171	bool_t fork_user; /! user defined placement for next fork() /
172	cxy_t fork_cxy; /! target cluster for next fork() /
173
174	list_entry_t sched_list; /! member of threads attached to same core /
175
176	chdev_t * chdev; /! chdev pointer (for a DEV thread only) /
177
178	reg_t save_sr; /! used by sched_yield() function /
179
180	ioc_command_t ioc_cmd; /! IOC device generic command /
181	txt_command_t txt_cmd; /! TXT device generic command /
182	nic_command_t nic_cmd; /! NIC device generic command /
183	mmc_command_t mmc_cmd; /! MMC device generic command /
184	dma_command_t dma_cmd; /! DMA device generic command /
185
186	cxy_t rpc_client_cxy; /! client cluster index (for a RPC thread) /
187
188	xlist_entry_t wait_list; /! member of threads blocked on same cond /
189
190	list_entry_t locks_root; /! root of list of locks taken /
191	xlist_entry_t xlocks_root; /! root of xlist of remote locks taken /
192	uint32_t local_locks; /! number of local locks owned by thread /
193	uint32_t remote_locks; /! number of remote locks owned by thread /
194
195	thread_info_t info; /! embedded thread_info_t /
196
197	uint32_t signature; /! for kernel stack overflow detection /
198	}
199	thread_t;
200
201	/***************************************************************************************
202	* This macro returns a pointer on the calling thread from the core hardware register.
203	**************************************************************************************/
204
205	#define CURRENT_THREAD (hal_get_current_thread())
206
207	/***************************************************************************************
208	* This function returns a printable string for a thread type.
209	***************************************************************************************
210	* @ type : thread type.
211	* returns pointer on string.
212	**************************************************************************************/
213	char * thread_type_str( uint32_t type );
214
215	/***************************************************************************************
216	* This function is used by the pthread_create() system call to create a "new" thread
217	* in an existing process. It allocates memory for an user thread descriptor in the
218	* local cluster, and initializes it from information contained in the arguments.
219	* The CPU context is initialized from scratch.
220	* It is registered in the local process descriptor specified by the <pid> argument.
221	* The THREAD_BLOCKED_GLOBAL bit is set => the thread must be activated by the caller
222	* to start at the next scheduling point.
223	***************************************************************************************
224	* @ pid : process identifier.
225	* @ start_func : pointer on entry function.
226	* @ start_args : pointer on function argument (can be NULL).
227	* @ attr : pointer on pthread attributes descriptor.
228	* @ new_thread : [out] address of buffer for new thread descriptor pointer.
229	* @ returns 0 if success / returns ENOMEM if error.
230	**************************************************************************************/
231	error_t thread_user_create( pid_t pid,
232	void * start_func,
233	void * start_arg,
234	pthread_attr_t * attr,
235	thread_t ** new_thread );
236
237	/***************************************************************************************
238	* This function is used by the sys_fork() system call to create the "child" thread
239	* in the local cluster. It allocates memory for a thread descriptor, and initializes
240	* it from the "parent" thread descriptor defined by the <parent_thread_xp> argument.
241	* The new thread is attached to the core that has the lowest load in local cluster.
242	* It is registered in the "child" process defined by the <child_process> argument.
243	* This new thread inherits its user stack from the parent thread, as it uses the
244	* Copy-On-Write mechanism to get a private stack when required.
245	* The content of the parent kernel stack is copied into the child kernel stack, as
246	* the Copy-On-Write mechanism cannot be used for kernel segments (because kernel
247	* uses physical addressing on some architectures).
248	* The CPU and FPU execution contexts are created and linked to the new thread.
249	* but the actual context copy is NOT done, and must be done by by the sys_fork().
250	* The THREAD_BLOCKED_GLOBAL bit is set => the thread must be activated to start.
251	***************************************************************************************
252	* @ parent_thread_xp : extended pointer on parent thread descriptor.
253	* @ child_process : local pointer on child process descriptor.
254	* @ child_thread : [out] address of buffer for child thread descriptor pointer.
255	* @ returns 0 if success / returns -1 if error.
256	**************************************************************************************/
257	error_t thread_user_fork( xptr_t parent_thread_xp,
258	process_t * child_process,
259	thread_t ** child_thread );
260
261	/***************************************************************************************
262	* This function is called by the process_make_exec() function to re-initialise the
263	* thread descriptor of the calling thread (that will become the new process main
264	* thread), and immediately jump to user code without returning to kentry!!!
265	* It must be called by the main thread of the calling process.
266	* - A new user stack vseg is created and initialised.
267	* - The kernel stack (currently in use) is not modified.
268	* - The function calls the hal_cpu_context_exec() to re-initialize the CPU context
269	* an jump to user code.
270	***************************************************************************************
271	* @ entry_func : main thread entry point.
272	* @ argc : number of main thread arguments.
273	* @ argv : array of pointers on stringarguments.
274	* @ returns 0 if success / returns ENOMEM if error.
275	**************************************************************************************/
276	error_t thread_user_exec( void * entry_func,
277	uint32_t argc,
278	char ** argv);
279
280	/***************************************************************************************
281	* This function allocates memory for a kernel thread descriptor in the local cluster,
282	* and initializes it from arguments values.
283	* It is called by kernel_init() to statically create all DEV server threads
284	* It is also called to dynamically create RPC threads when required.
285	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
286	***************************************************************************************
287	* @ new_thread : address of buffer for new thread pointer.
288	* @ type : kernel thread type.
289	* @ func : pointer on function.
290	* @ args : function arguments.
291	* @ core_lid : local core index.
292	* @ returns 0 if success / returns ENOMEM if error
293	**************************************************************************************/
294	error_t thread_kernel_create( thread_t ** new_thread,
295	thread_type_t type,
296	void * func,
297	void * args,
298	lid_t core_lid );
299
300	/***************************************************************************************
301	* This function is called by the kernel_init() function to initialize the IDLE thread
302	* descriptor from arguments values.
303	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
304	* It returns a kernel panic if failure.
305	***************************************************************************************
306	* @ thread : pointer on existing thread descriptor.
307	* @ type : kernel thread type.
308	* @ func : pointer on function.
309	* @ args : function arguments.
310	* @ core_lid : local core index.
311	**************************************************************************************/
312	void thread_idle_init( thread_t * thread,
313	thread_type_t type,
314	void * func,
315	void * args,
316	lid_t core_lid );
317
318	/***************************************************************************************
319	* This function is called by the sched_handle_signals() function to releases
320	* the physical memory allocated for a thread in a given cluster, when this thread
321	* is marked for delete. This include the thread descriptor itself, the associated
322	* CPU and FPU context, and the physical memory allocated for an user thread local stack.
323	* The destroyed thread is removed from the local process th_tbl[] array, and returns
324	* true when the destroyed thread was the last thread registered in process.
325	***************************************************************************************
326	* @ thread : pointer on the thread descriptor to release.
327	* @ return true, if the thread was the last registerd thread in local process.
328	**************************************************************************************/
329	bool_t thread_destroy( thread_t * thread );
330
331	/***************************************************************************************
332	* This function defines the code of the thread executed by all cores after kernel_init,
333	* or when no other thread is runnable for a given core.
334	* It enter and infinite loop in wich:
335	* - it unmask the IRQs
336	* - it optionally calls the hal_core_sleep() function to reduce the power consumption
337	* (this behavior is controlled by the CONFIG_THREAD_IDLE_MODE_SLEEP flag).
338	* - it call the sched_yield() function to find another runnable thread.
339	*
340	* TODO: In the TSAR architecture the hal_core_sleep() function forces the core to
341	* low-power mode. Any IRQ will force the core to exit this low-power mode, but no ISR
342	* is executed. We must analyse if we have the same behaviour for I86 architectures...
343	**************************************************************************************/
344	void thread_idle_func();
345
346	/***************************************************************************************
347	* This function is used by a "blocker" thread running in the same cluster as a "target"
348	* thread to request the scheduler of the target thread to acknowledge that the target
349	* thread is blocked and not running, at the next context switch.
350	* This function executes atomically the following actions :
351	* - it set the request_pending boolean in the target scheduler descriptor.
352	* - it set the REQ_ACK flag in the "flags" field of the target thread descriptor.
353	* - It registers the responses counter pointer in the target thread descriptor.
354	* The request_pending flag is handled as a set/reset flip-flop by the "blocker" thread
355	* and by the "target" scheduler.
356	***************************************************************************************
357	* @ target : local pointer on target thread.
358	* @ ack_rsp_count : local pointer on responses counter.
359	**************************************************************************************/
360	void thread_set_req_ack( thread_t * target,
361	uint32_t * ack_rsp_count );
362
363	/***************************************************************************************
364	* This function is used by the sched_handle_signal() function executed by the
365	* scheduler of a "target" thread to reset a "blocked not running" acknowledge request
366	* in both the target thread descriptor, and in the target thread scheduler.
367	***************************************************************************************
368	* @ target : local pointer on target thread.
369	**************************************************************************************/
370	void thread_reset_req_ack( thread_t * target );
371
372	/***************************************************************************************
373	* This function checks if the calling thread can deschedule.
374	***************************************************************************************
375	* @ returns true if no locks taken.
376	**************************************************************************************/
377	inline bool_t thread_can_yield();
378
379	/***************************************************************************************
380	* This function implements the delayed descheduling mechanism : It is called by
381	* all lock release functions, and calls the sched_yield() function when all locks
382	* have beeen released and the calling thread THREAD_FLAG_SCHED flag is set.
383	**************************************************************************************/
384	void thread_check_sched();
385
386	/***************************************************************************************
387	* This function is used by the four sys_thread_cancel(), sys_thread_exit(),
388	* sys_kill() and sys_exit() system calls to mark for delete a given thread.
389	* It set the THREAD_BLOCKED_GLOBAL bit and set the the THREAD_FLAG_REQ_DELETE bit
390	* in the thread descriptor identified by the <thread_xp> argument, to ask the scheduler
391	* to asynchronously delete the target thread, at the next scheduling point.
392	* The calling thread can run in any cluster, as it uses remote accesses, but
393	* the target thread cannot be the main thread of the process identified by the <pid>,
394	* because the main thread must be deleted by the parent process argument.
395	* If the target thread is running in "attached" mode, and the <is_forced> argument
396	* is false, this function implements the required sychronisation with the joining
397	* thread, blocking the calling thread until the pthread_join() syscall is executed.
398	***************************************************************************************
399	* @ thread_xp : extended pointer on the target thread.
400	* @ pid : process identifier (to get the owner cluster identifier).
401	* @ is_forced : the deletion does not depends on the attached mode.
402	**************************************************************************************/
403	void thread_delete( xptr_t thread_xp,
404	pid_t pid,
405	bool_t is_forced );
406
407	/***************************************************************************************
408	* This function registers a blocking cause defined by the <cause> argument
409	* in a remote thread descriptor identified by the <thread_xp> argument.
410	* We need an extended pointer, because this function can be called by another thread
411	* than the target thread, executing the sys_kill() function.
412	* WARNING : this function does not deschedule the target thread, and the descheduling
413	* must be explicitely forced by a sched_yield().
414	***************************************************************************************
415	* @ thread_xp : extended pointer on remote thread descriptor.
416	* @ cause : mask defining the cause (one hot).
417	**************************************************************************************/
418	void thread_block( xptr_t thread_xp,
419	uint32_t cause );
420
421	/***************************************************************************************
422	* This function resets the bit identified by the <cause> argument in a remote
423	* thread descriptor identified by the <thread_xp> argument.
424	* We need an extended pointer, because the client thread of an I/O operation on a
425	* given device is not in the same cluster as the associated device descriptor.
426	* WARNING : this function does not reschedule the remote thread.
427	* The scheduling can be forced by sending an IPI to the core running the remote thread.
428	***************************************************************************************
429	* @ thread_xp : extended pointer the remote thread.
430	* @ cause : mask defining the cause (one hot).
431	* @ return non zero if the bit-vector was actually modified / return 0 otherwise
432	**************************************************************************************/
433	uint32_t thread_unblock( xptr_t thread_xp,
434	uint32_t cause );
435
436	/***************************************************************************************
437	* This function updates the calling thread user_time counter, and resets the thread
438	* cycles counter.
439	* TODO This function is not implemented.
440	***************************************************************************************
441	* @ thread : local pointer on target thread.
442	**************************************************************************************/
443	void thread_user_time_update( thread_t * thread );
444
445	/**************************************************************************************n
446	* This function updates the calling thread kernel_time counter, and resets the thread
447	* cycles counter.
448	* TODO This function is not implemented.
449	***************************************************************************************
450	* @ thread : local pointer on target thread.
451	**************************************************************************************/
452	void thread_kernel_time_update( thread_t * thread );
453
454	/***************************************************************************************
455	* This function returns the extended pointer on a thread descriptor identified
456	* by its thread identifier, and process identifier.
457	* It can be called by any thread running in any cluster.
458	***************************************************************************************
459	* @ pid : process identifier.
460	* @ trdid : thread identifier.
461	* @ return the extended pointer if thread found / return XPTR_NULL if not found.
462	**************************************************************************************/
463	xptr_t thread_get_xptr( pid_t pid,
464	trdid_t trdid );
465
466
467	#endif /* _THREAD_H_ */

Note: See TracBrowser for help on using the repository browser.

Download in other formats: