Changes between Version 3 and Version 4 of library_mwmr

Timestamp:

Nov 6, 2014, 6:03:30 PM (10 years ago)

Author:

alain

Comment:

--

library_mwmr

@@ -3 +3 @@
 The [source:soft/giet_vm/giet_libs/mwmr_channel.c mwmr_channel.c] and [source:soft/giet_vm/giet_libs/mwmr_channel.h mwmr_channel.h] files define an user-level communication middleware. 
 
-This middleware supports channelized communications in a parallel multi-tasks application, where the communication scheme can be explicitely and statically described by a Task and Communication Graph.
+It supports channelized communications in a parallel multi-tasks application, where the communication scheme can be explicitely and statically described by a Task and Communication Graph.
 Each MWMR (Multi-Writer Multi-Reader) channel can be accessed concurently by one or several writer(s) and by one or several reader(s). It is implemented as a software FIFO, protected by a build-in lock.
+
+This software FIFO can be directly accessed by an hardware coprocessor, thanks to the vc_mwmr_controller, but be describe here the the software API that can be used by a software application.
 
 An MWMR transaction transfer an integer number of items, and an item is an integer number of unsigned int (32 bits words). The max number of words that can be stored in a MWMR channel is defined by the"depth" parameter. The "width" parameter define the minimal number of words contained in an atomic item. Therefore, the "depth" parameter must be a multiple of the "width" parameter.
@@ -22 +24 @@
  * '''mwmr''' : MWMR channel virtual base address.
  * '''nitems''' : number of items to be transfered.
- * '''buffer''' : virtual base address of local buffer
+ * '''buffer''' : virtual base address of local buffer.
 It takes the lock for exclusive access before testing the channel state. If there is not enough space in mwmr channel to write nitems, it writes as many items as possible, releases the lock, and retry  after a random delay.
 
-=== void '''mwmr_read'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int    nitems ) ===
+=== void '''mwmr_read'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int nitems ) ===
 This function transfer (nitems * width) 32 bits words from the MWMR channel to a task private buffer.
  * '''mwmr''' : MWMR channel virtual base address.
  * '''nitems''' : number of items to be transfered.
- * '''buffer''' : virtual base address of local buffer
+ * '''buffer''' : virtual base address of local buffer.
 It takes the lock for exclusive access before testing the channel state. If there is not enough space in mwmr channel to write nitems, it writes as many items as possible, releases the lock, and retry  after a random delay.
 
@@ -37 +39 @@
 The ''nb_mwmr_read()'' and ''nb_mwmr_write()'' functions are non-blocking functions. 
 
-=== unsigned int '''nb_mwmr_write'''() ===
-// This is a non-blocking function.
-// The nitems parameter is the number of items to be transfered.
-// The requested transfer is therefore (nitems * width) words.
-// It takes the lock for exclusive access before testing the channel state.
-// If there is not enough data in mwmr channel to read nitems,
-// it reads as many items as possible, releases the lock, and returns 
-// the number of read items (it can be 0).
-///////////////////////////////////////////////////////////////////////////////////
+=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int nitems ) ===
+This function request to transfer (nitems * width) 32 bits words from a task private buffer tot he MWMR channel.
+ * '''mwmr''' : MWMR channel virtual base address.
+ * '''nitems''' : number of items to be transfered.
+ * '''buffer''' : virtual base address of local buffer.
+It takes the lock for exclusive access before testing the channel state. If there is not enough free space in the channel, it transfer as many items as possible, releases the lock, and returns the number of actually transfered items (it can be 0).
+
+=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int nitems ) ===
+This function request to transfer (nitems * width) 32 bits words from the MWMR channel to a task private buffer.
+ * '''mwmr''' : MWMR channel virtual base address.
+ * '''nitems''' : number of items to be transfered.
+ * '''buffer''' : virtual base address of local buffer.
+It takes the lock for exclusive access before testing the channel state. If there is not enough data in the channel, it transfer as many items as possible, releases the lock, and returns the number of actually transfered items (it can be 0).
+