Ignore:
Timestamp:
May 16, 2018, 8:31:35 PM (6 years ago)
Author:
satin@…
Message:

add newlib,libalmos-mkh, restructure shared_syscalls.h and mini-libc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/libs/mini-libc/stdio.h

    r443 r444  
    2525#define _STDIO_H_
    2626
    27 #include <shared_syscalls.h>
     27#include <almos-mkh/stdio.h>
    2828
    2929#define  NULL  (void *)0
     30/*********************************************************************************************
     31 * This function writes a formated string to the standard "stdout" stream.
     32 *********************************************************************************************
     33 * @ returns number of characters written if success / returns -1 if failure.
     34 ********************************************************************************************/
     35int printf( const char * format, ... );
    3036
    31 /****************** Standard (POSIX) system calls  **************************************/
     37/*********************************************************************************************
     38 * This function writes one single character to the standard "stdout" stream.
     39 *********************************************************************************************
     40 * @ returns written character code if success / returns 0 (EOF) if failure.
     41 ********************************************************************************************/
     42int putchar( int c );
    3243
    33 /***************************************************************************************** 
    34  * This function terminates a process.
    35  *****************************************************************************************
    36  * @ status   : terminaison status : 0 / EXIT_SUCCESS / EXIT_FAILURE.
    37  ****************************************************************************************/
    38 void exit( int status );
     44/*********************************************************************************************
     45 * This function returns one single character from the standard "stdin" stream.
     46 *********************************************************************************************
     47 * @ returns read character code if success / returns 0 (EOF) if failure.
     48 ********************************************************************************************/
     49int getchar();
    3950
    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  ****************************************************************************************/
    48 int 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  ****************************************************************************************/
    63 void * 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  ****************************************************************************************/
    79 int 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  ****************************************************************************************/
    92 int 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  ****************************************************************************************/
    105 int 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  ****************************************************************************************/
    117 int 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  ****************************************************************************************/
    130 int 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  ****************************************************************************************/
    142 int 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  ****************************************************************************************/
    150 int 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  ****************************************************************************************/
    159 int 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  ****************************************************************************************/
    171 int 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  ****************************************************************************************/
    182 DIR * 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  ****************************************************************************************/
    190 struct 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  ****************************************************************************************/
    199 int 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  ****************************************************************************************/
    208 int 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  ****************************************************************************************/
    218 int 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  ****************************************************************************************/
    227 int 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  ****************************************************************************************/
    238 int 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  ****************************************************************************************/
    249 int 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  ****************************************************************************************/
    262 int 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  ****************************************************************************************/
    280 int 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  ****************************************************************************************/
    288 int 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  ****************************************************************************************/
    304 int 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  ****************************************************************************************/
    324 int 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  ****************************************************************************************/
    336 int 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  ****************************************************************************************/
    347 int wait( int * status );
    348 
    349 
    350 /****************** Non standard (ALMOS_MKH specific) system calls **********************/
    351 
    352 
    353 /*****************************************************************************************
    354  * This function is used to give the process identified by the <pid> argument the
    355  * exclusive ownership of the attached TXT_RX terminal.
    356  *****************************************************************************************
    357  * @ pid        : process identifier.
    358  * @ returns O if success / returns -1 if process not found.
    359  ****************************************************************************************/
    360 int fg( unsigned int pid );
    361 
    362 /***************************************************************************************
    363  * This function returns the hardware platform parameters.
    364  ***************************************************************************************
    365  * @ x_size   : [out] number of clusters in a row.
    366  * @ y_size   : [out] number of clusters in a column.
    367  * @ ncores   : [out] number of cores per cluster.
    368  * @ return always 0.
    369  **************************************************************************************/
    370 int get_config( unsigned int * x_size,
    371                 unsigned int * y_size,
    372                 unsigned int * ncores );
    373 
    374 /***************************************************************************************
    375  * This function returns the cluster an local index for the calling core.
    376  ***************************************************************************************
    377  * @ cxy      : [out] cluster identifier.
    378  * @ lid      : [out] core local index in cluster.
    379  * @ return always 0.
    380  **************************************************************************************/
    381 int get_core( unsigned int * cxy,
    382               unsigned int * lid );
    383 
    384 /***************************************************************************************
    385  * This function returns the calling core cycles counter,
    386  * taking into account a possible overflow on 32 bits architectures.
    387  ***************************************************************************************
    388  * @ cycle    : [out] current cycle value.
    389  * @ return always 0.
    390  **************************************************************************************/
    391 int get_cycle( unsigned long long * cycle );
    392 
    393 /***************************************************************************************
    394  * This debug function displays on the kernel terminal TXT0
    395  * the thread / process / core identifiers, the current cycle, plus a user defined
    396  * message as specified by the <string> argument.
    397  ***************************************************************************************
    398  * @ string    : [in] user defined message.
    399  **************************************************************************************/
    400 void display_string( char * string );
    401 
    402 /***************************************************************************************
    403  * This debug function displays on the kernel terminal TXT0
    404  * the state of the VMM forthe process <pid>, in cluster <cxy>.
    405  * It can be called by any thread running in any cluster.
    406  ***************************************************************************************
    407  * @ pid      : [in] process identifier.
    408  * @ return 0 if success / return -1 if illegal argument.
    409  **************************************************************************************/
    410 int display_vmm( unsigned int  cxy,
    411                  unsigned int  pid );
    412 
    413 /***************************************************************************************
    414  * This debug function displays on the kernel terminal TXT0
    415  * the state of the core scheduler identified by the <cxy> and <lid> arguments.
    416  * It can be called by any thread running in any cluster.
    417  ***************************************************************************************
    418  * @ cxy      : [in] target cluster identifier.
    419  * @ lid      : [in] target core local index.
    420  * @ return 0 if success / return -1 if illegal arguments.
    421  **************************************************************************************/
    422 int display_sched( unsigned int  cxy,
    423                    unsigned int  lid );
    424 
    425 /***************************************************************************************
    426  * This debug function displays on the kernel terminal TXT0
    427  * the list of process registered in a given cluster identified by the <cxy> argument.
    428  * It can be called by any thread running in any cluster.
    429  ***************************************************************************************
    430  * @ cxy      : [in] target cluster identifier.
    431  * @ return 0 if success / return -1 if illegal argument.
    432  **************************************************************************************/
    433 int display_cluster_processes( unsigned int  cxy );
    434 
    435 /***************************************************************************************
    436  * This debug function displays on the kernel terminal TXT0
    437  * the list of channel devices available in the architecture.
    438  * It can be called by any thread running in any cluster.
    439  ***************************************************************************************
    440  * @ return always 0.
    441  **************************************************************************************/
    442 int display_chdev();
    443 
    444 /***************************************************************************************
    445  * This debug function displays on the kernel terminal TXT0
    446  * the list of channel device or pseudo-files registered in the VFS cache.
    447  * It can be called by any thread running in any cluster.
    448  ***************************************************************************************
    449  * @ return always 0.
    450  **************************************************************************************/
    451 int display_vfs();
    452 
    453 /***************************************************************************************
    454  * This debug function displays on the kernel terminal TXT0
    455  * the list of processes attached to a given TXT channel.
    456  * It can be called by any thread running in any cluster.
    457  ***************************************************************************************
    458  * @ return always 0.
    459  **************************************************************************************/
    460 int display_txt_processes( unsigned int txt_id );
    461 
    462 /*****************************************************************************************
    463  * This debug function is used to activate / desactivate the context switches trace
    464  * for a core identified by the <cxy> and <lid> arguments.
    465  * It can be called by any thread running in any cluster.
    466  *****************************************************************************************
    467  * @ active     : activate trace if non zero / desactivate if zero.
    468  * @ cxy        : cluster identifier.
    469  * @ lid        : core local index.
    470  * @ returns O if success / returns -1 if illegal arguments.
    471  ****************************************************************************************/
    472 int trace( unsigned int active,
    473            unsigned int cxy,
    474            unsigned int lid );
    475 
     51/*********************************************************************************************
     52 * This function copies a formated string to a fixed size buffer.
     53 * it includes the NUL terminating character.
     54 * it cheks that the formated string fit in the buffer length.
     55 *********************************************************************************************
     56 * @ string    :  pointer on target buffer.
     57 * @ length    : max bumber of characters in target buffer.
     58 * @ format    : formated string.
     59 * @ returns number of characters written if success / returns -1 if failure.
     60 ********************************************************************************************/
     61int snprintf( char         * string,
     62              unsigned int   length,
     63              const char   * format, ... );
    47664
    47765#endif  // _STDIO_H_
Note: See TracChangeset for help on using the changeset viewer.