Context Navigation

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

Last change on this file since 447 was 446, checked in by alain, 7 years ago
miscelaneous...
File size: 25.7 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_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	* that is returned by the kernel to the user:
122	* - The TRDID 16 LSB bits contain the LTID (Local Thread Index).
123	* - The TRDID 16 MSB bits contain the CXY of cluster containing the thread.
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	*
128	* WARNING : Don't modify the first 4 fields order, as this order is used by the
129	* hal_kentry assembly code for the TSAR architecture.
130	**************************************************************************************/
131
132	#define THREAD_SIGNATURE 0xDEADBEEF
133
134	typedef struct thread_s
135	{
136	void * cpu_context; /! pointer on CPU context switch /
137	void * fpu_context; /! pointer on FPU context switch /
138	void * uzone_current; /! used by hal_do_syscall & hal_do_except /
139	void * uzone_previous; /! used by hal_do_syscall & hal_do_except /
140
141	intptr_t k_stack_base; /! kernel stack base address /
142	uint32_t k_stack_size; /! kernel stack size (bytes) /
143
144	uint32_t trdid; /! thread index (cxy.ltid) /
145	thread_type_t type; /! thread type /
146	uint32_t quantum; /! number of clock ticks given to thread /
147	uint32_t ticks_nr; /! number of ticks used /
148	uint32_t time_last_check; /! last cpu_time_stamp /
149	core_t * core; /! pointer to the owner core /
150	process_t * process; /! pointer on local process descriptor /
151	xptr_t parent; /! extended pointer on parent thread /
152
153	remote_spinlock_t join_lock; /! lock protecting the join/exit /
154	xptr_t join_xp; /! joining/killer thread extended pointer /
155
156	uint32_t * ack_rsp_count; /! pointer on acknowledge response counter /
157
158	intptr_t u_stack_base; /! user stack base address /
159	uint32_t u_stack_size; /! user stack size (bytes) /
160
161	void * entry_func; /! pointer on entry function /
162	void * entry_args; /! pointer on entry function arguments /
163
164	uint32_t flags; /! bit vector of flags /
165	uint32_t blocked; /! bit vector of blocking causes /
166
167	error_t errno; /! errno value set by last system call /
168	uint32_t utls; /! user thread local storage /
169
170	bool_t fork_user; /! user defined placement for next fork() /
171	cxy_t fork_cxy; /! target cluster for next fork() /
172
173	list_entry_t sched_list; /! member of threads attached to same core /
174
175	chdev_t * chdev; /! chdev pointer (for a DEV thread only) /
176
177	reg_t save_sr; /! used by sched_yield() function /
178
179	ioc_command_t ioc_cmd; /! IOC device generic command /
180	txt_command_t txt_cmd; /! TXT device generic command /
181	nic_command_t nic_cmd; /! NIC device generic command /
182	mmc_command_t mmc_cmd; /! MMC device generic command /
183	dma_command_t dma_cmd; /! DMA device generic command /
184
185	cxy_t rpc_client_cxy; /! client cluster index (for a RPC thread) /
186
187	xlist_entry_t wait_list; /! member of threads blocked on same cond /
188
189	list_entry_t locks_root; /! root of list of locks taken /
190	xlist_entry_t xlocks_root; /! root of xlist of remote locks taken /
191	uint32_t local_locks; /! number of local locks owned by thread /
192	uint32_t remote_locks; /! number of remote locks owned by thread /
193
194	thread_info_t info; /! embedded thread_info_t /
195
196	uint32_t signature; /! for kernel stack overflow detection /
197	}
198	thread_t;
199
200	/***************************************************************************************
201	* This macro returns a pointer on the calling thread from the core hardware register.
202	**************************************************************************************/
203
204	#define CURRENT_THREAD (hal_get_current_thread())
205
206	/***************************************************************************************
207	* This function returns a printable string for a thread type.
208	***************************************************************************************
209	* @ type : thread type.
210	* returns pointer on string.
211	**************************************************************************************/
212	char * thread_type_str( uint32_t type );
213
214	/***************************************************************************************
215	* This function is used by the pthread_create() system call to create a "new" thread
216	* in an existing process. It allocates memory for an user thread descriptor in the
217	* local cluster, and initializes it from information contained in the arguments.
218	* The CPU context is initialized from scratch.
219	* It is registered in the local process descriptor specified by the <pid> argument.
220	* The THREAD_BLOCKED_GLOBAL bit is set => the thread must be activated to start.
221	***************************************************************************************
222	* @ pid : process identifier.
223	* @ start_func : pointer on entry function.
224	* @ start_args : pointer on function argument (can be NULL).
225	* @ attr : pointer on pthread attributes descriptor.
226	* @ new_thread : [out] address of buffer for new thread descriptor pointer.
227	* @ returns 0 if success / returns ENOMEM if error.
228	**************************************************************************************/
229	error_t thread_user_create( pid_t pid,
230	void * start_func,
231	void * start_arg,
232	pthread_attr_t * attr,
233	thread_t ** new_thread );
234
235	/***************************************************************************************
236	* This function is used by the sys_fork() system call to create the "child" thread
237	* in the local cluster. It allocates memory for a thread descriptor, and initializes
238	* it from the "parent" thread descriptor defined by the <parent_thread_xp> argument.
239	* The new thread is attached to the core that has the lowest load in local cluster.
240	* It is registered in the "child" process defined by the <child_process> argument.
241	* This new thread inherits its user stack from the parent thread, as it uses the
242	* Copy-On-Write mechanism to get a private stack when required.
243	* The content of the parent kernel stack is copied into the child kernel stack, as
244	* the Copy-On-Write mechanism cannot be used for kernel segments (because kernel
245	* uses physical addressing on some architectures).
246	* The CPU and FPU execution contexts are created and linked to the new thread.
247	* but the actual context copy is NOT done, and must be done by by the sys_fork().
248	* The THREAD_BLOCKED_GLOBAL bit is set => the thread must be activated to start.
249	***************************************************************************************
250	* @ parent_thread_xp : extended pointer on parent thread descriptor.
251	* @ child_process : local pointer on child process descriptor.
252	* @ child_thread : [out] address of buffer for child thread descriptor pointer.
253	* @ returns 0 if success / returns -1 if error.
254	**************************************************************************************/
255	error_t thread_user_fork( xptr_t parent_thread_xp,
256	process_t * child_process,
257	thread_t ** child_thread );
258
259	/***************************************************************************************
260	* This function allocates memory for a kernel thread descriptor in the local cluster,
261	* and initializes it from arguments values.
262	* It is called by kernel_init() to statically create all DEV server threads
263	* It is also called to dynamically create RPC threads when required.
264	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
265	***************************************************************************************
266	* @ new_thread : address of buffer for new thread pointer.
267	* @ type : kernel thread type.
268	* @ func : pointer on function.
269	* @ args : function arguments.
270	* @ core_lid : local core index.
271	* @ returns 0 if success / returns ENOMEM if error
272	**************************************************************************************/
273	error_t thread_kernel_create( thread_t ** new_thread,
274	thread_type_t type,
275	void * func,
276	void * args,
277	lid_t core_lid );
278
279	/***************************************************************************************
280	* This function is called by the kernel_init() function to initialize the IDLE thread
281	* descriptor from arguments values.
282	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
283	***************************************************************************************
284	* @ thread : pointer on existing thread descriptor.
285	* @ type : kernel thread type.
286	* @ func : pointer on function.
287	* @ args : function arguments.
288	* @ core_lid : local core index.
289	* @ returns 0 if success / returns EINVAL if error
290	**************************************************************************************/
291	error_t thread_idle_init( thread_t * thread,
292	thread_type_t type,
293	void * func,
294	void * args,
295	lid_t core_lid );
296
297	/***************************************************************************************
298	* This function is called by the sched_handle_signals() function to releases
299	* the physical memory allocated for a thread in a given cluster, when this thread
300	* is marked for delete. This include the thread descriptor itself, the associated
301	* CPU and FPU context, and the physical memory allocated for an user thread local stack.
302	* The destroyed thread is removed from the local process th_tbl[] array, and returns
303	* true when the destroyed thread was the last thread registered in process.
304	***************************************************************************************
305	* @ thread : pointer on the thread descriptor to release.
306	* @ return true, if the thread was the last registerd thread in local process.
307	**************************************************************************************/
308	bool_t thread_destroy( thread_t * thread );
309
310	/***************************************************************************************
311	* This function defines the code of the thread executed by all cores after kernel_init,
312	* or when no other thread is runnable for a given core.
313	* It enter and infinite loop in wich:
314	* - it unmask the IRQs
315	* - it optionally calls the hal_core_sleep() function to reduce the power consumption
316	* (this behavior is controlled by the CONFIG_THREAD_IDLE_MODE_SLEEP flag).
317	* - it call the sched_yield() function to find another runnable thread.
318	*
319	* TODO: In the TSAR architecture the hal_core_sleep() function forces the core to
320	* low-power mode. Any IRQ will force the core to exit this low-power mode, but no ISR
321	* is executed. We must analyse if we have the same behaviour for I86 architectures...
322	**************************************************************************************/
323	void thread_idle_func();
324
325	/***************************************************************************************
326	* This function is used by a "blocker" thread running in the same cluster as a "target"
327	* thread to request the scheduler of the target thread to acknowledge that the target
328	* thread is blocked and not running, at the next context switch.
329	* This function executes atomically the following actions :
330	* - it set the request_pending boolean in the target scheduler descriptor.
331	* - it set the REQ_ACK flag in the "flags" field of the target thread descriptor.
332	* - It registers the responses counter pointer in the target thread descriptor.
333	* The request_pending flag is handled as a set/reset flip-flop by the "blocker" thread
334	* and by the "target" scheduler.
335	***************************************************************************************
336	* @ target : local pointer on target thread.
337	* @ ack_rsp_count : local pointer on responses counter.
338	**************************************************************************************/
339	void thread_set_req_ack( thread_t * target,
340	uint32_t * ack_rsp_count );
341
342	/***************************************************************************************
343	* This function is used by the sched_handle_signal() function executed by the
344	* scheduler of a "target" thread to reset a "blocked not running" acknowledge request
345	* in both the target thread descriptor, and in the target thread scheduler.
346	***************************************************************************************
347	* @ target : local pointer on target thread.
348	**************************************************************************************/
349	void thread_reset_req_ack( thread_t * target );
350
351	/***************************************************************************************
352	* This function checks if the calling thread can deschedule.
353	***************************************************************************************
354	* @ returns true if no locks taken.
355	**************************************************************************************/
356	inline bool_t thread_can_yield();
357
358	/***************************************************************************************
359	* This function implements the delayed descheduling mechanism : It is called by
360	* all lock release functions, and calls the sched_yield() function when all locks
361	* have beeen released and the calling thread THREAD_FLAG_SCHED flag is set.
362	**************************************************************************************/
363	void thread_check_sched();
364
365	/***************************************************************************************
366	* This function is used by the four sys_thread_cancel(), sys_thread_exit(),
367	* sys_kill() and sys_exit() system calls to mark for delete a given thread.
368	* It set the THREAD_BLOCKED_GLOBAL bit and set the the THREAD_FLAG_REQ_DELETE bit
369	* in the thread descriptor identified by the <thread_xp> argument, to ask the scheduler
370	* to asynchronously delete the target thread, at the next scheduling point.
371	* The calling thread can run in any cluster, as it uses remote accesses, but
372	* the target thread cannot be the main thread of the process identified by the <pid>,
373	* because the main thread must be deleted by the parent process argument.
374	* If the target thread is running in "attached" mode, and the <is_forced> argument
375	* is false, this function implements the required sychronisation with the joining
376	* thread, blocking the calling thread until the pthread_join() syscall is executed.
377	***************************************************************************************
378	* @ thread_xp : extended pointer on the target thread.
379	* @ pid : process identifier (to get the owner cluster identifier).
380	* @ is_forced : the deletion does not depends on the attached mode.
381	**************************************************************************************/
382	void thread_delete( xptr_t thread_xp,
383	pid_t pid,
384	bool_t is_forced );
385
386	/***************************************************************************************
387	* This function registers a blocking cause defined by the <cause> argument
388	* in a remote thread descriptor identified by the <thread_xp> argument.
389	* We need an extended pointer, because this function can be called by another thread
390	* than the target thread, executing the sys_kill() function.
391	* WARNING : this function does not deschedule the target thread, and the descheduling
392	* must be explicitely forced by a sched_yield().
393	***************************************************************************************
394	* @ thread_xp : extended pointer on remote thread descriptor.
395	* @ cause : mask defining the cause (one hot).
396	**************************************************************************************/
397	void thread_block( xptr_t thread_xp,
398	uint32_t cause );
399
400	/***************************************************************************************
401	* This function resets the bit identified by the <cause> argument in a remote
402	* thread descriptor identified by the <thread_xp> argument.
403	* We need an extended pointer, because the client thread of an I/O operation on a
404	* given device is not in the same cluster as the associated device descriptor.
405	* WARNING : this function does not reschedule the remote thread.
406	* The scheduling can be forced by sending an IPI to the core running the remote thread.
407	***************************************************************************************
408	* @ thread_xp : extended pointer the remote thread.
409	* @ cause : mask defining the cause (one hot).
410	* @ return non zero if the bit-vector was actually modified / return 0 otherwise
411	**************************************************************************************/
412	uint32_t thread_unblock( xptr_t thread_xp,
413	uint32_t cause );
414
415	/***************************************************************************************
416	* This function updates the calling thread user_time counter, and resets the thread
417	* cycles counter.
418	* TODO This function is not implemented.
419	***************************************************************************************
420	* @ thread : local pointer on target thread.
421	**************************************************************************************/
422	void thread_user_time_update( thread_t * thread );
423
424	/**************************************************************************************n
425	* This function updates the calling thread kernel_time counter, and resets the thread
426	* cycles counter.
427	* TODO This function is not implemented.
428	***************************************************************************************
429	* @ thread : local pointer on target thread.
430	**************************************************************************************/
431	void thread_kernel_time_update( thread_t * thread );
432
433	/***************************************************************************************
434	* This function returns the extended pointer on a thread descriptor identified
435	* by its thread identifier, and process identifier.
436	* It can be called by any thread running in any cluster.
437	***************************************************************************************
438	* @ pid : process identifier.
439	* @ trdid : thread identifier.
440	* @ return the extended pointer if thread found / return XPTR_NULL if not found.
441	**************************************************************************************/
442	xptr_t thread_get_xptr( pid_t pid,
443	trdid_t trdid );
444
445
446	#endif /* _THREAD_H_ */

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

Download in other formats: