1 files changed, 376 insertions, 26 deletions

diff --git a/libmaple/include/libmaple/dma.h b/libmaple/include/libmaple/dma.h
index 0aed572..0ef495a 100644
--- a/libmaple/include/libmaple/dma.h
+++ b/libmaple/include/libmaple/dma.h
@@ -42,49 +42,399 @@ extern "C"{
 
 /* <series/dma.h> provides:
  *
+ * - An opaque dma_tube type, and predefined rvalues for each tube
+ *   supported by the series.
+ *
+ *   A "DMA tube" is a series-specific (hopefully integer) datatype
+ *   that abstracts the conduit through which DMA-ed data flow.
+ *
+ *   Examples: On STM32F1, dma_tube is just an alias for dma_channel,
+ *   and the tube values are just DMA_CH1 (=1), DMA_CH2 (=2), etc.
+ *
+ *   Note that a dma_tube doesn't have to be an enum, and its values
+ *   don't have to be integral. They _do_ need to be cheap to pass as
+ *   arguments, though.
+ *
+ * - struct dma_tube_reg_map (and typedef to dma_tube_reg_map). DMA
+ *   register maps tend to be split into global registers and per-tube
+ *   registers. It's convenient to pass around pointers to a tube's
+ *   registers, since that makes it possible to configure or otherwise
+ *   mess with a tube without knowing which one you're dealing with.
+ *
+ * - Base pointers to the various dma_tube_reg_maps.
+ *
+ *   Examples: On STM32F1, these are DMAxCHy_BASE. You can access
+ *   registers like DMAxCHy_BASE->CPAR, etc.
+ *
+ * - enum dma_request_src (and typedef to dma_request_src). This
+ *   specifies the peripheral DMA request sources (e.g. USART TX DMA
+ *   requests, etc.).
+ *
+ * - enum dma_mode_flags (and typedef to dma_mode_flags). Used in
+ *   dma_tube_config. If two series both support the same mode flags,
+ *   they must use the same enumerator names for those flags (the
+ *   values of those enumerators are of course allowed to differ).
+ *
  * - Normal stuff: dma_reg_map and base pointers, register bit
  *   definitions, dma_dev pointer declarations, and any other
- *   convenience functions useful for that series.
- */
+ *   convenience functions useful for the series. */
 #include <series/dma.h>
-
+/* <libmaple/dma_common.h> buys us dma_dev and other necessities. */
+#include <libmaple/dma_common.h>
 #include <libmaple/libmaple_types.h>
-#include <libmaple/nvic.h>
-#include <libmaple/rcc.h>
 
 /*
- * Devices
+ * Declarations/documentation for some of the series-provided types.
+ */
+
+/**
+ * @brief (Series-dependent) DMA request sources.
+ *
+ * These specify the various pieces of peripheral functionality which
+ * may make DMA requests.  Use them to set up a DMA transfer (see
+ * struct dma_tube_config, dma_tube_cfg()).
  */
+enum dma_request_src;
 
-/* Encapsulates state related to user interrupt handlers. You
- * shouldn't touch these directly; use dma_attach_interrupt() and
- * dma_detach_interupt() instead. */
-typedef struct dma_handler_config {
-    void (*handler)(void);     /* User handler */
-    nvic_irq_num irq_line;     /* IRQ line for interrupt */
-} dma_handler_config;
+/**
+ * @brief (Series-dependent) DMA tube configuration flags.
+ * These specify miscellaneous bits of configuration for a DMA tube.
+ * @see struct dma_mode_config
+ */
+enum dma_cfg_flags;
 
-/** DMA device type */
-typedef struct dma_dev {
-    dma_reg_map               *regs;       /**< Register map */
-    rcc_clk_id                 clk_id;     /**< Clock ID */
-    struct dma_handler_config  handlers[]; /**< For internal use */
-} dma_dev;
+/**
+ * @brief (Series-dependent) DMA tube register map type.
+ * This allows you to access a tube's registers as a group.
+ * @see dma_tube_regs()
+ */
+struct dma_tube_reg_map;
 
 /*
  * Convenience functions
  */
 
+/* Initialization */
+
 void dma_init(dma_dev *dev);
 
-/*
- * Hack: This is here so the series header can declare it and access
- * dma_dev->regs without knowing the structure of dma_dev. Don't use
- * it outside of a series header.
+/* dma_tube configuration
+ *
+ * Use these types and functions to set up DMA transfers, handle
+ * interrupts, etc. The main function of interest is dma_tube_cfg(),
+ * which the various series implement separately. */
+
+/**
+ * @brief Specifies a DMA tube configuration.
+ *
+ * Use one of these to set up a DMA transfer by passing it to
+ * dma_tube_cfg().
+ *
+ * @see dma_tube_cfg()
+ * @see dma_xfer_size
+ */
+typedef struct dma_tube_config {
+    /** Source of data */
+    __io void     *tube_src;
+    /** Source transfer size */
+    dma_xfer_size  tube_src_size;
+
+    /** Destination of data */
+    __io void     *tube_dst;
+    /** Destination transfer size */
+    dma_xfer_size  tube_dst_size;
+
+    /**
+     * Number of data to transfer (0 to 65,535).
+     *
+     * Note that this is NOT measured in bytes; it's measured in
+     * number of data, which occur in multiples of tube_src_size. For
+     * example, if tube_src_size is DMA_SIZE_32BITS and tube_nr_xfers
+     * is 2, then 8 total bytes will be transferred.
+     */
+    unsigned tube_nr_xfers;
+
+    /**
+     * Target-specific configuration flags.
+     *
+     * These are an OR of series-specific enum dma_mode_flags values.
+     * Consult the documentation for your target for what flags you
+     * can use here.
+     *
+     * Typical flag examples: DMA_CFG_SRC_INC, DMA_CFG_DST_INC,
+     * DMA_CFG_CIRC, DMA_CFG_CMPLT_IE, etc.
+     */
+    unsigned tube_flags;
+
+    /**
+     * Currently unused. You must set this to 0 or something valid for
+     * your target. */
+    void *target_data;
+
+    /**
+     * Hardware DMA request source.
+     *
+     * This is ignored for memory-to-memory transfers.
+     */
+    enum dma_request_src tube_req_src;
+} dma_tube_config;
+
+#define DMA_TUBE_CFG_SUCCESS 0
+#define DMA_TUBE_CFG_EREQ    1
+#define DMA_TUBE_CFG_ENDATA  2
+#define DMA_TUBE_CFG_EDEV    3
+#define DMA_TUBE_CFG_ESRC    4
+#define DMA_TUBE_CFG_EDST    5
+#define DMA_TUBE_CFG_EDIR    6
+#define DMA_TUBE_CFG_ESIZE   7
+#define DMA_TUBE_CFG_ECFG    0xFF
+/**
+ * @brief Configure a DMA tube.
+ *
+ * Use this function to set up a DMA transfer. The tube will be
+ * disabled before being reconfigured. The transfer will have low
+ * priority by default. You can choose another priority before the
+ * transfer begins using dma_set_priority(). You can manage your
+ * interrupt handlers for the tube using dma_attach_interrupt() and
+ * dma_detach_interrupt().
+ *
+ * After calling dma_tube_cfg() and performing any other desired
+ * configuration, start the transfer using dma_enable().
+ *
+ * @param dev  DMA device.
+ * @param tube DMA tube to configure.
+ * @param cfg  Configuration to apply to tube.
+ *
+ * @return DMA_TUBE_CFG_SUCCESS (0) on success, <0 on failure. On
+ *         failure, returned value will be the opposite (-) of one of:
+ *
+ *         - DMA_TUBE_CFG_EREQ: tube doesn't work with cfg->tube_req_src
+ *         - DMA_TUBE_CFG_ENDATA: cfg->tube_[src,dst]_size are
+ *           incompatible with cfg->tube_nr_xfers, or cfg->tube_nr_xfers
+ *           is out of bounds.
+ *         - DMA_TUBE_CFG_EDEV: dev does not support cfg
+ *         - DMA_TUBE_CFG_ESRC: bad cfg->tube_src
+ *         - DMA_TUBE_CFG_EDST: bad cfg->tube_dst
+ *         - DMA_TUBE_CFG_EDIR: dev can't transfer from cfg->tube_src to
+ *           cfg->tube_dst
+ *         - DMA_TUBE_CFG_ESIZE: something ended up wrong due to MSIZE/PSIZE
+ *         - DMA_TUBE_CFG_ECFG: generic "something's wrong"
+ *
+ * @sideeffect Disables tube. May alter tube's registers even when an
+ *             error occurs.
+ * @see struct dma_tube_config
+ * @see dma_attach_interrupt()
+ * @see dma_detach_interrupt()
+ * @see dma_enable()
+ */
+extern int dma_tube_cfg(dma_dev *dev, dma_tube tube, dma_tube_config *cfg);
+
+/* Other tube configuration functions. You can use these if
+ * dma_tube_cfg() isn't enough, or to adjust parts of an existing tube
+ * configuration. */
+
+/** DMA transfer priority. */
+typedef enum dma_priority {
+    DMA_PRIORITY_LOW       = 0, /**< Low priority */
+    DMA_PRIORITY_MEDIUM    = 1, /**< Medium priority */
+    DMA_PRIORITY_HIGH      = 2, /**< High priority */
+    DMA_PRIORITY_VERY_HIGH = 3, /**< Very high priority */
+} dma_priority;
+
+/**
+ * @brief Set the priority of a DMA transfer.
+ *
+ * You may not call this function while the tube is enabled.
+ *
+ * @param dev DMA device
+ * @param tube DMA tube
+ * @param priority priority to set.
+ */
+extern void dma_set_priority(dma_dev *dev, dma_tube tube,
+                             dma_priority priority);
+
+/**
+ * @brief Set the number of data transfers on a DMA tube.
+ *
+ * You may not call this function while the tube is enabled.
+ *
+ * @param dev DMA device
+ * @param tube Tube through which the transfer will occur.
+ * @param num_transfers Number of DMA transactions to set.
+ */
+extern void dma_set_num_transfers(dma_dev *dev, dma_tube tube,
+                                  uint16 num_transfers);
+
+/**
+ * @brief Set the base memory address where data will be read from or
+ *        written to.
+ *
+ * You must not call this function while the tube is enabled.
+ *
+ * If the DMA memory size is 16 bits, the address is automatically
+ * aligned to a half-word.  If the DMA memory size is 32 bits, the
+ * address is aligned to a word.
+ *
+ * @param dev DMA Device
+ * @param tube Tube whose base memory address to set.
+ * @param address Memory base address to use.
+ */
+extern void dma_set_mem_addr(dma_dev *dev, dma_tube tube, __io void *address);
+
+/**
+ * @brief Set the base peripheral address where data will be read from
+ *        or written to.
+ *
+ * You must not call this function while the channel is enabled.
+ *
+ * If the DMA peripheral size is 16 bits, the address is automatically
+ * aligned to a half-word. If the DMA peripheral size is 32 bits, the
+ * address is aligned to a word.
+ *
+ * @param dev DMA Device
+ * @param tube Tube whose peripheral data register base address to set.
+ * @param addr Peripheral memory base address to use.
+ */
+extern void dma_set_per_addr(dma_dev *dev, dma_tube tube, __io void *address);
+
+/* Interrupt handling */
+
+/**
+ * @brief Attach an interrupt to a DMA transfer.
+ *
+ * Interrupts are enabled using series-specific mode flags in
+ * dma_tube_cfg().
+ *
+ * @param dev DMA device
+ * @param tube Tube to attach handler to
+ * @param handler Interrupt handler to call when tube interrupt fires.
+ * @see dma_tube_cfg()
+ * @see dma_get_irq_cause()
+ * @see dma_detach_interrupt()
+ */
+extern void dma_attach_interrupt(dma_dev *dev, dma_tube tube,
+                                 void (*handler)(void));
+
+
+/**
+ * @brief Detach a DMA transfer interrupt handler.
+ *
+ * After calling this function, the given tube's interrupts will be
+ * disabled.
+ *
+ * @param dev DMA device
+ * @param tube Tube whose handler to detach
+ * @sideeffect Clears the tube's interrupt enable bits.
+ * @see dma_attach_interrupt()
+ */
+extern void dma_detach_interrupt(dma_dev *dev, dma_tube tube);
+
+/* Tube enable/disable */
+
+/**
+ * @brief Enable a DMA tube.
+ *
+ * If the tube has been properly configured, calling this function
+ * allows it to start serving DMA requests.
+ *
+ * @param dev DMA device
+ * @param tube Tube to enable
+ * @see dma_tube_cfg()
+ */
+extern void dma_enable(dma_dev *dev, dma_tube tube);
+
+/**
+ * @brief Disable a DMA channel.
+ *
+ * Calling this function makes the tube stop serving DMA requests.
+ *
+ * @param dev DMA device
+ * @param tube Tube to disable
+ */
+extern void dma_disable(dma_dev *dev, dma_tube tube);
+
+/**
+ * @brief Check if a DMA tube is enabled.
+ * @param dev DMA device.
+ * @param tube Tube to check.
+ * @return 0 if the tube is disabled, >0 if it is enabled.
+ */
+static inline uint8 dma_is_enabled(dma_dev *dev, dma_tube tube);
+
+/* Other conveniences */
+
+/**
+ * @brief Obtain a pointer to an individual DMA tube's registers.
+ *
+ * Examples:
+ *
+ * - On STM32F1, dma_channel_regs(DMA1, DMA_CH1)->CCR is DMA1_BASE->CCR1.
+ *
+ * @param dev DMA device.
+ * @param tube DMA tube whose register map to obtain.
+ * @return (Series-specific) tube register map.
+ */
+static inline dma_tube_reg_map* dma_tube_regs(dma_dev *dev, dma_tube tube);
+
+/**
+ * Encodes the reason why a DMA interrupt was called.
+ * @see dma_get_irq_cause()
+ */
+typedef enum dma_irq_cause {
+    DMA_TRANSFER_COMPLETE,      /**< Transfer is complete. */
+    DMA_TRANSFER_HALF_COMPLETE, /**< Transfer is half complete. */
+    DMA_TRANSFER_ERROR,         /**< Error occurred during transfer. */
+    DMA_TRANSFER_DME_ERROR,     /**<
+                                 * @brief Direct mode error occurred during
+                                 *        transfer. */
+    DMA_TRANSFER_FIFO_ERROR,    /**< FIFO error occurred during transfer. */
+} dma_irq_cause;
+
+/**
+ * @brief Discover the reason why a DMA interrupt was called.
+ *
+ * You may only call this function within an attached interrupt
+ * handler for the given channel.
+ *
+ * This function resets the internal DMA register state which encodes
+ * the cause of the interrupt; consequently, it can only be called
+ * once per interrupt handler invocation.
+ *
+ * @param dev DMA device
+ * @param tube Tube whose interrupt is being handled.
+ * @return Reason why the interrupt fired.
+ * @sideeffect Clears flags in dev's interrupt status registers.
+ * @see dma_attach_interrupt()
+ * @see dma_irq_cause
+ */
+extern dma_irq_cause dma_get_irq_cause(dma_dev *dev, dma_tube tube);
+
+/**
+ * @brief Get the ISR status bits for a DMA channel.
+ *
+ * The bits are returned right-aligned, in the order they appear in
+ * the corresponding ISR register.
+ *
+ * If you're trying to figure out why a DMA interrupt fired, you may
+ * find dma_get_irq_cause() more convenient.
+ *
+ * @param dev DMA device
+ * @param tube Tube whose ISR bits to return.
+ * @see dma_get_irq_cause().
+ */
+static inline uint8 dma_get_isr_bits(dma_dev *dev, dma_tube tube);
+
+/**
+ * @brief Clear the ISR status bits for a given DMA tube.
+ *
+ * If you're trying to clean up after yourself in a DMA interrupt, you
+ * may find dma_get_irq_cause() more convenient.
+ *
+ * @param dev DMA device
+ * @param tube Tube whose ISR bits to clear.
+ * @see dma_get_irq_cause()
  */
-static __always_inline dma_reg_map* _dma_dev_regs(dma_dev *dev) {
-    return dev->regs;
-}
+static inline void dma_clear_isr_bits(dma_dev *dev, dma_tube tube);
 
 #ifdef __cplusplus
 } // extern "C"