1 /** 2 * @file i2c.h 3 * @copyright Copyright (C) 2015-2021 Alibaba Group Holding Limited 4 */ 5 6 #ifndef _AOS_I2C_H 7 #define _AOS_I2C_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include <aos/kernel.h> 14 15 /** @addtogroup aos_i2c_device I2C 16 * aos i2c API. 17 * 18 * @{ 19 */ 20 21 22 /* Define the wait forever timeout macro */ 23 #define AOS_WAIT_FOREVER 0xFFFFFFFFU 24 25 /* 26 * I2C bus's clock rate 27 */ 28 #define I2C_BUS_CLK_10K 10000 29 #define I2C_BUS_CLK_100K 100000 30 #define I2C_BUS_CLK_400K 400000 31 #define I2C_BUS_CLK_1000K 1000000 32 #define I2C_BUS_CLK_3400K 3400000 33 34 /* Slave device's address mode */ 35 #define I2C_SLAVE_ADDR_WIDTH_7BIT 0 /**< 7 bit mode */ 36 #define I2C_SLAVE_ADDR_WIDTH_10BIT 1 /**< 10 bit mode */ 37 38 #define I2C_MEM_ADDR_SIZE_8BIT 1 /**< i2c memory address size 8bit */ 39 #define I2C_MEM_ADDR_SIZE_16BIT 2 /**< i2c memory address size 16bit */ 40 41 typedef uint32_t* i2c_dev_handle_t; 42 43 typedef struct i2c_slave_config { 44 uint16_t addr; /**< slave device's address */ 45 uint32_t clk; /**< clock during i2c transaction */ 46 uint32_t addr_width; /**< device's address mode: 7 bit or 10 bit */ 47 } i2c_slave_config_t; 48 49 50 /** 51 * setup new I2C channel with specified slave device's config to communicate with slave device 52 * 53 * @param[in] id host I2C controller's channel ID 54 * @param[in] config slave device's address, address width and clock settings, \ref i2c_slave_config_t 55 * 56 * @return handle of the i2c device, used for later i2c operations on I2C slave device, when open operation success; 57 NULL when open operation fails 58 */ 59 i2c_dev_handle_t aos_i2c_open (uint32_t id, i2c_slave_config_t *config); 60 61 /** 62 * close target I2C communication channel 63 * 64 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 65 * 66 * @return 0 if operation success 67 negative error code if operation fails 68 */ 69 aos_status_t aos_i2c_close (i2c_dev_handle_t dev); 70 71 /** 72 * set I2C bus's clock when communicate with target I2C slave 73 * 74 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 75 * @param[in] clk target clock to be used 76 * 77 * @return 0 if operation success 78 negative error code if operation fails 79 */ 80 aos_status_t aos_i2c_clk_set (i2c_dev_handle_t dev, uint32_t clk); 81 82 /** 83 * set slave device's address witdh on target I2C channel 84 * 85 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 86 * @param[in] addr_width slave device's address width, 7-bit or 10-bit only 87 * 88 * @return 0 if operation success 89 negative error code if operation fails 90 */ 91 aos_status_t aos_i2c_addr_width_set (i2c_dev_handle_t dev, uint32_t addr_width); 92 93 /** 94 * set slave device's address on target I2C channel 95 * 96 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 97 * @param[in] addr slave device's address width 98 * 99 * @return 0 if operation success 100 negative error code if operation fails 101 */ 102 aos_status_t aos_i2c_slave_addr_set (i2c_dev_handle_t dev, uint16_t addr); 103 104 /** 105 * issue I2C write operation on target I2C channel 106 * 107 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 108 * @param[in] buf pointer to the buffer to be sent 109 * @param[in] len number of data to be sent 110 * @param[in] timeout in unit of ms, current i2c transaction's timeout value 111 * use AOS_WAIT_FOREVER for endless wait until operation success or fails 112 * 113 * @return 0 if operation success 114 negative error code if operation fails 115 */ 116 int32_t aos_i2c_master_send (i2c_dev_handle_t dev, char *buf, uint32_t len, uint32_t timeout); 117 118 /** 119 * issue I2C read operation on target I2C channel 120 * 121 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 122 * @param[in] buf pointer to the buffer where to save the received data 123 * @param[in] len number of data to be read 124 * @param[in] timeout in unit of ms, current i2c transaction's timeout value 125 * use AOS_WAIT_FOREVER for endless wait until operation success or fails 126 * 127 * @return 0 if operation success 128 negative error code if operation fails 129 */ 130 int32_t aos_i2c_master_recv (i2c_dev_handle_t dev, char *buf, uint32_t len, uint32_t timeout); 131 132 /** 133 * issue I2C memory/register write operation on target I2C channel 134 * 135 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 136 * @param[in] addr address of target memory/register to be write 137 * @param[in] addr_len address's length, either I2C_MEM_ADDR_SIZE_8BIT or I2C_MEM_ADDR_SIZE_16BIT 138 * @param[in] buf pointer to the buffer to be written 139 * @param[in] len number of data to be written 140 * @param[in] timeout in unit of ms, current i2c transaction's timeout value 141 * use AOS_WAIT_FOREVER for endless wait until operation success or fails 142 * 143 * @return 0 if operation success 144 negative error code if operation fails 145 */ 146 int32_t aos_i2c_mem_write (i2c_dev_handle_t dev, uint16_t addr, uint8_t addr_len, uint8_t *buf, uint32_t len, uint32_t timeout); 147 148 /** 149 * issue I2C memory/register read operation on target I2C channel 150 * 151 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 152 * @param[in] addr address of target memory/register to be read 153 * @param[in] addr_len address's length, , either I2C_MEM_ADDR_SIZE_8BIT or I2C_MEM_ADDR_SIZE_16BIT 154 * @param[in] buf pointer to the buffer for read operation 155 * @param[in] len number of data to be read 156 * @param[in] timeout in unit of ms, current i2c transaction's timeout value 157 * use AOS_WAIT_FOREVER for endless wait until operation success or fails 158 * 159 * @return 0 if operation success 160 negative error code if operation fails 161 */ 162 int32_t aos_i2c_mem_read (i2c_dev_handle_t dev, uint16_t addr, uint8_t addr_len, uint8_t *buf, uint32_t len, uint32_t timeout); 163 164 /** 165 * issue I2C memory/register read operation on target I2C channel 166 * 167 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 168 * @param[in] level level of current power management level 169 * 170 * @return 0 if operation success 171 negative error code if operation fails 172 */ 173 aos_status_t aos_i2c_pm_ctrl (i2c_dev_handle_t dev, int level); 174 175 /** 176 * get the number of I2C hardware module 177 * 178 * @param[in] dev handle of the i2c device to be operated, must be the return value of aos_i2c_open 179 * @param[in] level level of current power management level 180 * 181 * @return 0 if operation success 182 negative error code if operation fails 183 */ 184 int32_t aos_i2c_get_num(void); 185 186 /** @} */ 187 188 #ifdef __cplusplus 189 } 190 #endif 191 192 #endif /* _AOS_I2C_H */ 193