Changeset 433 for trunk/kernel/syscalls/syscalls.h

Timestamp:

Feb 14, 2018, 3:40:19 PM (6 years ago)

Author:

alain

Message:

blip

File:

• trunk/kernel/syscalls/syscalls.h (modified) (8 diffs)

trunk/kernel/syscalls/syscalls.h

@@ -171 +171 @@
 /****************************************************************************************** 
  * [10] This function implement the exit system call terminating a POSIX process.
+ * In the present implementation, this function implements actually the _exit():
+ * - it does not flush open ourput steams.
+ * - it does not close open streams.
  ******************************************************************************************
  * @ status   : terminaison status (not used in present implementation).
@@ -421 +424 @@
 
 /****************************************************************************************** 
- * [34] This function implements the "kill" system call.
+ * [34] This function implements the "kill" system call on the kernel side.
  * It register the signal defined by the <sig_id> argument in all thread descriptors 
  * of a target process identified by the <pid> argument. This is done in all clusters
@@ -432 +435 @@
  ****************************************************************************************** 
  * @ pid      : target process identifier.
- * @ sig_id   : index defining the signal type (from 1 to 31). 
+ * @ sig_id   : index defining the signal type. 
  * @ return 0 if success / returns -1 if failure.
  *****************************************************************************************/
@@ -439 +442 @@
 
 /****************************************************************************************** 
- * [35] This function implements the "getpid" system call.
+ * [35] This function implements the "getpid" system call on the kernel side.
  ****************************************************************************************** 
  * @ returns the process PID for the calling thread.
@@ -446 +449 @@
 
 /****************************************************************************************** 
- * [36] This function implement the "fork" system call.
- * The calling process descriptor (parent process), and the associated thread descriptor are
- * replicated in the same cluster as the calling thread, but the new process (child process)
- * is registered in another target cluster, that is the new process owner. 
- * The child process and the associated main thread will be migrated to the target cluster
- * later, when the child process makes an "exec" or any other system call... TODO [AG]
+ * [36] This function implement the "fork" system call on the kernel side.
+ * The calling process descriptor (parent process), and the associated thread descriptor
+ * are replicated in a - likely - remote cluster, that becomes the child process owner. 
+ * The child process get a new PID, and is linked to the parent PID. The child process 
+ * inherit from its parent the memory image, and all open files (including the TXT).
+ * The child process becomes the TXT terminal owner.
  * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
  * stored in the calling thread descriptor by the specific fork_place() system call.
- * If not, the sys_fork() function makes a query to the DQDT to select the target cluster. 
+ * If not, the kernel function makes a query to the DQDT to select the target cluster. 
  ****************************************************************************************** 
  * @ if success, returns child process PID to parent, and return O to child.
@@ -462 +465 @@
 
 /****************************************************************************************** 
- * [37] This function implement the "exec" system call, that creates a new process 
- * descriptor.
- * It is executed in the client cluster, but the new process descriptor and the main
- * thread are created in a server cluster, that is generally another cluster. 
- * - if the server_cluster is the client cluster, it calls directly the process_make_exec()
- *   function to create a new process, and launch a new thread in local cluster.
- * - if the target_cluster is remote, it calls the rpc_process_exec_client() to execute
- *   process_signedmake_exec() on the remote cluster.
- * In both case this function build an exec_info_t structure containing all informations
- * required to build the new process descriptor and the associated thread.
- * Finally, the calling process and thread are deleted.
+ * [37] This function implement the "exec" system call on the kernel side.
+ * It creates, in the same cluster as the calling thread, a new process descriptor,
+ * and a new associated main thread descriptor, executing a new memory image defined 
+ * by the <filename> argument. This new process inherit from the old process the PID
+ * and the PPID, as well as all open files (including the TXT). 
+ * The old process descriptor, and all its threads are blocked, and marked for deletion.
+ * Therefore the exec syscall does not return to the calling thread in case of success.
+ * This function build an exec_info_t structure containing the new process arguments,
+ * as defined by the <arv> argument, and the new process environment variables, 
+ * as defined by the <envp>  argument.
+ * TODO : the <argv> and <envp> arguments are not supported yet (both must be NULL).
  ****************************************************************************************** 
  * @ filename : string pointer on .elf filename (pointer in user space)
  * @ argv     : array of strings on process arguments (pointers in user space)
  * @ envp     : array of strings on environment variables (pointers in user space)
- * @ returns O if success / returns -1 if failure.
+ * @ does not return if success / returns -1 if failure.
  *****************************************************************************************/
 int sys_exec( char  * filename,
@@ -495 +498 @@
 
 /****************************************************************************************** 
- * [39] This blocking function wait a change of a child process state. A change can be:
- * - a termination of child following a child exit.
- * - a termination of child following a SIGKILL signal.
+ * [39] This blocking function waits a change of a child process state, that can be:
+ * - a termination of child following a process_make_exit().
+ * - a termination of child following a process_make_kill().
  * - a blocking of child following a SIGSTOP signal.
- * It returns the PID of the involved child process, after storing in the memory slot
- * pointed by the <status> argument relevant information on the child state change.
+ * In case of a multi-thread process, this function must be called by the main thread
+ * runningin the reference cluster.
+ * When a change has been observed, it returns the PID of the child process, and stores
+ * in the <status> argument relevant information on the child state change.
  * The following macros can be used to extract information from status:
  * - WIFEXITED(status)   : is true if the child process terminated with an exit().
@@ -506 +511 @@
  * - WIFSTOPPED(status)  : is true if the child process is stopped by a signal.
  * - WEXITSTATUS(status) : returns the low-order 8 bits of the exit() argument.
- * A status of 0 indicates a normal termination.
  * If a parent process terminates without waiting for all child processes to terminate,
  * the remaining child processes are attached to the init process.
- ******************************************************************************************
- * @ status : pointer on the child PID status.
- * @ return child PID if success / return -1 if failure.
+ * WARNING: negative values for the <pid> argument are not supported.
+ ******************************************************************************************
+ * @ searched_pid : searched child process identifier.
+ * @ status       : [out] child termination status.
+ * @ return child PID if success / return -1 if searched PID not found.
  *****************************************************************************************/
 int sys_wait( uint32_t * status );