= GIET_VM / User-Level System Calls =

The  [source:soft/giet_vm/giet_libs/stdio.c stdio.c] and [source:soft/giet_vm/giet_libs/stdio.h stdio.h] files  define all system calls provided to user applications by the GIET-VM. System calls are prefixed by ''giet_''.

[[PageOutline]]

All these functions use a ''syscall'' instruction to enter the system. 
For most system calls, in case of failure (illegal arguments), the calling thread
is killed with a ''giet_pthread_exit()''. 

 == __Processor related system calls__ ==

These system calls access the MIPS32 protected registers CP0_PROCID and CP0_TIME.

 === 1) void '''giet_proc_xyp'''( unsigned int* cluster_x, unsigned int* cluster_y unsigned int* p )===
Each thread is statically allocated to one processor P[x,y,p] in the boot phase, and there is no thread migration.
This function returns the processor identifiers (x,y,p) for the processor running the calling thread. It access the wired global processor index stored in the CP0_PROCID register.
 The <x> and <y> arguments are the the cluster coordinates. The <p> argument is the processor local index.
The format is CP0_PROCID = ( ( cluster_x << Y_WIDTH + cluster_y ) << P_WIDTH ) + lpid 

 === 2) unsigned int '''giet_proctime'''() ===
This function returns the local processor time from the CP0_TIME register (number of cycles from reset),
This register is a 32 bits wrapping register
 
 === 3) unsigned int '''giet_rand'''() ===
This function returns a pseudo-random value derived from both the CP0_PROCID and CP0_TIME registers.
The value is always between 0 & 65535.


 == __Thread related system calls__ ==

The GIET-VM support a subset of the POSIX Threads API, defined below.
.
The ''pthread_t'' and ''pthread_attr_t'' types are defined in the [source:soft/giet_vm/giet_libs/stdio.h stdio.h] file.

 === 1)  int '''giet_pthread_create'''( pthread_t*  buffer , pthread_attr_t* attr , void* function , void* arg ) ===
This functions activates one thread that will execute the C function defined by the ''function'' argument.
All thread activated by this system call must have been defined in the application mapping.
The ''attr'' argument (pthread attributes) is not supported, and should be set to NULL: The stack size must be defined in the mapping, and the pthread is activated in attached mode. In the current implementation, the ''arg'' argument (argument to be passed to ''function'') is not supported, and should be set to NULL.
The thread identifier stored in the ''buffer'' argument by the kernel is unique in a given space: It is actually build from the 4 following informations : [x,y,p,ltid], where x,y,p are the processor coordinates, and ltid is the thread index in the scheduler.    
 * '''buffer''' : pointer on a buffer that will contain the activated thread identifier.
 * '''attr''' :  not supported in the current implementation / must be set to NULL.
 * '''function''' : pointer on function
 * '''arg''' : not supported in the current implementation / must be set to NULL.
Return 0 if success.
Return -1  if no matching thread.
Return -2  if attr or arg not NULL.

 === 2) void '''giet_pthread_exit'''( void* string ) ===
This function send a KILL signal to the calling thread, that is immediately desactivated, and goes to the ''blocked'' state. All resources dynamically allocated to the thread, such as private peripheral channels are released. An user defined message is displayed on the kernel terminal TTY0.
 * '''string''': message on TTY0.

 === 3) int '''giet_pthread_join'''( pthread_t  trdid , void** ptr ) ===
This blocking function can be used to detect completion of a thread previously activated by a giet_pthread_create().
It returns only when the thread identified by the <trdid> argument is desactivated. 
The <ptr> argument is not supported, and should be set to NULL.
 * '''trdid''' : unique thread identifier in vspace.
 * '''ptr''' : not supported.
Return 0 if success.
Return -1  if no matching thread.
Return -2  if ptr not NULL

 === 4) int '''giet_pthread_kill'''( pthread_t trdid , int signal ) === 
This function send a KILL signal to the thread identified by the <trdid> argument, in the same space as the calling thread.
If the <signal> argument has a non zero value, the target thread will be deactivated at the next context switch.
If the <signal> argument is zero, the thread existence is checked, but the KILL signal it is not sent.
 * '''trdid''' : thread identifier in vspace.
 * '''signal''' : deactivation if non zero.
Return 0 if success.
Return -1 if no matching thread.

 === 5) void '''giet_pthreadt_yield'''() ===
The thread calling this function is descheduled and the processor is allocated to another thread. The calling thread is not deactivated and keep in the ''runable'' state.

The following functions define various GIET_VM specific extensions to the POSIX threads API.

 === 6) void '''giet_pthread_assert'''( unsigned int condition, char* string ) ===
This function is an extension to the POSIX standard. It send a KILL signal and deactivates immediately the calling thread (as does the giet_pthread_exit() function), with a TTY0 message defined by the <string> argument if the <condition> argument has a zero value.
 * '''condition''' : thread exit if condition value is 0.
 * '''string''' : message displayed on TTY0.

 === 7) int '''giet_pthread_pause'''( char* vspace , pthread_t trdid ) ===
This function is an extension to the POSIX standard. It deschedules and deactivates immediately the thread identified by the <vspace> and <trdid> arguments. The target thread goes to the ''blocked'' state, and will not be scheduled until the thread is reactivated by the giet_pthread_resume() function. The thread context (including the resources dynamically allocated to the thread) is not modified.
 * '''vspace''' : vspace name.
 * '''trdid''' : thread identifier in vspace.
Return 0 if success.
Return -1 if no matching thread.

 === 8) int '''get_pthread_resume'''( char* vspace , pthread_t trdid ) === 
This function is an extension to the POSIX standard. It  reactivates a thread identified by the <vspace> and <trdid> arguments, that was descheduled by the gift_pthread_pause() function. The target thread goes to the ''runable'' state, and can be rescheduled at the next context switch to resume execution.
 * '''vspace''' : vspace name.
 * '''trdid''' : thread identifier in vspace.
Return 0 if success.
Return -1 if no matching thread.


 == __Application related system calls__ ==

 === 1) void '''giet_kill_application'''( char* name ) ===
This function kill the application identified by the vspace '''name''' argument: 
All application threads defined in the mapping receive a KILL signal and will be deactivated at the next context switch. The private peripherals or coprocessors are released. The physical memory allocated to the killed application segments is not released.

 === 2) void '''giet_exec_application'''( char* name ) ===
This function starts execution for the the application identified by the vspace '''name''' argument.
The application  data segments are (re)loaded into memory from the .elf file. 
Only thread that has the ''is_main'' flag set  in the mapping is activated.

=== 3) void '''get_applications_status'''( ) ===
This function display on kernel TTY0, for all registered vspace, the status of each thread defined in the space.


 ==  __Coprocessors related system calls__ ==

The GIET_VM allows user applications to use hardware accelerators (called coprocessors). These coprocessors can be distributed in the architecture, but there is at most one coprocessor per cluster. To be supported by the GIET_VM, a coprocessor must use the '''vci_mwmr_dma''' component, that is a generic multi-channels DMA controller.

The '''vci_mwmr_dma''' component provide to coprocessor a variable number of TO_COPROC or FROM_COPROC ports, that implement FIFO interfaces. Coprocessor can request to transfer one or several bursts of 32 bits words, without address. The burst size (generally a cache line), the number of TO_COPROC and FROM_COPROC ports, and the number of bursts for a given port are hardware parameters, depending on the coprocessor type. Each port define a private communication channel between the coprocessor and a user memory buffer. The total number of channels cannot be larger than 16. A channel is identified by an index, and the TO_COPROC channels have the smallest indexes.

The user application must use the ''giet_coproc_alloc()'' system call to get a private hardware coprocessor. Then it must use the ''giet_coproc_channel_init()'' system call to configure the TO_COPROC/FROM_COPROC channels. Finally, the coprocessor and the communication channels are activated by the ''giet_coproc_run()'' system call. 

The '''vci_mwmr_dma''' component implements two transfer modes:
 * In '''MODE_MWMR''', each channel FSM  implements the 7 steps MWMR protocol, and transfer an "infinite" data stream, between one coprocessor port and a MWMR software FIFO in memory. The ''giet_coproc_run()'' system call is non blocking, as the synchronisation is done through the MWMR FIFOs (no transfer completion event). The MWR IRQ is only asserted if a VCI error is reported in a memory access. 
 * In '''MODE_DMA_IRQ''' or '''MODE_DMA_NO_IRQ''', each channel FSM transfers a single buffer between one coprocessor port and the memory, and keep blocked when the transfer is completed. 
   - In '''MODE_DMA_IRQ''', the calling thread is descheduled, after coprocessor activation, in the ''giet_coproc_run()'' system call. It is rescheduled by the MWR IRQ signaling the global completion. The _mwr_isr() scan all channels status registers to report possible addressing errors, and reset the communication channels.
   - In '''MODE_DMA_NO_IRQ''', the ''giet_coproc_run()'' system call returns after coprocessor activation, and the user application must use the blocking ''giet_coproc_completed()'' system call that directly scan the channels registers to detect  completion, report errors, and reset the channels.

'''WARNING''': For a given coprocessor, all channels must be running in the same mode.

'''WARNING''' : For all channels, the memory buffer base address and size  must be multiple of the hardware burst size.

The VCI transactions corresponding to different TO_COPROC / FROM_COPROC channels are interleaved and parallelized on the VCI network. 

Besides the TO_COPROC/FROM_COPROC communication channels, the '''vci_mwmr_dma''' component support up to 16 coprocessor-specific configuration/status registers. 
 * The '''configuration''' registers are Read and Write. 
 * The '''status''' registers are Read only.


The list of currently  supported coprocessors and their characteristics are defined below:
||  coproc_type               ||     Function                             ||nb_to_coproc || nb_from_coproc || nb_config  || nb_status ||  
|| MWR_COPROC_GCD ||   Greater Common Divider      ||    2                 ||          1               ||       1         ||       0        ||
|| MWR_COPROC_DCT  ||   Discrete Cosinus Transform ||    1                 ||          1               ||        1        ||        0       ||
|| MWR_COPROC_CPY  ||   Memory Copy                      ||    1                 ||          1               ||        1        ||       0        ||      

 === 1) void '''giet_coproc_alloc'''( unsigned int   coproc_type , unsigned int* coproc_info ) ===
This function allocates a private coprocessor to the calling thread, taking a lock to grant exclusive ownership, and register the coprocessor coordinates in the thread context.
In the current implementation, the thread exit if there is no coprocessor of requested type in the same cluster as the calling thread.
In case of success, it returns the coprocessor characteristics in the '''coproc_info''' variable.
 * '''coproc_type''' : see supported types above.
 * '''coproc_info''' (return value) :  nb_to_coprocs = info[7:0] / nb_from_coproc = info[15:8] / nb_config = info[23:16] / nb_status = info[31:24]

 === 2) void '''giet_coproc_channel_init'''( unsigned int channel , giet_coproc_channel_t*  desc ) ===
This function initializes a TO_COPROC/FROM_COPROC communication channel. It uses the he following structure (defined in the [source:soft/giet_vm/giet_libs/stdio.h stdio.h] file) to specify the channel parameters:
{{{
typedef struct giet_coproc_channel
{
    unsigned int  channel_mode;    // MWMR / DMA_IRQ / DMA_NO_IRQ
    unsigned int  buffer_size;     // memory buffer size
    unsigned int  buffer_vaddr;    // memory buffer virtual address
    unsigned int  mwmr_vaddr;      // MWMR descriptor virtual address
    unsigned int  lock_vaddr;      // lock for MWMR virtual address
} giet_coproc_channel_t;
}}}
 * '''channel''' communication channel index. TO_COPROC channels use the smallest indexes.
 * '''desc''' pointer on the giet_coproc_channel_t structure.

 === 3) void '''giet_coproc_run'''( unsigned int coproc_reg_index ) ===
This function activates all communication channels and the allocated coprocessor itself.
 * '''coproc_reg_index''' : coprocessor configuration register index to be written for coprocessor activation.

 === 4) void '''giet_coproc_completed'''( ) ===
This blocking function can be used to synchronize a software thread with an hardware coprocessor running in DMA_NO_IRQ mode.
It polls the status register of all communication channels, and returns only when all transfers are completed. 
This function exit when at least one channel status register indicates a  bus error (illegal memory access). 

 === 5) void '''giet_coproc_release'''( unsigned int coproc_reg_index ) ===
 This function releases the coprocessor allocated to the calling thread, after deactivation.
 * '''coproc_reg_index''' : coprocessor configuration register index to be written for coprocessor deactivation.


 ==  __TTY related system calls__ ==

The GIET_VM allows an user thread to use a private TTY terminal, or to display log message on the kernel TTY0 terminal.

 === 1) void '''giet_tty_alloc'''( unsigned int shared ) ===
If the '''shared''' argument has a zero value, this function allocates a private terminal : the TTY terminal index is registered only in the calling thread context. 
If the '''shared''' argument has a non-zero value, it allocate a shared terminal : the same TTY terminal index is registered in the thread context of all threads that are in the same vspace as the calling thread.
The calling thread exit if no TTY terminal available. 

WARNING: A shared TTY should be protected by an user-level lock.

  === 2) void '''giet_tty_printf'''( char* format, ... ) ===
This function print formated text on a private terminal that must have been allocated to the calling thread by the ''get_tty_alloc()'' function. Therefore,  it does not take any lock, but checks terminal allocation. 
Only a limited number of formats are supported:
   * %d : signed decimal
   * %u : unsigned decimal
   * %x : 32 bits hexadecimal
   * %l : 64 bits hexadecimal
   * %c : char
   * %s : string
thread exit if  private terminal index not defined, or in case of illegal format. 

 === 3) void '''giet_tty_getc'''( char* byte ) ===
This blocking function fetches a single character from the private terminal that must have been previously allocated to the calling thread. It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer. The thread exit if a threadprivate TTY index not defined.

 === 4) void '''giet_tty_getw'''( unsigned int* val ) ===
This blocking function fetches a string of decimal characters (most significant digit first) to build a 32-bits unsigned integer from the private TTY terminal  that must have been allocated to the calling thread. It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer.
The non-blocking system function _tty_read is called several times, and the decimal characters are written in a 32 characters buffer until a <LF> character is read. It ignores non-decimal characters, and displays an echo  for each decimal character. The <DEL> character is interpreted, and previous characters can be cancelled.  When the <LF> character is received, the string is converted to an unsigned int value. If the number of decimal digit is too large for the 32 bits range, the zero value is returned.
The thread threadexit if private TTY index not defined.

 === 5) void '''giet_tty_gets'''( char* buf, unsigned int bufsize ) ===
This blocking function fetches a string from the private terminal that must have been allocated to the calling threadthread. It writes the string to a fixed length buffer.
It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer.
Up to (bufsize - 1) characters (including the non printable characters) are copied into buffer, and the string is completed by a NUL character. The <LF> character is interpreted, and the function close the string with a NUL character if <LF> is read. The <DEL> character is interpreted, and the corresponding character(s) are removed from the target buffer. It does not provide an echo.
The thread exit if a private TTY index is threadnot defined.

 ==  __Timer related system calls__ ==

The GIET_VM allows an user thread to activate a private timer channel, generating periodical IRQs. This timer is allocated in the external multi-timers peripheral.

 === 1) void '''giet_timer_alloc'''()
This function allocates a private user timer  to the calling thread, and registers the channel index in the thread context.
The thread exit if no timer channel is available

 === 2) void '''giet_timer_start'''( unsigned int period )
This function starts the private timer allocated to the calling thread.
The thread exit if no channel is allocated to the calling thread.

 === 3) void '''giet_timer_stop'''( ) ===
This function stops the private timer allocated to the calling thread.
The thread exit if no channel is allocated to the calling thread.

 ==  __File system related system calls__ ==

The Giet-VM supports a FAT32 file system, and uses distributed data structures to access the file system:
 * The Inode-Tree (distributed on all clusters) is the internal representation of the File System tree.
 * The Fat-Cache (distributed on all clusters) is used to cache the FAT region of the block device.
 * The File-Cache (distributed on all clusters / one cache per open file) is used to cache the DATA region of the block device.
 * The File-Descriptor-Array (in cluster[0,0]) contains the open files descriptors.
 * The Fat-Descriptor (in cluster[0,0] contains the FAT32 general information.

The error code map (negative values) is defined in the  [source:soft/giet_vm/giet_fat32/fat32_shared.h fat32_shared.h] file.
 
=== 1) int '''giet_fat_open'''( char* pathname, unsigned int flags ) ===
This function allocates a file descriptor to the calling thread, for the file identified by its absolute ‘’<pathname>. 
If several threads try to open the same file, each thread obtains a private file descriptor.
The semantic is similar to the UNIX open() function, but the UNIX access rights are not supported. 
The two following flags are supported, and can be ''ored'' to define the <flags> argument:
 * O_RDONLY (0x01) : file accessed as read-only. Default is read/write.
 * O_CREATE  (0x20) : file created if it does not exist on disk. Default is no creation.
If one of the directories specified in the paththread does not exist, an error is returned.

WARNING : A single node name (file or directory) cannot be larger than 33 characters. 

Returns file descriptor index if success.
Returns a negative value if error.


=== 2)  int '''giet_fat_close'''( unsigned int fd_id ) ===
Close a file identified by the ''fd_id'' file descriptor.
It decrements the reference count in the inode associated to the file, and release the fd_id entry in the file descriptors array.
If the reference count is zero, it writes all dirty clusters on block device, and releases the memory allocated to the file_cache.

Returns 0 if success.
Returns a negative value if error.

=== 3) int '''get_fat_file_info'''( unsigned int fd_id , unsigned int* size , unsigned int* offset ) ===
This function returns the "size" and the current "offset" value for a file identified  by the "fd_id" argument. 

Returns 0 if success.
Returns a negative value if error.

=== 4) int '''giet_fat_read'''( unsigned int fd_id , void* buffer , unsigned int count ) ===
This function has the same semantic as the UNIX "read()" function. It transfers "count" bytes from the kernel File_Cache associated to the file identified by "fd_id", to the user "buffer", starting from the current file offset. The offset value is incremented by count.
In case of miss in the File_Cache, it loads all involved clusters into cache.

Returns number of bytes actually transferred if success.
Returns 0 if (offset + count) is larger than the file size. 
Returns a negative value if error.


 === 5) int '''giet_fat_write'''( unsigned int fd_id , void* buffer, unsigned int count ) ===
This function has the same semantic as the UNIX "write()" function. It transfers "count" bytes from the user "buffer" to the kernel File_Cache associated to the file identified by "fd_id", starting from the current file offset. The offset value is incremented by count. It increases the file size and allocate new clusters if (count + offset) is larger than the current file size. Then it loads and updates all involved clusters in the cache.
The FAT region on block device is updated if new clusters are allocated, but the block device DATA region is NOT updated.

Returns number of bytes actually transferred if success.
Returns a negative value if error.

=== 6) int '''giet_fat_lseek'''( unsigned int fd_id , unsigned int offset , unsigned int whence ) ===
This function has the same semantic as the UNIX lseek() function.
It repositions the offset in the file descriptor "fd_id", according to the "offset" and "whence" arguments.
The two accepted values for the whence argument are 
 * SEEK_SET (0) : new_offset <= offset
 * SEEK_CUR (1) : new_offset <= current_offset + offset

Returns new offset value (bytes) if success.
Returns a negative value if error.

=== 7) int '''giet_fat_remove'''( char* pathname , unsigned int should_be_dir ) ===
This function has the same semantic as the UNIX unlink() function.
It deletes a file identified by the absolute "pathname" argument from the sile system.
An error is reported if the references count (number of open file descriptor) is not zero.
All clusters allocated to this file in the block device DATA region are released.
The Inode-Tree is updated.
the Fat-Cache is updated, and the FAT region is updated on the block device. 
The memory allocated for the associated File_Cache is released.

Returns 0 if success.
Returns a negative value if error.

=== 8) int '''get_fat_rename'''( char* old_path , char* new_path )===
This function has the same semantic as the UNIX rename() function.
It  causes the node identified by <old_path> to be renamed as <new_path>.  If <new_path>  exists, it is first removed.
Both <old_path> and <new_path> must be of the same type (either directories or non directories).

Returns 0 if success.
Returns a negative value if error.

=== 9) int '''giet_fat_mkdir'''( char* pathname ) ===
This function has the same semantic as the UNIX mkdir() function.
It creates in the file system the directory specified by the absolute "pathname" argument.  
The Inode-Tree is updated.
One cluster is allocated to the new directory, containing the "." and ".." entries.
The associated File-Cache is created.
The Fat-Cache is updated, and the FAT region on block device is updated.
The DATA region on block device is updated.

Returns 0 if success.
Returns a negative value if error.

=== 10) int '''giet_fat_opendir'''( char* pathname ) ===
This function allocates a file descriptor to the calling thread, for the directory identified by its absolute <pathname>. 

Returns the file descriptor associated to the diredtory if success.
Returns a negative value if error.

=== 11) int '''giet_fat_closedir'''( unsigned int fd_id ) ===
Close a directory identified by the <fd_id> file descriptor.
It decrements the reference count in the inode associated to the directory, 
and release the fd_id entry in the file descriptors array.

Returns 0 if success.
Returns a negative value if error.

=== 12) int '''giet_fat_readdir'''( unsigned int fd_id , fat_dirent_t* entry ) ===
This function access one directory entry identified by the  <fd_id> argument (obtained by the
giet_fat_opendir() function), and writes the relevant informations to the <entry> argument.
This includes the cluster, size, is_dir, and name.

Returns 0 if success.
Returns a negative value if error.


 == __Network related system call__ ==

The GIET_VM allows a user application to get and use a private NIC channel, using the CMA component (chained buffers DMA) to transfer packets to or an user buffer.
The NIC channel and the CMA channel are registered in the threads contexts.

 === 1) void '''giet_nic_tx_alloc'''( unsigned int xmax,  unsigned int ymax) ===
This function must be called by one single thread (typically the main() ). It allocates a private NIC_TX channel (coming with the associated kernel NIC_TX chbuf), and a private CMA_TX channel  to an application. It registers these NIC_TX and CMA_TX channels in the contexts of all threads that are in the same vspace as the calling thread. These NIC and CMA channels are therefore shared by all thread of a multi-threads application. 
The packets are transfered by the hardware to the NIC from a distributed kernel chbuf (one 4 Kbytes container per cluster), where the number of involved clusters is defined by the <xmax> & <ymax> arguments. The (xmax / ymax) arguments cannot be larger than (X_SIZE / Y_SIZE) defining the max number of clusters in the platform, but they can be smaller.
The calling thread exit if no available NIC_TX channel,  if no available CMA channel, if (xmax / ymax) are too large, or if there is not enough memory for the distributed kernel containers in one selected cluster.

 === 2) void '''giet_nic_rx_alloc'''( unsigned int xmax,  unsigned int ymax ) ===
This function must be called by one single thread (typically the main() ). It allocates a private NIC_RX channel (coming with the associated kernel NIC_RX chbuf), and a private CMA channel  to an application. It registers these NIC_RX and CMA_RX channels in the contexts of all threads that are in the same space as the calling thread. These NIC and CMA channels are therefore shared by all threads of a multi-threads application.
The packets are transfered by the hardware from the NIC to a distributed kernel chbuf (one 4 Kbytes container per cluster), where the number of involved clusters is defined by the <xmax> & <ymax> argumentss. The (xmax / ymax) arguments cannot be larger than (X_SIZE / Y_SIZE) defining the max number of clusters in the platform, but they can be smaller.
The calling thread exit if no available NIC_TX channel,  if no available CMA channel, if (xmax / ymax) are too large, or if there is not enough memory for the distributed kernel containers in one selected cluster.

 === 3) void '''giet_nic_tx_start'''( ) ===
This function  must be called by one single thread (typically the main() ). It activates both the NIC_TX channel, and the CMA_TX channel allocated to an application, to start the transfer of packets from the distributed kernel chbuf to the NIC.
The calling thread exit if no allocated NIC_TX channel or no allocated CMA_TX channel. 

 === 4) void '''giet_nic_rx_start'''( ) ===
This function  must be called by one single thread (typically the main() ). It activates both the NIC_RX channel, and the CMA_RX channel allocated to an application, to start the transfer of packets from the NIC to the distributed kernel chbuf.
The calling thread exit if no allocated NIC_RX channel or no allocated CMA_RX channel.

 === 5) void '''giet_nic_tx_move'''(  void* buffer ) ===
This blocking function transfer one container (4 Kbytes)  from an user buffer to the kernel chbuf defined by the NIC_TX channel registered in the calling thread context. The <buffer> argument is the container base address in user space.
Several user threads can concurrently access the same chbuf, because the syscall handler takes the lock protecting the chbuf. It returns only when the container has been fully transfered.
The calling thread exit if the buffer is not in user space, or if no allocated NIC_TX channel, or in case of timeout. 

 === 6) void '''giet_nic_rx_move'''( void* buffer ) ===
This blocking function transfer one container (4 Kbytes)  from the kernel chbuf defined by the NIC_TX channel registered in the calling thread context to an user buffer. The <buffer> argument is the container base address in user space.
Several user threads can concurrently access the same chbuf, because the syscall handler takes the lock protecting the chbuf. It returns only when the container has been fully transfered.
The calling thread exit if the buffer is not in user space, or if no allocated NIC_RX channel, or in case of timeout. 

 === 7) void '''giet_nic_tx_stop'''( ) ===
This function must be called by one single thread (typically the main() ). It desactivates both the NIC_TX channel and the CMA_TX channel allocated to the calling thread.
The calling thread exit if no allocated NIC_TX channel or no allocated CMA_TX channel.

 === 8) void '''giet_nic_rx_stop'''( ) ===
This function  must be called by one single thread (typically the main() ). It desactivates both the NIC_RX channel and the CMA channel allocated to the calling thread.
The calling thread exit if no allocated NIC_RX channel or no allocated CMA channel.

 === 9) void '''giet_nic_rx_clear'''( ) ===
This function reset all instrumentation (packets counters) associated to the RX channels.

 === 10) void '''giet_nic_tx_clear'''( ) ===
This function reset all instrumentation (packets counters) associated to the TX channels.

 === 11) void '''giet_nic_rx_stats'''( ) ===
This function display on kernel TTY0 the content of the instrumentation registers associated to the RX channels.

 === 12) void '''giet_nic_tx_stats'''( ) ===
This function display on kernel TTY0 the content of the instrumentation registers associated to the TX channels.


 == __Frame Buffer related system calls__ ==

To display images, an user thread can access the frame buffer through a memcpy() or through the ''Chained Buffer DMA'' controller (called CMA). 
The four first functions use a private CMA channel that is registered in the thread context. The Two last functions use a memcpy().

 === 1) void '''giet_fbf_cma_alloc'''()
This function allocates a private CMA channel  to the calling thread, and registers the channel index
in the thread context.
The threadthread exit if no CMA channel available

 === 2) void '''giet_fbf_cma_init_buf'''( void* buf0_vbase , void* buf1_vbase , void* sts0_vaddr , void* sts1_vaddr ) ===
This function initializes the chained buffer descriptors for the two source buffers and the frame buffer.
The buf0 and buf1 user buffers must be large enough to store a complete image, and must be aligned on a 64 bytes boundary.
The sts0 and sts1 user buffers contain just a Boolean, but they must be large enough to store 64 bytes, and must be aligned on a 64 bytes boundary.
 * '''buf0_vbase''' : virtual address of the first data buffer.
 * '''buf1_vbase''' : virtual address of  the second  data buffer,
 * '''sts0_vaddr''' : virtual address of the first buffer status.
 * '''sts1_vaddr''' : virtual address of the second buffer status.

 === 3) void '''giet_fbf_cma_start'''( unsigned int length ) ===
This function activates the transfer of a stream of images from two user buffers to the frame buffer. It must be used in conjunction with the giet_fbf_cma_display() function. The chained buffer descriptors should have been initialized by the giet_fbf_cma_init_buf() function.
 * '''length''' is the size of the image (bytes). 

 === 4) void '''giet_fbf_cma_display'''( unsigned int buffer ) ===
This function enables the transfer of the specified buffer.
 * '''buffer''' is the buffer index (0 or 1).

 === 5) void '''giet_fbf_cma_stop'''( ) ===
This function desactivates the CMA channel allocated to the calling thread.

 === 6) void '''giet_fbf_sync_read'''( unsigned int offset , void* buffer , unsigned int length ) ===
This blocking function use a memcopy strategy to transfer data from the frame buffer to an user buffer.
 * '''offset''' defines the offset (in bytes) in the frame buffer,
 * '''buffer'''  is the user buffer base address,
 * '''length'''  is the number of bytes to be transfered. 

 === 7) void '''giet_fbf_sync_write'''( unsigned int offset , void* buffer , unsigned int length ) ===
This blocking function use a memcopy strategy to transfer data from an user buffer to the frame buffer.
 * '''offset''' defines the offset (in bytes) in the frame buffer,
 * '''buffer'''  is the user buffer base address,
 * '''length'''  is the number of bytes to be transfered. 


==  __Miscelaneous system calls__ ==

 === 1) void '''giet_procs_number'''( unsigned int* x_size , unsigned int* y_size , unsigned int* nprocs ) ===
This function returns the actual number of processors in a clusterized 2D mesh architecture. The <x_size> argument is the number of clusters containing processors in a row. The <y_size> argument is the number of clusters containing processors in a column. The <nprocs> argument is the number of processors per cluster.

 === 2) void '''giet_vseg_get_vbase'''( char* vspace_name, char*  vseg_name, unsigned int* vbase) ===
This function returns in the <vbase> argument the virtual base address of a vseg defined in the mapping_info data structure. The vseg is identified by the <vspace_name> and <vseg_name> arguments. In case of error (such as undefined vspace or undefined vseg), the calling thread exit.

 === 3) void '''giet_vseg_get_length'''( char* vspace_name, char*  vseg_name, unsigned int* length) ===
This function returns in the <length> argument the length (bytes) of a vseg defined in the mapping_info data structure. 
The vseg is identified by the <vspace_name> and <vseg_name>. In case of error (such as undefined vspace or undefined vseg), the calling thread exit.

 === 4) void '''giet_heap_info'''( unsigned int* vaddr, unsigned int* length, unsigned int  x, unsigned int  y );
This function returns in the <vaddr> and <length> arguments the characteristics of the user heap located in cluster[x,y] and defined in the space running the calling thread. In case of error (such as undefined heap segment in the selected cluster, or illegal cluster coordinates) it returns <vaddr> = <length> = 0.

 === 5) void '''giet_get_xy'''( void* ptr, unsigned int* px, unsigned int* py ) ===
This function returns through the <px> and <py> arguments the coordinates of the cluster containing the physical address associated to the <ptr> argument containing a virtual address. In case of error (unmapped virtual address), the calling thread exit.