Document dma_cbuf service

srv/dma_cbuf.c

@@ -12,9 +12,13 @@
 
 //--local definitions-----------------------------------------------------------
 
+/**
+ * DMA configuration to be used for the buffer. Additionnal configuration may be
+ * added by the peripherals used
+ */
 #define DMA_CONFIG (DMA_CONFIG_IRQ_COMPLETE | DMA_CONFIG_FROM_PERIPH  \
 					| DMA_CONFIG_CIRCULAR | DMA_CONFIG_INC_MEM        \
-					| DMA_CONFIG_PSIZE_8BITS | DMA_CONFIG_MSIZE_8BITS)
+					| DMA_CONFIG_MSIZE_8BITS)
 
 static void cbuf_callback(enum DmaIRQSource src, volatile void* param);
 

srv/dma_cbuf.h

@@ -26,8 +26,8 @@ struct DmaCircBuffer {
 	uint16_t size;            //the size of the buffer
 	uint16_t begin;           //pointer to the current begin of the buffer
 
-	enum DmaPeriph dma;
-	enum DmaChannel channel;
+	enum DmaPeriph dma;      //DMA peripheral used for transfers
+	enum DmaChannel channel; //DMA channel used for transfers
 
 	bool dma_looped;          //whether the DMA looped or not (buffer overflow)
 };
@@ -38,8 +38,12 @@ struct DmaCircBuffer {
 /**
  * Configure a DMA circular buffer for a single DMA channel. A standard buffer
  * is used a base to construct a circular buffer, supplied in data by DMA
- * tranfers from a peripheral. The DMA's priority is given as parameters.
+ * tranfers from a peripheral.
  * The peripheral's specific configuration must be handled separately.
+ * Each peripheral's driver is responsible for providing the DMA configuration
+ * for said peripheral, though it can be manually given too. Please note that
+ * multiple peripherals may share the same DMA channel, which will cause issue
+ * when used with this buffer.
  *
  * Once this function is called, the system will start running right away and
  * will stay running until manually stopped
@@ -48,6 +52,10 @@ void dma_cbuf_configure(volatile struct DmaCircBuffer* buffer,
 		const struct DmaParam* param, enum DmaConfig priority,
 		volatile void* raw_buffer, uint16_t buffer_size);
 
+/**
+ * Reads a bytes from the buffer, returning if the read operation was
+ * successfull, 1 otherwise. This function is non-blocking.
+ */
 uint32_t dma_cbuf_read_byte(volatile struct DmaCircBuffer* buffer,
 		uint8_t* byte);