DMA: prep for F2 with new "tube" API.

To prepare for STM32F2/F4 DMA support, introduce a new libmaple DMA
API, and move some code around to make priority level and interrupt
handling more generic.

The new API is based on a new set of types (dma_tube, struct
dma_tube_reg_map, enum dma_request_src, enum dma_cfg_flags, and struct
dma_tube_config).

The central abstraction is the dma_tube type. STM32F2/F4 use DMA
streams to control dataflow, and STM32F1 uses channels. dma_tube
stands for whichever is appropriate for the current target. Dealing
with tubes allows for configuring and using DMA with opaque tube
values in the same source, instead of (as with ST's firmware)
requiring two separate codebases.

The new API is also more user-friendly, as it doesn't require knowing
which DMA address registers to set and which configuration register
flags go along with them. It now suffices to specify the source and
destination for the DMA transfer, along with their sizes. This avoids
confusion (e.g. for memory-to-memory transfers, data flows from the
peripheral address register to the memory register, which might be
surprising on F2, which has two memory address registers).

The old API (based on enum dma_mode_flags and dma_setup_transfer()) is
still available on F1, but deprecate it.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

2 files changed, 490 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"
diff --git a/libmaple/include/libmaple/dma_common.h b/libmaple/include/libmaple/dma_common.h
new file mode 100644
index 0000000..67475f7
--- /dev/null
+++ b/libmaple/include/libmaple/dma_common.h
@@ -0,0 +1,114 @@
+/******************************************************************************
+ * The MIT License
+ *
+ * Copyright (c) 2012 LeafLabs, LLC.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *****************************************************************************/
+
+/**
+ * @file libmaple/include/libmaple/dma_common.h
+ * @author Marti Bolivar <mbolivar@leaflabs.com>
+ * @brief Common DMA sub-header for <series/dma.h> and <libmaple/dma.h>.
+ *
+ * WARNING: CONTENTS UNSTABLE
+ *
+ * The existence of this file is an implementation detail.  Its
+ * contents are not stable, so never include it directly.  If you need
+ * something from here, #include <libmaple/dma.h> instead.
+ */
+
+/*
+ * There's a fair amount of common DMA functionality needed by each
+ * <series/dma.h> and <libmaple/dma.h>.  This header exists in order
+ * to provide it to both, avoiding some hacks and circular
+ * dependencies.
+ */
+
+#ifndef _LIBMAPLE_DMA_COMMON_H_
+#define _LIBMAPLE_DMA_COMMON_H_
+
+#ifdef __cplusplus
+extern "C"{
+#endif
+
+#include <libmaple/libmaple_types.h>
+#include <libmaple/nvic.h>
+#include <libmaple/rcc.h>
+
+/*
+ * Devices
+ */
+
+struct dma_reg_map;
+
+/* 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;
+
+/** DMA device type */
+typedef struct dma_dev {
+    struct dma_reg_map        *regs;       /**< Register map */
+    rcc_clk_id                 clk_id;     /**< Clock ID */
+    struct dma_handler_config  handlers[]; /**< For internal use */
+} dma_dev;
+
+/**
+ * @brief DMA channels
+ *
+ * Notes:
+ * - This is also the dma_tube type for STM32F1.
+ * - Channel 0 is not available on all STM32 series.
+ *
+ * @see dma_tube
+ */
+typedef enum dma_channel {
+    DMA_CH0 = 0,                /**< Channel 0 */
+    DMA_CH1 = 1,                /**< Channel 1 */
+    DMA_CH2 = 2,                /**< Channel 2 */
+    DMA_CH3 = 3,                /**< Channel 3 */
+    DMA_CH4 = 4,                /**< Channel 4 */
+    DMA_CH5 = 5,                /**< Channel 5 */
+    DMA_CH6 = 6,                /**< Channel 6 */
+    DMA_CH7 = 7,                /**< Channel 7 */
+} dma_channel;
+
+/**
+ * @brief Source and destination transfer sizes.
+ * Use these when initializing a struct dma_tube_config.
+ * @see struct dma_tube_config
+ * @see dma_tube_cfg
+ */
+typedef enum dma_xfer_size {
+    DMA_SIZE_8BITS  = 0,        /**< 8-bit transfers */
+    DMA_SIZE_16BITS = 1,        /**< 16-bit transfers */
+    DMA_SIZE_32BITS = 2,        /**< 32-bit transfers */
+} dma_xfer_size;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif