From 395e5b355bab702943c2fcfdffa2dbab1b0e8d15 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 19 May 2011 14:50:44 -0400 Subject: 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. --- libmaple/i2c.h | 132 +++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 85 insertions(+), 47 deletions(-) (limited to 'libmaple/i2c.h') 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; -- cgit v1.2.3