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

Last change on this file since 684 was 683, checked in by alain, 4 years ago

All modifications required to support the <tcp_chat> application
including error recovery in case of packet loss.A
File size: 48.5 KB
Line 
1/*
2 * syscalls.h - Kernel side services for syscall handling.
3 *
4 * Author     Alain Greiner (2016,2017,2018,2019,2020)
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_kernel_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/******************************************************************************************
40 * This function forces the calling thread to sleep, for a fixed number of seconds.
41 ******************************************************************************************
42 * @ seconds   : number of seconds.
43 *****************************************************************************************/
44int sys_alarm( uint32_t seconds );
45
46/******************************************************************************************
47 * This function implement all operations on a POSIX barrier.
48 * The kernel structure representing a barrier is defined in the remote_barrier.h file.
49 * The code implementting the operations is defined in the remote_barrier.c file.
50 ******************************************************************************************
51 * @ vaddr     : barrier address in user space == identifier.
52 * @ operation : BARRIER_INIT / BARRIER_DESTROY / BARRIER_WAIT.
53 * @ count     : number of expected threads (only used by BARRIER_INIT).
54 * @ attr      : barrier attributes address in user space (only used by BARRIER_INIT).
55 * @ return 0 if success / return -1 if failure.
56 *****************************************************************************************/
57int sys_barrier( intptr_t   vaddr,
58                 uint32_t   operation,
59                 uint32_t   count,
60                 intptr_t   attr );
61
62/******************************************************************************************
63 * This function change the current working directory in reference process descriptor.
64 ******************************************************************************************
65 * @ pathname   : pathname (can be relative or absolute).
66 * @ return 0 if success / returns -1 if failure.
67 *****************************************************************************************/
68int sys_chdir( char * pathname );
69
70/******************************************************************************************
71 * This function change the acces rights for the file/directory inode identified by the
72 * <pathname> argument, as specified by the <mode> argument.
73 ******************************************************************************************
74 * @ pathname : pathname (can be relative or absolute).
75 * @ mode     : acces rights.
76 * @ return 0 if success / returns -1 if failure.
77 *****************************************************************************************/
78int sys_chmod( char       * pathname,
79               uint32_t     mode );
80
81/******************************************************************************************
82 * This function release the memory allocated for the file descriptor identified by
83 * the <file_id> argument, and remove the fd array_entry in all copies of the process
84 * descriptor.
85 ******************************************************************************************
86  file_id   : file descriptor index in fd_array.
87 * @ returns 0 if success / returns -1 if failure.
88 *****************************************************************************************/
89int sys_close( uint32_t file_id );
90
91/******************************************************************************************
92 * This function closes the directory identified by the <dirp> argument, and releases
93 * all structures associated with the <dirp> pointer.
94 ******************************************************************************************
95 * @ dirp     : [in] user pointer on dirent array identifying the open directory.
96 * @ return 0 if success / returns -1 if failure.
97 *****************************************************************************************/
98int sys_closedir( DIR * dirp );
99
100/******************************************************************************************
101 * This function implement all operations on a POSIX condition variable.
102 * The kernel structure representing a condvar is defined in the remote_condvar.h file,
103 * The code implementing the operations is defined in the remote_condvar.c file.
104 ******************************************************************************************
105 * @ vaddr     : condvar virtual address in user space == identifier.
106 * @ operation : operation type (see below).
107 * @ attr      : mutex virtual address in user space == identifier.
108 * @ return 0 if success / return -1 if failure.
109 *****************************************************************************************/
110int sys_condvar( void     * condvar,
111                 uint32_t   operation,
112                 void     * mutex );
113
114/******************************************************************************************
115 * This debug function displays on the kernel terminal TXT0 an user defined string,
116 * or the current state of a kernel structure, identified by the <type> argument.
117 * The <arg0>, <arg1>, and <arg2> arguments depends on the structure type.
118 ******************************************************************************************
119 * type      : [in] type of display
120 * arg0      : [in] type dependant argument.
121 * arg1      : [in] type dependant argument.
122 * arg2      : [in] type dependant argument.
123 * @ return 0 if success / return -1 if illegal arguments
124 *****************************************************************************************/
125int sys_display( reg_t  type,
126                 reg_t  arg0,
127                 reg_t  arg1,
128                 reg_t  arg2 );
129
130/******************************************************************************************
131 * This function implement the "exec" system call on the kernel side.
132 * It creates, in the same cluster as the calling thread, a new process descriptor,
133 * and a new associated main thread descriptor, executing a new memory image defined
134 * by the <filename> argument. This new process inherit from the old process the PID
135 * and the PPID, as well as all open files registered in fd_array, including the TXT.
136 * The old process descriptor, and all its threads are blocked, and marked for deletion.
137 * Therefore the exec syscall does not return to the calling thread in case of success.
138 * This function must be called by the main thread (thread 0 in owner cluster), of the
139 * calling process, to destroy all process copies, and all other threads in all clusters.
140 ******************************************************************************************
141 * Implementation note:
142 * It fill the calling process "exec_info" structure containing all informations required
143 * to initialize the new process descriptor and the associated main thread. This includes:
144 * - pathname to the new process .elf> file in VFS.
145 * - array of string pointers defining the process arguments, and the associated strings.
146 * - array of string pointers defining environment variables, and the associated strings.
147 * To do this, it calls the process_exec_get_strings function, that copies all relevant
148 * information from user space to kernel space, using functions defined in <hal_uspace.h>.
149 * Then it calls the process_make_exec() function that returns only in case of failure.
150 *
151 * TODO : the <envs> argument is not supported yet and must be NULL.
152 ******************************************************************************************
153 * @ filename      : string pointer on .elf filename (pointer in user space)
154 * @ user_args     : array of strings on process arguments (pointers in user space)
155 * @ user_envs     : array of strings on environment variables (pointers in user space)
156 * @ does not return if success / returns -1 if failure.
157 *****************************************************************************************/
158int sys_exec( char  * filename,
159              char ** user_args,
160              char ** user_envs );
161
162/******************************************************************************************
163 * This function implements the "exit" system call terminating a POSIX process.
164 * It can be called by any thread running in any cluster.
165 * It uses both remote accesses to access the owner process descriptor, and the
166 * RPC_PROCESS_SIGACTION to delete remote process copies and thread descriptors.
167 * In the present implementation, this function implements actually the _exit():
168 * - it does not flush open output streams.
169 * - it does not close open streams.
170 ******************************************************************************************
171 * @ status   : terminaison status returned to parent process.
172 * @ return 0 if success / return -1 if failure.
173 *****************************************************************************************/
174int sys_exit( uint32_t status );
175
176/******************************************************************************************
177 * This generic function implements the non-standard FBF related syscalls.
178 * The operation types mnemonics are defined in the <shared_fbf> file.
179 * The supported operations are defined in the <almosmkh.h> & <almosmkh.c> files.
180 * This function ckecks the syscall arguments, and call the relevant kernel function.
181 ******************************************************************************************
182 * @ arg0       : operation type (mnemonics defined in shared_fbf.h)
183 * @ arg1       : depends on operation type
184 * @ arg2       : depends on operation type
185 * @ arg3       : depends on operation type
186 * @ return 0 if success / return -1 if illegal argument.
187 *****************************************************************************************/
188int sys_fbf( reg_t   arg0,
189             reg_t   arg1,
190             reg_t   arg2,
191             reg_t   arg3 );
192
193/******************************************************************************************
194 * This function gives the process identified by the <pid> argument
195 * the exclusive ownership of its TXT_TX terminal (put it in foreground).
196 ******************************************************************************************
197 * @ pid    : process identifier.
198 * @ return 0 if success / return -1 if failure.
199 *****************************************************************************************/
200int sys_fg( pid_t   pid );
201
202/******************************************************************************************
203 * This function implements the "fsync" system call.
204 * It forces all modified pages of the file mapper identified by the <fd> argument
205 * to be copied to the IOC device.
206 * It can be called by any thread running in any cluster.
207 * TODO not implemented yet.
208 ******************************************************************************************
209 * @ file_id   : file descriptor index in fd_array.
210 * @ return 0 if success / return -1 if failure.
211 *****************************************************************************************/
212int sys_fsync( uint32_t file_id );
213
214/******************************************************************************************
215 * This function implement the "fork" system call on the kernel side.
216 * The calling process descriptor (parent process), and the associated thread descriptor
217 * are replicated in a - likely - remote cluster, that becomes the child process owner.
218 * The child process get a new PID, and is linked to the parent PID. The child process
219 * inherit from its parent the memory image, and all open files (including the TXT).
220 * The child process becomes the TXT terminal owner.
221 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
222 * stored in the calling thread descriptor by the specific fork_place() system call.
223 * If not, the kernel function makes a query to the DQDT to select the target cluster.
224 ******************************************************************************************
225 * @ if success, returns child process PID to parent, and return O to child.
226 * @ if failure, returns -1 to parent / no child process is created.
227 *****************************************************************************************/
228int sys_fork( void );
229
230/******************************************************************************************
231 * This generic function implements all the non standard syscalls of type "get_xxx()",
232 * defined in the <almosmkh.h> and <almosmkh.c> files.
233 * The operation types mnemonics are defined in the <shared_almos.h> file.
234 * This function ckecks the syscall arguments, and call the relevant kernel function.
235 ******************************************************************************************
236 * @ arg0       : operation type (mnemonics defined in shared_get.h)
237 * @ arg1       : depends on operation type
238 * @ arg2       : depends on operation type
239 * @ arg3       : depends on operation type
240 * @ return 0 if success / return -1 if illegal argument.
241 *****************************************************************************************/
242int sys_get( reg_t   arg0,
243             reg_t   arg1,
244             reg_t   arg2,
245             reg_t   arg3 );
246
247/******************************************************************************************
248 * This function implements the non-standard "get_best_core" syscall.
249 * It selects, in a macro-cluster specified by the <base_cxy> and <level> arguments,
250 * the core that has the lowest load.
251 * When an active core has been found in the target macro-cluster, it writes into the
252 * <cxy> and <lid> buffers the cluster identifier and the core local index, and return 0.
253 * It returns -1 in case of illegal arguments (level / cxy / lid).
254 * It returns +1 if there is no active core in specified macro-cluster.
255 ******************************************************************************************
256 * @ base_cxy : [in]  any cluster identifier in macro-cluster.
257 * @ level    : [in]  macro-cluster level in [1,2,3,4,5].
258 * @ cxy      : [out] selected core cluster identifier.
259 * @ lid      : [out] selected core local index in cluster.
260 * @ return 0 if success / -1 if illegal arguments / +1 if no core in macro-clusters.
261 *****************************************************************************************/
262int sys_get_best_core( uint32_t   base_cxy,
263                       uint32_t   level,
264                       uint32_t * cxy,
265                       uint32_t * lid );
266
267/******************************************************************************************
268 * This function implement the non-standard get_config() syscall.
269 * It returns the global hardware platform parameters in the <config> shared structure,
270 * that is defined in the shared_almos.h file.
271 ******************************************************************************************
272 * @ config   : [out] pointer on the hard_config_t structure in user space.
273 * @ return 0 if success / return -1 if illegal argument
274 *****************************************************************************************/
275int sys_get_config( struct hard_config_s * config );
276
277/******************************************************************************************
278 * This function implements the non-standard get_core_id() syscall.
279 * It returns in <cxy> and <lid> the calling core cluster and local index.
280 ******************************************************************************************
281 * @ cxy      : [out] cluster identifier (fixed format)
282 * @ lid      : [out] core local index in cluster.
283 * @ return 0 if success / return -1 if illegal arguments
284 *****************************************************************************************/
285int sys_get_core_id( uint32_t * cxy,
286                     uint32_t * lid );
287
288/******************************************************************************************
289 * This function implements the non-standard get_cycle() syscall.
290 * It returns in a 64 bits user buffer the calling core cycles count.
291 * It uses both the hardware register and the core descriptor cycles count to take
292 * into account a possible harware register overflow  in 32 bits architectures.
293 ******************************************************************************************
294 * cycle    : [out] address of buffer in user space.
295 * @ return 0 if success / return -1 if illegal arguments
296 *****************************************************************************************/
297int sys_get_cycle( uint64_t * cycle );
298
299/******************************************************************************************
300 * This function returns the pathname of the current working directory.
301 ******************************************************************************************
302 * buf     : buffer addres in user space.
303 * nbytes  : user buffer size in bytes.
304 * @ return 0 if success / returns -1 if failure.
305 *****************************************************************************************/
306int sys_getcwd( char     * buf,
307                uint32_t   nbytes );
308
309/******************************************************************************************
310 * This function implements the non-standard "get_nb_cores" syscall.
311 * It writes in the <ncores> buffer the number of cores in the target cluster <cxy>.
312 ******************************************************************************************
313 * @ cxy      : [in]  target cluster identifier.
314 * @ ncores   : [out] number of cores / 0 if cluster cxy undefined in architecture.
315 * @ return 0 if success / return -1 if illegal "ncores" arguments.
316 *****************************************************************************************/
317int sys_get_nb_cores( uint32_t   cxy,
318                      uint32_t * ncores );
319
320/******************************************************************************************
321 * This function implements the "getpid" system call on the kernel side.
322 ******************************************************************************************
323 * @ returns the process PID for the calling thread.
324 *****************************************************************************************/
325int sys_getpid( void );
326
327/******************************************************************************************
328 * This function implements the non-standard "get_thread_info" syscall.
329 * It copies in the user structure defined by the <info> argument the values registered
330 * in the calling thread "thread_info_t" kernel structure.
331 ******************************************************************************************
332 * @ info      : [out] pointer on thread_info_t structure in user space.
333 * @ return 0 if success / return -1 if illegal argument.
334 *****************************************************************************************/
335int sys_get_thread_info( thread_info_t * info );
336
337/******************************************************************************************
338 * This function tests whether a given file descriptor dentified by the <file_id>
339 * argument is an open file descriptor referring to a terminal.
340 ******************************************************************************************
341 * @ file_id   : file descriptor index
342 * @ return 1 if it is a TXT device / return 0 if it is not a TXT device.
343 *****************************************************************************************/
344int sys_isatty( uint32_t file_id );
345
346/******************************************************************************************
347 * This function returns a non-zero value in the <is_fg> buffer when the process
348 * identified by the <pid> argument is the current TXT owner.
349 ******************************************************************************************
350 * @ pid      : process identifier.
351 * @ is_fg    : pointer on buffer.
352 * @ return 0 if success / return -1 if failure.
353 *****************************************************************************************/
354int sys_is_fg( pid_t      pid,
355               uint32_t * is_fg );
356
357/******************************************************************************************
358 * This function implements the "kill" system call on the kernel side.
359 * It register the signal defined by the <sig_id> argument in all thread descriptors
360 * of a target process identified by the <pid> argument. This is done in all clusters
361 * containing threads for the target process.
362 * It can be executed by any thread running in any cluster, as this function uses
363 * remote access to traverse the list of process copies stored in the owner cluster,
364 * and the RPC_SIGNAL_RISE to signal the remote threads.
365 * This function does nothing for (sig_id == 0). This can be used to check process pid.
366 * TODO : This first implementation supports only SIGKILL / SIGSTOP / SIGCONT values.
367 ******************************************************************************************
368 * @ pid      : target process identifier.
369 * @ sig_id   : index defining the signal type.
370 * @ return 0 if success / returns -1 if failure.
371 *****************************************************************************************/
372int sys_kill( pid_t    pid,
373              uint32_t sig_id );
374
375/******************************************************************************************
376 * This function repositions the offset of the file descriptor identified by the
377 * <file_id> argument, according to the operation type defined by the <whence> argument.
378 ******************************************************************************************
379 * @ file_id  : open file index in fd_array.
380 * @ offset   : used to compute new offset value.
381 * @ whence   : operation type (see below).
382 * @ returns new offset value if success / returns -1 if failure.
383 *****************************************************************************************/
384int sys_lseek( xptr_t    file_id,
385               uint32_t  offset,
386               uint32_t  whence );
387
388/******************************************************************************************
389 * This function implements the "mkdir" system call, creating a new directory in
390 * the file system, as defined by the <pathname> argument, with the access permission
391 * defined by the <rights> argument. All nodes but the last in the pathname must exist.
392 * It can be called by any thread running in any cluster.
393 ******************************************************************************************
394 * @ pathname  : pathname defining the new directory location in file system.
395 * @ rights    : access rights (non used yet).
396 * @ return 0 if success / return -1 if failure.
397 *****************************************************************************************/
398int sys_mkdir( char     * pathname,
399               uint32_t   rights );
400
401/******************************************************************************************
402 * This function creates a new inode/dentry couple of type FIFO, and registers it in
403 * the Inode-Tree, as specified by the <pathname> and <mode> arguments.
404 * The associated file descriptors are created later, using the sys_open() function.
405 ******************************************************************************************
406 * @ pathname   : pathname (can be relative or absolute).
407 * @ mode       : access rights (as defined in chmod).
408 * @ return 0 if success / returns -1 if failure.
409 *****************************************************************************************/
410int sys_mkfifo( char     * pathname,
411                uint32_t   mode );
412
413/******************************************************************************************
414 * This function map physical memory (or a file) in the calling thread virtual space.
415 * The <attr> argument is a pointer on a structure for arguments (see shared_mman.h).
416 * The user defined virtual address (MAP_FIXED flag) is not supported.
417 * TODO : the access rights checking is not implemented yet [AG]
418 * TODO : the Copy on Write for MAP_PRIVATE is not implemented yet [AG]
419 ******************************************************************************************
420 * @ attr       : pointer on attributes structure.
421 * @ returns 0 if success / returns -1 if failure.
422 *****************************************************************************************/
423int sys_mmap( mmap_attr_t * attr );
424
425/******************************************************************************************
426 * This function remove an existing mapping defined by the <addr> and <size>
427 * arguments in user space. This can modify the number of vsegs:
428 * (a) if the region is not entirely mapped in one existing vseg, it's an error.
429 * (b) if the region has same base and size as an existing vseg, the vseg is removed.
430 * (c) if the removed region cut the exiting vseg in two parts, it is resized.
431 * (d) if the removed region cut the vseg in three parts, it is modified, and a new
432 *     vseg is created with same type.
433 * All existing VSL copies are updated.
434******************************************************************************************
435 * @ addr  : base address in user space.
436 * @ size  : number of bytes.
437 * @ return 0 if success / return -1 if failure.
438 *****************************************************************************************/
439int sys_munmap( void     * addr,
440                uint32_t   size );
441
442/******************************************************************************************
443 * This function implement all operations on a POSIX mutex.
444 * The kernel structure representing a barrier is defined in the remote_barrier.h file.
445 * The code implementting the operations is defined in the remote_barrier.c file.
446 ******************************************************************************************
447 * @ vaddr     : mutex virtual address in user space == identifier.
448 * @ operation : MUTEX_INIT / MUTEX_DESTROY / MUTEX_LOCK / MUTEX_UNLOCK
449 * @ attr      : mutex attributes (non supported yet => must be 0).
450 * @ return 0 if success / return -1 if failure.
451 *****************************************************************************************/
452int sys_mutex( void     * vaddr,
453               uint32_t   operation,
454               uint32_t   count );
455
456/******************************************************************************************
457 * This function creates a new file descriptor for an existing inode.
458 * It creates a new inode if required by the flags.
459 ******************************************************************************************
460 * @ pathname   : pathname in the inode tree (can be relative or absolute).
461 * @ flags      : bit vector attributes (see in shared_fcntl.h file)
462 * @ mode       : access rights.
463 * @ return file descriptor index in fd_array if success / return -1 if failure.
464 *****************************************************************************************/
465int sys_open( char       * pathname,
466              uint32_t     flags,
467              uint32_t     mode );
468
469/******************************************************************************************
470 * This function creates an user level directory descriptor (including the associated
471 * array of user level dirents), and intialise it from the kernel directory mapper, that
472 * contains all entries in this directory). The directory is identified by the <pathname>
473 * argument. If the corresponding inode is missing in the Inode Tree, the inode is created,
474 * but the directory must exist in the file system.
475 * It returns a DIR pointer <dirp> on the dirent array in user space.
476 * The calling process fd_array is NOT modified.
477 ******************************************************************************************
478 * @ pathname   : [in]  pathname (can be relative or absolute).
479 * @ dirp       : [out] buffer for pointer on user directory (DIR).
480 * @ return 0 if success / returns -1 if failure.
481 *****************************************************************************************/
482int sys_opendir( char * pathname,
483                 DIR ** dirp );
484
485/******************************************************************************************
486 * This function creates in the calling thread cluster an unnamed pipe, implemented
487 * as a remote_buffer_t, creates two (read and write) file descriptors, and links these
488 * two file descriptors to the pipe.
489 * TODO  : the dynamic memory allocation in case of buffer full is not implemented.
490 * FIXME : wich syscall release the kernel memory allocated by this syscall ?
491 ******************************************************************************************
492 * @ fd   : pointeur on a 2 slots array of fdid : fd[0] read / fd[1] write.
493 * @ return 0 if success / return -1 if failure.
494 *****************************************************************************************/
495int sys_pipe( fdid_t * fd );
496
497/******************************************************************************************
498 * This function implements the non-standard place_fork() syscall.
499 * It can be used to specify the target cluster <cxy> for a new process created
500 * by a subsequent fork() syscall.
501 * WARNING: it must be called before each fork() syscall, as the placement specification
502 *          is reset by the fork syscall.
503 ******************************************************************************************
504 * @ cxy    : cluster identifier.
505 * @ return 0 if success / return -1 if failure.
506 *****************************************************************************************/
507int sys_place_fork( uint32_t cxy );
508
509/******************************************************************************************
510 * This function read bytes from an open file identified by its file descriptor.
511 * The file can be a regular file or character oriented device.
512 * IRQs are enabled during this system call.
513 ******************************************************************************************
514 * @ file_id  : open file index in fd_array.
515 * @ buf      : buffer virtual address in user space.
516 * @ count    : number of bytes.
517 * @ returns number of bytes actually read if success / returns -1 if failure.
518 *****************************************************************************************/
519int sys_read( uint32_t   file_id,
520              void     * buf,
521              uint32_t   count );
522
523/******************************************************************************************
524 * This function returns an user pointer on the dirent structure describing the
525 * next directory entry in the directory identified by the <dirp> argument.
526 ******************************************************************************************
527 * @ dirp     : [in]  user pointer on dirent array identifying the open directory.
528 * @ buffer   : [out] pointer on user buffer for a pointer on dirent in user space.
529 * @ return O if success / returns -1 if failure.
530 *****************************************************************************************/
531int sys_readdir( DIR            * dirp,
532                 struct dirent ** buffer );
533
534/******************************************************************************************
535 * This function causes the file named <old> to be renamed as <new>.
536 * If new exists, it is first removed.  Both old and new must be of the same type (both
537 * must be either directories or non-directories) and must reside on the same file system.
538 * It guarantees that an instance of <new> will always exist, even if the system should
539 * crash in the middle of the operation.
540 ******************************************************************************************
541 * @ old      : old file name.
542 * @ new      : new file name.
543 * @ return 0 if success / return -1 if failure.
544 *****************************************************************************************/
545int sys_rename( char *old,
546                char *new );
547
548/******************************************************************************************
549 * This function removes a directory file whose name is given by <pathname>.
550 * The directory must not have any entries other than `.' and `..'.
551 ******************************************************************************************
552 * @ pathname   : pathname (can be relative or absolute).
553 * @ return 0 if success / returns -1 if failure.
554 *****************************************************************************************/
555int sys_rmdir( char * pathname );
556
557/******************************************************************************************
558 * This function implement all operations on a POSIX unnamed semaphore,
559 * that can be shared by threads running in different clusters.
560 * The kernel structure representing a remote semaphore is in the remote_sem.h file,
561 * and the code implementing the operations is in the remore_sem.c file.
562 ******************************************************************************************
563 * @ vaddr         : semaphore virtual address in user space == identifier.
564 * @ operation     : SEM_INIT / SEM_DESTROY / SEM_GETVALUE / SEM_POST / SEM_WAIT.
565 * @ init_value    : initial semaphore value.
566 * @ current_value : pointer on buffer for current semaphore value.
567 * @ return 0 if success / return -1 if failure.
568 *****************************************************************************************/
569int sys_sem( void       * vaddr,
570             uint32_t     operation,
571             uint32_t     init_value,
572             uint32_t   * current_value );
573
574/******************************************************************************************
575 * This function associate a specific signal handler to a given signal type.
576 * The handlers for the SIGKILL and SIGSTOP signals cannot be redefined.
577 ******************************************************************************************
578 * @ sig_id    : index defining signal type (from 1 to 31).
579 * @ handler   : pointer on fonction implementing the specific handler.
580 * @ return 0 if success / returns -1 if failure.
581 *****************************************************************************************/
582int sys_signal( uint32_t   sig_id,
583                void     * handler );
584
585/******************************************************************************************
586 * This generic function implements all socket related syscalls.
587 * The operation types mnemonics are defined in the <shared_socket> file.
588 * The supported operations are defined in the <socket.h> & <socket.c> files.
589 * This function ckecks the syscall arguments, and call the relevant kernel function.
590 ******************************************************************************************
591 * @ arg0       : operation type (mnemonics defined in shared_socket.h)
592 * @ arg1       : depends on operation type
593 * @ arg2       : depends on operation type
594 * @ arg3       : depends on operation type
595 * @ return 0 if success / return -1 if illegal argument.
596 *****************************************************************************************/
597int sys_socket( reg_t   arg0,
598                reg_t   arg1,
599                reg_t   arg2,
600                reg_t   arg3 );
601
602/******************************************************************************************
603 * This function  returns in the <stat> structure, defined in the "shared_syscalls.h"
604 * file, various informations on the file/directory identified by the <pathname> argument.
605 * TODO only the <st_ino>, <st_mode>,<st_uid>,<st_gid>,<st_size> are set.
606 ******************************************************************************************
607 * @ pathname  : user pointer on file pathname.
608 * @ stat      : user pointer on the stat structure.
609 * @ returns O if success / returns -1 if failure.
610 *****************************************************************************************/
611int sys_stat( char        * pathname,
612              struct stat * stat );
613
614/******************************************************************************************
615 * This function implements the "sync" system call.
616 * It forces all modified pages in all kernel mappers to be copied to the IOC device.
617 * It can be called by any thread running in any cluster.
618 * TODO not implemented yet.
619 ******************************************************************************************
620 * @ return 0 if success / return -1 if failure.
621 *****************************************************************************************/
622int sys_sync( void );
623
624/******************************************************************************************
625 * This function returns in the structure <tv>, defined in the time.h file,
626 * the current time (in seconds & micro-seconds).
627 * It is computed from the calling core descriptor.
628 * The timezone is not supported.
629 ******************************************************************************************
630 * @ tv      : pointer on the timeval structure.
631 * @ tz      : pointer on the timezone structure : must be NULL.       
632 * @ return 0 if success / returns -1 if failure.
633 *****************************************************************************************/
634int sys_timeofday( struct timeval  * tv,
635                   struct timezone * tz );
636
637/******************************************************************************************
638 * This function requests a target thread identified by its <trdid> argument
639 * to be cancelled. It calls the thread_kill() function to block the target thread
640 * on the THREAD_BLOCKED_GLOBAL condition, and to set the THREAD_FLAG_REQ_DELETE.
641 * The thread will be detached from its process, and the memory allocated to the thread
642 * descriptor will be released by the scheduler at the next scheduling point.
643 ******************************************************************************************
644 * @ trdid   : thread identifier.
645 * @ return 0 if success / return -1 if illegal argument.
646 *****************************************************************************************/
647int sys_thread_cancel( trdid_t  trdid );
648
649/******************************************************************************************
650 * This function creates a new user thread. The <user_attr> argument is a pointer
651 * on astructure containing the thread attributes, defined in thread.h file.
652 ******************************************************************************************
653 * @ trdid_ptr   : [out] pointer on buffer for created thread trdid.
654 * @ user_attr   : [in]  pointer on thread attributes structure.
655 * @ start_func  : [in]  pointer on start function.
656 * @ start_args  : [in]  pointer on start function arguments.
657 * @ return 0 if success / return -1 if failure.
658 *****************************************************************************************/
659int sys_thread_create( trdid_t               * trdid_ptr,
660                       struct pthread_attr_s * user_attr,
661                       void                  * start_func,
662                       void                  * start_args );
663
664/******************************************************************************************
665 * This function detach a joinable thread.
666 ******************************************************************************************
667 * @ trdid   : thread identifier.
668 * @ return 0 if success / return -1 if failure.
669 *****************************************************************************************/
670int sys_thread_detach( trdid_t  trdid );
671
672/******************************************************************************************
673 * This function terminates the execution of the calling user thread, and makes
674 * the <exit_status> pointer available to any successful pthread_join() with the
675 * terminating thread.
676 * - If the calling thread is the main thread, it calls the sys_exit() function to delete
677 *   completely the user process. 
678 * - if the calling thread is not the main thread, it registers the <exit_status> pointer
679 *   in the thread descriptor, and calls the thread_delete() function, that will set the
680 *   THREAD_SIG_EXIT signal, set the THREAD_BLOCKED_GLOBAL bit in thread descriptor, and
681 *   deschedules. All memory allocated to the thread is released later by the scheduler.
682 *   If the thread is in "detached" mode, the thread_delete() function implements
683 *   the synchonisation with the joining thread.
684 ******************************************************************************************
685 * @ exit_status  : [out] pointer to be returned to joining thread if thread is attached.
686 * @ return 0 if success / return -1 if all locks not released or illegal argument.
687 *****************************************************************************************/
688int sys_thread_exit( void * exit_status );
689
690/******************************************************************************************
691 * This blocking function suspend execution of the calling thread until completion
692 * of another target thread identified by the <trdid> argument.
693 * The target thread must be joinable (running in ATTACHED mode), and must be different
694 * from the calling thread.
695 * If the <exit_value> argument is not NULL, the value passed to pthread_exit() by the
696 * target thread is stored in the location referenced by exit_value.
697 ******************************************************************************************
698 * @ trdid     : [in]  target thread identifier.
699 * @ thread    : [out] buffer for exit_value returned by target thread.
700 * @ return 0 if success / return -1 if failure.
701 *****************************************************************************************/
702int sys_thread_join( trdid_t    trdid,
703                     void    ** exit_value );
704
705/******************************************************************************************
706 * This function blocks the calling thread on the THREAD_BLOCKED_SLEEP condition,
707 * and deschedules. When the <seconds> argument is non-zero, this argument defines
708 * the sleeping time. When it is zero, the sleeping time is unbounded, and the thread
709 * must be unblocked by the sys_thread_wakeup() function
710 ******************************************************************************************
711 * @ seconds : number of seconds of sleep / No alarm is activated when 0.
712 * @ return 0 if success / returns -1 if failure.
713 *****************************************************************************************/
714int sys_thread_sleep( uint32_t seconds );
715
716/******************************************************************************************
717 * This function unblock the thread identified by its <trdid> from the
718 * THREAD_BLOCKED_SLEEP condition, and cancel the registered alarm if required.
719 ******************************************************************************************
720 * @ trdid  : target thread identifier.
721 * @ return 0 if success / return -1 if failure.
722 *****************************************************************************************/
723int sys_thread_wakeup( trdid_t trdid );
724
725/******************************************************************************************
726 * This function calls the scheduler for the core running the calling thread.
727 ******************************************************************************************
728 * @ return always 0.
729 *****************************************************************************************/
730int sys_thread_yield( void );
731
732/******************************************************************************************
733 * This debug function is used to activate / desactivate the context switches trace
734 * for a core identified by the <cxy> and <lid> arguments.
735 * It can be called by any other thread in the same process.
736 ******************************************************************************************
737 * @ active     : activate trace if true / desactivate trace if false.
738 * @ cxy        : cluster identifier.
739 * @ lid        : core local index.
740 * @ returns O if success / returns -1 if failure.
741 *****************************************************************************************/
742int sys_trace( bool_t   active,
743               cxy_t    cxy, 
744               lid_t    lid );
745
746/******************************************************************************************
747 * This function implement the operations related to User Thread Local Storage.
748 * It is actually implemented as an uint32_t variable in the thread descriptor.
749 ******************************************************************************************
750 * @ operation  : UTLS operation type as defined below.
751 * @ value      : argument value for the UTLS_SET operation.
752 * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
753 *****************************************************************************************/
754int sys_utls( uint32_t operation,
755              uint32_t value );
756
757/******************************************************************************************
758 * This function removes a directory entry identified by the <pathname> from the
759 * directory, and decrement the link count of the file referenced by the link.
760 * If the link count reduces to zero, and no process has the file open, then all resources
761 * associated with the file are reclaimed.  If one or more process have the file open when
762 * the last link is removed, the link is removed, but the removal of the file is delayed
763 * until all references to it have been closed.
764 ******************************************************************************************
765 * @ pathname   : pathname (can be relative or absolute).
766 * @ returns 0 if success / returns -1 if failure.
767 *****************************************************************************************/
768int sys_unlink( char * pathname );
769
770/******************************************************************************************
771 * This blocking function waits a change of a child process state, that can be:
772 * - a termination of child following a process_make_exit().
773 * - a termination of child following a process_make_kill().
774 * - a blocking of child following a SIGSTOP signal.
775 * In case of a multi-thread process, this function must be called by the main thread
776 * runningin the reference cluster.
777 * When a change has been observed, it returns the PID of the child process, and stores
778 * in the <status> argument relevant information on the child state change.
779 * The following macros can be used to extract information from status:
780 * - WIFEXITED(status)   : is true if the child process terminated with an exit().
781 * - WIFSIGNALED(status) : is true if the child process killed by a signal.
782 * - WIFSTOPPED(status)  : is true if the child process is stopped by a signal.
783 * - WEXITSTATUS(status) : returns the low-order 8 bits of the exit() argument.
784 * If a parent process terminates without waiting for all child processes to terminate,
785 * the remaining child processes are attached to the init process.
786 * WARNING: negative values for the <pid> argument are not supported.
787 ******************************************************************************************
788 * @ searched_pid : searched child process identifier.
789 * @ status       : [out] child termination status.
790 * @ return child PID if success / return -1 if searched PID not found.
791 *****************************************************************************************/
792int sys_wait( uint32_t * status );
793
794/******************************************************************************************
795 * This function writes bytes to an open file identified by its file descriptor.
796 * The file can be a regular file or character oriented device. For a regular file,
797 * the target inode "size" field is updated if (offset + count) is larger than the
798 * current "size" value. The size value registered in the mappers of the parent(s)
799 * directory are not modified and will be asynchronously updated when the file is closed.
800 * IRQs are enabled during this system call.
801 ******************************************************************************************
802 * @ file_id  : open file index in fd_array.
803 * @ buf      : buffer virtual address in user space.
804 * @ count    : number of bytes.
805 * @ returns number of bytes actually written if success / returns -1 if failure.
806 *****************************************************************************************/
807int sys_write( uint32_t   file_id,
808               void     * buf,
809               uint32_t   count );
810
811
812#endif  // _SYSCALLS_H_
Note: See TracBrowser for help on using the repository browser.