wiki:library_stdio

Version 10 (modified by alain, 10 years ago) (diff)

--

The stdio Library

The stdio.c and stdio.h files define all system calls provided to user applications by the GIET-VM. They are generally prefixed by giet_.

1) Processor related system calls

int giet_procid()

This function returns the global processor identifier gpid, depending on (X,Y,L) where X,Y are the cluster coordinates, and L is the local processor index. The format is gpid = X<<Y_WIDTH + Y) * NB_PROCS_MAX) + L

int giet_proctime()

This function returns the local processor time (number of cycles from reset.

int giet_rand()

This function returns a pseudo-random value derived from both the processor cycle count and the processor index. This value is comprised between 0 & 65535.

2) Task related system calls

int giet_proc_task_id()

This functions returns the local task index, identifying the task amongst all task running on the same processor.

int giet_global_task_id()

This functions returns the global task id, unique in the system.

int giet_thread_id()

This functions returns the thread index, identiying the task in a given vspace.

3) TTY related system calls

void giet_tty_printf( char* format, ... )

This function print formated text on a private terminal that must have been allocated to the calling task in the mapping (use_tty argument). Therefore, it does not take the TTY lock. In case or error, it makes a giet_exit().

Only a limited number of formats are supported:

  • %d : signed decimal
  • %u : unsigned decimal
  • %x : 32 bits hexadecimal
  • %l : 64 bits hexadecimal
  • %c : char
  • %s : string

void giet_shr_printf( char* format, ... )

This function print formated text on the shared terminal arbitrarily allocated by the kernel, taking the TTY lock for exclusive access. It supports the same formats as the giet_tty_printf() function. In case or error, it makes a giet_exit().

void giet_tty_getc( char* byte )

This blocking function fetches a single character from the private terminal that must have been allocated to the calling task in the application mapping. It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer. In case or error (such as TTY index not defined), it makes a giet_exit().

void giet_tty_getw( unsigned int* val )

This blocking function fetches a string of decimal characters (most significant digit first) to build a 32-bits unsigned integer from the private TTY terminal that must have been allocated to the calling task in the application mapping. It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer. The non-blocking system function _tty_read is called several times, and the decimal characters are written in a 32 characters buffer until a <LF> character is read. It ignores non-decimal characters, and displays an echo system function) for each decimal character. The <DEL> character is interpreted, and previous characters can be cancelled. When the <LF> character is received, the string is converted to an unsigned int value. If the number of decimal digit is too large for the 32 bits range, the zero value is returned. In case or error (such as TTY index not defined), it makes a giet_exit().

void giet_tty_gets( char* buf, unsigned int bufsize )

This blocking function fetches a string from the private terminal that must have been allocated to the calling task in the application mapping. It writes the string to a fixed length buffer. It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer. Up to (bufsize - 1) characters (including the non printable characters) are copied into buffer, and the string is completed by a NUL character. The <LF> character is interpreted, and the function close the string with a NUL character if <LF> is read. The <DEL> character is interpreted, and the corresponding character(s) are removed from the target buffer. It does not provide an echo. In case or error (such as TTY index not defined), it makes a giet_exit().

4) File system related system calls

The Giet-VM supports a FAT32 file system.

int giet_fat_open( const char* pathname, unsigned int flags )

Open a file identified by the pathname argument. The read/write flags are not supported yet: no effect. Return -1 in case or error.

void giet_fat_read( unsigned int fd, void* buffer, unsigned int count, unsigned int offset )

Read count sectors from a file identified by the fd argument, skipping offset sectors in file, and writing into the user memory buffer. The user buffer base address should be 64 bytes aligned. In case or error, it makes a giet_exit().

void giet_fat_write( unsigned int fd, void* buffer, unsigned int count, unsigned int offset )

Write count sectors into a file identified by the fd argument, skipping offset sectors in file, and reading from the user memory buffer. The user buffer base address should be 64 bytes aligned. In case or error, it makes a giet_exit().

void giet_fat_close( unsigned int fd )

Close a file identified by the fd file descriptor.

5) Network related system calls

6) Frame Buffer related system calls

void giet_fb_sync_read( unsigned int offset, void* buffer, unsigned int length )

This blocking function use a memcopy strategy to transfer data from the frame buffer to an user buffer: offset defines the offset (in bytes) in the frame buffer, buffer is the user buffer base address, length is the number of bytes to be transfered. In case or error, it makes a giet_exit().

void giet_fb_sync_write( unsigned int offset, void* buffer, unsigned int length )

This blocking function use a memcopy strategy to transfer data from an user buffer to the frame buffer: offset defines the offset (in bytes) in the frame buffer, buffer is the user buffer base address, length is the number of bytes to be transfered. In case or error, it makes a giet_exit().

void giet_fb_cma_init( void* buf0, void* buf1, unsigned int length )

This function initializes the two chained bufffer (sorce and destination) used by the chained buffer DMA controller (CMA) to transfer a stream of data from the user buffers to the frame buffer. A CMA channel should have been allocated to the calling task in the application mapping. buf0 is the first user buffer base address, buf1 is the second user buffer base address, length is the buffer size (bytes). In case or error, it makes a giet_exit().

void giet_fb_cma_write( unsigned int buffer_id )

This function enables the transfer of the buffer specified by the buffer_id argument (0 or 1).

void giet_fb_cma_stop( )

This function desactivates the CMA channel allocated to the calling task.

7) Miscelaneous system calls

void giet_exit( char* string )

This function stops execution of the calling task with a TTY message explaining the cause. The user task is descheduled and becomes not runable: it does not consume processor cycles anymore.

void giet_assert( unsigned int condition, char* string )

This function uses the giet_exit() system call to kill the calling task if the condition is false.

void giet_context_switch()

The user task calling this function is descheduled and the processor is allocated to another task.

void giet_procnumber( unsigned int cluster_xy, unsigned int buffer )

This function returns in the buffer argument the number of processors in the cluster specified by the cluster_xy argument. In case or error (such as illegal cluster index), it makes a giet_exit().

void giet_vobj_get_vbase( char* vspace_name, char* vobj_name, unsigned int* vobj_vaddr)

This function returns in argument vobj_vaddr the virtual base address of a vobj defined in the mapping_info data structure), identified by the two arguments vspace_name and vobj_name. In case of error (such as undefined vspace or undefined vobj), it makes a giet_exit().

void giet_heap_info( unsigned int* vaddr, unsigned int* length, unsigned int x, unsigned int y );

This function supports access to the running task's heap or to a remote heap. If (x < X_SIZE) and (y < Y_SIZE), it returns the base address and length of the heap associated to any task running on cluster(x,y). Otherwise, it returns the base address and length of the heap associated to the calling task. In case of error (such as undefined heap segment in the selected cluster, it returns heap_size = 0).