The MWMR Library

The mwmr_channel.c​ and 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. 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.

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.

A private lock provides exclusive access to the MWMR channel, that can have a variable number of producers and a variable number of consumers.

WARNING : The MWMR channels, being generally shared by several tasks, must be defined in the mapping, to be initialised by the GIET in the boot phase, and to define the length and width parameters. The channel must be in a non cacheable segment, if the platform does not provide hardware cache coherence.

The vobj_get_vbase() system call can be used by the tasks to get the virtual base address of the channel from it's name.

Blocking Functions

The mwmr_read() and mwmr_write() functions are blocking functions, that return only when the transfer is completed.

void mwmr_write( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int nitems )

This function transfer (nitems * width) 32 bits words from a task private buffer to the 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 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 )

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

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.

Non Blocking Functions

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). /