stm32f1xx_HBL/drv/dma.h

/** @file dma.h
 * Module handling Direct Memory Access controller
 *
 * The module provides functions to configure the dma channels and controller
 * transfers
 */

#ifndef _DMA_H_
#define _DMA_H_

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

#include "stdint.h"


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

/**
 * Available DMA peripherals. Note that some of these peripherals may not be
 * available on all chips
 */
enum DmaPeriph {
	DMA_PERIPH_1,
	DMA_PERIPH_2,
};

/**
 * Available DMA channels. Note that some of these channels may not be
 * available on all chips and all DMA peripheral
 */
enum DmaChannel {
	DMA_CHANNEL_1 = 0,
	DMA_CHANNEL_2,
	DMA_CHANNEL_3,
	DMA_CHANNEL_4,
	DMA_CHANNEL_5,
	DMA_CHANNEL_6, //not available for DMA 2
	DMA_CHANNEL_7, //not available for DMA 2
};

/**
 * Configuration options for memory-to-peripheral transfers
 */
enum DmaConfig {
	DMA_CONFIG_IRQ_COMPLETE = (0x1 <<  1),
	DMA_CONFIG_IRQ_HALF     = (0x1 <<  2),
	DMA_CONFIG_IRQ_ERROR    = (0x1 <<  3),
	DMA_CONFIG_FROM_MEM     = (0x1 <<  4),
	DMA_CONFIG_FROM_PERIPH  = (0x0 <<  4),
	DMA_CONFIG_CIRCULAR     = (0x1 <<  5),
	DMA_CONFIG_INC_PERIPH   = (0x1 <<  6),
	DMA_CONFIG_INC_MEM      = (0x1 <<  7),
	DMA_CONFIG_PSIZE_8BITS  = (0x0 <<  8),
	DMA_CONFIG_PSIZE_16BITS = (0x1 <<  8),
	DMA_CONFIG_PSIZE_32BITS = (0x2 <<  8),
	DMA_CONFIG_MSIZE_8BITS  = (0x0 << 10),
	DMA_CONFIG_MSIZE_16BITS = (0x1 << 10),
	DMA_CONFIG_MSIZE_32BITS = (0x2 << 10),
	DMA_CONFIG_PRIO_LOW     = (0x0 << 12),
	DMA_CONFIG_PRIO_MEDIUM  = (0x1 << 12),
	DMA_CONFIG_PRIO_HIGH    = (0x2 << 12),
	DMA_CONFIG_PRIO_VHIGH   = (0x3 << 12),
};

/**
 * Configuration options for memory-to-memory transfers
 */
enum DmaConfigM2M {
	DMA_CONFIG_M2M_IRQ_COMPLETE = (0x1 <<  1),
	DMA_CONFIG_M2M_IRQ_HALF     = (0x1 <<  2),
	DMA_CONFIG_M2M_IRQ_ERROR    = (0x1 <<  3),
	DMA_CONFIG_M2M_INC_SRC      = (0x1 <<  6),
	DMA_CONFIG_M2M_INC_DEST     = (0x1 <<  7),
	DMA_CONFIG_M2M_SSIZE_8BITS  = (0x0 <<  8),
	DMA_CONFIG_M2M_SSIZE_16BITS = (0x1 <<  8),
	DMA_CONFIG_M2M_SSIZE_32BITS = (0x2 <<  8),
	DMA_CONFIG_M2M_DSIZE_8BITS  = (0x0 << 10),
	DMA_CONFIG_M2M_DSIZE_16BITS = (0x1 << 10),
	DMA_CONFIG_M2M_DSIZE_32BITS = (0x2 << 10),
	DMA_CONFIG_M2M_PRIO_LOW     = (0x0 << 12),
	DMA_CONFIG_M2M_PRIO_MEDIUM  = (0x1 << 12),
	DMA_CONFIG_M2M_PRIO_HIGH    = (0x2 << 12),
	DMA_CONFIG_M2M_PRIO_VHIGH   = (0x3 << 12),
};

/**
 * Available sources for a DMA IRQ. These sources can be enabled independently
 * in the DMA configuration.
 */
enum DmaIRQSource {
	DMA_IRQ_SOURCE_COMPLETE = (0x1 << 1),
	DMA_IRQ_SOURCE_HALF     = (0x1 << 2),
	DMA_IQR_SOURCE_ERROR    = (0x2 << 3),
};

/**
 * Prototype of the IRQ callbacks that the applicative code can provide
 */
typedef void (*DmaCallback)(enum DmaIRQSource src, volatile void* param);

/**
 * Generic struct used to share DAM configs between peripheral drivers and
 * services providing DMA interfaces
 */
struct DmaParam {
	void* periph;
	enum DmaConfig config;    //DMA config, must correspond to peripheral
	enum DmaPeriph dma;       //DMA peripheral, must correspond to peripheral
	enum DmaChannel channel;  //DMA channel, must correspond to peripheral
};


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

/**
 * Configures the given DMA channel with the provided configuration, to perform
 * a transfer to or from the given peripheral register. The specified callback,
 * if any, will be called on the enabled IRQ sources, with the specified
 * parameter, if any.
 *
 * This function doesn't initiate transfers, use dma_start() for that
 */
void dma_configure(enum DmaPeriph dma, enum DmaChannel channel,
		enum DmaConfig config_mask, volatile void* periph,
		DmaCallback callback, volatile void* cb_param);

/**
 * Unimplemented
 */
void dma_configure_mem2mem(enum DmaPeriph dma, enum DmaChannel channel,
		enum DmaConfigM2M config_mask, const void* src, void* dest,
		uint16_t size, DmaCallback callback, void* cb_param);

/**
 * Resets the given DMA channel, restoring the default configuration and
 * disabling it
 */
void dma_reset(enum DmaPeriph dma, enum DmaChannel channel);

/**
 * Initiate a transfer on the given DMA channel, to or from the given memory
 * address, and of the specified size.
 *
 * Should only be used after the channel has been configured through
 * dma_configure()
 * All transfers started must be eventually stopped, or the channel reset, for
 * proper IRQ behavior.
 */
void dma_start(enum DmaPeriph dma, enum DmaChannel channel,
		volatile void* mem, uint16_t size);

/**
 * Stops a transfer on the given DMA channel. If the transfer has already
 * ended, properly shutdown the channel. Configuration is not lost after calling
 * this function and dma_start() may be called again
 */
void dma_stop(enum DmaPeriph dma, enum DmaChannel channel);

/**
 * Enters a DMA critical section, disabling the given channel's IRQs until
 * dma_exit_critical() is called
 */
void dma_enter_critical(enum DmaPeriph dma, enum DmaChannel channel);

/**
 * Exists a DMA critical section previously entered through
 * dma_enter_critical(). Reenables the given channel's IRQs
 */
void dma_exit_critical(enum DmaPeriph dma, enum DmaChannel channel);

/**
 * Returns the remaining number of bytes to be transmitted while a transfer is
 * running. When no transfer is running, returns the number of bytes to transfer
 * next
 */
uint16_t dma_get_remaining(enum DmaPeriph dma, enum DmaChannel channe);


#endif //_DMA_H_