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