Context Navigation

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

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

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

Download in other formats: