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

Last change on this file since 627 was 625, checked in by alain, 6 years ago

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