Changes between Version 12 and Version 13 of library_mwmr

Timestamp:

Dec 2, 2014, 6:44:56 PM (10 years ago)

Author:

alain

Comment:

--

library_mwmr

@@ -6 +6 @@
 
 It supports channelized communications , when the communication scheme can be 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.
+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, user-level spin_lock.
 
 This software FIFO can be directly accessed by an hardware coprocessor, thanks to the vc_mwmr_controller, but we only describe here the software API that can be used by a software applications.
 
-An MWMR transaction transfer an integer number of ''items'' between a task private buffer and the MWMR  channel. An ''item'' is an integer number of unsigned int (32 bits words). The channel "width" parameter define the number of words contained in an atomic ''item''. 
+An MWMR transaction transfer an integer number of items between a task private buffer and the MWMR communication channel. An item is the smallest quantity of data that can be atomically transfered. It is an integer number of 32 bits words (unsigned int). 
 
-WARNING (i) The max number of words that can be stored in a MWMR channel is 1018 words (4072 bytes), because  the mwmr_channel_t object has a fixed size (4Kbytes in the present implementation).
+An MWMR channel is therefore defined by two parameters:
+ * The '''width''' parameter define the number of words contained in an item (can be 1). 
+ * The '''nitems''' parameter define the max number of items that can be stored in the FIFO. 
 
-WARNING (ii) The MWMR channel, can be accessed by several tasks, but it must be initialized by one single task.
+In the user code, an MWMR channel must be defined by two global variables:
+ * a '''channel descriptor''' is a variable of type '''mwmr_channel_t'''.
+ * a '''data buffer''' that is an array of (width * items) unsigned int entries.
 
-WARNING (iii) The channel must be declared in a non cacheable segment, if the platform does not provide hardware cache coherence.
+WARNING (i) The MWMR channel, can be accessed by several tasks, but it must be initialized by one single task.
+
+WARNING (ii) The channel must be declared in a non cacheable segment, if the platform does not provide hardware cache coherence.
 
 == Initialisation Function ==
 
-=== void '''mwmr_init'''( mwmr_channel_t* mwmr, unsigned int width, unsigned int    items ) ===
-This function initializes the MWMR channel descriptor (including the lock). 
- * '''mwmr''' : MWMR channel virtual base address.
+=== void '''mwmr_init'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int  width, unsigned int  items ) ===
+This function initializes the MWMR channel descriptor (including the lock protecting exclusive access). 
+ * '''mwmr''' : MWMR channel descriptor base address.
+ * '''buffer''' : data buffer (unsigned int) base address.
  * '''width''' : number of 32 bits words contained in an item.
- * '''items''' : max number of items in the channel.
+ * '''nitems''' : max number of items in the channel.
 It must be called by one single task.
 
@@ -31 +38 @@
 The ''mwmr_read()'' and ''mwmr_write()'' functions are blocking functions, that return only when the requested transfer is completed.
 
-=== void '''mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int    nitems ) ===
+=== void '''mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int  items ) ===
 This function transfer (nitems * width) 32 bits words from a task private buffer to the MWMR channel.
  * '''mwmr''' : MWMR channel virtual base address.
  * '''buffer''' : virtual base address of local buffer.
- * '''nitems''' : number of items to be transfered.
-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.
+ * '''items''' : number of items to be transfered.
+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, does not return, but retry to take the lock to transfer the rest of the data... up to completion.
 
-=== 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 items ) ===
 This function transfer (nitems * width) 32 bits words from the MWMR channel to a task private buffer.
  * '''mwmr''' : MWMR channel virtual base address.
  * '''buffer''' : virtual base address of local buffer.
- * '''nitems''' : number of items to be transfered.
-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.
+ * '''items''' : number of items to be transfered.
+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, does not return, but retry to take the lock to transfer the rest of the data... up to completion.
 
 
@@ -50 +57 @@
 The ''nb_mwmr_read()'' and ''nb_mwmr_write()'' functions are non-blocking functions. 
 
-=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int nitems ) ===
+=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int items ) ===
 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.
  * '''buffer''' : virtual base address of local buffer.
- * '''nitems''' : number of items to be transfered.
+ * '''items''' : number of items to be transfered.
 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 ) ===
+=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int items ) ===
 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.
  * '''buffer''' : virtual base address of local buffer.
- * '''nitems''' : number of items to be transfered.
+ * '''items''' : number of items to be transfered.
 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).