Changeset 683 for trunk/kernel/kern/process.h

Timestamp:

Jan 13, 2021, 12:36:17 AM (3 years ago)

Author:

alain

Message:

All modifications required to support the <tcp_chat> application
including error recovery in case of packet loss.A

File:

• trunk/kernel/kern/process.h (modified) (7 diffs)

trunk/kernel/kern/process.h

@@ -98 +98 @@
  * This structure defines the information required by the process_make_exec() function
  * to create a new reference process descriptor, and the associated main thread.
- * All fields in this structure are filled by the sys_exec() function, using the
- * process_exec_get_strings() function.
+ * All fields in this structure are filled by the sys_exec() function.
  *
  * It contains three parts:
@@ -106 +105 @@
  * - the "envs_pointers" & "envs_nr" fields define the env variables (one env == one string).
  *
- * For both the arguments, and the environment variables, the array of pointers and the
- * strings themselve are stored in kernel space in the same kernel buffer containing
- * an integer number of pages, defined by CONFIG_VMM_ARGS_SIZE and CONFIG_VMM_ENVS_SIZE.
- * This aligned kernel buffer (one or several contiguous physical pages) contains :
+ * For both the arguments and the environment variables, the array of pointers and the
+ * strings themselve are stored in the same kernel buffer. These kernel buffers contain
+ * an integer number of contiguous pages, defined by the CONFIG_VMM_ARGS_SIZE and 
+ * CONFIG_VMM_ENVS_SIZE parameters respectively.
+ * Each kernel (args / envs) buffer contains :
  * - in the first bytes, a fixed size kernel array of pointers on the strings.
  * - in the following bytes, the strings themselves.
- * The size of these arrays of pointers is defined by CONFIG_PROCESS_ARGS_MAX_NR
- * and CONFIG¨PROCESS_ENVS_MAX_NR.
- *
- * WARNING: The "args_pointers" & "envs_pointers" kernel buffer are directly mapped to
- *          the "args" and "envs" user vsegs to be accessed by the user process. 
- *          Therefore, the arrays of pointers build by the sys_exec() function contain
- *          kernel pointers, but the process_make_exec() function replace these pointers
- *          by user pointers in the new process user space.
+ * The size of these arrays of pointers is defined by the CONFIG_PROCESS_ARGS_MAX_NR and
+ * CONFIG_PROCESS_ENVS_MAX_NR parameters respectively.
+ *
+ * WARNING (1) The "args_pointers[i]" & "envs_pointers[i] stored in the dynamically
+ *             allocated kernel buffers are local pointers. They must be extended by the
+ *             local cluster identifier to compute a valid PPN.
+ * WARNING (2) The "args" & "envs" kernel buffers will be mapped to the "args" and "envs"
+ *             user vsegs, to be accessed by the new user process. 
+ *             The process_make_exec() function must therefore replace the kernel pointers
+ *             set by sys_exec(), by user pointers in the new process user space.
  ********************************************************************************************/
 
@@ -232 +234 @@
  * The process GPT is initialised as required by the target architecture.
  * The "kcode" and "kdata" segments are registered in the process VSL.
+ * This function does not return an error code: in case of failure, it print a PANIC message
+ * on kernel terminal TXT0, and the core goes to sleep mode.
  *********************************************************************************************
  * @ process  : [in] pointer on process descriptor to initialize.
@@ -241 +245 @@
 /*********************************************************************************************
  * This function allocates memory and initializes the "process_init" descriptor and the
- * associated "thread_init" descriptor. It is called once at the end of the kernel 
- * initialisation procedure. Its local process identifier is 1, and parent process 
- * is the kernel process in cluster 0.
+ * associated "thread_init" descriptor. It is called once at the end of the kernel_init() 
+ * procedure. Its local process identifier is 1, and parent process is the kernel process.
  * The "process_init" is the first user process, and all other user processes will be forked
  * from this process. The code executed by "process_init" is stored in a .elf file, whose
  * pathname is defined by the CONFIG_PROCESS_INIT_PATH configuration variable. 
- * The process_init does not use the [STDIN/STDOUT/STDERR] streams, but it is linked
- * to kernel TXT0, because these streams must be defined for all user processes.
+ * This function does not return an error code: in case of failure, it print a PANIC message
+ * on kernel terminal TXT0, and the core goes to sleep mode.
  ********************************************************************************************/
 void process_init_create( void );
@@ -415 +418 @@
 
 /*********************************************************************************************
- * This function is called twice by the sys_exec() function :
- * - to register the main() arguments (args) in the process <exec_info> structure.
- * - to register the environment variables (envs) in the <exec_info> structure.
- * In both cases the input is an array of NULL terminated string pointers in user space,
- * identified by the <u_pointers> argument. The strings can be dispatched anywhere in 
- * the calling user process space. The max number of envs, and the max number of args are 
- * defined by the CONFIG_PROCESS_ARGS_NR and CONFIG_PROCESS_ENVS_MAX_NR parameters. 
- *********************************************************************************************
- * Implementation Note:
- * Both the array of pointers and the strings themselve are stored in kernel space in one
- * single, dynamically allocated, kernel buffer containing an integer number of pages,
- * defined by the CONFIG_VMM_ENVS_SIZE and CONFIG_VMM_STACK_SIZE parameters.
- * This aligned kernel buffer (one or several contiguous physical pages) contains :
- * - in the first bytes a fixed size kernel array of kernel pointers on the strings.
- * - in the following bytes the strings themselves.
- * All the pointers, and the actual number of strings are stored in the process exec_info
- * structure defined in the <process.h> file.
- *********************************************************************************************
- * @ is_args     : [in]    true if called for (args) / false if called for (envs).
- * @ u_pointers  : [in]    array of pointers on the strings (in user space).
- * @ exec_info   : [inout] pointer on the exec_info structure.
- * @ return 0 if success / non-zero if too many strings or no memory.
- ********************************************************************************************/
-error_t process_exec_get_strings( bool_t         is_args,
-                                  char        ** u_pointers,
-                                  exec_info_t  * exec_info );
-
-/*********************************************************************************************
  * This function implements the "execve" system call, and is called by sys_exec() function.
  * It must be called by the main thread of the calling "old" process.
@@ -595 +570 @@
  * @ dst_xp   : extended pointer on the source process descriptor (in owner cluster).
  * @ src_xp   : extended pointer on the destination process descriptor (in owner cluster).
- ********************************************************************************************/
-void process_fd_replicate( xptr_t dst_xp,
-                           xptr_t src_xp );
+ * @ return 0 if success / return -1 if failure
+ ********************************************************************************************/
+error_t process_fd_replicate( xptr_t dst_xp,
+                              xptr_t src_xp );
 
 /*********************************************************************************************
@@ -617 +593 @@
  ********************************************************************************************/
 void process_fd_display( xptr_t process_xp );
+
+/*********************************************************************************************
+ * This utility function builds in the buffer defined by the <buffer> and <size> arguments
+ * a printable string describing the current state of a process descriptor identified 
+ * by the <process_xp> argument, or a WARNING message if the buffer size is too small.
+ *********************************************************************************************
+ * @ process_xp  : extended pointer on target process descriptor.
+ * @ buffer      : kernel buffer for string.
+ * @ size        : buffer size in bytes.
+ * @ return always the string length (not including NUL), that can be a warning message.
+ ********************************************************************************************/
+uint32_t process_build_string( xptr_t   process_xp,
+                               char   * buffer,
+                               uint32_t size );
 
 /********************   Thread Related Operations   *****************************************/