source: trunk/libs/stdio.h @ 434

Last change on this file since 434 was 434, checked in by alain, 8 years ago

blap
File size: 26.2 KB
Line 
1/*
2 * stdio.h - User side syscalls definition.
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 _STDIO_H_
25#define _STDIO_H_
26
27#include <shared_syscalls.h>
28
29#define  NULL  (void *)0
30
31/****************** Standard (POSIX) system calls  **************************************/
32
33/*****************************************************************************************
34 * This function terminates a process.
35 *****************************************************************************************
36 * @ status   : terminaison status : 0 / EXIT_SUCCESS / EXIT_FAILURE.
37 ****************************************************************************************/
38void exit( int status );
39
40/*****************************************************************************************
41 * This function open or create an open file descriptor.
42 *****************************************************************************************
43 * @ pathname   : pathname (can be relative or absolute).
44 * @ flags      : bit vector attributes (see syscalls).
45 * @ mode       : access rights (if O_CREAT is set).
46 * @ return file descriptor index in fd_array if success / return -1 if failure.
47 ****************************************************************************************/
48int open( const char * pathname,
49          int          flags,
50          int          mode );
51
52/*****************************************************************************************
53 * This function map physical memory (or a file) in the calling thread virtual space.
54 *****************************************************************************************
55 * @ addr       : unused and unsupported : must be NULL.
56 * @ length     : requested number of bytes.
57 * @ prot       : RWX access modes.
58 * @ flags      : MAP_FILE / MAP_ANON / MAP_PRIVATE / MAP_SHARED (defined in syscalls.h) 
59 * @ fdid       : file descriptor index (if MAP_FILE).                     
60 * @ offset         : offset in file (if MAP_FILE)
61 * @ return 0 if success / return -1 if failure.
62 ****************************************************************************************/
63void * mmap( void         * addr,
64             unsigned int   length,
65             int            prot,
66             int            flags,
67             int            fd,
68             unsigned int   offset );
69
70/*****************************************************************************************
71 * This function read bytes from an open file identified by its file descriptor.
72 * This file can be a regular file or a character oriented device.
73 *****************************************************************************************
74 * @ file_id  : open file index in fd_array.
75 * @ buf      : buffer virtual address in user space.
76 * @ count    : number of bytes.
77 * @ return number of bytes actually read if success / returns -1 if failure.
78 ****************************************************************************************/
79int read( int            fd,
80          void         * buf,
81          unsigned int   count );
82
83/*****************************************************************************************
84 * This function writes bytes to an open file identified by its file descriptor.
85 * This file can be a regular file or character oriented device.
86 *****************************************************************************************
87 * @ file_id  : open file index in fd_array.
88 * @ buf      : buffer virtual address in user space.
89 * @ count    : number of bytes.
90 * @ return number of bytes actually written if success / returns -1 if failure.
91 ****************************************************************************************/
92int write( int            fd,
93           const void   * buf,
94           unsigned int   count );
95
96/*****************************************************************************************
97 * This function repositions the offset of the file descriptor identified by <file_id>,
98 * according to the operation type defined by the <whence> argument.
99 *****************************************************************************************
100 * @ fd       : open file index in fd_array.
101 * @ offset   : used to compute new offset value.
102 * @ whence   : operation type (SEEK_SET / SEEK_CUR / SEEK_END defined in syscalls.h)
103 * @ return 0 if success / returns -1 if failure.
104 ****************************************************************************************/
105int lseek( int           fd,
106           unsigned int  offset,
107           int           whence );
108
109/*****************************************************************************************
110 * This function release the memory allocated for the file descriptor identified by
111 * the <file_id> argument, and remove the fd array_entry in all copies of the process
112 * descriptor.
113 *****************************************************************************************
114 * fd   : file descriptor index in fd_array.
115 * @ return 0 if success / returns -1 if failure.
116 ****************************************************************************************/
117int close( int fd );
118
119/*****************************************************************************************
120 * This function removes a directory entry identified by the <pathname> from the
121 * directory, and decrement the link count of the file referenced by the link.
122 * If the link count reduces to zero, and no process has the file open, then all resources
123 * associated with the file are released.  If one or more process have the file open when
124 * the last link is removed, the link is removed, but the removal of the file is delayed
125 * until all references to it have been closed.
126 *****************************************************************************************
127 * @ pathname   : pathname (can be relative or absolute).
128 * @ return 0 if success / returns -1 if failure.
129 ****************************************************************************************/
130int unlink( const char * pathname );
131
132/*****************************************************************************************
133 * This function creates in the calling thread cluster an unnamed pipe, and two
134 * (read and write) file descriptors to access this pipe. The calling function must pass
135 * the pointer on the fd[] array.
136 * TODO not implemented yet...
137 *****************************************************************************************
138 * @ file_id[0] : [out] read only file descriptor index.
139 * @ file_id[1] : [out] write only file descriptor index.
140 * @ return 0 if success / return -1 if failure.
141 ****************************************************************************************/
142int pipe( int fd[2] );
143
144/*****************************************************************************************
145 * This function change the current working directory in reference process descriptor.
146 *****************************************************************************************
147 * @ pathname   : pathname (can be relative or absolute).
148 * @ return 0 if success / returns -1 if failure.
149 ****************************************************************************************/
150int chdir( const char * pathname );
151
152/*****************************************************************************************
153 * This function creates a new directory in file system.
154 *****************************************************************************************
155 * @ pathname   : pathname (can be relative or absolute).
156 * @ mode       : access rights (as defined in chmod).
157 * @ return 0 if success / returns -1 if failure.
158 ****************************************************************************************/
159int mkdir( const char * pathname,
160           int          mode );
161
162/*****************************************************************************************
163 * This function creates a named FIFO file in the calling thread cluster.
164 * The associated read and write file descriptors mut be be  explicitely created
165 * using the open() system call.
166 *****************************************************************************************
167 * @ pathname   : pathname (can be relative or absolute).
168 * @ mode       : access rights (as defined in chmod).
169 * @ return 0 if success / returns -1 if failure.
170 ****************************************************************************************/
171int mkfifo( const char * pathname,
172            int          mode );
173
174/*****************************************************************************************
175 * This function opens the directory identified by the <pathname> argument,
176 * associates a directory stream with it and returns an user space pointer to identify
177 * this directory stream in subsequent operations. 
178 *****************************************************************************************
179 * @ pathname   : pathname (can be relative or absolute).
180 * @ returns DIR* pointer if success / returns NULL if pathname cannot be accessed.
181 ****************************************************************************************/
182DIR * opendir( const char * pathname );
183
184/*****************************************************************************************
185 * This function returns a pointer to the next directory entry.
186 *****************************************************************************************
187 * @ dirp     : DIR pointer identifying the directory.
188 * @ returns dirent* pointer / returns NULL upon reaching end of directory or on error.
189 ****************************************************************************************/
190struct dirent * readdir( DIR * dirp );
191
192/*****************************************************************************************
193 * This function closes the directory identified by the <dirp> argument, and releases
194 * all structures associated with the <dirp> pointer.
195 *****************************************************************************************
196 * @ dirp     : DIR pointer identifying the directory.
197 * @ returns 0 if success / returns -1 if failure.
198 ****************************************************************************************/
199int closedir( DIR * dirp );
200
201/*****************************************************************************************
202 * This function returns the pathname of the current working directory.
203 *****************************************************************************************
204 * buf     : buffer addres in user space.
205 * nbytes  : user buffer size in bytes.
206 * @ return 0 if success / returns -1 if failure.
207 ****************************************************************************************/
208int getcwd( char       * buf,
209            unsigned int nbytes );
210
211/*****************************************************************************************
212 * This function removes a directory file whose name is given by <pathname>.
213 * The directory must not have any entries other than `.' and `..'.
214 *****************************************************************************************
215 * @ pathname   : pathname (can be relative or absolute).
216 * @ return 0 if success / returns -1 if failure.
217 ****************************************************************************************/
218int rmdir( char * pathname ); 
219
220/*****************************************************************************************
221 * This function implement the operations related to User Thread Local Storage.
222 *****************************************************************************************
223 * @ operation  : UTLS operation type as defined in "shared_sycalls.h" file.
224 * @ value      : argument value for the UTLS_SET operation.
225 * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
226 ****************************************************************************************/
227int utls( unsigned int operation,
228          unsigned int value );
229
230/*****************************************************************************************
231 * This function change the acces rights for the file/dir identified by the
232 * pathname argument.
233 *****************************************************************************************
234 * @ pathname   : pathname (can be relative or absolute).
235 * @ rights     : acces rights.
236 * @ return 0 if success / returns -1 if failure.
237 ****************************************************************************************/
238int chmod( char     * pathname,
239           unsigned int   rights );
240
241/*****************************************************************************************
242 * This function associate a specific signal handler to a given signal type.
243 * The handlers for the SIGKILL and SIGSTOP signals cannot be redefined.
244 *****************************************************************************************
245 * @ sig_id    : index defining signal type (from 1 to 31).
246 * @ handler   : pointer on fonction implementing the specific handler.
247 * @ return 0 if success / returns -1 if failure.
248 ****************************************************************************************/
249int signal( unsigned int   sig_id,
250            void         * handler );
251
252/*****************************************************************************************
253 * This function returns in the structure <tv>, defined in the time.h file,
254 * the current time (in seconds & micro-seconds).
255 * It is computed from the calling core descriptor.
256 * The timezone is not supported.
257 *****************************************************************************************
258 * @ tv      : pointer on the timeval structure.
259 * @ tz      : pointer on the timezone structure : must be NULL.       
260 * @ return 0 if success / returns -1 if failure.
261 ****************************************************************************************/
262int gettimeofday( struct timeval  * tv,
263                  struct timezone * tz );
264
265/*****************************************************************************************
266 * This function implements the "kill" system call on the user side.
267 * It register the signal defined by the <sig_id> argument in all thread descriptors
268 * of a target process identified by the <pid> argument. This is done in all clusters
269 * containing threads for the target process.
270 * It can be executed by any thread running in any cluster, as this function uses
271 * remote access to traverse the list of process copies stored in the owner cluster,
272 * and the RPC_SIGNAL_RISE to signal the remote threads.
273 * This function does nothing for (sig_id == 0). This can be used to check process pid.
274 * TODO : This first implementation supports only SIGKILL / SIGSTOP / SIGCONT values.
275 *****************************************************************************************
276 * @ pid      : target process identifier.
277 * @ sig_id   : index defining the signal type.
278 * @ return 0 if success / returns -1 if failure.
279 ****************************************************************************************/
280int kill( unsigned int  pid,
281          unsigned int  sig_id );
282
283/*****************************************************************************************
284 * This function implements the "getpid" system call on the user side.
285 *****************************************************************************************
286 * @ returns the process PID for the calling thread process.
287 ****************************************************************************************/
288int getpid();
289
290/*****************************************************************************************
291 * This function implement the "fork" system call on the user side.
292 * The calling process descriptor (parent process), and the associated thread descriptor
293 * are replicated in a - likely - remote cluster, that becomes the new process owner.
294 * The child process get a new PID is linked to the parent PID. The child process inherit
295 * from the parent process the memory image, and all open files (including the TXT).
296 * The child process becomes the TXT terminal owner.
297 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
298 * stored in the calling thread descriptor by the specific fork_place() system call.
299 * If not, the kernel function makes a query to the DQDT to select the target cluster.
300 *****************************************************************************************
301 * @ if success, returns child process PID to parent, and return O to child.
302 * @ if failure, returns -1 to parent / no child process is created.
303 ****************************************************************************************/
304int fork();
305
306/*****************************************************************************************
307 * This function implement the "exec" system call on the user side.
308 * It creates, in the same cluster as the calling thread, a new process descriptor,
309 * and a new associated main thread descriptor, executing a new memory image defined
310 * by the <filename> argument. This new process inherit from the old process the PID
311 * and the PPID, as well as all open files (including the TXT).
312 * The old process descriptor, and all its threads are blocked, and marked for deletion.
313 * Therefore the exec syscall does not return to the calling thread in case of success.
314 * This function build an exec_info_t structure containing the new process arguments,
315 * as defined by the <arv> argument, and the new process environment variables,
316 * as defined by the <envp>  argument.
317 * TODO : the <argv> and <envp> arguments are not supported yet (both must be NULL).
318 *****************************************************************************************
319 * @ filename : string pointer on .elf filename (virtual pointer in user space)
320 * @ argv     : array of strings on process arguments (virtual pointers in user space)
321 * @ envp     : array of strings on environment variables (virtual pointers in user space)
322 * @ does not return if success / returns -1 if failure.
323 ****************************************************************************************/
324int exec( char  * filename,
325          char ** argv,
326          char ** envp );
327
328/*****************************************************************************************
329 * This function  returns in the <stat> structure, defined in the "shared_syscalls.h"
330 * file, various informations on the file/directory identified by the <pathname> argument.
331 *****************************************************************************************
332 * @ pathname  : user pointer on file pathname.
333 * @ stat      : user pointer on the stat structure.
334 * @ returns O if success / returns -1 if failure.
335 ****************************************************************************************/
336int stat( const char  * pathname,
337          struct stat * stat );
338
339/*****************************************************************************************
340 * This blocking function returns only when one child process of the calling process
341 * changes state (from RUNNING to STOPPED / EXITED / KILLED). It returns the terminating
342 * child process PID, and set in the <status> buffer the new child process state.
343 *****************************************************************************************
344 * @ status    : [out] terminating child process state.
345 * @ returns terminating child process pid.
346 ****************************************************************************************/
347int wait( int * status );
348
349/****************** Non standard (ALMOS_MKH specific) system calls **********************/
350
351
352/*****************************************************************************************
353 * This function is used to give the process identified by the <pid> argument the
354 * exclusive ownership of the attached TXT_RX terminal.
355 *****************************************************************************************
356 * @ pid        : process identifier.
357 * @ returns O if success / returns -1 if process not found.
358 ****************************************************************************************/
359int fg( unsigned int pid );
360
361/***************************************************************************************
362 * This function returns the hardware platform parameters.
363 ***************************************************************************************
364 * @ x_size   : [out] number of clusters in a row.
365 * @ y_size   : [out] number of clusters in a column.
366 * @ ncores   : [out] number of cores per cluster.
367 * @ return always 0.
368 **************************************************************************************/
369int get_config( unsigned int * x_size,
370                unsigned int * y_size,
371                unsigned int * ncores );
372
373/***************************************************************************************
374 * This function returns the cluster an local index for the calling core.
375 ***************************************************************************************
376 * @ cxy      : [out] cluster identifier.
377 * @ lid      : [out] core local index in cluster.
378 * @ return always 0.
379 **************************************************************************************/
380int get_core( unsigned int * cxy,
381              unsigned int * lid );
382
383/***************************************************************************************
384 * This function returns the calling core cycles counter,
385 * taking into account a possible overflow on 32 bits architectures.
386 ***************************************************************************************
387 * @ cycle    : [out] current cycle value.
388 * @ return always 0.
389 **************************************************************************************/
390int get_cycle( unsigned long long * cycle );
391
392/***************************************************************************************
393 * This debug function displays on the kernel terminal TXT0
394 * the thread / process / core identifiers, the current cycle, plus a user defined
395 * message as specified by the <string> argument.
396 ***************************************************************************************
397 * @ string    : [in] user defined message.
398 **************************************************************************************/
399void display_string( char * string );
400
401/***************************************************************************************
402 * This debug function displays on the kernel terminal TXT0
403 * the state of the process VMM identified by the <pid> argument.
404 * It can be called by any thread running in any cluster.
405 ***************************************************************************************
406 * @ pid      : [in] process identifier.
407 * @ return 0 if success / return -1 if illegal argument.
408 **************************************************************************************/
409int display_vmm( unsigned int  pid );
410
411/***************************************************************************************
412 * This debug function displays on the kernel terminal TXT0
413 * the state of the core scheduler identified by the <cxy> and <lid> arguments.
414 * It can be called by any thread running in any cluster.
415 ***************************************************************************************
416 * @ cxy      : [in] target cluster identifier.
417 * @ lid      : [in] target core local index.
418 * @ return 0 if success / return -1 if illegal arguments.
419 **************************************************************************************/
420int display_sched( unsigned int  cxy,
421                   unsigned int  lid );
422
423/***************************************************************************************
424 * This debug function displays on the kernel terminal TXT0
425 * the list of process registered in a given cluster identified by the <cxy> argument.
426 * It can be called by any thread running in any cluster.
427 ***************************************************************************************
428 * @ cxy      : [in] target cluster identifier.
429 * @ return 0 if success / return -1 if illegal argument.
430 **************************************************************************************/
431int display_process( unsigned int  cxy );
432
433/***************************************************************************************
434 * This debug function displays on the kernel terminal TXT0
435 * the list of channel devices available in the architecture.
436 * It can be called by any thread running in any cluster.
437 ***************************************************************************************
438 * @ return always 0.
439 **************************************************************************************/
440int display_chdev();
441
442/***************************************************************************************
443 * This debug function displays on the kernel terminal TXT0
444 * the list of channel device or pseudo-files registered in the VFS cache.
445 * It can be called by any thread running in any cluster.
446 ***************************************************************************************
447 * @ return always 0.
448 **************************************************************************************/
449int display_vfs();
450
451/*****************************************************************************************
452 * This debug function is used to activate / desactivate the trace for a thread
453 * identified by the <trdid> and <pid> arguments.
454 * It can be called by any other thread in the same process.
455 *****************************************************************************************
456 * @ operation  : operation type.
457 * @ pid        : process identifier.
458 * @ trdid      : thread identifier.
459 * @ returns O if success / returns -1 if illegal arguments.
460 ****************************************************************************************/
461int trace( unsigned int operation,
462           unsigned int pid, 
463           unsigned int trdid );
464
465
466#endif  // _STDIO_H_
Note: See TracBrowser for help on using the repository browser.