Context Navigation

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

Last change on this file since 406 was 406, checked in by alain, 7 years ago
This version executed successfully the user "init" process on a mono-processor TSAR architecture.
File size: 27.9 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 <hal_special.h>
30	#include <xlist.h>
31	#include <list.h>
32	#include <hal_context.h>
33	#include <spinlock.h>
34	#include <core.h>
35	#include <cluster.h>
36	#include <process.h>
37	#include <dev_ioc.h>
38	#include <dev_nic.h>
39	#include <dev_txt.h>
40	#include <dev_mmc.h>
41	#include <dev_dma.h>
42
43	/***************************************************************************************
44	* These macros are used to compose or decompose global thread identifier (TRDID)
45	* to or from cluster identifier / local thread index (CXY , LTID)
46	**************************************************************************************/
47
48	#define LTID_FROM_TRDID( trdid ) (ltid_t)(trdid & 0x0000FFFF)
49	#define CXY_FROM_TRDID( trdid ) (cxy_t)(trdid >> 16)
50	#define TRDID( cxy , ltid ) (trdid_t)((cxy << 16) \| ltid )
51
52	/***************************************************************************************
53	* This defines the various pthread_attr_t attributes bit-vector.
54	**************************************************************************************/
55
56	/***************************************************************************************
57	* This opaque structure contains the user defined attributes for a user thread.
58	* It is passed as input argument to the thread_user_create() function.
59	* It is set by the user application itself, using the pthread_attr_***() functions.
60	* The currently supported attributes are defined below.
61	**************************************************************************************/
62
63	typedef struct pthread_attr_s
64	{
65	uint32_t attributes; /! user defined attributes bit vector /
66	cxy_t cxy; /! target cluster identifier /
67	lid_t lid; /! target core index /
68	}
69	pthread_attr_t;
70
71	typedef enum
72	{
73	PT_ATTR_DETACH = 0x0001, /! user defined not joinable /
74	PT_ATTR_CLUSTER_DEFINED = 0x0002, /! user defined target cluster /
75	PT_ATTR_CORE_DEFINED = 0x0004, /! user defined core index in cluster /
76	}
77	pt_attributes_t;
78
79	/***************************************************************************************
80	* This enum defines the thread types.
81	**************************************************************************************/
82
83	typedef enum
84	{
85	THREAD_USER = 0, /! user thread (pthread) /
86	THREAD_RPC = 1, /! kernel thread executing pending RPCs /
87	THREAD_DEV = 2, /! kernel thread executing I/O device commands /
88	THREAD_KERNEL = 3, /! other kernel thread /
89	THREAD_IDLE = 4, /! kernel idle thread /
90	THREAD_TYPES_NR
91	}
92	thread_type_t;
93
94	/***************************************************************************************
95	* This defines the thread flags bit-vector.
96	**************************************************************************************/
97
98	#define THREAD_FLAG_LOADABLE 0x0001 /! This thread has not been executed yet /
99	#define THREAD_FLAG_DETACHED 0x0002 /! This thread is detached from parent /
100	#define THREAD_FLAG_JOIN 0x0004 /! Parent thread made a join /
101	#define THREAD_FLAG_EXIT 0x0008 /! This thread made an exit /
102	#define THREAD_FLAG_SCHED 0x0010 /! Descheduling required for this thread /
103
104	/***************************************************************************************
105	* This defines the masks associated to the thread signals.
106	**************************************************************************************/
107
108	#define THREAD_SIG_KILL 0x0001 /! This thread must be destroyed ASAP /
109
110	/***************************************************************************************
111	* This defines the masks associated to the blocking causes.
112	**************************************************************************************/
113
114	#define THREAD_BLOCKED_GLOBAL 0x0001 /! thread deactivated / wait activation /
115	#define THREAD_BLOCKED_IO 0x0002 /! thread wait IO operation completion /
116	#define THREAD_BLOCKED_MAPPER 0x0004 /! thread wait mapper /
117	#define THREAD_BLOCKED_JOIN 0x0008 /! thread blocked in join / wait exit /
118	#define THREAD_BLOCKED_EXIT 0x0010 /! thread blocked in exit / wait join i /
119	#define THREAD_BLOCKED_KILL 0x0020 /! thread received kill signal /
120	#define THREAD_BLOCKED_SEM 0x0040 /! thread wait semaphore /
121	#define THREAD_BLOCKED_PAGE 0x0080 /! thread wait page access /
122	#define THREAD_BLOCKED_USERSYNC 0x0100 /! thread wait POSIX (cond/mutex/barrier) /
123
124	#define THREAD_BLOCKED_IDLE 0x1000 /! thread RPC wait activation /
125	#define THREAD_BLOCKED_DEV_QUEUE 0x2000 /! thread DEV wait queue /
126	#define THREAD_BLOCKED_DEV_ISR 0x4000 /! thread DEV wait ISR /
127
128	/***************************************************************************************
129	* This structure defines thread instrumentation informations.
130	**************************************************************************************/
131
132	typedef struct thread_info_s
133	{
134	uint32_t pgfault_nr; /! cumulated number of page fault /
135	uint32_t sched_nr; /! TODO ??? [AG] /
136	uint32_t u_err_nr; /! TODO ??? [AG] /
137	uint32_t m_err_nr; /! TODO ??? [AG] /
138	uint32_t tm_tmp; /! temp date to compute execution duration /
139	uint32_t tm_exec; /! TODO ??? [AG] /
140	uint32_t tm_create; /! date of the creation /
141	uint32_t tm_born; /! date of the thread loading /
142	uint32_t tm_dead; /! date of the death /
143	cycle_t tm_sleep; /! TODO ??? [AG] /
144	cycle_t tm_wait; /! TODO ??? [AG] /
145	cycle_t tm_usr; /! user execution duration /
146	cycle_t tm_sys; /! system execution duration /
147	}
148	thread_info_t;
149
150	/***************************************************************************************
151	* This structure defines a thread descriptor.
152	* It is used for both the user threads and the kernel threads.
153	* In a process, a user thread is identified by a unique TRDID (thread identifier),
154	* that is returned by the kernel to the user:
155	* - The TRDID 16 LSB bits contain the LTID (Local Thread Index).
156	* - The TRDID 16 MSB bits contain the CXY of cluster containing the thread.
157	* - The LTID is used to index the th_tbl[] array in the local process descriptor.
158	* This TRDID is computed by the process_register_thread() function, when the user
159	* thread is registered in the local copy of the process descriptor.
160	*
161	* WARNING : Don't modify the first 4 fields order, as this order is used by the
162	* hal_kentry assembly code for the TSAR architecture.
163	**************************************************************************************/
164
165	#define THREAD_SIGNATURE 0xDEADBEEF
166
167	typedef struct thread_s
168	{
169	void * cpu_context; /! used for context switch /
170	void * fpu_context; /! used for dynamic FPU allocation /
171
172	intptr_t k_stack_base; /! kernel stack base address /
173	uint32_t k_stack_size; /! kernel stack size (bytes) /
174
175	uint32_t trdid; /! thread index (cxy.ltid) /
176	thread_type_t type; /! thread type /
177	uint32_t quantum; /! number of clock ticks given to thread /
178	uint32_t ticks_nr; /! number of ticks used /
179	uint32_t time_last_check; /! last cpu_time_stamp /
180	core_t * core; /! pointer to the owner core /
181	process_t * process; /! pointer on local process descriptor /
182	xptr_t parent; /! extended pointer on parent thread /
183
184	void * exit_value; /! exit_value used in case of join /
185
186	uint32_t local_locks; /! number of local locks owned by thread /
187	list_entry_t locks_root; /! root of local locks list /
188
189	remote_spinlock_t * flags_lock; /! lock protecting the flags /
190
191	uint32_t remote_locks; /! number of local locks owned by thread /
192	xlist_entry_t xlocks_root; /! root of remote locks list /
193
194	intptr_t u_stack_base; /! user stack base address /
195	uint32_t u_stack_size; /! user stack size (bytes) /
196
197	void * entry_func; /! pointer on entry function /
198	void * entry_args; /! pointer on entry function arguments /
199
200	uint32_t flags; /! bit vector of flags /
201	uint32_t blocked; /! bit vector of blocking causes /
202	uint32_t signals; /! bit vector of signals /
203
204	error_t errno; /! errno value set by last system call /
205	uint32_t utls; /! user thread local storage /
206
207	bool_t fork_user; /! user defined placement for next fork() /
208	cxy_t fork_cxy; /! target cluster for next fork() /
209
210	xlist_entry_t children_root; /! root of list of attached children /
211	uint32_t children_nr; /! number of attached children threads /
212	remote_spinlock_t * children_lock; /! lock protecting the children list /
213
214	xlist_entry_t brothers_list; /! member of threads with same parent /
215
216	list_entry_t sched_list; /! member of threads attached to same core /
217
218	uint32_t dev_channel; /! device channel for a DEV thread /
219
220	ioc_command_t ioc_cmd; /! IOC device generic command /
221	txt_command_t txt_cmd; /! TXT device generic command /
222	nic_command_t nic_cmd; /! NIC device generic command /
223	mmc_command_t mmc_cmd; /! MMC device generic command /
224	dma_command_t dma_cmd; /! DMA device generic command /
225
226	cxy_t rpc_client_cxy; /! client cluster index (for a RPC thread) /
227
228	xlist_entry_t wait_list; /! member of threads blocked on same cond /
229
230	thread_info_t info; /! embedded thread_info_t /
231
232	uint32_t signature; /! for kernel stack overflow detection /
233	}
234	thread_t;
235
236	/***************************************************************************************
237	* This macro returns a pointer on the calling thread from the core hardware register.
238	**************************************************************************************/
239
240	#define CURRENT_THREAD (hal_get_current_thread())
241
242	/***************************************************************************************
243	* This function returns a printable string for a thread type.
244	***************************************************************************************
245	* @ type : thread type.
246	* returns pointer on string.
247	**************************************************************************************/
248	char * thread_type_str( uint32_t type );
249
250	/***************************************************************************************
251	* This function allocates memory for a user thread descriptor in the local cluster,
252	* and initializes it from information contained in the arguments.
253	* It is used by the "pthread_create" system call.
254	* The CPU context is initialized from scratch, and the "loadable" field is set.
255	* The new thread is attached to the core specified in the <attr> argument.
256	* It is registered in the local process descriptor specified by the <pid> argument.
257	* The thread descriptor pointer is returned to allow the parent thread to register it
258	* in its children list.
259	* The THREAD_BLOCKED_GLOBAL bit is set => the thread must be activated to start.
260	***************************************************************************************
261	* @ pid : process identifier.
262	* @ start_func : pointer on entry function.
263	* @ start_args : pointer on function argument (can be NULL).
264	* @ attr : pointer on pthread attributes descriptor.
265	* @ new_thread : [out] address of buffer for new thread descriptor pointer.
266	* @ returns 0 if success / returns ENOMEM if error.
267	**************************************************************************************/
268	error_t thread_user_create( pid_t pid,
269	void * start_func,
270	void * start_arg,
271	pthread_attr_t * attr,
272	thread_t ** new_thread );
273
274	/***************************************************************************************
275	* This function allocates memory for an user thread descriptor in the local cluster,
276	* and initializes it from information contained in the calling thread descriptor.
277	* It is used by the fork() system call to create the child process main thread.
278	* The new thread is attached to the core with the lowest load.
279	* It is registered in the process descriptor defined by the "process" argument.
280	* This new thread inherits its execution context from the calling thread,
281	* and the "loadable" field is NOT set.
282	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
283	***************************************************************************************
284	* @ process : local pointer on owner process descriptor.
285	* @ new_thread : [out] address of buffer for new thread descriptor pointer.
286	* @ returns 0 if success / returns ENOMEM if error.
287	**************************************************************************************/
288	error_t thread_user_fork( process_t * process,
289	thread_t ** new_thread );
290
291	/***************************************************************************************
292	* This function allocates memory for a kernel thread descriptor in the local cluster,
293	* and initializes it from arguments values, calling the thread_kernel_init() function,
294	* that also allocates and initializes the CPU context.
295	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
296	***************************************************************************************
297	* @ new_thread : address of buffer for new thread pointer.
298	* @ type : kernel thread type.
299	* @ func : pointer on function.
300	* @ args : function arguments.
301	* @ core_lid : local core index.
302	* @ returns 0 if success / returns ENOMEM if error
303	**************************************************************************************/
304	error_t thread_kernel_create( thread_t ** new_thread,
305	thread_type_t type,
306	void * func,
307	void * args,
308	lid_t core_lid );
309
310	/***************************************************************************************
311	* This function initializes an existing kernel thread descriptor from arguments values.
312	* The THREAD_BLOCKED_GLOBAL bit is set, and the thread must be activated to start.
313	***************************************************************************************
314	* @ thread : pointer on existing thread descriptor.
315	* @ type : kernel thread type.
316	* @ func : pointer on function.
317	* @ args : function arguments.
318	* @ core_lid : local core index.
319	* @ returns 0 if success / returns EINVAL if error
320	**************************************************************************************/
321	error_t thread_kernel_init( thread_t * thread,
322	thread_type_t type,
323	void * func,
324	void * args,
325	lid_t core_lid );
326
327	/***************************************************************************************
328	* This function releases the physical memory allocated for a thread descriptor
329	* in the local cluster. It can be used for both an user and a kernel thread.
330	* The physical memory dynamically allocated in the HEAP or MMAP zones by an user
331	* thread will be released when the process is killed, and the page table flushed.
332	***************************************************************************************
333	* @ thread : pointer on the thread descriptor to release.
334	**************************************************************************************/
335	void thread_destroy( thread_t * thread );
336
337	/***************************************************************************************
338	* This function defines the code of the thread executed by all cores after kernel_init,
339	* or when no other thread is runnable for a given core.
340	*
341	* TODO: In the TSAR architecture, it enters an infinite loop, in wich it forces
342	* the core in sleep (low-power) mode. Any IRQ will force the core to exit this sleep
343	* mode, but no ISR is executed.
344	* TODO: We must analyse if we have the same behaviour for I86 architectures...
345	**************************************************************************************/
346	void thread_idle_func();
347
348	/***************************************************************************************
349	* This function registers a child thread in the global list of attached
350	* children threads of a parent thread.
351	* It does NOT take a lock, as this function is always called by the parent thread.
352	***************************************************************************************
353	* @ xp_parent : extended pointer on the parent thread descriptor.
354	* @ xp_child : extended pointer on the child thread descriptor.
355	**************************************************************************************/
356	void thread_child_parent_link( xptr_t xp_parent,
357	xptr_t xp_child );
358
359	/***************************************************************************************
360	* This function removes an user thread from the parent thread global list
361	* of attached children threads.
362	***************************************************************************************
363	* @ xp_parent : extended pointer on the parent thread descriptor.
364	* @ xp_child : extended pointer on the child thread descriptor.
365	**************************************************************************************/
366	void thread_child_parent_unlink( xptr_t xp_parent,
367	xptr_t xp_child );
368
369	/***************************************************************************************
370	* This function atomically sets a signal in a thread descriptor.
371	***************************************************************************************
372	* @ thread : local pointer on target thread.
373	*s released all locks @ mask : mask on selected signal.
374	**************************************************************************************/
375	inline void thread_set_signal( thread_t * thread,
376	uint32_t mask );
377
378	/***************************************************************************************
379	* This function resets a signal in a thread descriptor.
380	***************************************************************************************
381	* @ thread : local pointer on target thread.
382	* @ mask : mask on selected signal.
383	**************************************************************************************/
384	inline void thread_reset_signal( thread_t * thread,
385	uint32_t mask );
386
387	/***************************************************************************************
388	* This function returns true if the calling thread is attached to its parent thread.
389	**************************************************************************************/
390	inline bool_t thread_is_joinable();
391
392	/***************************************************************************************
393	* This function returns true if the calling thread is not blocked.
394	**************************************************************************************/
395	inline bool_t thread_is_runnable();
396
397	/***************************************************************************************
398	* This function checks if the calling thread can deschedule.
399	***************************************************************************************
400	* @ returns true if no locks taken.
401	**************************************************************************************/
402	inline bool_t thread_can_yield();
403
404	/***************************************************************************************
405	* This function implements the delayed descheduling machanism : It is called by
406	* all lock release functions, and calls the sched_yield() function when all locks
407	* have beeen released and the THREAD_FLAG_SCHED flag is set.
408	**************************************************************************************/
409	void thread_check_sched();
410
411	/***************************************************************************************
412	* This function can be used by the calling thread to suicide.
413	* All locks must be previously released.
414	* The scenario depends on the attached/detached flag :
415	* - if detached, it sets the SIG_KILL signal in the "signals" bit_vector, registers
416	* the BLOCKED_EXIT bit in the "blocked" bit_vector, and deschedule.
417	* - if attached, it simply sets the BLOCKED_EXIT bit in the "blocked" bit vector
418	* and deschedule. The SIG_KILL signal will be set by the parent thread when
419	* executing the pthread_join().
420	***************************************************************************************
421	* @ returns 0 if success / returns EINVAL if locks_count is not zero.
422	**************************************************************************************/
423	error_t thread_exit();
424
425	/***************************************************************************************
426	* This function registers a blocking cause in the target thread "blocked" bit vector.
427	* Warning : this function does not deschedule the calling thread.
428	* The descheduling can be forced by a sched_yield().
429	***************************************************************************************
430	* @ thread : local pointer on target thread.
431	* @ cause : mask defining the cause (one hot).
432	**************************************************************************************/
433	void thread_block( thread_t * thread,
434	uint32_t cause );
435
436	/***************************************************************************************
437	* This function resets the bit identified by the cause argument in the "blocked"
438	* bit vector of a remote thread descriptor.
439	* We need an extended pointer, because the client thread of an I/O operation on a
440	* given device is not in the same cluster as the associated device descriptor.
441	* Warning : this function does not reschedule the remote thread.
442	* The scheduling can be forced by sending an IPI to the core running the remote thread.
443	***************************************************************************************
444	* @ thread : extended pointer on the remote thread.
445	* @ cause : mask defining the cause (one hot).
446	**************************************************************************************/
447	void thread_unblock( xptr_t thread,
448	uint32_t cause );
449
450	/***************************************************************************************
451	* This function kills a target thread, identified by its local pointer.
452	* It is generally called by the local process_destroy() function.
453	* - it forces the global blocked bit in target thread descriptor.
454	* - it set the SIG_KILL signal in target thread.
455	* - it send an IPI_SCHED_REQUEST to the target thread core.
456	***************************************************************************************
457	* @ thread : local pointer on the target thread.
458	* @ returns 0 if success / returns EINVAL if locks_count is not zero.
459	**************************************************************************************/
460	void thread_kill( thread_t * thread );
461
462	/***************************************************************************************
463	* This function updates the calling thread user_time counter, and resets the thread
464	* cycles counter.
465	* TODO This function is not implemented.
466	***************************************************************************************
467	* @ thread : local pointer on target thread.
468	**************************************************************************************/
469	void thread_user_time_update( thread_t * thread );
470
471	/**************************************************************************************n
472	* This function updates the calling thread kernel_time counter, and resets the thread
473	* cycles counter.
474	* TODO This function is not implemented.
475	***************************************************************************************
476	* @ thread : local pointer on target thread.
477	**************************************************************************************/
478	void thread_kernel_time_update( thread_t * thread );
479
480	/***************************************************************************************
481	* This function handles all pending signals for the thread identified by the <thread>
482	* argument. It is called each time the core exits the kernel, after handling an
483	* interrupt, exception or syscall.
484	* TODO This function is not implemented.
485	***************************************************************************************
486	* @ thread : local pointer on target thread.
487	**************************************************************************************/
488	void thread_signals_handle( thread_t * thread );
489
490	/***************************************************************************************
491	* This function returns the extended pointer on a thread descriptor identified
492	* by its thread identifier, and process identifier.
493	* It can be called by any thread running in any cluster.
494	***************************************************************************************
495	* @ pid : process identifier.
496	* @ trdid : thread identifier.
497	* @ return the extended pointer if thread found / return XPTR_NULL if not found.
498	**************************************************************************************/
499	xptr_t thread_get_xptr( pid_t pid,
500	trdid_t trdid );
501
502
503	#endif /* _THREAD_H_ */

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

Download in other formats: