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

== __Miscelaneous syscall handlers__ ==

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

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

== __TTY related syscall handlers__ ==

=== int '''_sys_tty_alloc'''() ===

=== 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  the number of characters that have been written.

=== 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 channel 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  the number of characters that have been read (0/1).

=== void '''_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.
It returns only when the lock has been successfully taken.

=== void '''_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.

== __TIM retated syscall handlers__ ==

=== int '''_sys_timer_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_timer_start'''( unsigned int period ) ===
This function starts the user timer channel allocated to the calling task.
Returns -1 if no allocated timer.

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

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

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

 === unsigned int '''_local_task_id'''() ===
Returns current task local index (amongst tasks running on a given processor).

 === unsigned int '''_global_task_id'''() ===
Returns current task global index (amongst all tasks running on all processors).

=== unsigned int '''_thread_id'''() ===
Returns current thread index (amongst all tasks in a given multi-tasks application).

 === unsigned int '''_procs_number'''( unsigned int  cluster_id, unsigned int* number ) ===
Returns in buffer argument the number of processors in cluster specified by the cluster_id argument.

 === unsigned int '''_get_vobj_ptr'''( char* vspace_name,  char* vobj_name,  mapping_vobj_t**  pvobj ) ===
This function returns in the res_vobj argument a pointer on a vobj identified by the (vspace_name / vobj_name ) couple. 
Returns 0 if success, >0 if not found

 === unsigned int '''_vobj_get_vbase'''( char* vspace_name,  char* vobj_name,  unsigned int* vobj_vbase ) ===
This function writes in vobj_base the virtual base address of a vobj  identified by the (vspace_name / vobj_name ) couple.
Returns 0 if success, >0 if not found

 === unsigned int '''_vobj_get_length'''( char* vspace_name,  char* vobj_name,  unsigned int* vobj_length ) ===
This function writes in vobj_length the length of a vobj identified by the (vspace_name / vobj_name ) couple.
Returns 0 if success, >0 if not found

 === unsigned int '''_get_xy_from_ptr'''( void* ptr,  unsigned int*  px,  unsigned int*  py ) ===
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, > 0 if ptr not mapped in the calling task vspace.