1 /* 2 * Copyright (C) 2017-2020 Alibaba Group Holding Limited 3 */ 4 5 /****************************************************************************** 6 * @file iic.h 7 * @brief header file for iic driver 8 * @version V1.0 9 * @date 08. Apr 2020 10 * @model iic 11 ******************************************************************************/ 12 13 #ifndef _DRV_IIC_H_ 14 #define _DRV_IIC_H_ 15 16 #include <stdint.h> 17 #include <stdbool.h> 18 #include <drv/common.h> 19 #include <drv/dma.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 \enum csi_iic_mode_t 27 \brief iic work in master/slave mode 28 */ 29 typedef enum { 30 IIC_MODE_MASTER = 0U, ///< IIC master 31 IIC_MODE_SLAVE ///< IIC slave 32 } csi_iic_mode_t; 33 34 /** 35 \enum csi_iic_speed_t 36 \brief iic speed mode 37 */ 38 typedef enum { 39 IIC_BUS_SPEED_STANDARD = 0U, ///< Standard Speed (<=100kHz) 40 IIC_BUS_SPEED_FAST, ///< Fast Speed (<=400kHz) 41 IIC_BUS_SPEED_FAST_PLUS, ///< Fast plus Speed (<= 1MHz) 42 IIC_BUS_SPEED_HIGH ///< High Speed (<=3.4MHz) 43 } csi_iic_speed_t; 44 45 /** 46 \enum csi_iic_address_mode_t 47 \brief iic address mode 48 */ 49 typedef enum { 50 IIC_ADDRESS_7BIT = 0U, ///< 7-bit address mode 51 IIC_ADDRESS_10BIT ///< 10-bit address mode 52 } csi_iic_addr_mode_t; 53 54 /** 55 \enum csi_iic_mem_addr_size_t 56 \brief iic memory address size 57 */ 58 typedef enum { 59 IIC_MEM_ADDR_SIZE_8BIT = 0U, ///< IIC e2prom 8bit address mode 60 IIC_MEM_ADDR_SIZE_16BIT ///< IIC e2prom 16bit address mode 61 } csi_iic_mem_addr_size_t; 62 63 /** 64 \enum csi_iic_event_t 65 \brief iic event signaled by iic driver 66 */ 67 typedef enum { 68 IIC_EVENT_SEND_COMPLETE = 0U, ///< Master/slave Send finished 69 IIC_EVENT_RECEIVE_COMPLETE, ///< Master/slave Receive finished 70 IIC_EVENT_ERROR_OVERFLOW, ///< Master/slave fifo overflow error 71 IIC_EVENT_ERROR_UNDERFLOW, ///< Master/slave fifo underflow error 72 IIC_EVENT_ERROR ///< The receive buffer was completely filled to FIFO and more data arrived. That data is lost 73 } csi_iic_event_t; 74 75 /** 76 \struct csi_iic_t 77 \brief iic ctrl block 78 */ 79 typedef struct csi_iic csi_iic_t; 80 struct csi_iic { 81 csi_dev_t dev; ///< IIC hw-device info 82 void (*callback)(csi_iic_t *iic, csi_iic_event_t event, void *arg); ///< IIC event callback for user 83 void *arg; ///< User private param passed to user callback 84 uint8_t *data; ///< IIC transfer-data buffer 85 uint32_t size; ///< IIC transfer-data size 86 csi_iic_mode_t mode; ///< IIC mode 87 csi_dma_ch_t *tx_dma; ///< Send dma channel handle 88 csi_dma_ch_t *rx_dma; ///< Receive dma channel handle 89 void *send; ///< Send function pointer asynchronously 90 void *receive; ///< Receive function pointer asynchronously 91 csi_state_t state; ///< IIC current state 92 void *priv; 93 }; 94 95 typedef void (*csi_iic_master_send_async_t)(csi_iic_t *iic, uint32_t devaddr, const void *data, uint32_t size); 96 typedef void (*csi_iic_master_receive_async_t)(csi_iic_t *iic, uint32_t devaddr, void *data, uint32_t size); 97 typedef void (*csi_iic_slave_send_async_t)(csi_iic_t *iic, const void *data, uint32_t size); 98 typedef void (*csi_iic_slave_receive_async_t)(csi_iic_t *iic, void *data, uint32_t size); 99 100 /** 101 \brief Init iic ctrl block 102 Initializes the resources needed for the iic instance 103 \param[in] iic Handle of iic instance 104 \param[in] idx Index of instance 105 \return error code \ref csi_error_t 106 */ 107 csi_error_t csi_iic_init(csi_iic_t *iic, uint32_t idx); 108 109 /** 110 \brief Uninit iic ctrl block 111 Stops operation and releases the software resources used by the instance 112 \param[in] iic Handle of iic instance 113 \return None 114 */ 115 void csi_iic_uninit(csi_iic_t *iic); 116 117 /** 118 \brief Config iic master or slave mode 119 \param[in] iic Handle of iic instance 120 \param[in] mode iic mode \ref csi_iic_mode_t 121 \return error code \ref csi_error_t 122 */ 123 csi_error_t csi_iic_mode(csi_iic_t *iic, csi_iic_mode_t mode); 124 125 /** 126 \brief Config iic addr mode 127 \param[in] iic Handle of iic instance 128 \param[in] addr_mode iic addr mode \ref csi_iic_addr_mode_t 129 \return error code \ref csi_error_t 130 */ 131 csi_error_t csi_iic_addr_mode(csi_iic_t *iic, csi_iic_addr_mode_t addr_mode); 132 133 /** 134 \brief Config iic speed 135 \param[in] iic Handle of iic instance 136 \param[in] speed iic speed mode \ref csi_iic_speed_t 137 \return error code \ref csi_error_t 138 */ 139 csi_error_t csi_iic_speed(csi_iic_t *iic, csi_iic_speed_t speed); 140 141 /** 142 \brief Config iic own addr 143 \param[in] iic Handle of iic instance 144 \param[in] own_addr iic set own addr at slave mode 145 \return error code \ref csi_error_t 146 */ 147 csi_error_t csi_iic_own_addr(csi_iic_t *iic, uint32_t own_addr); 148 149 /** 150 \brief Start sending data as iic master 151 This function is blocking 152 \param[in] iic Handle of iic instance 153 \param[in] devaddr Addrress of slave device 154 \param[in] data Pointer to send data buffer 155 \param[in] size Size of data items to send 156 \param[in] timout Unit of time delay(ms) 157 \return The amount of real data sent or error code 158 */ 159 int32_t csi_iic_master_send(csi_iic_t *iic, uint32_t devaddr, const void *data, uint32_t size, uint32_t timeout); 160 161 /** 162 \brief Start receiving data as iic master 163 This function is blocking 164 \param[in] iic Handle to operate 165 \param[in] devaddr iic addrress of slave device 166 \param[out] data Pointer to buffer for data to receive from iic receiver 167 \param[in] size Size of data items to receive 168 \param[in] timeout Unit of time delay(ms) 169 \return The amount of real data received or error code 170 */ 171 int32_t csi_iic_master_receive(csi_iic_t *iic, uint32_t devaddr, void *data, uint32_t size, uint32_t timeout); 172 173 /** 174 \brief Start sending data as iic master 175 This function is non-blocking,\ref csi_iic_event_t is signaled when transfer completes or error happens 176 \param[in] iic Handle to operate 177 \param[in] devaddr iic addrress of slave device 178 \param[in] data Pointer to send data buffer 179 \param[in] size Size of data items to send 180 \return error code \ref csi_error_t 181 */ 182 csi_error_t csi_iic_master_send_async(csi_iic_t *iic, uint32_t devaddr, const void *data, uint32_t size); 183 184 /** 185 \brief Start receiving data as iic master. 186 This function is non-blocking.\ref csi_iic_event_t is signaled when transfer completes or error happens 187 \param[in] iic Handle to operate 188 \param[in] devaddr iic addrress of slave device 189 \param[out] data Pointer to buffer for data to receive from iic receiver 190 \param[in] size Size of data items to receive 191 \return error code \ref csi_error_t 192 */ 193 csi_error_t csi_iic_master_receive_async(csi_iic_t *iic, uint32_t devaddr, void *data, uint32_t size); 194 195 /** 196 \brief Start sending data as iic master 197 This function is blocking 198 \param[in] iic Handle of iic instance 199 \param[in] devaddr Addrress of slave device 200 \param[in] memaddr Internal addr of device 201 \param[in] memaddr_size Internal addr mode of device 202 \param[in] data Pointer to send data buffer 203 \param[in] size Size of data items to send 204 \param[in] timout Unit of time delay(ms) 205 \return The amount of real data sent or error code 206 */ 207 int32_t csi_iic_mem_send(csi_iic_t *iic, uint32_t devaddr, uint16_t memaddr, csi_iic_mem_addr_size_t memaddr_size, const void *data, uint32_t size, uint32_t timeout); 208 209 /** 210 \brief Start receiving data as iic master 211 This function is blocking 212 \param[in] iic Handle to operate 213 \param[in] devaddr iic addrress of slave device 214 \param[in] memaddr Internal addr of device 215 \param[in] memaddr_mode Internal addr mode of device 216 \param[out] data Pointer to buffer for data to receive from eeprom device 217 \param[in] size Size of data items to receive 218 \param[in] timeout Unit of time delay(ms) 219 \return The amount of real data received or error code 220 */ 221 int32_t csi_iic_mem_receive(csi_iic_t *iic, uint32_t devaddr, uint16_t memaddr, csi_iic_mem_addr_size_t memaddr_size, void *data, uint32_t size, uint32_t timeout); 222 223 /** 224 \brief Start sending data as iic slave 225 This function is blocking 226 \param[in] iic Handle to operate 227 \param[in] data Pointer to buffer with data to send to iic master 228 \param[in] size Size of data items to send 229 \param[in] timeout Unit of time delay(ms) 230 \return The amount of real data sent or error code 231 */ 232 int32_t csi_iic_slave_send(csi_iic_t *iic, const void *data, uint32_t size, uint32_t timeout); 233 234 /** 235 \brief Start receiving data as iic slave 236 This function is blocking 237 \param[in] iic Handle to operate 238 \param[out] data Pointer to buffer for data to receive from iic master 239 \param[in] size Size of data items to receive 240 \param[in] timeout Unit of time delay(ms) 241 \return The amount of real data received or error code 242 */ 243 int32_t csi_iic_slave_receive(csi_iic_t *iic, void *data, uint32_t size, uint32_t timeout); 244 245 /** 246 \brief Start sending data as iic slave 247 This function is non-blocking,\ref csi_iic_event_t is signaled when transfer completes or error happens 248 \param[in] iic Handle to operate 249 \param[in] data Pointer to buffer with data to send to iic master 250 \param[in] size Size of data items to send 251 \return error code \ref csi_error_t 252 */ 253 csi_error_t csi_iic_slave_send_async(csi_iic_t *iic, const void *data, uint32_t size); 254 255 /** 256 \brief Start receiving data as iic slave 257 This function is non-blocking,\ref csi_iic_event_t is signaled when transfer completes or error happens 258 \param[in] handle iic handle to operate 259 \param[out] data Pointer to buffer for data to receive from iic master 260 \param[in] size Size of data items to receive 261 \return error code \ref csi_error_t 262 */ 263 csi_error_t csi_iic_slave_receive_async(csi_iic_t *iic, void *data, uint32_t size); 264 265 /** 266 \brief Attach callback to the iic 267 \param[in] iic iic handle to operate 268 \param[in] cb Event callback function \ref csi_iic_callback_t 269 \param[in] arg User private param for event callback 270 \return error code \ref csi_error_t 271 */ 272 csi_error_t csi_iic_attach_callback(csi_iic_t *iic, void *callback, void *arg); 273 274 /** 275 \brief Detach callback from the iic 276 \param[in] iic iic handle to operate 277 \return None 278 */ 279 void csi_iic_detach_callback(csi_iic_t *iic); 280 281 /** 282 \brief Config iic stop to generate 283 \param[in] iic iic handle to operate 284 \param[in] enable Transfer operation is pending - stop condition will not be generated 285 \return error code \ref csi_error_t 286 */ 287 csi_error_t csi_iic_xfer_pending(csi_iic_t *iic, bool enable); 288 289 /** 290 \brief Link DMA channel to iic device 291 \param[in] iic Handle to operate 292 \param[in] tx_dma The DMA channel handle for send, when it is NULL means to unlink the channel 293 \param[in] rx_dma The DMA channel handle for receive, when it is NULL means to unlink the channel 294 \return error code \ref csi_error_t 295 */ 296 csi_error_t csi_iic_link_dma(csi_iic_t *iic, csi_dma_ch_t *tx_dma, csi_dma_ch_t *rx_dma); 297 298 /** 299 \brief Get iic state 300 \param[in] iic Handle to operate 301 \param[out] state iic state \ref csi_state_t 302 \return error code \ref csi_error_t 303 */ 304 csi_error_t csi_iic_get_state(csi_iic_t *iic, csi_state_t *state); 305 306 /** 307 \brief Enable iic power manage 308 \param[in] iic iic handle to operate 309 \return error code \ref csi_error_t 310 */ 311 csi_error_t csi_iic_enable_pm(csi_iic_t *iic); 312 313 /** 314 \brief Disable iic power manage 315 \param[in] iic iic handle to operate 316 \return None 317 */ 318 void csi_iic_disable_pm(csi_iic_t *iic); 319 320 #ifdef __cplusplus 321 } 322 #endif 323 324 #endif /* _DRV_IIC_H_ */ 325