Changes between Version 67 and Version 68 of library_stdio

Timestamp:

Apr 12, 2015, 1:09:34 PM (9 years ago)

Author:

alain

Comment:

--

library_stdio

@@ -45 +45 @@
  ==  __Coprocessors related system calls__ ==
 
-The GIET_VM allows user applications to use hardware accelerators (called coprocessors). These coprocessors can be distributed in the architecture, but there is at most one coprocessor per cluster. To be supported by the GIET_VM, a coprocessor must use the ''vci_mwmr_dma'' component, that is a generic multi-channels DMA controller.
-
-On the coprocessor side, it provides TO_COPROC or FROM_COPROC ports, that implement FIFO interfaces. Coprocessor can request to transfer one or several bursts of 32 bits words on a TO_COPROC or FROM_COPROC port, without address. The burst size (generally a cache line), the number of TO_COPROC and FROM_COPROC ports, and the number of bursts for a given port are hardware parameters. Each port define a private communication channel between the coprocessor and a user memory buffer. The total number of channels cannot be larger than 16. A channel is identified by an index, and the TO_COPROC channels have the smallest indexes.
-
-Each communication channel implements three transfer modes that can be configured by software:
- * In '''MODE_MWMR''', the channel transfer an "infinite" data stream, between the coprocessor port and a MWMR software FIFO in memory. The MWMR_DMA controller  implements the 7 steps MWMR protocol.
- * In '''MODE_DMA_IRQ''', the channel transfer a single buffer between the coprocessor port and the memory. The number of VCI burst for a given channel depends on the memory buffer size, and the MWMR_DMA controller signals the transfer completion with an interrupt. 
- * The '''MODE_DMA_NO_IRQ''', is similar to the previous one, but the channel stops when the transfer is completed, without rising an interrupt.
+The GIET_VM allows user applications to use hardware accelerators (called coprocessors). These coprocessors can be distributed in the architecture, but there is at most one coprocessor per cluster. To be supported by the GIET_VM, a coprocessor must use the '''vci_mwmr_dma''' component, that is a generic multi-channels DMA controller.
+
+On the coprocessor side, it provides TO_COPROC or FROM_COPROC ports, that implement FIFO interfaces. Coprocessor can request to transfer one or several bursts of 32 bits words on a TO_COPROC or FROM_COPROC port, without address. The burst size (generally a cache line), the number of TO_COPROC and FROM_COPROC ports, and the number of bursts for a given port are hardware parameters, depending on the coprocessor type. Each port define a private communication channel between the coprocessor and a user memory buffer. The total number of channels cannot be larger than 16. A channel is identified by an index, and the TO_COPROC channels have the smallest indexes.
+
+The '''vci_mwmr_dma''' component implements two transfer modes that can be configured by the user application through dedicate system calls.
+ * In '''MODE_MWMR''', each channel FSM  implements the 7 steps MWMR protocol. It is activated by writing a non-zero value in the CHANNEL_RUNNING register, and transfer an "infinite" data stream, between the coprocessor port and a MWMR software FIFO in memory. There is no transfer completion signaling, as the synchronisation is done through the MWMR FIFOs. The MWR IRQ is only asserted if a VCI error is reported in memory access. 
+ * In '''MODE_DMA_IRQ''' or '''MODE_DMA_NO_IRQ, each channel FSM transfer a single buffer between the coprocessor port and the memory. It is activated by writing a non-zero value in the CHANNEL_RUNNING register. When transfer is completed, the channel FSM keep blocked until a zero value is written in the CHANNEL_RUNNING register. In MODE_DMA_IRQ, the calling task is descheduled after coprocessor activation in the ''giet_coproc_start()'' system call. The transfer completion is signaled by the WMR IRQ that updates the ''_coproc_done'' / ''_coproc_status'' variables, deactivate the coprocessor, and resume the calling task.  In '''MODE_DMA_NO_IRQ''', the ''giet_coproc_start()'' is not blocking, and the user task must use the ''giet_coproc_completed()'' system call to detect transfer completion (by polling the coprocessor registers).
 
 '''WARNING''' : For all channels, the memory buffer address and size  must be multiple of the hardware burst size.
 
-The VCI transactions corresponding to different channels are interleaved and parallelized on the VCI network. 
-
-Besides these communication channels, the ''vci_mwmr_dma'' component support up to 16 coprocessor-specific configuration/status registers. The ''configuration'' registers are Read and Write. The ''status'' registers are Read only.
+'''WARNING''': If all channels are not running in the same mode, the result is unpredictable.
+
+The VCI transactions corresponding to different TO_COPROC / FROM_COPROC channels are interleaved and parallelized on the VCI network. 
+
+Besides the TO_COPROC/FROM_COPROC communication channels, the '''vci_mwmr_dma''' component support up to 16 coprocessor-specific configuration/status registers. 
+ * The '''configuration''' registers are Read and Write. 
+ * The '''status''' registers are Read only.
 
 
@@ -67 +70 @@
 || MWR_COPROC_CPY  ||   Memory Copy                      ||    1                 ||          1               ||        1        ||       0        ||      
 
- === 1) void '''giet_coproc_alloc'''( unsigned int   coproc_type,  unsigned int*  coproc_key,  unsigned int* coproc_info ) ===
-This function allocates a private coprocessor to the calling task, taking a lock to grant exclusive ownership, and register the key in the task context.
+ === 1) void '''giet_coproc_alloc'''( unsigned int   coproc_type , unsigned int* coproc_info ) ===
+This function allocates a private coprocessor to the calling task, taking a lock to grant exclusive ownership, and register the coprocessor coordinates in the task context.
 In the current implementation, the task exit if there is no coprocessor of requested type in the same cluster as the calling task.
-In case of success, it returns an access key and the coprocessor characteristics in the '''coproc_info''' and '''coproc_key''' variables.
+In case of success, it returns the coprocessor characteristics in the '''coproc_info''' variable.
  * '''coproc_type''' : see supported types above.
- * '''coproc_key''' (return value) : identifier for coprocessor access.
  * '''coproc_info''' (return value) :  nb_to_coprocs = info[7:0] / nb_from_coproc = info[15:8] / nb_config = info[23:16] / nb_status = info[31:24]
 
- === 2) void '''giet_coproc_release'''( unsigned int  coproc_key ) ===
+ === 2) void '''giet_coproc_release'''( ) ===
  This function releases the coprocessor allocated to the calling task.
- * '''coproc_key''' : coprocessor identifier.
-
- === 3) void '''giet_coproc_channel_init'''( unsigned int  coproc_key,  unsigned int channel,  giet_coproc_channel_t*  desc ) ===
-This function initializes a communication channel. It uses the he following structure (defined in the [source:soft/giet_vm/giet_libs/stdio.h stdio.h] file) to specify the channel parameters:
+
+ === 3) void '''giet_coproc_channel_init'''( unsigned int channel , giet_coproc_channel_t*  desc ) ===
+This function initializes a TO_COPROC/FROM_COPROC communication channel. It uses the he following structure (defined in the [source:soft/giet_vm/giet_libs/stdio.h stdio.h] file) to specify the channel parameters:
 {{{
 typedef struct giet_coproc_channel
@@ -91 +92 @@
 } giet_coproc_channel_t;
 }}}
- * '''coproc_key''' : coprocessor identifier. 
  * '''channel''' communication channel index. TO_COPROC channels use the smallest indexes.
  * '''desc''' pointer on the giet_coproc_channel_t structure.
 
- === 4) void '''giet_coproc_start'''( unsigned int  coproc_key ) ===
-This function activates the communication channels and the allocated coprocessor.
- * '''coproc_key''' : coprocessor identifier.
-
- === 5) void '''giet_coproc_stop'''( unsigned int  coproc_key ) ===
-This function desactivates the communication channels and the allocated coprocessor.
- * '''coproc_key''' : coprocessor identifier. 
-
- === 6) void '''giet_coproc_completed'''(  unsigned int coproc_key  ) ===
+ === 4) void '''giet_coproc_start'''( unsigned int index ) ===
+This function activates all communication channels and the allocated coprocessor itself.
+ * '''index''' : coprocessor register index to be written for activation.
+
+ === 5) void '''giet_coproc_stop'''( unsigned int index ) ===
+This function desactivates all communication channels and the allocated coprocessor itself.
+* '''index''' : coprocessor register index to be written for activation.
+
+ === 6) void '''giet_coproc_completed'''( ) ===
 This blocking function can be used to synchronize a software task with an hardware coprocessor running in DMA_NO_IRQ mode.
 It polls the status register of all communication channels, and returns only when all transfers are completed. 
-This function exit when one status register indicates a  bus error (illegal memory access). 
- * '''coproc_key''' : coprocessor identifier.
+This function exit when at least one channel status register indicates a  bus error (illegal memory access). 
 
 
@@ -299 +298 @@
  === 8) void '''giet_get_xy'''( void* ptr, unsigned int* px, unsigned int* py ) ===
 This 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().  
-