Changes between Version 13 and Version 14 of library_mwmr


Ignore:
Timestamp:
Oct 29, 2015, 6:35:56 PM (10 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • library_mwmr

    v13 v14  
    33[[PageOutline]]
    44
    5 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, for parallel multi-tasks applications.
     5The [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, for parallel multi-threads applications.
    66
    77It supports channelized communications , when the communication scheme can be statically described by a Task and Communication Graph.
    88Each 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.
    99
    10 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.
     10This software FIFO can be directly accessed by an hardware coprocessor, thanks to the vci_mwmr_controller, but we only describe here the software API that can be used by a software applications.
    1111
    12 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).
     12An MWMR transaction transfer an integer number of items between a thread 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).
    1313
    14 An MWMR channel is therefore defined by two parameters:
     14An '''mwmr_channel_t''' communication channel is therefore defined by two parameters:
    1515 * The '''width''' parameter define the number of words contained in an item (can be 1).
    1616 * The '''nitems''' parameter define the max number of items that can be stored in the FIFO.
    … …  
    2424WARNING (ii) The channel must be declared in a non cacheable segment, if the platform does not provide hardware cache coherence.
    2525
    26 == Initialisation Function ==
     26The '''mwmr_read()''' and '''mwmr_write() blocking access functions can be used to implement a parallel application complying with the KPN (Kahn Process Network) semantic.
     27 
     28The '''nb_mwmr_read()''' and '''nb_mwmr_write() are non blocking access that can be used to implement various higher level communication protocols.
     29
     30Besides the MWMR channels, the MWMR library provide  another - optional - service: The '''mwmr_bufio_t''' buffer (and the associated access functions) can be used to implement a private input or output buffer,  and move data to or from a shared MWMR communication channel.  This buffer can be declared as a local variable in the stack of the reader/writer thread, and simplifies the access to the MWMR channel when the transfered data have a non fixed format, and must be analysed or produced byte per byte: an input buffer is automatically refill when it becomes empty; an output buffer is automatically flushed when it becomes full
     31
     32
     33== Communication Channel Initialisation ==
    2734
    2835=== void '''mwmr_init'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int  width, unsigned int  items ) ===
    … …  
    3441It must be called by one single task.
    3542
    36 == Blocking Access Functions ==
    37 
    38 The ''mwmr_read()'' and ''mwmr_write()'' functions are blocking functions, that return only when the requested transfer is completed.
     43== Communication Channel Blocking Access ==
    3944
    4045=== void '''mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int  items ) ===
    … …  
    5358
    5459
    55 == Non Blocking Access Functions ==
    56 
    57 The ''nb_mwmr_read()'' and ''nb_mwmr_write()'' functions are non-blocking functions.
     60== Communication Channel Non Blocking Access  ==
    5861
    5962=== unsigned int '''nb_mwmr_write'''( mwmr_channel_t* mwmr, unsigned int* buffer, unsigned int items ) ===
    … …  
    7174It 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).
    7275
     76== Private Buffer Initialization ==
     77
     78=== void '''mwmr_bufio_init'''( mwmr_bufio_t* bufio , uint8_t* buffer , uint32_t size , uint32_t is_input , mwmr_channel_t* mwmr ) ===
     79This function initializes the BUFIO descriptor.
     80 * '''bufio''' : pointer on the BUFIO descriptor.
     81 * '''buffer''' : pointer on the private buffer.
     82 * '''size''' : number of bytes in the private buffer / must be multiple of 4.
     83 * '''is_input''' : buffer type  / input buffer when non-zero.
     84 * '''mwmr''' : pointer on the associated MWMR channel descriptor.
     85 
     86== Private Buffer Access ==
     87                   
     88=== uint8_t '''mwmr_bufio_read_byte'''( mwmr_bufio_t* bufio ) ===
     89This blocking function uses the mwmr_read() function, and returns one single byte from the MWMR channel associated to the <bufio> input buffer.
     90
     91=== uint16_t '''mwmr_bufio_read_half'''( mwmr_bufio_t* bufio ) ===
     92This blocking function uses the mwmr_read() function, and returns two bytes from the MWMR channel associated to the <bufio> input buffer.
     93
     94=== uint32_t '''mwmr_bufio_read_word'''( mwmr_bufio_t* bufio ) ===
     95This blocking function uses the mwmr_read() function, and returns four bytes from the MWMR channel associated to the <bufio> input buffer.
     96
     97=== void '''mwmr_bufio_write_byte'''( mwmr_bufio_t* bufio , uint8_t value ) ===
     98
     99=== void '''mwmr_bufio_write_half'''( mwmr_bufio_t* bufio , uint16_t value ) ===
     100
     101=== void '''mwmr_bufio_write_word'''( mwmr_bufio_t* bufio , uint32_t value ) ===
     102
     103=== void '''mwmr_bufio_flush'''( mwmr_bufio_t* bufio ) ===
     104
     105=== void '''mwmr_bufio_skip'''( mwmr_bufio_t* bufio , uint32_t length ) ===
     106