i2c: Renaming, type changes, exposing i2c_init(), documentation.

Changes to struct i2c_dev members:

- uint8 clk_line's type is changing and is being renamed, is now
  rcc_clk_id clk_id
- uint8 ev_nvic_line's type is changing to nvic_irq_num
- uint8 er_nvic_line's type is changing to nvic_irq_num

Previous names were badly typed and inconsistent with the rest of
libmaple.

Exposing i2c_init(), also for consistency.

Adding/editing many Doxygen comments, for documentation and general
housekeeping.

1 files changed, 85 insertions, 47 deletions

diff --git a/libmaple/i2c.h b/libmaple/i2c.h
index d6285b3..3a397aa 100644
--- a/libmaple/i2c.h
+++ b/libmaple/i2c.h
@@ -32,58 +32,82 @@
 #ifndef _I2C_H_
 #define _I2C_H_
 
+/** I2C register map type */
 typedef struct i2c_reg_map {
-    __io uint32 CR1;
-    __io uint32 CR2;
-    __io uint32 OAR1;
-    __io uint32 OAR2;
-    __io uint32 DR;
-    __io uint32 SR1;
-    __io uint32 SR2;
-    __io uint32 CCR;
-    __io uint32 TRISE;
+    __io uint32 CR1;            /**< Control register 1 */
+    __io uint32 CR2;            /**< Control register 2 */
+    __io uint32 OAR1;           /**< Own address register 1 */
+    __io uint32 OAR2;           /**< Own address register 2 */
+    __io uint32 DR;             /**< Data register */
+    __io uint32 SR1;            /**< Status register 1 */
+    __io uint32 SR2;            /**< Status register 2 */
+    __io uint32 CCR;            /**< Clock control register */
+    __io uint32 TRISE;          /**< TRISE register */
 } i2c_reg_map;
 
+/** I2C device states */
 typedef enum i2c_state {
-    I2C_STATE_DISABLED          = 0,
-    I2C_STATE_IDLE              = 1,
-    I2C_STATE_XFER_DONE         = 2,
-    I2C_STATE_BUSY              = 3,
-    I2C_STATE_ERROR             = -1
+    I2C_STATE_DISABLED          = 0, /**< Disabled */
+    I2C_STATE_IDLE              = 1, /**< Idle */
+    I2C_STATE_XFER_DONE         = 2, /**< Done with transfer */
+    I2C_STATE_BUSY              = 3, /**< Busy */
+    I2C_STATE_ERROR             = -1 /**< Error occurred */
 } i2c_state;
 
+/**
+ * @brief I2C message type
+ */
 typedef struct i2c_msg {
-    uint16 addr;
+    uint16 addr;                /**< Address */
 #define I2C_MSG_READ            0x1
 #define I2C_MSG_10BIT_ADDR      0x2
-    uint16 flags;
-    uint16 length;
-    uint16 xferred;
-    uint8 *data;
+    uint16 flags;               /**< Bitwise OR of I2C_MSG_READ and
+                                     I2C_MSG_10BIT_ADDR */
+    uint16 length;              /**< Message length */
+    uint16 xferred;             /**< Messages transferred */
+    uint8 *data;                /**< Data */
 } i2c_msg;
 
+/**
+ * I2C device type.
+ */
 typedef struct i2c_dev {
-    i2c_reg_map *regs;
-    gpio_dev *gpio_port;
-    uint8 sda_pin;
-    uint8 scl_pin;
-    uint8 clk_line;
-    uint8 ev_nvic_line;
-    uint8 er_nvic_line;
-    volatile i2c_state state;
-    uint16 msgs_left;
-    i2c_msg *msg;
-    volatile uint32 timestamp;
-    uint32 error_flags;
+    i2c_reg_map *regs;          /**< Register map */
+    gpio_dev *gpio_port;        /**< SDA, SCL pins' GPIO port */
+    uint8 sda_pin;              /**< SDA bit on gpio_port */
+    uint8 scl_pin;              /**< SCL bit on gpio_port */
+    rcc_clk_id clk_id;          /**< RCC clock information */
+    nvic_irq_num ev_nvic_line;  /**< Event IRQ number */
+    nvic_irq_num er_nvic_line;  /**< Error IRQ number */
+    volatile i2c_state state;   /**< Device state */
+    uint16 msgs_left;           /**< Messages left */
+    i2c_msg *msg;               /**< Messages */
+    volatile uint32 timestamp;  /**< For internal use */
+    uint32 error_flags;         /**< Error flags, set on I2C error condition */
 } i2c_dev;
 
+/*
+ * Devices
+ */
+
 extern i2c_dev* const I2C1;
 extern i2c_dev* const I2C2;
 
-#define I2C1_BASE               (i2c_reg_map*)0x40005400
-#define I2C2_BASE               (i2c_reg_map*)0x40005800
+/*
+ * Register map base pointers
+ */
+
+/** I2C1 register map base pointer */
+#define I2C1_BASE               ((struct i2c_reg_map*)0x40005400)
+/** I2C2 register map base pointer */
+#define I2C2_BASE               ((struct i2c_reg_map*)0x40005800)
+
+/*
+ * Register bit definitions
+ */
+
+/* Control register 1 */
 
-/* Control register 1 bits */
 #define I2C_CR1_SWRST           BIT(15)       // Software reset
 #define I2C_CR1_ALERT           BIT(13)       // SMBus alert
 #define I2C_CR1_PEC             BIT(12)       // Packet error checking
@@ -93,7 +117,8 @@ extern i2c_dev* const I2C2;
 #define I2C_CR1_STOP            BIT(9)        // Stop generation
 #define I2C_CR1_PE              BIT(0)        // Peripheral Enable
 
-/* Control register 2 bits */
+/* Control register 2 */
+
 #define I2C_CR2_LAST            BIT(12)       // DMA last transfer
 #define I2C_CR2_DMAEN           BIT(11)       // DMA requests enable
 #define I2C_CR2_ITBUFEN         BIT(10)       // Buffer interrupt enable
@@ -101,12 +126,14 @@ extern i2c_dev* const I2C2;
 #define I2C_CR2_ITERREN         BIT(8)        // Error interupt enable
 #define I2C_CR2_FREQ            0xFFF         // Peripheral input frequency
 
-/* Clock control register bits */
+/* Clock control register */
+
 #define I2C_CCR_FS              BIT(15)       // Fast mode selection
 #define I2C_CCR_DUTY            BIT(14)       // 16/9 duty ratio
 #define I2C_CCR_CCR             0xFFF         // Clock control bits
 
-/* Status register 1 bits */
+/* Status register 1 */
+
 #define I2C_SR1_SB              BIT(0)        // Start bit
 #define I2C_SR1_ADDR            BIT(1)        // Address sent/matched
 #define I2C_SR1_BTF             BIT(2)        // Byte transfer finished
@@ -122,7 +149,8 @@ extern i2c_dev* const I2C2;
 #define I2C_SR1_TIMEOUT         BIT(14)       // Timeout or Tlow error
 #define I2C_SR1_SMBALERT        BIT(15)       // SMBus alert
 
-/* Status register 2 bits */
+/* Status register 2 */
+
 #define I2C_SR2_MSL             BIT(0)        // Master/slave
 #define I2C_SR2_BUSY            BIT(1)        // Bus busy
 #define I2C_SR2_TRA             BIT(2)        // Transmitter/receiver
@@ -132,11 +160,17 @@ extern i2c_dev* const I2C2;
 #define I2C_SR2_DUALF           BIT(7)        // Dual flag
 #define I2C_SR2_PEC             0xFF00        // Packet error checking register
 
+/*
+ * Convenience routines
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* i2c enable options */
+void i2c_init(i2c_dev *dev);
+
+/* I2C enable options */
 #define I2C_FAST_MODE           BIT(0)      // 400 khz
 #define I2C_DUTY_16_9           BIT(1)      // 16/9 duty ratio
 #define I2C_REMAP               BIT(2)      // Use alternate pin mapping
@@ -149,26 +183,30 @@ int32 i2c_master_xfer(i2c_dev *dev, i2c_msg *msgs, uint16 num, uint32 timeout);
 
 void i2c_bus_reset(const i2c_dev *dev);
 
+/**
+ * @brief Disable an I2C device
+ *
+ * This function disables the corresponding peripheral and marks dev's
+ * state as I2C_STATE_DISABLED.
+ *
+ * @param dev Device to disable.
+ */
 static inline void i2c_disable(i2c_dev *dev) {
     dev->regs->CR1 &= ~I2C_CR1_PE;
     dev->state = I2C_STATE_DISABLED;
 }
 
-/*
- * Low level register twiddling functions
- */
-
 /**
- * @brief turn on an i2c peripheral
- * @param dev i2c device
+ * @brief Turn on an I2C peripheral
+ * @param dev Device to enable
  */
 static inline void i2c_peripheral_enable(i2c_dev *dev) {
     dev->regs->CR1 |= I2C_CR1_PE;
 }
 
 /**
- * @brief turn off an i2c peripheral
- * @param dev i2c device
+ * @brief Turn off an I2C peripheral
+ * @param dev Device to turn off
  */
 static inline void i2c_peripheral_disable(i2c_dev *dev) {
     dev->regs->CR1 &= ~I2C_CR1_PE;