= 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 6 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 , unsigned int xmax , unsigned int ymax ) === This function allocates a private NIC_RX or NIC_TX channel, and a private CMA channel to the calling task. It register these channel indexes in the task context. It allocates the distributed kernel chbuf associated to the NIC channel: both the distributed 4 Kbytes containers (one container per cluster from the distributed kernel heap), and the chbuf descriptor (in the seg_kernel_data segment in cluster [0,0]). The number of involved clusters is defined by the (xmax / ymax) parameters, that cannot be larger than (X_SIZE, Y_SIZE), but can be smaller. * '''is_rx''' : boolean (RX transfer if non zero) * '''xmax''' : number of clusters in a row * '''ymax''' : number of clusters in a column Returns the NIC channel index if success. Return -1 if no NIC channel available, if no CMA channel available, if (xmax / ymax) are too large, or if not enough memory in the kernel heap. === 2) int '''_sys_nic_start'''( unsigned int is_rx, unsigned int channel ) === This function starts the NIC channel allocated to the calling task, and starts the CMA transfer between the NIC chbuf and the distributed kernel chbuf. The CMA component is configured in OUT_OF_ORDER transfer mode (non blocking when a SRC or DST container is not available). * '''is_rx''' : boolean (RX transfer if non zero) * '''channel''' : RX or TX channel index 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 is_rx, unsigned int channel, void* buffer ) === This function moves one 4 Kbytes container from the kernel chbuf defined by the ''nic_channel'' argument, to an user buffer defined by the ''buffer'' argument. This blocking function enforces locality and parallelism: it scans the two containers located in the same cluster as the calling task, and returns only when a full container has been found. * '''is_rx''' : boolean (RX transfer if non zero) * '''channel''' : RX or TX channel index. * '''buffer''' is the user buffer virtual base address. 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, unsigned int channel ) === This function stops the NIC and the CMA channels allocated to the calling task. * '''is_rx''' : boolean (RX transfer if non zero) * '''channel''' : RX or TX channel index Returns 0 if success. Returns -1 if no NIC channel or no CMA channel allocated to the calling task. === 5) int '''_sys_nic_clear'''( unsigned int is_rx, unsigned int channel ) === This function reset the NIC instrumentation registers (packet counters). * '''is_rx''' : boolean (RX channels if non zero) * '''channel''' : RX or TX channel index === 6) int '''_sys_nic_stats'''( unsigned int is_rx, unsigned int channel ) === This function displays on TTY0 the values stored in the NIC instrumentation registers (packet counters). * '''is_rx''' : boolean (RX channels if non zero) * '''channel''' : RX or TX channel index == 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. The CMA component is configured in IN_ORDER transfer mode (blocking when the expected source or destination buffer is not available). * '''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 buffer_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_index''' 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 '''_sys_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_size, unsigned int* y_size, unsigned int* nprocs ) === Returns in the arguments the 2D mesh size (only clusters containing processors), and the number of processors per cluster. === 9) int '''_sys_vseg_get_vbase'''( char* vspace_name, char* vobj_name, unsigned int* vbase ) === This function returns in the ''vbase'' argument the virtual base address of the private vseg identified by the (vspace_name / vseg_name ) couple. Returns 0 if success, -1 if vobj not found. === 10) int '''_sys_vseg_get_length'''( char* vspace_name, char* vseg_name, unsigned int* length ) === This function returns in the ''length'' argument the length of the private vseg identified by the (vspace_name / vseg_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 user heap vseg : 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. Returns 0 if success, returns -1 if not found.