Context Navigation

source: trunk/kernel/kern/process.h @ 501

Last change on this file since 501 was 485, checked in by viala@…, 6 years ago
[kern] Add void type to function prototypes with no parameter
File size: 36.6 KB

Rev	Line
[1]	1	/*
	2	* process.h - process related management functions
[173]	3	*
[1]	4	* Authors Ghassan Almaless (2008,2009,2010,2011,2012)
	5	* Mohamed Lamine Karaoui (2015)
[433]	6	* Alain Greiner (2016,2017,2018)
[1]	7	*
	8	* Copyright (c) UPMC Sorbonne Universites
	9	*
	10	* This file is part of ALMOS-MKH.
	11	*
	12	* ALMOS-MKH is free software; you can redistribute it and/or modify it
	13	* under the terms of the GNU General Public License as published by
	14	* the Free Software Foundation; version 2.0 of the License.
	15	*
	16	* ALMOS-MKH is distributed in the hope that it will be useful, but
	17	* WITHOUT ANY WARRANTY; without even the implied warranty of
	18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	19	* General Public License for more details.
	20	*
	21	* You should have received a copy of the GNU General Public License
	22	* along with ALMOS-MKH; if not, write to the Free Software Foundation,
	23	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
	24	*/
	25
	26	#ifndef _PROCESS_H_
	27	#define _PROCESS_H_
	28
[14]	29	#include <kernel_config.h>
[1]	30	#include <errno.h>
[457]	31	#include <hal_kernel_types.h>
[1]	32	#include <list.h>
	33	#include <xlist.h>
	34	#include <bits.h>
	35	#include <spinlock.h>
	36	#include <hal_atomic.h>
	37	#include <vmm.h>
	38	#include <cluster.h>
	39	#include <vfs.h>
	40
	41	/** Forward declarations **/
	42
	43	struct thread_s;
	44
	45	/*********************************************************************************************
	46	* These macros are used to compose or decompose global process identifier (PID)
	47	* to or from cluster identifier / local process index (CXY , LPID)
	48	********************************************************************************************/
	49
	50	#define LPID_FROM_PID( pid ) (lpid_t)(pid & 0x0000FFFF)
	51	#define CXY_FROM_PID( pid ) (cxy_t)(pid >> 16)
	52	#define PID( cxy , lpid ) (pid_t)((cxy << 16) \| lpid )
	53
	54	/*********************************************************************************************
[428]	55	* This enum defines the actions that can be executed by the process_sigaction() function.
[409]	56	********************************************************************************************/
	57
	58	enum process_sigactions
	59	{
[436]	60	BLOCK_ALL_THREADS = 0x11,
	61	UNBLOCK_ALL_THREADS = 0x22,
	62	DELETE_ALL_THREADS = 0x33,
[409]	63	};
	64
	65	/*********************************************************************************************
[1]	66	* This structure defines an array of extended pointers on the open file descriptors
	67	* for a given process. We use an extended pointer because the open file descriptor
	68	* is always stored in the same cluster as the inode associated to the file.
	69	* A free entry in this array contains the XPTR_NULL value.
	70	* The array size is defined by a the CONFIG_PROCESS_FILE_MAX_NR parameter.
[23]	71	* All modifications (open/close) in this structure must be done by the reference cluster,
	72	* and reported in process copies.
[1]	73	********************************************************************************************/
	74
	75	typedef struct fd_array_s
	76	{
[101]	77	remote_spinlock_t lock; /! lock protecting fd_array /
	78	uint32_t current; /! current number of open files /
	79	xptr_t array[CONFIG_PROCESS_FILE_MAX_NR]; /! xptr on open file descriptors /
[1]	80	}
	81	fd_array_t;
	82
	83	/*********************************************************************************************
	84	* This structure defines a process descriptor.
	85	* A process is identified by a unique PID (process identifier):
	86	* - The PID 16 LSB bits contain the LPID (Local Process Index)
	87	* - The PID 16 MSB bits contain the owner cluster CXY.
[409]	88	* In each cluster, the process manager allocates the LPID values for the process that
	89	* are owned by this cluster.
	90	* The process descriptor is replicated in all clusters containing at least one thread
	91	* of the PID process, with the following rules :
[443]	92	* 1) The <pid>, <ppid>, <ref_xp>, <owner_xp>, <vfs_root_xp>, <vfs_bin_xp> fields are
	93	* defined in all process descriptor copies.
[23]	94	* 2) The <vfs_cwd_xp> and associated <cwd_lock>, that can be dynamically modified,
	95	* are only defined in the reference process descriptor.
[409]	96	* 2) The <vmm>, containing the VSL (list of registered vsegs), and the GPT (generic
	97	* page table), are only complete in the reference process cluster, other copies
	98	* are actually use as read-only caches.
[23]	99	* 3) the <fd_array>, containing extended pointers on the open file descriptors, is only
	100	* complete in the reference process cluster, other copies are read-only caches.
[173]	101	* 4) The <sem_root>, <mutex_root>, <barrier_root>, <condvar_root>, and the associated
[23]	102	* <sync_lock>, that are dynamically allocated, are only defined in the reference cluster.
[440]	103	* 5) The <children_root>, <children_nr>, <children_list>, and <txt_list> fields are only
[428]	104	* defined in the reference cluster, and are undefined in other clusters.
	105	* 6) The <local_list>, <copies_list>, <th_tbl>, <th_nr>, <th_lock> fields
[23]	106	* are defined in all process descriptors copies.
[433]	107	* 7) The termination <flags> and <exit_status> are only defined in the reference cluster.
[443]	108	* The term_state format is defined in the shared_syscalls.h file.
[1]	109	********************************************************************************************/
	110
	111	typedef struct process_s
	112	{
[23]	113	vmm_t vmm; /! embedded virtual memory manager /
[1]	114
[23]	115	fd_array_t fd_array; /! embedded open file descriptors array /
[1]	116
[173]	117	xptr_t vfs_root_xp; /! extended pointer on current VFS root inode /
[428]	118	xptr_t vfs_bin_xp; /! extended pointer on .elf file descriptor /
[23]	119	pid_t pid; /! process identifier /
	120	xptr_t ref_xp; /! extended pointer on reference process /
[443]	121	xptr_t owner_xp; /! extended pointer on owner process /
[428]	122	xptr_t parent_xp; /! extended pointer on parent process /
[1]	123
[23]	124	xptr_t vfs_cwd_xp; /! extended pointer on current working dir inode /
	125	remote_rwlock_t cwd_lock; /! lock protecting working directory changes /
[173]	126
[23]	127	xlist_entry_t children_root; /! root of the children process xlist /
[428]	128	remote_spinlock_t children_lock; /! lock protecting children process xlist /
[23]	129	uint32_t children_nr; /! number of children processes /
[1]	130
[428]	131	xlist_entry_t children_list; /! member of list of children of same parent /
[23]	132	xlist_entry_t local_list; /! member of list of process in same cluster /
	133	xlist_entry_t copies_list; /! member of list of copies of same process /
[428]	134	xlist_entry_t txt_list; /! member of list of processes sharing same TXT /
[1]	135
[23]	136	spinlock_t th_lock; /! lock protecting th_tbl[] concurrent access /
	137	uint32_t th_nr; /! number of threads in this cluster /
[428]	138
[23]	139	struct thread_s * th_tbl[CONFIG_THREAD_MAX_PER_CLUSTER]; /! pointers on local threads /
[1]	140
[23]	141	xlist_entry_t sem_root; /! root of the process semaphore list /
	142	xlist_entry_t mutex_root; /! root of the process mutex list /
	143	xlist_entry_t barrier_root; /! root of the process barrier list /
	144	xlist_entry_t condvar_root; /! root of the process condvar list /
[428]	145	remote_spinlock_t sync_lock; /! lock protecting sem,mutex,barrier,condvar lists /
[1]	146
[433]	147	uint32_t term_state; /! termination status (flags & exit status) /
[1]	148	}
	149	process_t;
	150
	151	/*********************************************************************************************
[101]	152	* This structure defines the information required by the process_make_exec() function
[409]	153	* to create a new reference process descriptor, and the associated main thread.
[1]	154	********************************************************************************************/
	155
	156	typedef struct exec_info_s
	157	{
[23]	158	char path[CONFIG_VFS_MAX_PATH_LENGTH]; /! .elf file path /
[1]	159
	160	char ** args_pointers; /! physical base address of array of pointers /
	161	char * args_buf_base; /! physical base address of kernel args buffer /
	162	uint32_t args_nr; /! actual number of arguments /
	163
	164	char ** envs_pointers; /! physical base address of array of pointers /
	165	char * envs_buf_base; /! physical base address of kernel args buffer /
	166	char * envs_buf_free; /! physical address of first free slot in envs_buf /
	167	uint32_t envs_nr; /! actual number of environment variables /
	168	}
	169	exec_info_t;
	170
	171	/************* Process Descriptor Operations ***************************************/
	172
[173]	173	/*********************************************************************************************
	174	* This function allocates memory in local cluster for a process descriptor.
	175	*********************************************************************************************
[1]	176	* @ returns pointer on process descriptor if success / return NULL if failure
	177	********************************************************************************************/
	178	process_t * process_alloc();
	179
[173]	180	/*********************************************************************************************
	181	* This function releases memory in local cluster for a process descriptor.
	182	*********************************************************************************************
[1]	183	* @ process : pointer on process descriptor to release.
	184	********************************************************************************************/
	185	void process_free( process_t * process );
	186
[173]	187	/*********************************************************************************************
[428]	188	* This function initialize, in each cluster, the kernel "process_zero", that is the owner
	189	* of all kernel threads in a given cluster. It is called by the kernel_init() function.
	190	* The process_zero descriptor is allocated as a global variable in file kernel_init.c
	191	* Both the PID and PPID fields are set to zero, the ref_xp is the local process_zero,
	192	* and the parent process is set to XPTR_NULL. The th_tbl[] is initialized as empty.
	193	*********************************************************************************************
	194	* @ process : [in] pointer on local process descriptor to initialize.
	195	********************************************************************************************/
	196	void process_zero_create( process_t * process );
	197
	198	/*********************************************************************************************
[173]	199	* This function allocates memory and initializes the "process_init" descriptor and the
[409]	200	* associated "thread_init" descriptor. It is called once at the end of the kernel
[428]	201	* initialisation procedure. Its local process identifier is 1, and parent process
	202	* is the kernel process in cluster 0.
[173]	203	* The "process_init" is the first user process, and all other user processes will be forked
[101]	204	* from this process. The code executed by "process_init" is stored in a .elf file, whose
[409]	205	* pathname is defined by the CONFIG_PROCESS_INIT_PATH configuration variable.
[428]	206	* The process_init does not use the [STDIN/STDOUT/STDERR] streams, but it is linked
	207	* to kernel TXT0, because these streams must be defined for all user processes.
[173]	208	********************************************************************************************/
[485]	209	void process_init_create( void );
[1]	210
[173]	211	/*********************************************************************************************
[428]	212	* This function initializes a local, reference, user process descriptor from another process
[457]	213	* descriptor, defined by the <parent_xp> argument. The <process> and <pid> arguments must
	214	* be previously allocated by the caller. This function can be called by two functions:
	215	* 1) process_init_create() : process is the INIT process; parent is process-zero.
	216	* 2) process_make_fork() : the parent process descriptor is generally remote.
[428]	217	* The following fields are initialised :
	218	* - It set the pid / ppid / ref_xp / parent_xp / state fields.
[409]	219	* - It initializes the VMM (register the kentry, args, envs vsegs in VSL)
[408]	220	* - It initializes the FDT, defining the three pseudo files STDIN / STDOUT / STDERR.
[457]	221	* . if INIT process => link to kernel TXT[0].
	222	* . if KSH[i] process => allocate a free TXT[i] and give TXT ownership.
	223	* . if USER process => same TXT[i] as parent process and give TXT ownership.
[408]	224	* - It set the root_xp, bin_xp, cwd_xp fields.
	225	* - It reset the children list as empty, but does NOT register it in parent children list.
	226	* - It reset the TH_TBL list of threads as empty.
	227	* - It reset the semaphore / mutex / barrier / condvar lists as empty.
	228	* - It registers the process in the local_list, rooted in the local cluster manager.
	229	* - It registers the process in the copies_list, rooted in the owner cluster manager.
	230	* - It registers the process extended pointer in the local pref_tbl[] array.
	231	*********************************************************************************************
	232	* @ process : [in] pointer on local process descriptor to initialize.
	233	* @ pid : [in] process identifier.
[428]	234	* @ parent_xp : [in] extended pointer on parent process descriptor.
[408]	235	********************************************************************************************/
[1]	236	void process_reference_init( process_t * process,
	237	pid_t pid,
[457]	238	xptr_t parent_xp );
[1]	239
[173]	240	/*********************************************************************************************
	241	* This function initializes a copy process descriptor, in the local cluster,
	242	* from information defined in the reference remote process descriptor.
	243	*********************************************************************************************
[1]	244	* @ process : [in] local pointer on process descriptor to initialize.
	245	* @ reference_process_xp : [in] extended pointer on reference process descriptor.
	246	* @ return 0 if success / return ENOMEM if failure
	247	********************************************************************************************/
	248	error_t process_copy_init( process_t * local_process,
	249	xptr_t reference_process_xp );
	250
[173]	251	/*********************************************************************************************
[1]	252	* This function releases all memory allocated for a process descriptor in the local cluster,
[23]	253	* including memory allocated for embedded substructures (fd_array, vmm, etc).
[1]	254	* The local th_tbl[] array must be empty.
[173]	255	*********************************************************************************************
[1]	256	* @ process : pointer on the process descriptor.
	257	********************************************************************************************/
	258	void process_destroy( process_t * process );
	259
[173]	260	/*********************************************************************************************
[428]	261	* This debug function diplays on the kernel terminal TXT0 detailed informations on a
[443]	262	* process descriptor identified by the <process_xp> argument.
[428]	263	* It can be called by a thread running in any cluster.
[443]	264	* WARNING: this function uses the nolock_printk() function, and the TXT0 lock MUST be
	265	* taken by the caller function.
[428]	266	*********************************************************************************************
[443]	267	* @ process_xp : extended pointer on process descriptor.
[428]	268	********************************************************************************************/
	269	void process_display( xptr_t process_xp );
	270
	271	/*********************************************************************************************
	272	* This function returns a printable string defining the sigaction type.
	273	*********************************************************************************************
	274	* @ sigaction_type : BLOCK_ALL_THREADS / UNBLOCK_ALL_THREADS / DELETE_ALL_THREADS
	275	* @ return a string pointer.
	276	********************************************************************************************/
	277	char * process_action_str( uint32_t sigaction_type );
	278
	279	/*********************************************************************************************
[435]	280	* This function allows a client thread running in any cluster to block, unblock or delete
	281	* all threads of a process identified by the <pid> argument, depending on the
[436]	282	* <action_type> argument.
[440]	283	* WARNING : the DELETE and BLOCK actions are NOT executed on the target process main thread
	284	* (thread 0 in process owner cluster), and not executed on the calling thread itself.
[436]	285	* It uses the multicast, non blocking rpc_process_sigaction_client() function to send
[440]	286	* parallel requests to all remote clusters containing process copies.
[436]	287	* Then it blocks and deschedule to wait completion of these parallel requests.
	288	*
[416]	289	* It is used by the sys_kill() & sys_exit() functions to handle the "kill" & "exit" syscalls.
	290	* It is also used by the process_make_exec() function to handle the "exec" syscall.
[436]	291	* It is also called by the TXT device ISR to execute the ctrl C & ctrl Z commands.
	292	*
	293	* Implementation note:
	294	* This function allocates a - shared - RPC descriptor in client thread stack,
	295	* and initializes it. This RPC descriptor can be shared because all parallel,
	296	* non-blocking, RPC server threads use the same input arguments, including the
	297	* RPC responses counter field.
[409]	298	*********************************************************************************************
[435]	299	* @ pid : target process identifier.
[416]	300	* @ action_type : BLOCK_ALL_THREADS / UNBLOCK_ALL_THREADS / DELETE_ALL_THREADS
[1]	301	********************************************************************************************/
[435]	302	void process_sigaction( pid_t pid,
[409]	303	uint32_t action_type );
[1]	304
[173]	305	/*********************************************************************************************
[440]	306	* This function blocks all threads for a given <process> in the local cluster.
	307	* It scan the list of local thread, and sets the THREAD_BLOCKED_GLOBAL bit for all
	308	* threads, BUT the main thread (thread 0 in owner cluster), and the client thread
	309	* identified by the <client_xp> argument. It request the relevant schedulers to acknowledge
	310	* the blocking, using IPI if required, and returns only when all blockable threads
	311	* in cluster are actually blocked.
[416]	312	* The threads are not detached from the scheduler, and not detached from the local process.
[409]	313	*********************************************************************************************
	314	* @ process : pointer on the target process descriptor.
[440]	315	* @ client_xp : extended pointer on the client thread that should not be blocked.
[409]	316	********************************************************************************************/
[440]	317	void process_block_threads( process_t * process,
	318	xptr_t client_xp );
[409]	319
	320	/*********************************************************************************************
[440]	321	* This function marks for deletion all threads for a given <process> in the local cluster.
	322	* It scan the list of local thread, and sets the THREAD_FLAG_REQ_DELETE bit for all
	323	* threads, BUT the main thread (thread 0 in owner cluster), and the client thread
	324	* identified by the <client_xp> argument.
	325	* The actual deletion will be done by the scheduler at the next scheduling point.
[409]	326	*********************************************************************************************
	327	* @ process : pointer on the process descriptor.
[440]	328	* @ client_xp : extended pointer on the client thread that should not be marked.
[409]	329	********************************************************************************************/
[440]	330	void process_delete_threads( process_t * process,
	331	xptr_t client_xp );
[409]	332
	333	/*********************************************************************************************
[440]	334	* This function unblocks all threads of a given user process in a given cluster.
[409]	335	*********************************************************************************************
	336	* @ process : pointer on the process descriptor.
	337	********************************************************************************************/
[440]	338	void process_unblock_threads( process_t * process );
[409]	339
	340	/*********************************************************************************************
[1]	341	* This function returns a pointer on the local copy of a process identified by its PID.
[173]	342	* If this local copy does not exist yet, it is dynamically created, from the reference
[1]	343	* process descriptor, registered in the global copies_list, and registered in the local_list.
[23]	344	* This function is used by the thread_user_create() function.
[173]	345	*********************************************************************************************
[1]	346	* @ pid : searched process identifier.
	347	* @ returns pointer on the local process descriptor if success / returns NULL if failure.
	348	********************************************************************************************/
	349	process_t * process_get_local_copy( pid_t pid );
	350
[173]	351	/*********************************************************************************************
[436]	352	* This function returns the parent process identifier for a remote process descriptor
	353	* identified by an extended pointer.
	354	*********************************************************************************************
	355	* @ process_xp : extended pointer on remote process descriptor.
	356	* @ returns parent process dentifier.
	357	********************************************************************************************/
	358	pid_t process_get_ppid( xptr_t process_xp );
	359
	360	/*********************************************************************************************
[409]	361	* This function implements the "exec" system call, and is called by the sys_exec() function.
[408]	362	* The "new" process keep the "old" process PID and PPID, all open files, and env variables,
	363	* the vfs_root and vfs_cwd, but build a brand new memory image (new VMM from the new .elf).
[409]	364	* It actually creates a "new" reference process descriptor, and copies all relevant
	365	* information from the "old" process descriptor to the "new" process descriptor.
[408]	366	* It completes the "new" process descriptor, from information found in the <exec_info>
	367	* structure (defined in the process.h file), that must be built by the caller.
	368	* It creates and initializes the associated main thread. It finally destroys all copies
[409]	369	* of the "old" process in all clusters, and destroys all old associated threads.
[408]	370	* It is executed in the local cluster, that becomes both the "owner" and the "reference"
	371	* cluster for the "new" process.
[173]	372	*********************************************************************************************
[1]	373	* @ exec_info : [in] pointer on the exec_info structure.
	374	* @ return 0 if success / return non-zero if error.
	375	********************************************************************************************/
	376	error_t process_make_exec( exec_info_t * exec_info );
	377
[408]	378	/*********************************************************************************************
[443]	379	* This function implements the "fork" system call, and is called by the sys_fork() function,
	380	* likely throuch the RPC_PROCESS_MAKE_FORK.
	381	* It allocates memory and initializes a new "child" process descriptor, and the associated
	382	* "child" thread descriptor in local cluster. It involves up to three different clusters :
	383	* - the child (local) cluster can be any cluster selected by the sys_fork function.
[409]	384	* - the parent cluster must be the reference cluster for the parent process.
	385	* - the client cluster containing the thread requesting the fork can be any cluster.
[408]	386	* The new "child" process descriptor is initialised from informations found in the "parent"
	387	* reference process descriptor, containing the complete process description.
	388	* The new "child" thread descriptor is initialised from informations found in the "parent"
	389	* thread descriptor.
	390	*********************************************************************************************
	391	* @ parent_process_xp : extended pointer on the reference parent process.
	392	* @ parent_thread_xp : extended pointer on the parent thread requesting the fork.
	393	* @ child_pid : [out] child process identifier.
	394	* @ child_thread_ptr : [out] local pointer on child thread in target cluster.
	395	* @ return 0 if success / return non-zero if error.
	396	********************************************************************************************/
	397	error_t process_make_fork( xptr_t parent_process_xp,
	398	xptr_t parent_thread_xp,
	399	pid_t * child_pid,
	400	struct thread_s ** child_thread_ptr );
[1]	401
[446]	402
[173]	403	/****************** File Management Operations **************************************/
[1]	404
	405	/*********************************************************************************************
[173]	406	* This function initializes all entries of the local fd_array as empty.
	407	*********************************************************************************************
[1]	408	* @ process : pointer on the local process descriptor.
	409	********************************************************************************************/
	410	void process_fd_init( process_t * process );
	411
	412	/*********************************************************************************************
[23]	413	* This function uses as many remote accesses as required, to reset an entry in fd_array[],
[407]	414	* in all clusters containing a copy. The entry is identified by the <fdid> argument.
[173]	415	* This function must be executed by a thread running reference cluster, that contains
[23]	416	* the complete list of process descriptors copies.
[173]	417	*********************************************************************************************
[1]	418	* @ process : pointer on the local process descriptor.
[407]	419	* @ fdid : file descriptor index in the fd_array.
[1]	420	********************************************************************************************/
[23]	421	void process_fd_remove( process_t * process,
[407]	422	uint32_t fdid );
[1]	423
	424	/*********************************************************************************************
[173]	425	* This function returns an extended pointer on a file descriptor identified by its index
[23]	426	* in fd_array. It can be called by any thread running in any cluster.
[173]	427	* It accesses first the local process descriptor. In case of local miss, it uses remote
	428	* access to access the reference process descriptor.
	429	* It updates the local fd_array when the file descriptor exists in reference cluster.
[23]	430	* The file descriptor refcount is not incremented.
[173]	431	*********************************************************************************************
[1]	432	* @ process : pointer on the local process descriptor.
[407]	433	* @ fdid : file descriptor index in the fd_array.
[23]	434	* @ return extended pointer on file descriptor if success / return XPTR_NULL if not found.
[1]	435	********************************************************************************************/
[23]	436	xptr_t process_fd_get_xptr( process_t * process,
[407]	437	uint32_t fdid );
[1]	438
	439	/*********************************************************************************************
[173]	440	* This function checks the number of open files for a given process.
[23]	441	* It can be called by any thread in any cluster, because it uses portable remote access
	442	* primitives to access the reference process descriptor.
[173]	443	*********************************************************************************************
[23]	444	* @ returns true if file descriptor array full.
[1]	445	********************************************************************************************/
[485]	446	bool_t process_fd_array_full( void );
[1]	447
	448	/*********************************************************************************************
[23]	449	* This function allocates a free slot in the fd_array of the reference process,
	450	* register the <file_xp> argument in the allocated slot, and return the slot index.
	451	* It can be called by any thread in any cluster, because it uses portable remote access
	452	* primitives to access the reference process descriptor.
[173]	453	*********************************************************************************************
[23]	454	* @ file_xp : extended pointer on the file descriptor to be registered.
[407]	455	* @ fdid : [out] buffer for fd_array slot index.
[23]	456	* @ return 0 if success / return EMFILE if array full.
[1]	457	********************************************************************************************/
[407]	458	error_t process_fd_register( process_t * process,
	459	xptr_t file_xp,
	460	uint32_t * fdid );
[1]	461
	462	/*********************************************************************************************
[409]	463	* This function copies all non-zero entries (other than the three first stdin/stdout/stderr)
	464	* from a remote <src_xp> fd_array, embedded in a process descriptor, to another remote
	465	* <dst_xp> fd_array, embedded in another process descriptor.
	466	* The calling thread can be running in any cluster.
[1]	467	* It takes the remote lock protecting the <src_xp> fd_array during the copy.
[173]	468	* For each involved file descriptor, the refcount is incremented.
	469	*********************************************************************************************
[1]	470	* @ dst_xp : extended pointer on the destination fd_array_t.
	471	* @ src_xp : extended pointer on the source fd_array_t.
	472	********************************************************************************************/
	473	void process_fd_remote_copy( xptr_t dst_xp,
	474	xptr_t src_xp );
	475
	476
[23]	477
[173]	478	/****************** Thread Related Operations ***************************************/
[1]	479
	480	/*********************************************************************************************
	481	* This function registers a new thread in the local process descriptor.
	482	* It checks that there is an available slot in the local th_tbl[] array,
	483	* allocates a new LTID, and registers the new thread in the th_tbl[].
[443]	484	* It takes the lock protecting exclusive access to the th_tbl[].
[173]	485	*********************************************************************************************
[1]	486	* @ process : pointer on the local process descriptor.
	487	* @ thread : pointer on new thread to be registered.
	488	* @ trdid : [out] address of buffer for allocated trdid.
	489	* @ returns 0 if success / returns non zero if no slot available.
	490	********************************************************************************************/
	491	error_t process_register_thread( process_t * process,
	492	struct thread_s * thread,
	493	trdid_t * trdid );
	494
	495	/*********************************************************************************************
	496	* This function removes a thread registration from the local process descriptor.
[443]	497	* It takes the lock protecting exclusive access to the th_tbl[].
[173]	498	*********************************************************************************************
[1]	499	* @ thread : local pointer on thread to be removed.
[443]	500	* @ return true if the removed thread was the last registered thread.
[1]	501	********************************************************************************************/
[443]	502	bool_t process_remove_thread( struct thread_s * thread );
[1]	503
	504
[428]	505	/************* Terminals related operations ******************************************/
[1]	506
[428]	507	/*********************************************************************************************
	508	* This function scan the set of user TXT terminals to find a free terminal
	509	* (the list of attached processes is empty for a free TXT terminal).
	510	* It is called only by the process_reference_init() function when creating a KSH process.
	511	* It makes a kernel panic if no free TXT terminal is found.
[457]	512	* The allocated TXT terminal is only released when the KSH process is deleted.
[428]	513	*********************************************************************************************
	514	* @ return TXT terminal index if succes / kernel panic if no terminal found.
	515	********************************************************************************************/
[485]	516	uint32_t process_txt_alloc( void );
[428]	517
	518	/*********************************************************************************************
[450]	519	* This function attach a process, identified by the <process> argument to a TXT terminal,
	520	* identified by the <txt_id> channel index argument.
	521	* The process descriptor identified by the <process> argument must be in the owner cluster.
[428]	522	* It insert the process descriptor in the xlist rooted in the TXT_RX device.
	523	* It is called by the process_reference_init() function.
	524	*********************************************************************************************
	525	* @ process : local pointer on process descriptor.
	526	* @ txt_id : TXT channel index.
	527	********************************************************************************************/
	528	void process_txt_attach( process_t * process,
	529	uint32_t txt_id );
	530
	531	/*********************************************************************************************
[436]	532	* This function detach a process, identified by the <process_xp> argument,
[446]	533	* from the list of process attached to a given TXT terminal. It transfer the TXT ownership
	534	* to another process, if the detached process is the TXT owner.
	535	* The process descriptor identified by the <process_xp> argument must be in the owner
	536	* cluster, but the calling thread can be running in any cluster.
[428]	537	*********************************************************************************************
[436]	538	* @ process_xp : extended pointer on process descriptor.
[428]	539	********************************************************************************************/
[436]	540	void process_txt_detach( xptr_t process_xp );
[428]	541
	542	/*********************************************************************************************
[457]	543	* This function gives the TXT ownership to a process identified by the <process_xp> argument.
	544	* It can be called by a thread running in any cluster, but the <process_xp> must be the
	545	* owner cluster process descriptor.
[428]	546	*********************************************************************************************
[436]	547	* @ owner_xp : extended pointer on process descriptor in owner cluster.
[428]	548	********************************************************************************************/
[457]	549	void process_txt_set_ownership( xptr_t process_xp );
[428]	550
	551	/*********************************************************************************************
[457]	552	* When the process identified by the <owner_xp> argument has the exclusive ownership of
[436]	553	* the TXT_RX terminal, this function transfer this ownership to another attached process.
[443]	554	* The process descriptor must be the process owner.
	555	* This function does nothing if the process identified by the <process_xp> is not
	556	* the TXT owner.
[436]	557	* - If the current owner is not the KSH process, the new owner is the KSH process.
[443]	558	* - If the current owner is the KSH process, the new owner is another attached process.
[436]	559	* - If there is no other attached process, the TXT has no more defined owner.
[428]	560	*********************************************************************************************
[457]	561	* @ process_xp : extended pointer on process descriptor in owner cluster.
[428]	562	********************************************************************************************/
[457]	563	void process_txt_transfer_ownership( xptr_t process_xp );
[428]	564
[435]	565	/*********************************************************************************************
[457]	566	* This function returns true if the process identified by the <process_xp> argument
	567	* is the TXT owner. It can be called by a thread running in any cluster, but the
	568	* process_xp must be the owner cluster process descriptor.
[435]	569	*********************************************************************************************
[457]	570	* @ return a non-zero value if target process is TXT owner.
[435]	571	********************************************************************************************/
[457]	572	uint32_t process_txt_is_owner( xptr_t process_xp );
	573
	574	/*********************************************************************************************
	575	* This function returns an extended ponter on the current TXT owner process,
	576	* for the TXT terminal identified by the <channel> index.
	577	*********************************************************************************************
	578	* @ channel : TXT channel.
	579	* @ return extended pointer on TXT owner process.
	580	********************************************************************************************/
[436]	581	xptr_t process_txt_get_owner( uint32_t channel );
[435]	582
	583	/*********************************************************************************************
	584	* This debug function diplays on the kernel terminal the list of processes attached
	585	* to a given terminal identified by the <txt_id> argument.
	586	*********************************************************************************************
	587	* @ txt_id : TXT terminal channel.
	588	********************************************************************************************/
	589	void process_txt_display( uint32_t txt_id );
	590
	591
[1]	592	#endif /* _PROCESS_H_ */

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

Download in other formats: