= GIET-VM  / Syscall Handlers =

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 ==

=== 1) 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.

=== 2) 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.

=== 3) 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).

=== 4) 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.

=== 5) 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 ==

=== 1) 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.

=== 2) 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.

=== 3) 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 ==

These 4 functions can be used for both a NIC_RX or NIC_TX channel, depending on the '''is_rx''' argument.

=== 1) int '''_sys_nic_alloc'''( unsigned int is_rx ) ===
This function allocates a private NIC_RX or NIC_TX channel, the associated chbuf, and a private CMA channel to the calling task. It register these channel indexes in the task context.
 * '''is_isr''' : boolean (RX transfer if non zero)
Returns the NIC channel index if success. Return -1 if no NIC channel available, or if no CMA channel available.

=== 2) int '''_sys_nic_start'''( unsigned int is_rx ) ===
This function starts the NIC channel allocated to the calling task, and starts the CMA transfer between the internal NIC chbuf and the kernel chbuf allocated to the calling task.
 * '''is_isr''' : boolean (RX transfer if non zero)
Returns 0 if success. Returns -1 if no NIC channel or no CMA channel allocated to the calling task.

=== 3) int '''_sys_nic_move'''(  unsigned int nic_channel,  unsigned int is_rx,  void* buffer ) ===
This function moves one 4kbytes container between the kernel chbuf defined by the nic_channel argument, and an user buffer. 
 * '''nic_channel''' : selected nic_chbuf channel.
 * '''is_isr''' : boolean (RX transfer if non zero)
 * '''buffer''' is the user buffer virtual base address.
It supports concurrent kernel access to the chbuf, because It takes the lock protecting exclusive access to the chbuf pointer (index field). 
It is blocking if the kernel chbuf is empty (for an RX transfer) or full (for a TX transfer). The bloking situation
is bounded by a timeout defined by the GIET_NIC_TIMEOUT parameter defined in the ''giet_config.h'' file.
Returns 0 if success, returns -1 if the user buffer address is illegal, or if the NIC channel is too large, or if the timeout is elapsed.

=== 4) int '''_sys_nic_stop'''( unsigned int is_rx ) ===
This function stops the NIC and the CMA channels allocated to the calling task.
 * '''is_isr''' : boolean (RX transfer if non zero)
Returns 0 if success. Returns -1 if no NIC channel or no CMA 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. 
 
 === 1) 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.
 
 === 2) 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.

 === 3) 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.

 === 4) 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.

 === 5) 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.

 === 6) 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.


== Miscelaneous syscall handlers ==

=== 1) int '''_sys_ukn'''() ===
This function executed in case of undefined syscall. It just display an error message on TTY0.

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

=== 3) 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.

 === 4) 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.

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

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

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

 === 8) 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].

 === 9) 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.

 === 10) 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

 === 11) 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.

 === 12) 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.