GIET-VM / Syscall Handlers

The sys_handler.c​ and 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.

The _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.