source: trunk/libs/stdio.h @ 428

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

The "nostdio" library has been integrated in the stdio library.
File size: 25.6 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 POSIX "kill" system call.
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 *****************************************************************************************
271 * @ pid      : target process identifier.
272 * @ sig_id   : index defining the signal type (from 1 to 31).
273 * @ return 0 if success / returns -1 if failure.
274 ****************************************************************************************/
275int kill( unsigned int  pid,
276          unsigned int  sig_id );
277
278/*****************************************************************************************
279 * This function implements the POSIX "getpid" system call.
280 *****************************************************************************************
281 * @ returns the process PID for the calling thread process.
282 ****************************************************************************************/
283int getpid();
284
285/*****************************************************************************************
286 * This function implement the POSIX "fork" system call.
287 * The calling process descriptor (parent process), and the associated thread descriptor
288 * are replicated in the same cluster as the calling thread, but the new process (child
289 * process) is registered in another target cluster, that is the new process owner.
290 * The child process and the associated main thread will be migrated to the target cluster
291 * later, when the child process makes an "exec" or any other system call.
292 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
293 * stored in the calling thread descriptor by the specific fork_place() system call.
294 * If not, the kernel function makes a query to the DQDT to select the target cluster.
295 *****************************************************************************************
296 * @ returns child process PID if success / returns -1 if failure
297 ****************************************************************************************/
298int fork();
299
300/*****************************************************************************************
301 * This function implement the "exec" system call.
302 * It is executed in the client cluster, but the new process descriptor and main thread
303 * must be created in a server cluster, that is generally another cluster.
304 * - if the server_cluster is the client cluster, call directly the process_make_exec()
305 *   function to create a new process, and launch a new thread in local cluster.
306 * - if the target_cluster is remote, call rpc_process_exec_client() to execute the
307 *   process_make_exec() on the remote cluster.
308 * In both case this function build an exec_info_t structure containing all informations
309 * required to build the new process descriptor and the associated thread.
310 * Finally, the calling process and thread are deleted.
311 *****************************************************************************************
312 * @ filename : string pointer on .elf filename (virtual pointer in user space)
313 * @ argv     : array of strings on process arguments (virtual pointers in user space)
314 * @ envp     : array of strings on environment variables (virtual pointers in user space)
315 * @ returns O if success / returns -1 if failure.
316 ****************************************************************************************/
317int exec( char  * filename,
318          char ** argv,
319          char ** envp );
320
321/*****************************************************************************************
322 * This function  returns in the <stat> structure, defined in the "shared_syscalls.h"
323 * file, various informations on the file/directory identified by the <pathname> argument.
324 *****************************************************************************************
325 * @ pathname  : user pointer on file pathname.
326 * @ stat      : user pointer on the stat structure.
327 * @ returns O if success / returns -1 if failure.
328 ****************************************************************************************/
329int stat( const char  * pathname,
330          struct stat * stat );
331
332/*****************************************************************************************
333 * This blocking function returns only when one child process of the calling process
334 * changes state (from RUNNING to STOPPED / EXITED / KILLED). It returns the terminating
335 * child process PID, and set in the <status> buffer the new child process state.
336 *****************************************************************************************
337 * @ status    : [out] terminating child process state.
338 * @ returns terminating child process pid.
339 ****************************************************************************************/
340int wait( int * status );
341
342/****************** Non standard (ALMOS_MKH specific) system calls **********************/
343
344
345/*****************************************************************************************
346 * This function is used to give the process identified by the <pid> argument the
347 * exclusive ownership of the attached TXT_RX terminal.
348 *****************************************************************************************
349 * @ pid        : process identifier.
350 * @ returns O if success / returns -1 if process not found.
351 ****************************************************************************************/
352int fg( unsigned int pid );
353
354/***************************************************************************************
355 * This function returns the hardware platform parameters.
356 ***************************************************************************************
357 * @ x_size   : [out] number of clusters in a row.
358 * @ y_size   : [out] number of clusters in a column.
359 * @ ncores   : [out] number of cores per cluster.
360 * @ return always 0.
361 **************************************************************************************/
362int get_config( unsigned int * x_size,
363                unsigned int * y_size,
364                unsigned int * ncores );
365
366/***************************************************************************************
367 * This function returns the cluster an local index for the calling core.
368 ***************************************************************************************
369 * @ cxy      : [out] cluster identifier.
370 * @ lid      : [out] core local index in cluster.
371 * @ return always 0.
372 **************************************************************************************/
373int get_core( unsigned int * cxy,
374              unsigned int * lid );
375
376/***************************************************************************************
377 * This function returns the calling core cycles counter,
378 * taking into account a possible overflow on 32 bits architectures.
379 ***************************************************************************************
380 * @ cycle    : [out] current cycle value.
381 * @ return always 0.
382 **************************************************************************************/
383int get_cycle( unsigned long long * cycle );
384
385/***************************************************************************************
386 * This debug function displays on the kernel terminal TXT0
387 * the thread / process / core identifiers, the current cycle, plus a user defined
388 * message as specified by the <string> argument.
389 ***************************************************************************************
390 * @ string    : [in] user defined message.
391 **************************************************************************************/
392void display_string( char * string );
393
394/***************************************************************************************
395 * This debug function displays on the kernel terminal TXT0
396 * the state of the process VMM identified by the <pid> argument.
397 * It can be called by any thread running in any cluster.
398 ***************************************************************************************
399 * @ pid      : [in] process identifier.
400 * @ return 0 if success / return -1 if illegal argument.
401 **************************************************************************************/
402int display_vmm( unsigned int  pid );
403
404/***************************************************************************************
405 * This debug function displays on the kernel terminal TXT0
406 * the state of the core scheduler identified by the <cxy> and <lid> arguments.
407 * It can be called by any thread running in any cluster.
408 ***************************************************************************************
409 * @ cxy      : [in] target cluster identifier.
410 * @ lid      : [in] target core local index.
411 * @ return 0 if success / return -1 if illegal arguments.
412 **************************************************************************************/
413int display_sched( unsigned int  cxy,
414                   unsigned int  lid );
415
416/***************************************************************************************
417 * This debug function displays on the kernel terminal TXT0
418 * the list of process registered in a given cluster identified by the <cxy> argument.
419 * It can be called by any thread running in any cluster.
420 ***************************************************************************************
421 * @ cxy      : [in] target cluster identifier.
422 * @ return 0 if success / return -1 if illegal argument.
423 **************************************************************************************/
424int display_process( unsigned int  cxy );
425
426/***************************************************************************************
427 * This debug function displays on the kernel terminal TXT0
428 * the list of channel devices available in the architecture.
429 * It can be called by any thread running in any cluster.
430 ***************************************************************************************
431 * @ return always 0.
432 **************************************************************************************/
433int display_chdev();
434
435/***************************************************************************************
436 * This debug function displays on the kernel terminal TXT0
437 * the list of channel device or pseudo-files registered in the VFS cache.
438 * It can be called by any thread running in any cluster.
439 ***************************************************************************************
440 * @ return always 0.
441 **************************************************************************************/
442int display_vfs();
443
444/*****************************************************************************************
445 * This debug function is used to activate / desactivate the trace for a thread
446 * identified by the <trdid> and <pid> arguments.
447 * It can be called by any other thread in the same process.
448 *****************************************************************************************
449 * @ operation  : operation type.
450 * @ pid        : process identifier.
451 * @ trdid      : thread identifier.
452 * @ returns O if success / returns -1 if illegal arguments.
453 ****************************************************************************************/
454int trace( unsigned int operation,
455           unsigned int pid, 
456           unsigned int trdid );
457
458
459#endif  // _STDIO_H_
Note: See TracBrowser for help on using the repository browser.