/** @file dma_mbuf.h
 * Module handling Direct Memory Access controller's multibuffer system
 *
 * The module provides a convenient tool to send data to a peripheral in a
 * buffered, low-altency, low-cpu usage, non-blocking way
 */

#ifndef _DMA_MBUF_H_
#define _DMA_MBUF_H_

//--includes--------------------------------------------------------------------

#include "../drv/dma.h"


//--type definitions------------------------------------------------------------

/**
 * Struct used by the multibuffer system. This system allows bufferized writes
 * to a peripheral with no latency, minimal cpu usage and customisable buffer
 * sizes
 */
struct DmaMultiBuffer {
	uint8_t* raw_buffer;

	uint16_t buffer_size;

	uint8_t byte_index;
	uint8_t buffer_index;
	enum DmaPeriph dma;
	enum DmaChannel channel;

	bool dma_running;
};


//--functions-------------------------------------------------------------------

/**
 * Configure a DMA multibuffer for a single DMA channel. A list of buffers is
 * used to allow concurent write and DMA tranfers to the specified destination
 * wich must be a peripheral. The DMA's priority is also given as parameters.
 * The peripheral's specific configuration must be handled separately. 2 bytes
 * are reserved in each buffer for index storage.
 *
 * This system needs to be started manually: dma_mbuf_refresh() should be called
 * whenever a DMA transfer can be started. This can be done manually after
 * filling up the buffer. Transfers will then automatically be started as long
 * as there are bytes in the buffer. See the usart module for an usage exemple
 */
void dma_mbuf_configure(volatile struct DmaMultiBuffer* buffer,
		const struct DmaParam* param, enum DmaConfig priority,
		void* raw_buffer, uint16_t buffer_size);

/**
 * Write the given byte to the given buffer. Returns 0 if the write operation
 * was successfull, 1 otherwise. The function is non-blocking.
 *
 * Note: calling this function will not trigger a DMA transfer, see
 * dma_mbuf_refresh() to do that
 */
uint32_t dma_mbuf_write_byte(volatile struct DmaMultiBuffer* buffer,
		uint8_t byte);

/**
 * Refresh the buffer state, checking for bytes to send and triggering a DMA
 * transfer if necessary. Should be called for the first transfer, any remaining
 * transfer will be handled automatically until there are no bytes left in the
 * buffer
 */
void dma_mbuf_switch(volatile struct DmaMultiBuffer* buffer);


#endif //_DMA_MBUF_H_