Changes between Version 34 and Version 35 of library_stdio


Ignore:
Timestamp:
Nov 11, 2014, 3:19:24 PM (10 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • library_stdio

    v34 v35  
    1111Therefore, for all these system calls, the return value has not to be tested by the calling task.
    1212
    13  == __1) Processor related system calls__ ==
    14 
    15  === void '''giet_proc_xyp'''( unsigned int* cluster_x, unsigned int* cluster_y unsigned int* lpid )===
     13 == Processor related system calls ==
     14
     15 === 1) void '''giet_proc_xyp'''( unsigned int* cluster_x, unsigned int* cluster_y unsigned int* lpid )===
    1616This function returns the processor identifiers (X,Y,P) from the wired global processor index in CP0_PROCID.
    1717 * cluster_x : X cluster coordinate
    … …  
    2020No error possible, as the fixed format is  gpid = ( ( cluster_x << Y_WIDTH + cluster_y ) << P_WIDTH ) + lpid
    2121
    22  === unsigned int '''giet_proctime'''() ===
     22 === 2) unsigned int '''giet_proctime'''() ===
    2323This function returns the local processor time from the CP0_TIME register (number of cycles from reset).
    2424No error possible, as the processor implements a 32 bits wrapping register.
    2525 
    26  === unsigned int '''giet_rand'''() ===
     26 === 3) unsigned int '''giet_rand'''() ===
    2727This function returns a pseudo-random value derived from both the CP0_PROCID and CP0_TIME registers.
    2828No error possible, as the return value is always between 0 & 65535.
    2929
    30  == __2) Task related system calls__ ==
    31 
    32  === unsigned int '''giet_proc_task_id'''() ===
     30 == Task related system calls ==
     31
     32 === 1) unsigned int '''giet_proc_task_id'''() ===
    3333This functions returns (from the calling task context) the local task index, identifying the task amongst all task
    3434running on the same processor.
    35 
    3635No error possible.
    3736
    38  === unsigned int '''giet_global_task_id'''() ===
     37 === 2) unsigned int '''giet_global_task_id'''() ===
    3938This functions returns (from the calling task context) the global task id, unique in the system.
    40 
    4139No error possible.
    4240
    43  === unsigned int '''giet_thread_id'''() ===
     41 === 3) unsigned int '''giet_thread_id'''() ===
    4442This functions returns (from the calling task context) the thread index, identiying the task in a given vspace.
    45 
    4643No error possible.
    4744
    48  == __3) TTY related system calls__ ==
     45 ==  TTY related system calls ==
    4946
    5047The GIET_VM allows an user task to use a private TTY terminal, or to display log message on a shared TTY terminal.
    5148
    52  === void '''giet_tty_alloc'''() ===
     49 === 1) void '''giet_tty_alloc'''() ===
    5350This function allocates a private terminal to the calling task, and registers the terminal index in the task context.
    5451Task exit if no TTY terminal available.
    5552
    56   === void '''giet_tty_printf'''( char* format, ... ) ===
     53  === 2) void '''giet_tty_printf'''( char* format, ... ) ===
    5754This 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.
    5855Only a limited number of formats are supported:
    … …  
    6562Task exit if  private terminal index not defined, or in case of illegal format.
    6663
    67  === void '''giet_tty_getc'''( char* byte ) ===
     64 === 3) void '''giet_tty_getc'''( char* byte ) ===
    6865This 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. Task exit if private TTY index not defined.
    6966
    70  === void '''giet_tty_getw'''( unsigned int* val ) ===
     67 === 4) void '''giet_tty_getw'''( unsigned int* val ) ===
    7168This 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.
    7269The 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  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.
    7370Task exit if private TTY index not defined.
    7471
    75  === void '''giet_tty_gets'''( char* buf, unsigned int bufsize ) ===
     72 === 5) void '''giet_tty_gets'''( char* buf, unsigned int bufsize ) ===
    7673This 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.
    7774It uses the TTY_RX_IRQ interrupt, and the associated kernel buffer.
    … …  
    7976Task exit if private TTY index not defined.
    8077
    81  === void '''giet_shr_printf'''( char* format, ... ) ===
    82 This function print formated text on a shared terminal arbitrarily allocated by the kernel. It takes the TTY lock for exclusive access. It supports the same formats as the giet_tty_printf() function.
     78 === 6) void '''giet_shr_printf'''( char* format, ... ) ===
     79This function print formated text on the kernel terminal. It takes the TTY lock for exclusive access. It supports the same formats as the giet_tty_printf() function.
    8380Task exit in case of illegal format.
    8481
    85  == __4) Timer related system calls__ ==
     82 ==  Timer related system calls ==
    8683
    8784The GIET_VM allows an user task to activate a private timer channel, generating periodical IRQs. This timer is allocated in the external multi-timers peripheral.
    8885
    89  === void '''giet_timer_alloc'''()
     86 === 1) void '''giet_timer_alloc'''()
    9087This function allocates a private user timer  to the calling task, and registers the channel index in the task context.
    9188Task exit if no timer channel available
    9289
    93  === void '''giet_timer_start'''( unsigned int period )
     90 === 2) void '''giet_timer_start'''( unsigned int period )
    9491This function starts the private timer allocated to the calling task.
    9592Task exit if no channel allocated.
    9693
    97  === void '''giet_timer_stop'''( ) ===
     94 === 3) void '''giet_timer_stop'''( ) ===
    9895This function stops the private timer allocated to the calling task.
    9996Task exit if no channel allocated.
    10097
    101  == __5) File system related system calls__ ==
     98 ==  File system related system calls ==
    10299
    103100The Giet-VM supports a FAT32 file system.
    104101
    105  === int '''giet_fat_open'''( const char* pathname, unsigned int flags ) ===
    106 Open a file identified by the ''pathname'' argument. The read/write ''flags''  are not supported yet: no effect. Return -1 in case or error.
    107 
    108  === void '''giet_fat_read'''( unsigned int fd, void* buffer, unsigned int count, unsigned int offset ) ===
     102 === 1) int '''giet_fat_open'''( const char* pathname, unsigned int flags ) ===
     103This function open a file identified by the ''pathname'' argument. The read/write ''flags''  are not supported yet: no effect. Return -1 in case or error.
     104
     105 === 2) void '''giet_fat_read'''( unsigned int fd, void* buffer, unsigned int count, unsigned int offset ) ===
    109106Read ''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.
    110107In case or error, it makes a giet_exit().
    111108
    112  === void '''giet_fat_write'''( unsigned int fd, void* buffer, unsigned int count, unsigned int offset ) ===
     109 === 3) void '''giet_fat_write'''( unsigned int fd, void* buffer, unsigned int count, unsigned int offset ) ===
    113110Write ''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.
    114111In case or error, it makes a giet_exit().
    115112
    116  === void '''giet_fat_close'''( unsigned int fd ) ===
     113 === 4) void '''giet_fat_close'''( unsigned int fd ) ===
    117114Close a file identified by the ''fd'' file descriptor.
    118115
    119116
    120  == __6) Network related system calls__ ==
    121 
    122 The GIET_VM allows a user task to directly access a private NIC channel, and register the channel index in the task context.
    123 
    124  === void '''giet_nic_tx_alloc'''( ) ===
     117 == Network related system call ==
     118
     119The GIET_VM allows a user task to access a private NIC channel, using the CMA component (chained buffers DMA).
     120The NIC channel and the CMA channel are registered in the task context.
     121
     122 === 1) void '''giet_nic_tx_alloc'''( ) ===
    125123This function allocates a private NIC_TX channel (coming with the associated kernel NIC_TX chbuf), and a private CMA channel  to the calling task. It registers the corresponding indexes in the calling task context.
    126124The calling task exit if no available NIC_TX channel, or no available CMA channel.
    127125
    128  === void '''giet_nic_rx_alloc'''( ) ===
     126 === 2) void '''giet_nic_rx_alloc'''( ) ===
    129127This function allocates a private NIC_RX channel (coming with the associated kernel NIC_RX chbuf), and a private CMA channel  to the calling task. It registers the corresponding indexes in the calling task context.
    130128The calling task exit if no available NIC_RX channel, or no available CMA channel.
    131129
    132  === void '''giet_nic_tx_start'''( ) ===
     130 === 3) void '''giet_nic_tx_start'''( ) ===
    133131This function activates both the NIC_TX channel and the CMA channel allocated to the calling task.
    134132The calling task exit if no allocated NIC_TX channel or no allocated CMA channel.
    135133
    136  === void '''giet_nic_rx_start'''( ) ===
     134 === 4) void '''giet_nic_rx_start'''( ) ===
    137135This function activates both the NIC_RX channel and the CMA channel allocated to the calling task.
    138136The calling task exit if no allocated NIC_RX channel or no allocated CMA channel.
    139137
    140  === void '''giet_nic_tx_move'''( void* buffer ) ===
     138 === 5) void '''giet_nic_tx_move'''( void* buffer ) ===
    141139This blocking function requires to transfer one container (4K bytes)  from an user space buffer to the Network Controller.
    142140 * '''buffer'''  is the container base address in user space.
    … …  
    144142The calling task exit if no NIC channel allocated to the task, or in case of timeout.
    145143
    146  === void '''giet_nic_rx_move'''( void* buffer ) ===
     144 === 6) void '''giet_nic_rx_move'''( void* buffer ) ===
    147145This blocking function requires to transfer one container (4K bytes)  from  the Network Controller to an user space buffer.
    148146 * '''buffer''' is the container base address in user space.
    … …  
    150148The calling task exit if no NIC channel allocated to the task, or in case of timeout.
    151149
    152  == __7) Frame Buffer related system calls__ ==
    153 
    154 An user task can access the frame buffer through a memcpy() or through the chained buffer DMA controller.
    155 
    156  === void '''giet_fb_sync_read'''( unsigned int offset, void* buffer, unsigned int length ) ===
    157 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.
    158 
    159  === void '''giet_fb_sync_write'''( unsigned int offset, void* buffer, unsigned int length ) ===
    160 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.
    161 
    162  === void '''giet_fbf_cma_alloc'''()
     150 === 7) void '''giet_nic_tx_stop( ) ===
     151This function desactivates both the NIC_TX channel and the CMA channel allocated to the calling task.
     152The calling task exit if no allocated NIC_TX channel or no allocated CMA channel.
     153
     154 === 8) void '''giet_nic_rx_stop( ) ===
     155This function desactivates both the NIC_RX channel and the CMA channel allocated to the calling task.
     156The calling task exit if no allocated NIC_RX channel or no allocated CMA channel.
     157
     158 == Frame Buffer related system calls ==
     159
     160An user task can access the frame buffer through a memcpy() or through the chained buffer DMA controller (CMA).
     161The four first functions use a private CMA channel that is registered in the task context. The Two last functions use a memcpy().
     162
     163 === 1) void '''giet_fbf_cma_alloc'''()
    163164This function allocates a private CMA channel  to the calling task, and registers the channel index
    164165in the task context.
    165166Task exit if no CMA channel available
    166167
    167  === void '''giet_fbf_cma_start'''( void* buf0, void* buf1, unsigned int length ) ===
     168 === 2) void '''giet_fbf_cma_start'''( void* buf0, void* buf1, unsigned int length ) ===
    168169This function initializes the chained buffer DMA controller (CMA) to transfer a stream of images from two user buffers to the frame buffer. It must be used in conjunction with the giet_fbf_cma_display() function. A CMA channel should have been allocated to the calling task in the application mapping.
    169170 * '''buf0('' is the first user buffer base address
    … …  
    171172 * '''length''' is the buffer size (bytes).
    172173
    173  === void '''giet_fbf_cma_display'''( unsigned int buffer ) ===
     174 === 3) void '''giet_fbf_cma_display'''( unsigned int buffer ) ===
    174175This function enables the transfer of the buffer specified by the ''buffer'' argument (0 or 1).
    175176
    176  === void '''giet_fbf_cma_stop'''( ) ===
     177 === 4) void '''giet_fbf_cma_stop'''( ) ===
    177178This function desactivates the CMA channel allocated to the calling task.
    178179
    179  == __8) Miscelaneous system calls__ ==
    180 
    181  === void '''giet_exit'''( char* string ) ===
     180 === 5) void '''giet_fb_sync_read'''( unsigned int offset, void* buffer, unsigned int length ) ===
     181This 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.
     182
     183 === 6) void '''giet_fb_sync_write'''( unsigned int offset, void* buffer, unsigned int length ) ===
     184This 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.
     185
     186
     187== 8) Miscelaneous system calls ==
     188
     189 === 1) void '''giet_exit'''( char* string ) ===
    182190This 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.
    183191
    184  === void '''giet_assert'''( unsigned int condition, char* string ) ===
     192 === 2) void '''giet_assert'''( unsigned int condition, char* string ) ===
    185193This function uses the giet_exit() system call to kill the calling task if the condition is false.
    186194
    187  === void '''giet_context_switch'''() ===
     195 === 3) void '''giet_context_switch'''() ===
    188196The user task calling this function is descheduled and the processor is allocated to another task.
    189197
    190  === void '''giet_procnumber'''( unsigned int cluster_xy, unsigned int buffer ) ===
     198 === 4) void '''giet_procnumber'''( unsigned int cluster_xy, unsigned int buffer ) ===
    191199This 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().
    192200
    193  === void '''giet_vobj_get_vbase'''( char* vspace_name, char*  vobj_name, unsigned int* vbase) ===
     201 === 5) void '''giet_vobj_get_vbase'''( char* vspace_name, char*  vobj_name, unsigned int* vbase) ===
    194202This function returns in argument ''vbase'' the virtual base address of a vobj defined in the mapping_info data structure. The vobj is 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().
    195203
    196  === void '''giet_vobj_get_length'''( char* vspace_name, char*  vobj_name, unsigned int* length) ===
     204 === 6) void '''giet_vobj_get_length'''( char* vspace_name, char*  vobj_name, unsigned int* length) ===
    197205This function returns in argument ''length'' the length (bytes) of a vobj defined in the mapping_info data structure. The vobj is 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().
    198206
    199  === void '''giet_heap_info'''( unsigned int* vaddr, unsigned int* length, unsigned int  x, unsigned int  y );
     207 === 7) void '''giet_heap_info'''( unsigned int* vaddr, unsigned int* length, unsigned int  x, unsigned int  y );
    200208This 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).
    201209
    202  === void '''giet_get_xy'''( void* ptr, unsigned int* px, unsigned int* py ) ===
     210 === 8) void '''giet_get_xy'''( void* ptr, unsigned int* px, unsigned int* py ) ===
    203211This function takes as input a virtual address (''ptr'' argument), and returns through the ''px,py'' arguments the coordinates of the cluster containing the physical address associated to ''ptr''. In case of error (unmapped virtual address), it makes a giet_exit(). 
    204212