The MWMR Library

The mwmr_channel.c​ and mwmr_channel.h​ files define an user-level communication middleware, for parallel multi-tasks applications.

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.

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. An item is an integer number of unsigned int (32 bits words). The "width" parameter define the number of words contained in an atomic item.

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

WARNING (ii) The MWMR channel, can be accessed by several tasks, but it must be initialized by one single task.

WARNING (iii) The channel must be declared in a non cacheable segment, if the platform does not provide hardware cache coherence.

Initialisation

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.
• width : number of 32 bits words contained in an item.
• items : max number of items in the channel.

It must be called by one single task.

Blocking Access Functions

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 )

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 Access Functions

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 )

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