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

Last change on this file since 662 was 662, checked in by alain, 4 years ago

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