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

Last change on this file since 564 was 564, checked in by alain, 5 years ago

Complete restructuration of kernel locks.

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