= GIET-VM  / Syscall Handler =

The [source:soft/giet_vm/giet_kernel/sys_handler.c sys_handler.c] and [source:soft/giet_vm/giet_kernel/sys_handler.h sys_handler.h] files define the kernel data structure and functions that are used to handle the system calls. These functions are prefixed by ''_'' to remind that they can only be executed by a processor in kernel mode.

[[PageOutline]]

The [source:soft/giet_vm/giet_kernel/sys_handler.c _syscall_vector] array contains the 64 kernel functions (syscal handlers) defined by the GIET-VM to handle system calls.


== __TTY related syscall handlers__ ==

=== int '''_sys_tty_alloc'''() ===
This function allocates a private TTY terminal to the calling task, and registers the TTY index in the task context.
Returns 0 if success, returns -1 if not enough terminals.

=== int '''_sys_tty_write'''( const char*  buffer,  unsigned int length,  unsigned int channel ) ===  
This non-blocking function writes a character string from a fixed-length buffer to a TTY terminal identified by the channel argument. If channel argument is 0xFFFFFFFF, the TTY index is found in the task context. 
It is non blocking: it tests the TTY_STATUS register, and stops the transfer as soon as the TTY_STATUS[WRITE] bit is set. Returns -1 if no TTT terminal allocated to the calling task. Returns  the number of characters that have been written if a terminal is allocated.

=== int '''_sys_tty_read'''(  char* buffer,  unsigned int length,  unsigned int channel ) === 
This non-blocking function fetches one character from the terminal identified by the ''channel'' argument. If the ''channel'' argument is 0xFFFFFFFF, the TTY index is obtained from the current task context. 
It uses the TTY_GET_IRQ[tty_id] interrupt and the buffer must have been filled by the TTY_ISR.
It test the _tty_rx_full[tty_id] variable, read the _tty_rx_buf[tty_id] buffer, writes this character to the target buffer, and resets the_tty_rx_full[tty_id] register. The length argument is not used.
Returns -1 if no TTY terminal allocated to the calling task. Returns  the number of characters that have been read if a terminal is allocated (can be 0 or 1).

=== int '''_sys_tty_get_lock'''( unsigned int  channel,   unsigned int* save_sr_ptr ) ===
This blocking function try to take the lock protecting exclusive access to TTY terminal identified by the "channel" argument. It enters a critical section before taking the lock, and save the SR value at address defined by the ''save_sr_ptr'' argument. Returns -1 if no TTY terminal allocated to the calling task. If a TTY terminal is allocated, it returns only when the lock has been successfully taken.

=== int '''_sys_tty_release_lock'''( unsigned int  channel,  unsigned int* save_sr_ptr ) ===
This function releases the lock protecting exclusive access to TTY terminal identified by the ''channel'' argument.
It exit the critical section after lock release, and restore SR value from address defined by the ''save_sr_ptr'' argument. Returns -1 if no TTY terminal allocated to the calling task. 



== __TIM retated syscall handlers__ ==

=== int '''_sys_tim_alloc'''() ===
This function allocates a private timer to the calling task, and register the timer index in the task context.
Return -1 if no timer available.

=== int '''_sys_tim_start'''( unsigned int period ) ===
This function starts the user timer channel allocated to the calling task.
Returns 0 if success. Returns -1 if no allocated timer.

=== int '''_sys_tim_stop'''() ===
This function stops the user timer channel allocated to the calling task.
Returns 0 if success. Returns -1 if no allocated timer.



== __NIC related syscall handlers__ ==

=== int '''_sys_nic_alloc'''() ===
This function allocates a private NIC channel to the calling task, and register the channel index in the task context.
Return -1 if no NIC channel available.

=== int '''_sys_nic_sync_send'''( void* vbuf ) ===
This function uses a physical_memcpy() to transfer a 4kbytes container from an user buffer to a private NIC TX channel. It computes the physical base address associated to the user buffer. Returns 0 if success, returns -1 if the buffer address is illegal, or if there is no  NIC channel allocated to the calling task.

=== int '''_sys_nic_sync_receive'''( void* vbuf ) ===
This function uses a physical_memcpy() to transfer a 4kbytes container from a private NIC RX channel to an user buffer. It computes the physical base address associated to the user buffer. Returns 0 if success, returns -1 if the buffer address is illegal, or if there is no  NIC channel allocated to the calling task.



== __ FBF related syscall handlers__==

There exist two methods to access the ''vci_framebuffer'':
 * The _sys_fbf_sync_write() and _sys_fbf_sync_read() functions use a memcpy strategy to implement the transfer between a data buffer (user space) and the frame buffer (kernel space). They are blocking until completion of the transfer.
 * The _sys_fbf_cma_alloc(), _sys_fbf_cma_start(),  _sys_fbf_cma_display(), and _sys_fbf_cma_stop() functions use the ''vci_chbuf_dma'' component to transfer a stream of images from an user space chained buffer (two buffers) to the frame buffer. 
 
 === int '''_sys_fbf_sync_write'''( unsigned int offset,  void* buffer,   unsigned int length ) ===
This function transfer data from an user buffer to the frame_buffer device using a memcpy. 
 * '''offset''' : offset (in bytes) in the frame buffer.
 * '''buffer''' : base address of the memory buffer.
 * '''length''' : number of bytes to be transfered.

 === int '''_sys_fbf_sync_read'''( unsigned int offset,  void* buffer,   unsigned int length ) ===
This function transfer data from the frame_buffer device to anuser buffer using a memcpy.
 * '''offset''' : offset (in bytes) in the frame buffer.
 * '''buffer''' : base address of the memory buffer.
 * '''length''' : number of bytes to be transfered.

 === int '''_sys_fbf_cma_alloc'''() ===
This function allocates a private CMA channel to the calling task, and register the channel index in the task context.
Return -1 if no CMA channel available.
 
 === int '''_sys_fbf_cma_start'''( void* vbase0,  void* vbase1,  unsigned int length ) ===
This function initializes the CMA channel to start the transfer of a stream of images from an user chbuf (two buffers) to the frame buffer chbuf (one single buffer). The user buffers must be aligned on a word boundary.
 * '''vbase0''' : virtual base address of the first user buffer.
 * '''vbase1''' : virtual base address of the second user buffer.
 * '''length''' : buffer length (bytes)
It uses the _fbf_chbuf[] and _fbf_chbuf_paddr[] arrays, that are both indexed by the channel index, and makes the following actions: 
1. it computes the physical addresses for the two source user buffers, for the destination frame buffer, and initializes the channel descriptor _fbf_chbuf[i].
2. it computes the physical address for the chbuf descriptor and register it in the _fbf_chbuf_paddr[i]. 
3. it makes a SYNC request to L2 cache for channel descriptor if the IOB is used, because the channel descriptor is directly accessed in XRAM by the CMA component.
4. it Starts the CMA hardware channel, that will poll the channel descriptor to fransfer an user buffer to the frame buffer as soon as the source user buffer is marked valid.
Return 0 in case of success. 
Return -1 if no CMA channel allocated to the calling task, or if user buffers not aligned on a word boundary.

 === int '''_sys_fbf_cma_display'''( unsigned int index ) ===
This function is used in conjunction with the _fbf_cma_start() function, and must be called each time a new user buffer is available for display, to set the user buffer status in the chbuf descriptor.
The '''buffer'''  argument define the user buffer index (0 => buf0 / not 0 => buf1).
It makes the following actions if the IO Bridge component is used:
1. it makes an INVAL request for the channel descriptor, before testing the source buffer status, because it is modified in XRAM by the CMA component.
2. it makes a SYNC request for the source user buffer before activating the CMA  transfer, because the data will be read from XRAM by the CMA component.
3. it makes a SYNC request for the channel descriptor after modification of the SRC and DST status, because these descriptors will be read from XRAM by the CMA component.
Return 0 in case of success.
Return -1 if no CMA channel allocated to the calling task.

 === int '''_sys_fbf_cma_stop'''() ===
This function  desactivares the CMA channel  allocated to the calling task.
Return 0 in case of success.
Return -1 if no CMA channel allocated to the calling task.




== __Miscelaneous syscall handlers__ ==

=== int '''_sys_ukn'''() ===
Function executed in case of undefined syscall

=== int '''_sys_proc_xyp'''( unsigned int* x,  unsigned int*,   unsigned int* p ) ===
This function returns the processor (x,y,p) identifiers.

=== int '''_sys_task_exit'''() ===
The calling task goes to sleeping state, after printing an exit message.
It is descheduled and enters the "not runable" mode.

 === int '''_context_switch'''() ===
This function deschedules the calling task. It mask interrupts before calling the _ctx_switch, and restore it when the task is rescheduled.

 === int '''_sys_local_task_id'''() ===
This function returns the current task local index (amongst tasks running on a given processor).

 === int ''_sys'_global_task_id'''() ===
This function returns the current task global index (amongst all tasks running on all processors).

=== int '''_sys_thread_id'''() ===
This function returns the current task thread index (amongst all tasks in a given multi-tasks application).

 === int '''_sys_procs_number'''( unsigned int  x,  unsigned int y,  unsigned int* number ) ===
Returns in the ''number'' argument the number of processors in cluster[x,y].

 === int '''_sys_vobj_get_vbase'''( char* vspace_name,  char* vobj_name,  unsigned int* vbase ) ===
This function returns in the ''vbase'' argument the virtual base address of the vobj identified by the (vspace_name / vobj_name ) couple. Returns 0 if success, -1 if vobj not found.

 === int '''_sys_vobj_get_length'''( char* vspace_name,  char* vobj_name,  unsigned int* length ) ===
This function returns in the ''length'' argument the length of the vobj identified by the (vspace_name / vobj_name ) couple. Returns 0 if success, -1 if vobj not found

 === int '''_sys_xy_from_ptr'''( void* ptr,  unsigned int*  x,  unsigned int*  y ) ===
This function returns in the (x,y) arguments the coordinates of the  cluster where is mapped the ptr virtual address. It use the _get_context_slot() function to get the calling task page table, and uses the _v2p_translate() function to obtain the physical address. Returns 0 if success, -1 if ptr not mapped in the calling task vspace.

 === int '''_sys_heap_info'''( unsigned int* vaddr,   unsigned int* length,   unsigned int  x,  unsigned int  y ) ===
This function returns the information associated to a heap : vaddr and length.
 * If (x < X_SIZE) and (y < Y_SIZE), it return the heap associated to any task running in cluster(x,y). 
 * else, it return the heap associated to the calling task.
It uses the global task index (CTX_GTID_ID, unique for each giet task) and the vspace index (CTX_VSID_ID), that are defined in the calling task context to find the vobj_id containing the heap. 
Returns 0 if success, returns -1 if not found.