source: trunk/kernel/syscalls/syscalls.h @ 409

Last change on this file since 409 was 409, checked in by alain, 7 years ago

Fix bugs in exec

File size: 33.4 KB
Line 
1/*
2 * syscalls.h - Kernel side services for syscall handling.
3 *
4 * Author     Alain Greiner (2016,2017)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _SYSCALLS_H_
25#define _SYSCALLS_H_
26
27#include <hal_types.h>
28#include <shared_syscalls.h>
29
30/**   Forward declarations  *****/
31
32struct thread_s;                  // defined in thread.h
33struct pthread_attr_s;            // defined in thread.h
34struct vfs_stat_s;                // defined in vfs.h
35struct vfs_dirent_s;              // defined in vfs.h
36struct mmap_attr_s;               // defined in vmm.h
37
38/******************************************************************************************
39 * [0] This function terminates the execution of the calling user thread,
40 * and makes the exit_value pointer available to any successful pthread_join() with the
41 * terminating thread.
42 * It actually set the THREAD_SIG_EXIT signal, set the THREAD_BLOCKED_GLOBAL bit in the
43 * thread descriptor and deschedule.
44 * The thread will be detached from its process, and the memory allocated to the thread
45 * descriptor will be released later by the scheduler.
46 ******************************************************************************************
47 * @ exit_vallue  : pointer to be returned to joining thread if thread is attached.
48 * @ return 0 if success / return -1 if all locks not released or illegal argument.
49 *****************************************************************************************/
50int sys_thread_exit( void * exit_value );
51
52/******************************************************************************************
53 * [1] This function calls the scheduler for the core running the calling thread.
54 ******************************************************************************************
55 * @ x_size   : [out] number of clusters in a row.
56 * @ y_size   : [out] number of clusters in a column.
57 * @ ncores   : [out] number of cores per cluster.
58 * @ return always 0.
59 *****************************************************************************************/
60int sys_thread_yield();
61
62/******************************************************************************************
63 * [2] This function creates a new user thread. The <user_attr> argument is a pointer
64 * on astructure containing the thread attributes, defined in thread.h file.
65 ******************************************************************************************
66 * @ new_thread  : [out] local pointer on created thread descriptor.
67 * @ user_attr   : [in]  pointer on thread attributes structure.
68 * @ start_func  : [in]  pointer on start function.
69 * @ start_args  : [in]  pointer on start function arguments.
70 * @ return 0 if success / return -1 if failure.
71 *****************************************************************************************/
72int sys_thread_create( struct thread_s        * new_thread,
73                       struct pthread_attr_s  * user_attr,
74                       void                   * start_func,
75                       void                   * start_args );
76
77/******************************************************************************************
78 * [3] This blocking function suspend execution of the calling thread until completion
79 * of another target thread identified by the <trdid> argument.
80 * If the <exit_value> argument is not NULL, the value passed to pthread_exit() by the
81 * target thread is stored in the location referenced by exit_value.
82 ******************************************************************************************
83 * @ trdid     : [in]  target thread identifier.
84 * @ thread    : [out] buffer for exit_value returned by target thread.
85 * @ return 0 if success / return -1 if failure.
86 *****************************************************************************************/
87int sys_thread_join( trdid_t    trdid,
88                     void    ** exit_value );
89
90/******************************************************************************************
91 * [4] This function detach a joinable thread.
92 ******************************************************************************************
93 * @ trdid   : thread identifier.
94 * @ return 0 if success / return -1 if failure.
95 *****************************************************************************************/
96int sys_thread_detach( trdid_t  trdid );
97
98/******************************************************************************************
99 * [5] This function requests a target thread identified by its <trdid> argument
100 * to be cancelled. Depending on killer thread and target thread location, it calls
101 * the thread_kil() function or the rpc_thread_kill_client() function to do the work.
102 * It actually set the THREAD_SIG_KILL signal, set the THREAD_BLOCKED_GLOBAL bit in the
103 * target thread descriptor and return.
104 * The thread will be detached from its process, and the memory allocated to the thread
105 * descriptor will be released later by the scheduler.
106 ******************************************************************************************
107 * @ trdid   : thread identifier.
108 * @ return 0 if success / return -1 if illegal argument.
109 *****************************************************************************************/
110int sys_thread_cancel( trdid_t  trdid );
111
112/******************************************************************************************
113 * [6] This function implement all operations on a POSIX unnamed semaphore,
114 * that can be shared by threads running in different clusters.
115 * The kernel structure representing a remote semaphore is in the remote_sem.h file,
116 * and the code implementing the operations is in the remore_sem.c file.
117 ******************************************************************************************
118 * @ vaddr     : semaphore virtual address in user space == identifier.
119 * @ operation : SEM_INIT / SEM_DESTROY / SEM_GETVALUE / SEM_POST / SEM_WAIT.
120 * @ value     : pointer on in/out argument in user space.
121 * @ return 0 if success / return -1 if failure.
122 *****************************************************************************************/
123int sys_sem( void       * vaddr,
124             uint32_t     operation,
125             uint32_t   * value );
126
127/******************************************************************************************
128 * [7] This function implement all operations on a POSIX condition variable.
129 * The kernel structure representing a cond_var is defined in the remote_cv.h file,
130 * The code implementing the operations is defined in the remote_cv.c file.
131 ******************************************************************************************
132 * @ vaddr     : condvar virtual address in user space == identifier.
133 * @ operation : operation type (see below).
134 * @ attr      : mutex virtual address in user space == identifier.
135 * @ return 0 if success / return -1 if failure.
136 *****************************************************************************************/
137int sys_condvar( void     * condvar,
138                 uint32_t   operation,
139                 void     * mutex );
140
141/******************************************************************************************
142 * [8] This function implement all operations on a POSIX barrier.
143 * The kernel structure representing a barrier is defined in the remote_barrier.h file.
144 * The code implementting the operations is defined in the remote_barrier.c file.
145 ******************************************************************************************
146 * @ vaddr     : barrier virtual address in user space == identifier.
147 * @ operation : BARRIER_INIT / BARRIER_DESTROY / BARRIER_WAIT.
148 * @ count     : number of expected threads (only used by BARRIER_INIT operation).
149 * @ return 0 if success / return -1 if failure.
150 *****************************************************************************************/
151int sys_barrier( void     * vaddr,
152                 uint32_t   operation,
153                 uint32_t   count );
154
155/******************************************************************************************
156 * [9] This function implement all operations on a POSIX mutex.
157 * The kernel structure representing a barrier is defined in the remote_barrier.h file.
158 * The code implementting the operations is defined in the remote_barrier.c file.
159 ******************************************************************************************
160 * @ vaddr     : mutex virtual address in user space == identifier.
161 * @ operation : MUTEX_INIT / MUTEX_DESTROY / MUTEX_LOCK / MUTEX_UNLOCK
162 * @ attr      : mutex attributes (non supported yet => must be 0).
163 * @ return 0 if success / return -1 if failure.
164 *****************************************************************************************/
165int sys_mutex( void     * vaddr,
166               uint32_t   operation,
167               uint32_t   count );
168
169/******************************************************************************************
170 * [10] This function implement the exit system call terminating a POSIX process.
171 ******************************************************************************************
172 * @ status   : terminaison status (not used in present implementation).
173 *****************************************************************************************/
174int sys_exit( uint32_t status );
175
176/******************************************************************************************
177 * [11] This function remove an existing mapping defined by the <addr> and <size>
178 * arguments in user space.
179 ******************************************************************************************
180 * @ addr  : base address in user space.
181 * # size  : number of bytes.
182 * @ return 0 if success / return -1 if failure.
183 *****************************************************************************************/
184int sys_munmap( void     * addr,
185                uint32_t   size );
186
187/******************************************************************************************
188 * [12] This function open or create an open file descriptor.
189 ******************************************************************************************
190 * @ pathname   : pathname (can be relative or absolute).
191 * @ flags      : bit vector attributes (see below).
192 * @ mode       : access rights.
193 * @ return file descriptor index in fd_array if success / return -1 if failure.
194 *****************************************************************************************/
195int sys_open( char    * pathname,
196              uint32_t  flags,
197              uint32_t  mode );
198
199/******************************************************************************************
200 * [13] This function map physical memory (or a file) in the calling thread virtual space.
201 * The <attr> argument is a pointer on a structure for arguments (see shared_syscalls.h).
202 ******************************************************************************************
203 * @ attr       : pointer on attributes structure.
204 * @ return 0 if success / return -1 if failure.
205 *****************************************************************************************/
206int sys_mmap( mmap_attr_t * attr );
207
208/******************************************************************************************
209 * [14] This function read bytes from an open file identified by its file descriptor.
210 * The file can be a regular file or character oriented device.
211 * IRQs are enabled during this system call.
212 ******************************************************************************************
213 * @ file_id  : open file index in fd_array.
214 * @ buf      : buffer virtual address in user space.
215 * @ count    : number of bytes.
216 * @ return number of bytes actually read if success / returns -1 if failure.
217 *****************************************************************************************/
218int sys_read( uint32_t   file_id,
219              void     * buf,
220              uint32_t   count );
221
222/******************************************************************************************
223 * [15] This function writes bytes to an open file identified by its file descriptor.
224 * The file can be a regular file or character oriented device.
225 * IRQs are enabled during this system call.
226 ******************************************************************************************
227 * @ file_id  : open file index in fd_array.
228 * @ buf      : buffer virtual address in user space.
229 * @ count    : number of bytes.
230 * @ return number of bytes actually written if success / returns -1 if failure.
231 *****************************************************************************************/
232int sys_write( uint32_t   file_id,
233               void     * buf,
234               uint32_t   count );
235
236/******************************************************************************************
237 * [16] This function repositions the offset of the file descriptor identified by <file_id>,
238 * according to the operation type defined by the <whence> argument.
239 ******************************************************************************************
240 * @ file_id  : open file index in fd_array.
241 * @ offset   : used to compute new offset value.
242 * @ whence   : operation type (see below).
243 * @ return 0 if success / returns -1 if failure.
244 *****************************************************************************************/
245int sys_lseek( xptr_t    file_id,
246               uint32_t  offset,
247               uint32_t  whence );
248
249/******************************************************************************************
250 * [17] This function release the memory allocated for the file descriptor identified by
251 * the <file_id> argument, and remove the fd array_entry in all copies of the process
252 * descriptor.
253 ******************************************************************************************
254  file_id   : file descriptor index in fd_array.
255 * @ return 0 if success / returns -1 if failure.
256 *****************************************************************************************/
257int sys_close( uint32_t file_id );
258
259/******************************************************************************************
260 * [18] This function removes a directory entry identified by the <pathname> from the
261 * directory, and decrement the link count of the file referenced by the link.
262 * If the link count reduces to zero, and no process has the file open, then all resources
263 * associated with the file are reclaimed.  If one or more process have the file open when
264 * the last link is removed, the link is removed, but the removal of the file is delayed
265 * until all references to it have been closed.
266 ******************************************************************************************
267 * @ pathname   : pathname (can be relative or absolute).
268 * @ return 0 if success / returns -1 if failure.
269 *****************************************************************************************/
270int sys_unlink( char * pathname );
271
272/******************************************************************************************
273 * [19] This function creates in the calling thread cluster an unnamed pipe, and two
274 * (read and write) file descriptors.
275 * TODO not implemented yet...
276 ******************************************************************************************
277 * @ file_id[0] : [out] read only file descriptor index.
278 * @ file_id[1] : [out] write only file descriptor index.
279 * @ return 0 if success / return -1 if failure.
280 *****************************************************************************************/
281int sys_pipe( uint32_t file_id[2] );
282
283/******************************************************************************************
284 * [20] This function change the current working directory in reference process descriptor.
285 ******************************************************************************************
286 * @ pathname   : pathname (can be relative or absolute).
287 * @ return 0 if success / returns -1 if failure.
288 *****************************************************************************************/
289int sys_chdir( char * pathname );
290
291/******************************************************************************************
292 * [21] This function creates a new directory in file system.
293 ******************************************************************************************
294 * @ pathname   : pathname (can be relative or absolute).
295 * @ mode       : access rights (as defined in chmod).
296 * @ return 0 if success / returns -1 if failure.
297 *****************************************************************************************/
298int sys_mkdir( char    * pathname,
299               uint32_t  mode );
300
301/******************************************************************************************
302 * [22] This function creates a named FIFO file in the calling thread cluster.
303 * The associated read and write file descriptors mut be be  explicitely created
304 * using the sys_open() function.
305 ******************************************************************************************
306 * @ pathname   : pathname (can be relative or absolute).
307 * @ mode       : access rights (as defined in chmod).
308 * @ return 0 if success / returns -1 if failure.
309 *****************************************************************************************/
310int sys_mkfifo( char     * pathname,
311                uint32_t   mode );
312
313/******************************************************************************************
314 * [23] This function open a directory, that must exist in the file system, returning
315 * a DIR pointer on the directory in user space.
316 ******************************************************************************************
317 * @ pathname   : pathname (can be relative or absolute).
318 * @ dirp       : [out] buffer for pointer on user directory (DIR).
319 * @ return 0 if success / returns -1 if failure.
320 *****************************************************************************************/
321int sys_opendir( char * pathname,
322                 DIR ** dirp );
323
324/******************************************************************************************
325 * [24] This function returns an user pointer on the dirent structure describing the
326 * next directory entry in the directory identified by the <dirp> argument.
327 ******************************************************************************************
328 * @ dirp     : user pointer identifying the searched directory.
329 * @ dentp    : [out] buffer for pointer on user direntory entry (dirent).
330 * @ return O if success / returns -1 if failure.
331 *****************************************************************************************/
332int sys_readdir( DIR            * dirp,
333                 struct dirent ** dentp );
334
335/******************************************************************************************
336 * [25] This function closes the directory identified by the <dirp> argument, and releases
337 * all structures associated with the <dirp> pointer.
338 ******************************************************************************************
339 * @ dirp     : user pointer identifying the directory.
340 * @ return 0 if success / returns -1 if failure.
341 *****************************************************************************************/
342int sys_closedir( DIR * dirp );
343
344/******************************************************************************************
345 * [26] This function returns the pathname of the current working directory.
346 ******************************************************************************************
347 * buf     : buffer addres in user space.
348 * nbytes  : user buffer size in bytes.
349 * @ return 0 if success / returns -1 if failure.
350 *****************************************************************************************/
351int sys_getcwd( char     * buf,
352                uint32_t   nbytes );
353
354/******************************************************************************************
355 * [27] This slot is not used.
356 *****************************************************************************************/
357
358/******************************************************************************************
359 * [28] This function forces the calling thread to sleep, for a fixed number of cycles.
360 ******************************************************************************************
361 * cycles   : number of cycles.
362 *****************************************************************************************/
363int sys_alarm( uint32_t cycles );
364
365/******************************************************************************************
366 * [29] This function removes a directory file whose name is given by <pathname>.
367 * The directory must not have any entries other than `.' and `..'.
368 ******************************************************************************************
369 * @ pathname   : pathname (can be relative or absolute).
370 * @ return 0 if success / returns -1 if failure.
371 *****************************************************************************************/
372int sys_rmdir( char * pathname ); 
373
374/******************************************************************************************
375 * [30] This function implement the operations related to User Thread Local Storage.
376 * It is actually implemented as an uint32_t variable in the thread descriptor.
377 ******************************************************************************************
378 * @ operation  : UTLS operation type as defined below.
379 * @ value      : argument value for the UTLS_SET operation.
380 * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
381 *****************************************************************************************/
382int sys_utls( uint32_t operation,
383              uint32_t value );
384
385/******************************************************************************************
386 * [31] This function change the acces rights for the file/dir identified by the
387 * pathname argument.
388 ******************************************************************************************
389 * @ pathname   : pathname (can be relative or absolute).
390 * @ rights     : acces rights.
391 * @ return 0 if success / returns -1 if failure.
392 *****************************************************************************************/
393int sys_chmod( char     * pathname,
394               uint32_t   rights );
395
396/******************************************************************************************
397 * [32] This function associate a specific signal handler to a given signal type.
398 * Tee handlers for the SIGKILL and SIGSTOP signals cannot be redefined.
399 ******************************************************************************************
400 * @ sig_id    : index defining signal type (from 1 to 31).
401 * @ handler   : pointer on fonction implementing the specific handler.
402 * @ return 0 if success / returns -1 if failure.
403 *****************************************************************************************/
404int sys_signal( uint32_t   sig_id,
405                void     * handler );
406
407/******************************************************************************************
408 * [33] This function returns in the structure <tv>, defined in the time.h file,
409 * the current time (in seconds & micro-seconds).
410 * It is computed from the calling core descriptor.
411 * The timezone is not supported.
412 ******************************************************************************************
413 * @ tv      : pointer on the timeval structure.
414 * @ tz      : pointer on the timezone structure : must be NULL.       
415 * @ return 0 if success / returns -1 if failure.
416 *****************************************************************************************/
417int sys_timeofday( struct timeval  * tv,
418                   struct timezone * tz );
419
420/******************************************************************************************
421 * [34] This function implements the "kill" system call.
422 * It register the signal defined by the <sig_id> argument in all thread descriptors
423 * of a target process identified by the <pid> argument. This is done in all clusters
424 * containing threads for the target process.
425 * It can be executed by any thread running in any cluster, as this function uses
426 * remote access to traverse the list of process copies stored in the owner cluster,
427 * and the RPC_SIGNAL_RISE to signal the remote threads.
428 ******************************************************************************************
429 * @ pid      : target process identifier.
430 * @ sig_id   : index defining the signal type (from 1 to 31).
431 * @ return 0 if success / returns -1 if failure.
432 *****************************************************************************************/
433int sys_kill( pid_t    pid,
434              uint32_t sig_id );
435
436/******************************************************************************************
437 * [35] This function implements the "getpid" system call.
438 ******************************************************************************************
439 * @ returns the process PID for the calling thread.
440 *****************************************************************************************/
441int sys_getpid();
442
443/******************************************************************************************
444 * [36] This function implement the "fork" system call.
445 * The calling process descriptor (parent process), and the associated thread descriptor are
446 * replicated in the same cluster as the calling thread, but the new process (child process)
447 * is registered in another target cluster, that is the new process owner.
448 * The child process and the associated main thread will be migrated to the target cluster
449 * later, when the child process makes an "exec" or any other system call... TODO [AG]
450 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
451 * stored in the calling thread descriptor by the specific fork_place() system call.
452 * If not, the sys_fork() function makes a query to the DQDT to select the target cluster.
453 ******************************************************************************************
454 * @ if success, returns child process PID to parent, and return O to child.
455 * @ if failure, returns -1 to parent / no child process is created.
456 *****************************************************************************************/
457int sys_fork();
458
459/******************************************************************************************
460 * [37] This function implement the "exec" system call, that creates a new process
461 * descriptor.
462 * It is executed in the client cluster, but the new process descriptor and the main
463 * thread are created in a server cluster, that is generally another cluster.
464 * - if the server_cluster is the client cluster, it calls directly the process_make_exec()
465 *   function to create a new process, and launch a new thread in local cluster.
466 * - if the target_cluster is remote, it calls the rpc_process_exec_client() to execute
467 *   process_signedmake_exec() on the remote cluster.
468 * In both case this function build an exec_info_t structure containing all informations
469 * required to build the new process descriptor and the associated thread.
470 * Finally, the calling process and thread are deleted.
471 ******************************************************************************************
472 * @ filename : string pointer on .elf filename (pointer in user space)
473 * @ argv     : array of strings on process arguments (pointers in user space)
474 * @ envp     : array of strings on environment variables (pointers in user space)
475 * @ returns O if success / returns -1 if failure.
476 *****************************************************************************************/
477int sys_exec( char  * filename,
478              char ** argv,
479              char ** envp );
480
481/******************************************************************************************
482 * [38] This function  returns in the <stat> structure, defined in the "shared_syscalls.h"
483 * file, various informations on the file/directory identified by the <pathname> argument.
484 ******************************************************************************************
485 * @ pathname  : user pointer on file pathname.
486 * @ stat      : user pointer on the stat structure.
487 * @ returns O if success / returns -1 if failure.
488 *****************************************************************************************/
489int sys_stat( const char  * pathname,
490              struct stat * stat );
491
492/******************************************************************************************
493 * [39] This non-standard function is used to activate / desactivate the trace for a thread
494 * identified by the <trdid> and <pid> arguments.
495 * It can be called by any other thread in the same process.
496 ******************************************************************************************
497 * @ operation  : operation type as defined below.
498 * @ pid        : process identifier.
499 * @ trdid      : thread identifier.
500 * @ returns O if success / returns -1 if failure.
501 *****************************************************************************************/
502int sys_trace( uint32_t operation,
503               pid_t    pid, 
504               uint32_t trdid );
505
506/******************************************************************************************
507 * [40] This function returns the hardware platform parameters.
508 ******************************************************************************************
509 * @ x_size   : [out] number of clusters in a row.
510 * @ y_size   : [out] number of clusters in a column.
511 * @ ncores   : [out] number of cores per cluster.
512 * @ return 0 if success / return -1 if illegal arguments
513 *****************************************************************************************/
514int sys_get_config( uint32_t * x_size,
515                    uint32_t * y_size,
516                    uint32_t * ncores );
517
518/******************************************************************************************
519 * [41] This function returns the calling core cluster and local index.
520 ******************************************************************************************
521 * @ cxy      : [out] cluster identifier (fixed format)
522 * @ lid      : [out] core local index in cluster.
523 * @ return 0 if success / return -1 if illegal arguments
524 *****************************************************************************************/
525int sys_get_core( uint32_t * cxy,
526                  uint32_t * lid );
527
528/******************************************************************************************
529 * [42] This function returns in a 64 bits user buffer the calling core cycles count.
530 * It uses both the hardware register and the core descriptor cycles count to take
531 * into account a possible harware register overflow  in 32 bits architectures.
532 ******************************************************************************************
533 * cycle    : [out] address of buffer in user space.
534 * @ return 0 if success / return -1 if illegal arguments
535 *****************************************************************************************/
536int sys_get_cycle( uint64_t * cycle );
537
538/******************************************************************************************
539 * [43] This debug function displays on the kernel terminal the current state of a
540 * scheduler identified by the <cxy> and <lid> arguments.
541 ******************************************************************************************
542 * cxy      : [in] target cluster identifier.
543 * lid      : [in] target core local index.
544 * @ return 0 if success / return -1 if illegal arguments
545 *****************************************************************************************/
546int sys_get_sched( uint32_t  cxy,
547                   uint32_t  lid );
548
549/******************************************************************************************
550 * [44] This debug function requires the kernel to display on the kernel terminal a message
551 * containing the thread / process / core identifiers, and the cause of panic,
552 * as defined by the <string> argument.
553 ******************************************************************************************
554 * string   : [in] message to be displayed.
555 * @ return always 0.
556 *****************************************************************************************/
557int sys_panic( char * string );
558
559/******************************************************************************************
560 * [45] This function block the calling thread on the THREAD_BLOCKED_GLOBAL condition,
561 * and deschedule.
562 ******************************************************************************************
563 * @ return 0 if success / returns -1 if failure.
564 *****************************************************************************************/
565int sys_thread_sleep();
566
567/******************************************************************************************
568 * [46] This function unblock the thread identified by its <trdid> from the
569 * THREAD_BLOCKED_GLOBAL condition.
570 ******************************************************************************************
571 * @ trdid  : target thread identifier.
572 * @ return 0 if success / return -1 if failure.
573 *****************************************************************************************/
574int sys_thread_wakeup();
575
576
577#endif  // _SYSCALLS_H_
Note: See TracBrowser for help on using the repository browser.