= 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 FIFO type 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. The burst length is an hardware parameter.

Each channel implements two running modes:
 * in '''MWMR''' mode the channel FSM transfer an infinite" stream of data to or from a MWMR software FIFO, implementing the 7 steps MWMR protocol.
 * in '''DMA''' mode the channel FSM transfer a fixed size chunk of data to or from a memory buffer, with an optional completion signaling interrupt.

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

The addressable registers map and command codes are defined [source:soft/giet_vm/giet_drivers/mwr_driver.h here].

 == Channel Registers access functions == 

 === void '''_mwr_channel_init'''( unsigned int cluster_xy, unsigned int channel, unsigned int mode, unsigned long long buffer_paddr, unsigned int buffer_size, unsigned long long desc_paddr, unsigned long long lock_paddr ) ===
This function initialises all registers defining one communication channel for a given coprocessor.
 * '''cluster_xy''' is the cluster index
 * '''channel''' is the channel index
 * '''mode''' is the requested mode (MWMR / DMA_IRQ / DMA_NO_IRQ)
 * '''buffer_paddr''' is the memory buffer physical address
 * '''buffer_size''' is the memory buffer size (bytes)
 * '''desc_paddr''' is the MWMR descriptor physical address (only used in MWMR mode)
 * '''lock_paddr''' is the MWMR lock physical address (only used in MWMR mode)

 === void '''_mwr_channel_start'''( unsigned int cluster_xy,  unsigned int channel ) ===
This function activates one communication channel for a given coprocessor (set a non zero value in the RUNNING channel register).
 * '''cluster_xy''' is the cluster index
 * '''channel''' is the channel index

 === void '''_mwr_channel_stop'''( unsigned int cluster_xy,  unsigned int channel ) ===
This function desactivates one communication channel for a given coprocessor (set a zero value in the RUNNING channel register).
 * '''cluster_xy''' is the cluster index
 * '''channel''' is the channel index

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