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

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

1) Introduce up to 4 command lines arguments in the KSH "load" command.
These arguments are transfered to the user process through the
argc/argv mechanism, using the user space "args" vseg.

2) Introduce the named and anonymous "pipes", for inter-process communication
through the pipe() and mkfifo() syscalls.

3) Introduce the "chat" application to validate the two above mechanisms.

4) Improve printk() and assert() fonctions in printk.c.

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