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

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

Introduce three new types of vsegs (KCODE,KDATA,KDEV)
to map the kernel vsegs in the process VSL and GPT.
This now used by both the TSAR and the I86 architectures.
File size: 37.3 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; 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 initializes the VMM (register the kentry, args, envs vsegs in VSL)
238 * - It initializes the FDT, defining the three pseudo files STDIN / STDOUT / STDERR.
239 *   . if INIT process     => link to kernel TXT[0].
240 *   . if KSH[i] process   => allocate a free TXT[i] and give TXT ownership.
241 *   . if USER process     => same TXT[i] as parent process and give TXT ownership.
242 * - It set the root_xp, bin_xp, cwd_xp fields.
243 * - It reset the children list as empty, but does NOT register it in parent children list.
244 * - It reset the TH_TBL list of threads as empty.
245 * - It reset the semaphore / mutex / barrier / condvar lists as empty.
246 * - It registers the process in the local_list, rooted in the local cluster manager.
247 * - It registers the process in the copies_list, rooted in the owner cluster manager.
248 * - It registers the process extended pointer in the local pref_tbl[] array.
249 *********************************************************************************************
250 * @ process      : [in] pointer on local process descriptor to initialize.
251 * @ pid          : [in] process identifier.
252 * @ parent_xp    : [in] extended pointer on parent process descriptor.
253 ********************************************************************************************/
254void process_reference_init( process_t * process,
255                             pid_t       pid,
256                             xptr_t      parent_xp );
257
258/*********************************************************************************************
259 * This function initializes a copy process descriptor, in the local cluster,
260 * from information defined in the reference remote process descriptor.
261 *********************************************************************************************
262 * @ process              : [in] local pointer on process descriptor to initialize.
263 * @ reference_process_xp : [in] extended pointer on reference process descriptor.
264 * @ return 0 if success / return ENOMEM if failure
265 ********************************************************************************************/
266error_t process_copy_init( process_t * local_process,
267                           xptr_t      reference_process_xp );
268
269/*********************************************************************************************
270 * This function releases all memory allocated for a process descriptor in the local cluster,
271 * including memory allocated for embedded substructures (fd_array, vmm, etc).
272 * The local th_tbl[] array must be empty.
273 *********************************************************************************************
274 * @ process     : pointer on the process descriptor.
275 ********************************************************************************************/
276void process_destroy( process_t * process );
277
278/*********************************************************************************************
279 * This debug function diplays on the kernel terminal TXT0 detailed informations on a
280 * process descriptor identified by the <process_xp> argument.
281 * It can be called by a thread running in any cluster.
282 * WARNING: this function uses the nolock_printk() function, and the  TXT0 lock MUST be
283 * taken by the caller function.
284 *********************************************************************************************
285 * @ process_xp : extended pointer on process descriptor.
286 ********************************************************************************************/
287void process_display( xptr_t process_xp );
288
289/*********************************************************************************************
290 * This function returns a printable string defining the sigaction type.
291 *********************************************************************************************
292 * @ sigaction_type   : BLOCK_ALL_THREADS / UNBLOCK_ALL_THREADS / DELETE_ALL_THREADS
293 * @ return a string pointer.
294 ********************************************************************************************/
295const char * process_action_str( process_sigactions_t sigaction_type );
296
297/*********************************************************************************************
298 * This function allows a client thread running in any cluster to block, unblock or delete
299 * all threads of a process identified by the <pid> argument, depending on the
300 * <action_type> argument.
301 *
302 * It uses the multicast, non blocking rpc_process_sigaction_client() function to send
303 * parallel requests to all remote clusters containing process copies.
304 * Then it blocks and deschedule to wait completion of these parallel requests.
305 *
306 * It is used by the sys_kill() & sys_exit() functions to handle the "kill" & "exit" syscalls.
307 * It is also used by the process_make_exec() function to handle the "exec" syscall.
308 * It is also called by the TXT device ISR to execute the ctrl C & ctrl Z commands.
309 *
310 * WARNING (1) the DELETE action is NOT executed on the target process main thread
311 * (thread 0 in process owner cluster), and not executed on the client thread itself.
312 *
313 * WARNING (2) the BLOCK action is executed on all target process threads, and this function
314 * returns only when all threads BUT the client thread are actually blocked and not running.
315 * When the client thread is also a target thread, it is blocked but not descheduled.
316 *
317 * WARNING (3) the UNBLOCK action is executed on all target process threads, as the
318 * client thread cannot be a target thread.
319 *
320 * Implementation note:
321 * This function allocates a - shared - RPC descriptor in client thread stack,
322 * and initializes it. This RPC descriptor can be shared because all parallel,
323 * non-blocking, RPC server threads use the same input arguments, including the
324 * RPC responses counter field.
325 *********************************************************************************************
326 * @ pid         : target process identifier.
327 * @ action_type : BLOCK_ALL_THREADS / UNBLOCK_ALL_THREADS / DELETE_ALL_THREADS
328 ********************************************************************************************/
329void process_sigaction( pid_t       pid,
330                        uint32_t    action_type );
331
332/*********************************************************************************************
333 * This function marks for delete all threads for a given <process> in the local cluster.
334 * It scan the list of local thread, and sets the THREAD_FLAG_REQ_DELETE bit for all
335 * threads, BUT the main thread (thread 0 in owner cluster), and the client thread
336 * identified by the <client_xp> argument.
337 * The actual delete will be done by the scheduler at the next scheduling point.
338 *********************************************************************************************
339 * @ process     : pointer on the process descriptor.
340 * @ client_xp   : extended pointer on the client thread that should not be marked.
341 ********************************************************************************************/
342void process_delete_threads( process_t * process,
343                             xptr_t      client_xp );
344
345/*********************************************************************************************
346 * This function blocks all threads for a given <process> in the local cluster.
347 * It scan the list of local thread, and sets the THREAD_BLOCKED_GLOBAL bit for all threads.
348 * It request the relevant schedulers to acknowledge the blocking, using IPI if required,
349 * when the target thread is running on another core than the calling thread.
350 * It returns only when all threads in cluster, including the caller are actually blocked.
351 * The threads are not detached from the scheduler, and not detached from the local process.
352 *********************************************************************************************
353 * @ process     : pointer on the target process descriptor.
354 ********************************************************************************************/
355void process_block_threads( process_t * process );
356
357/*********************************************************************************************
358 * This function unblocks all threads of a given user process in a given cluster.
359 *********************************************************************************************
360 * @ process     : pointer on the process descriptor.
361 ********************************************************************************************/
362void process_unblock_threads( process_t * process );
363
364/*********************************************************************************************
365 * This function returns a pointer on the local copy of a process identified by its PID.
366 * If this local copy does not exist yet, it is dynamically created, from the reference
367 * process descriptor, registered in the global copies_list, and registered in the local_list.
368 * This function is used by the thread_user_create() function.
369 *********************************************************************************************
370 * @ pid     : searched process identifier.
371 * @ returns pointer on the local process descriptor if success / returns NULL if failure.
372 ********************************************************************************************/
373process_t * process_get_local_copy( pid_t pid );
374
375/*********************************************************************************************
376 * This function returns the parent process identifier for a remote process descriptor
377 * identified by an extended pointer.
378 *********************************************************************************************
379 * @ process_xp   : extended pointer on remote process descriptor.
380 * @ returns parent process dentifier.
381 ********************************************************************************************/
382pid_t process_get_ppid( xptr_t process_xp );
383
384/*********************************************************************************************
385 * This function implements the "exec" system call, and is called by the sys_exec() function.
386 * The "new" process keep the "old" process PID and PPID, all open files, and env variables,
387 * the vfs_root and vfs_cwd, but build a brand new memory image (new VMM from the new .elf).
388 * It is executed in the local cluster, that becomes both the "owner" and the "reference"
389 * cluster for the "new" process.
390 *********************************************************************************************
391 * @ exec_info   : [in]  pointer on the exec_info structure.
392 * @ return 0 if success / return non-zero if error.
393 ********************************************************************************************/
394error_t process_make_exec( exec_info_t * exec_info );
395
396/*********************************************************************************************
397 * This function implements the "fork" system call, and is called by the sys_fork() function,
398 * likely throuch the RPC_PROCESS_MAKE_FORK.
399 * It allocates memory and initializes a new "child" process descriptor, and the associated
400 * "child" thread descriptor in local cluster. It involves up to three different clusters :
401 * - the child (local) cluster can be any cluster selected by the sys_fork function.
402 * - the parent cluster must be the reference cluster for the parent process.
403 * - the client cluster containing the thread requesting the fork can be any cluster.
404 * The new "child" process descriptor is initialised from informations found in the "parent"
405 * reference process descriptor, containing the complete process description.
406 * The new "child" thread descriptor is initialised from informations found in the "parent"
407 * thread descriptor.
408 *********************************************************************************************
409 * @ parent_process_xp  : extended pointer on the reference parent process.
410 * @ parent_thread_xp   : extended pointer on the parent thread requesting the fork.
411 * @ child_pid          : [out] child process identifier.
412 * @ child_thread_ptr   : [out] local pointer on child thread in target cluster.
413 * @ return 0 if success / return non-zero if error.
414 ********************************************************************************************/
415error_t process_make_fork(  xptr_t             parent_process_xp,
416                            xptr_t             parent_thread_xp,
417                            pid_t            * child_pid, 
418                            struct thread_s ** child_thread_ptr );
419
420
421/********************   File Management Operations   ****************************************/
422
423/*********************************************************************************************
424 * This function initializes all entries of the local fd_array as empty.
425 *********************************************************************************************
426 * @ process  : pointer on the local process descriptor.
427 ********************************************************************************************/
428void process_fd_init( process_t * process );
429
430/*********************************************************************************************
431 * This function allocates a free slot in the fd_array of the reference process
432 * identified by the <process_xp> argument, register the <file_xp> argument in the
433 * allocated slot, and return the slot index in the <fdid> buffer.
434 * It can be called by any thread in any cluster, because it uses remote access
435 * primitives to access the reference process descriptor.
436 * It takes the lock protecting the reference fd_array against concurrent accesses.
437 *********************************************************************************************
438 * @ process_xp : [in]  extended pointer on client reference process.
439 * @ file_xp    : [in]  extended pointer on the file descriptor to be registered.
440 * @ fdid       : [out] buffer for fd_array slot index.
441 * @ return 0 if success / return EMFILE if array full.
442 ********************************************************************************************/
443error_t process_fd_register( xptr_t      process_xp,
444                             xptr_t      file_xp,
445                             uint32_t  * fdid );
446
447/*********************************************************************************************
448 * This function uses as many remote accesses as required, to reset an entry in fd_array[],
449 * in all clusters containing a copy. The entry is identified by the <fdid> argument.
450 * This function must be executed by a thread running in reference cluster, that contains
451 * the complete list of process descriptors copies.
452 * It takes the lock protecting the reference fd_array against concurrent accesses.
453 * TODO this function is not implemented yet.
454 *********************************************************************************************
455 * @ process  : [in] pointer on the local process descriptor.
456 * @ fdid     : [in] file descriptor index in the fd_array.
457 ********************************************************************************************/
458void process_fd_remove( process_t * process,
459                        uint32_t    fdid );
460
461/*********************************************************************************************
462 * This function returns an extended pointer on a file descriptor identified by its index
463 * in fd_array. It can be called by any thread running in any cluster.
464 * It accesses first the local process descriptor. In case of local miss, it takes
465 * the lock protecting the reference fd_array, and access the reference process descriptor.
466 * It updates the local fd_array when the file descriptor exists in reference cluster.
467 * It takes the lock protecting the reference fd_array against concurrent accesses.
468 * The file descriptor refcount is not incremented.
469 *********************************************************************************************
470 * @ process  : pointer on the local process descriptor.
471 * @ fdid     : file descriptor index in the fd_array.
472 * @ return extended pointer on file descriptor if success / return XPTR_NULL if not found.
473 ********************************************************************************************/
474xptr_t process_fd_get_xptr( process_t * process,
475                            uint32_t    fdid );
476
477/*********************************************************************************************
478 * This function copies all non-zero entries (other than the three first stdin/stdout/stderr)
479 * from a remote <src_xp> fd_array, embedded in a process descriptor, to another remote
480 * <dst_xp> fd_array, embedded in another process descriptor.
481 * The calling thread can be running in any cluster.
482 * It takes the lock protecting the reference fd_array against concurrent accesses.
483 * For each involved file descriptor, the refcount is incremented.
484 *********************************************************************************************
485 * @ dst_xp   : extended pointer on the destination fd_array_t.
486 * @ src_xp   : extended pointer on the source fd_array_t.
487 ********************************************************************************************/
488void process_fd_remote_copy( xptr_t dst_xp,
489                             xptr_t src_xp );
490
491/*********************************************************************************************
492 * This function checks the current number of open files for a given process.
493 * It can be called by any thread in any cluster, because it uses portable remote access
494 * primitives to access the reference process descriptor.
495 * It does not take the lock protecting the reference fd_array.
496 *********************************************************************************************
497 * @ returns true if file descriptor array full.
498 ********************************************************************************************/
499bool_t process_fd_array_full( void );
500
501
502
503/********************   Thread Related Operations   *****************************************/
504
505/*********************************************************************************************
506 * This function atomically registers a new thread in the local process descriptor.
507 * It checks that there is an available slot in the local th_tbl[] array, and allocates
508 * a new LTID using the relevant lock depending on the kernel/user type.
509 *********************************************************************************************
510 * @ process  : pointer on the local process descriptor.
511 * @ thread   : pointer on new thread to be registered.
512 * @ trdid    : [out] buffer for allocated trdid.
513 * @ returns 0 if success / returns non zero if no slot available.
514 ********************************************************************************************/
515error_t process_register_thread( process_t       * process,
516                                 struct thread_s * thread,
517                                 trdid_t         * trdid );
518
519
520/***************   Terminals related operations  ********************************************/
521
522/*********************************************************************************************
523 * This function scan the set of user TXT terminals to find a free terminal
524 * (the list of attached processes is empty for a free TXT terminal).
525 * It is called only by the process_reference_init() function when creating a KSH process.
526 * It makes a kernel panic if no free TXT terminal is found.
527 * The allocated TXT terminal is only released when the KSH process is deleted.
528 *********************************************************************************************
529 * @ return TXT terminal index if succes / kernel panic if no terminal found.
530 ********************************************************************************************/
531uint32_t process_txt_alloc( void );
532
533/*********************************************************************************************
534 * This function attach a process, identified by the <process> argument to a TXT terminal,
535 * identified by the <txt_id> channel index argument.
536 * The process descriptor identified by the <process> argument must be in the owner cluster. 
537 * It insert the process descriptor in the xlist rooted in the TXT_RX device.
538 * It is called by the process_reference_init() function.
539 *********************************************************************************************
540 * @ process  : local pointer on process descriptor.
541 * @ txt_id   : TXT channel index.
542 ********************************************************************************************/
543void process_txt_attach( process_t * process,
544                         uint32_t    txt_id );
545
546/*********************************************************************************************
547 * This function detach a process, identified by the <process_xp> argument,
548 * from the list of process attached to a given TXT terminal. It transfer the TXT ownership
549 * to another process, if the detached process is the TXT owner.
550 * The process descriptor identified by the <process_xp> argument must be in the owner
551 * cluster, but the calling thread can be running in any cluster.
552 *********************************************************************************************
553 * @ process_xp  : extended pointer on process descriptor.
554 ********************************************************************************************/
555void process_txt_detach( xptr_t  process_xp );                     
556
557/*********************************************************************************************
558 * This function gives a process identified by the <process_xp> argument the exclusive
559 * ownership of its attached TXT_RX terminal (i.e. put the process in foreground).
560 * It can be called by a thread running in any cluster, but the <process_xp> must be the
561 * owner cluster process descriptor.
562 *********************************************************************************************
563 * @ owner_xp  : extended pointer on process descriptor in owner cluster.
564 ********************************************************************************************/
565void process_txt_set_ownership( xptr_t process_xp );
566
567/*********************************************************************************************
568 * When the process identified by the <owner_xp> argument has the exclusive ownership of
569 * the TXT_RX terminal, this function transfer this ownership to another attached process.
570 * The process descriptor must be the process owner.
571 * This function does nothing if the process identified by the <process_xp> is not
572 * the TXT owner.
573 * - If the current owner is not the KSH process, the new owner is the KSH process.
574 * - If the current owner is the KSH process, the new owner is another attached process.
575 * - If there is no other attached process, the TXT has no more defined owner.
576 *********************************************************************************************
577 * @ process_xp  : extended pointer on process descriptor in owner cluster.
578 ********************************************************************************************/
579void process_txt_transfer_ownership( xptr_t process_xp );
580
581/*********************************************************************************************
582 * This function returns true if the  process identified by the <process_xp> argument
583 * is the TXT owner. It can be called by a thread running in any cluster, but the
584 * process_xp must be the owner cluster process descriptor.
585 *********************************************************************************************
586 * @ returns true if target process is TXT owner.
587 ********************************************************************************************/
588bool_t process_txt_is_owner( xptr_t process_xp );
589
590/*********************************************************************************************
591 * This function returns an extended ponter on the current TXT owner process,
592 * for the TXT terminal identified by the <channel> index.
593 *********************************************************************************************
594 * @ channel : TXT channel.
595 * @ return extended pointer on TXT owner process.
596 ********************************************************************************************/
597xptr_t process_txt_get_owner( uint32_t channel );
598
599/*********************************************************************************************
600 * This debug function diplays on the kernel terminal the list of processes attached
601 * to a given terminal identified by the <txt_id> argument.
602 *********************************************************************************************
603 * @ txt_id  : TXT terminal channel.
604 ********************************************************************************************/
605void process_txt_display( uint32_t txt_id );
606
607
608#endif  /* _PROCESS_H_ */
Note: See TracBrowser for help on using the repository browser.