= GIET_VM / MWR Driver =

[[PageOutline]]


The [source:soft/giet_vm/giet_drivers/mwr_driver.c mwr_driver.c] and [source:soft/giet_vm/giet_drivers/mwr_driver.h mwr_driver.h] files define the MWR driver for the vci_mwmr_dma peripheral.

The vci_mwmr_dma component is a multi-channels DMA controller that can be used to connect an hardware coprocesseur to a VCI interconnect.
This component provides the coprocessor one or several TO_COPROC or FROM_COPROC communication channels, without address.
Each T0_COPROC/FROM_COPROC port contains an hardware FIFO interface (DATA, R_WOK, W_ROK signals), plus three signals (REQ, ACK, BURSTS) allowing the coprocessor
to request an integer number of data burst. Each burst contains a fixed number of 32 bits words. For each coprocessor type, the burst length is an hardware parameter.

These communication channels implement two running modes:
 * in '''MWMR''' mode (Multi-Writer / Multi-Reader), the channel FSM transfer an ''infinite'' data stream between the coprocessor and a MWMR software FIFO, implementing the 7 steps MWMR protocol.
 * in '''DMA''' mode the channel FSM transfer data between the coprocessor and a fixed size memory buffer, with an optional interrupt signaling completion. 

The vci_mwmr_dma component is an ''internal'' peripheral, that can be replicated in all clusters. Each cluster can contain at most one coprocessor.

For the vci_mwmr_dma component, the addressable registers map and the command codes are defined [source:soft/giet_vm/giet_drivers/mwr_driver.h here].

Besides these communication channels registers, the vci_mwmr_dma componentt supports up to 16 coprocessor specific configuration/status registers. Configuration registers are Read/Write. Status registers are Read-Only.


 == __Coprocessor registers access functions__ ==

These functions can be used to access the coprocessor specific registers.

 === void '''_mwr_set_coproc_register'''( unsigned int cluster_xy ,  unsigned int index ,  unsigned int value ) ===
This function set a a new value in a coprocessor register.
 * '''cluster_xy''' : cluster coordinates.
 * '''index''' : register index.
 * '''value''' : value to be written.

 === unsigned int '''_mwr_get coproc_register'''( unsigned int cluster_xy , unsigned int index) ===
  * '''cluster_xy''' : cluster coordinates.
 * '''index''' : register index.

 == __Channel registers access functions__ == 

These functions access the communication channels registers contained in the vci_mwmr_dma controller.

 === void '''_mwr_set_channel_register'''( unsigned int cluster_xy ,  unsigned int channel ,  unsigned int index ,  unsigned int value ) ===
This function set a a new value in a coprocessor register.
 * '''cluster_xy''' : cluster coordinates.
 * '''channel''': channel index.
 * '''index''' : register index.
 * '''value''' : value to be written.

 === unsigned int '''_mwr_get channel_register'''( unsigned int cluster_xy , unsigned int channel,  unsigned int index) ===
 * '''cluster_xy''' : cluster coordinates.
 * '''channel''': channel index.
 * '''index''' : register index.

 == __Interrupt Service Routine__ ==

 === void '''_mwr_isr( unsigned int irq_type,  unsigned int irq_id,  unsigned int channel )
This Interrupt Service Routine handles the IRQ signaling the completion of a data transfer for a channel running in DMA_IRQ mode).
It set the _dma_done[x][y] synchronisation variable.