1 /** 2 **************************************************************************************** 3 * 4 * @file app_i2c.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of I2C app library. 7 * 8 **************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 **************************************************************************************** 36 */ 37 38 /** @addtogroup PERIPHERAL Peripheral Driver 39 * @{ 40 */ 41 42 /** @addtogroup APP_DRIVER APP DRIVER 43 * @{ 44 */ 45 46 /** @defgroup APP_IIC IIC 47 * @brief IIC APP module driver. 48 * @{ 49 */ 50 51 52 #ifndef _APP_I2C_H_ 53 #define _APP_I2C_H_ 54 55 #include "gr55xx_hal.h" 56 #include "app_io.h" 57 #include "app_drv_error.h" 58 #ifdef ENV_USE_FREERTOS 59 #include "app_rtos_cfg.h" 60 #endif 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 #ifdef HAL_I2C_MODULE_ENABLED 67 68 /** @addtogroup APP_I2C_ENUM Enumerations 69 * @{ 70 */ 71 72 /** 73 * @brief I2C module Enumerations definition 74 */ 75 typedef enum { 76 APP_I2C_ID_0, /**< I2C module 0. */ 77 APP_I2C_ID_1, /**< I2C module 1. */ 78 APP_I2C_ID_MAX /**< Only for check parameter, not used as input parameters. */ 79 } app_i2c_id_t; 80 81 /** 82 * @brief I2C role Enumerations definition 83 */ 84 typedef enum { 85 APP_I2C_ROLE_MASTER, /**< I2C master device. */ 86 APP_I2C_ROLE_SLAVE, /**< I2C slave device. */ 87 APP_I2C_ROLE_MAX, /**< Only for check parameter, not used as input parameters. */ 88 } app_i2c_role_t; 89 90 /** 91 * @brief I2C operating mode Enumerations definition 92 */ 93 typedef enum { 94 APP_I2C_TYPE_INTERRUPT, /**< Interrupt operation mode */ 95 APP_I2C_TYPE_POLLING, /**< Polling operation mode */ 96 APP_I2C_TYPE_DMA, /**< DMA operation mode */ 97 APP_I2C_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */ 98 } app_i2c_type_t; 99 100 /** 101 * @brief I2C event Enumerations definition 102 */ 103 typedef enum { 104 APP_I2C_EVT_ERROR, /**< Error reported by I2C peripheral. */ 105 APP_I2C_EVT_TX_CPLT, /**< Requested TX transfer completed. */ 106 APP_I2C_EVT_RX_DATA, /**< Requested RX transfer completed. */ 107 } app_i2c_evt_type_t; 108 /** @} */ 109 110 /** @addtogroup APP_I2C_STRUCTURES Structures 111 * @{ 112 */ 113 /** 114 * @brief I2C IO Structures 115 */ 116 typedef struct { 117 app_io_type_t type; /**< Specifies the type of SPI IO. */ 118 app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */ 119 uint32_t pin; /**< Specifies the IO pins to be configured. 120 This parameter can be any value of @ref GR551x_pins. */ 121 app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */ 122 } app_i2c_pin_t; 123 124 /** 125 * @brief I2C IO configuration Structures 126 */ 127 typedef struct { 128 app_i2c_pin_t scl; /**< Set the configuration of I2C SCL pin. */ 129 app_i2c_pin_t sda; /**< Set the configuration of I2C SDA pin. */ 130 } app_i2c_pin_cfg_t; 131 132 /** 133 * @brief I2C operate mode Enumerations definition 134 */ 135 typedef struct { 136 app_i2c_type_t type; /**< Specifies the operation mode of I2C. */ 137 dma_channel_t tx_dma_channel; /**< Specifies the dma channel of I2C TX. */ 138 dma_channel_t rx_dma_channel; /**< Specifies the dma channel of I2C RX. */ 139 } app_i2c_mode_t; 140 141 /** 142 * @brief I2C parameters structure definition 143 */ 144 typedef struct { 145 app_i2c_id_t id; /**< specified I2C module ID. */ 146 app_i2c_role_t role; /**< specified the role of I2C. */ 147 app_i2c_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified I2C module. */ 148 app_i2c_mode_t use_mode; /**< I2C operate mode. */ 149 i2c_init_t init; /**< I2C communication parameters. */ 150 } app_i2c_params_t; 151 152 /** 153 * @brief I2C event structure definition 154 */ 155 typedef struct { 156 app_i2c_evt_type_t type; /**< Type of event. */ 157 union { 158 uint32_t error_code; /**< I2C Error code . */ 159 uint16_t size; /**< I2C transmitted/received counter. */ 160 } data; /**< I2C data. */ 161 } app_i2c_evt_t; 162 163 /** 164 * @brief I2C event callback definition 165 */ 166 typedef void (*app_i2c_evt_handler_t)(app_i2c_evt_t *p_evt); 167 168 /** @} */ 169 170 /* Exported functions --------------------------------------------------------*/ 171 /** @addtogroup HAL_APP_I2C_DRIVER_FUNCTIONS Functions 172 * @{ 173 */ 174 /** 175 **************************************************************************************** 176 * @brief Initialize the APP I2C DRIVER according to the specified parameters 177 * in the app_i2c_params_t and app_i2c_evt_handler_t. 178 * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode 179 * is set, you can't use interrupt mode. 180 * 181 * @param[in] p_params: Pointer to app_i2c_params_t parameter which contains the 182 * configuration information for the specified I2C module. 183 * @param[in] evt_handler: I2C user callback function. 184 * 185 * @return Result of initialization. 186 **************************************************************************************** 187 */ 188 uint16_t app_i2c_init(app_i2c_params_t *p_params, app_i2c_evt_handler_t evt_handler); 189 190 /** 191 **************************************************************************************** 192 * @brief De-initialize the APP I2C DRIVER peripheral. 193 * 194 * @param[in] id: De-initialize for a specific ID. 195 * 196 * @return Result of De-initialization. 197 **************************************************************************************** 198 */ 199 uint16_t app_i2c_deinit(app_i2c_id_t id); 200 201 /** 202 **************************************************************************************** 203 * @brief Receive in master or slave mode an amount of data in blocking mode. 204 * 205 * @param[in] id: which I2C module want to receive. 206 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 207 must be shifted at right before call interface. 208 * @param[in] p_data: Pointer to data buffer 209 * @param[in] size: Amount of data to be sent 210 * @param[in] timeout: Timeout duration 211 * 212 * @return Result of operation. 213 **************************************************************************************** 214 */ 215 uint16_t app_i2c_receive_sync(app_i2c_id_t id, uint16_t target_address, 216 uint8_t *p_data, uint16_t size, uint32_t timeout); 217 218 /** 219 **************************************************************************************** 220 * @brief Receive in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA. 221 * 222 * @param[in] id: which I2C module want to receive. 223 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 224 must be shifted at right before call interface. 225 * @param[in] p_data: Pointer to data buffer 226 * @param[in] size: Amount of data to be sent 227 * 228 * @return Result of operation. 229 **************************************************************************************** 230 */ 231 uint16_t app_i2c_receive_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size); 232 233 /** 234 **************************************************************************************** 235 * @brief Transmits in master or slave mode an amount of data in blocking mode. 236 * 237 * @param[in] id: which I2C module want to transmit. 238 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 239 must be shifted at right before call interface. 240 * @param[in] p_data: Pointer to data buffer 241 * @param[in] size: Amount of data to be sent 242 * @param[in] timeout: Timeout duration 243 * 244 * @return Result of operation. 245 **************************************************************************************** 246 */ 247 uint16_t app_i2c_transmit_sync(app_i2c_id_t id, uint16_t target_address, 248 uint8_t *p_data, uint16_t size, uint32_t timeout); 249 250 /** 251 **************************************************************************************** 252 * @brief Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA. 253 * 254 * @param[in] id: which I2C module want to transmit. 255 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 256 must be shifted at right before call interface. 257 * @param[in] p_data: Pointer to data buffer 258 * @param[in] size: Amount of data to be sent 259 * 260 * @return Result of operation. 261 **************************************************************************************** 262 */ 263 uint16_t app_i2c_transmit_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size); 264 265 /** 266 **************************************************************************************** 267 * @brief Read an amount of data in blocking mode from a specific memory address 268 * 269 * @param[in] id: I2C module ID. 270 * @param[in] dev_address: Target device address: The device 7 bits address value 271 * in datasheet must be shifted at right before call interface 272 * @param[in] mem_address: Internal memory address 273 * @param[in] mem_addr_size: Size of internal memory address 274 * @param[in] p_data: Pointer to data buffer 275 * @param[in] size: Amount of data to be sent 276 * @param[in] timeout: Timeout duration 277 * 278 * @return Result of operation. 279 **************************************************************************************** 280 */ 281 uint16_t app_i2c_mem_read_sync(app_i2c_id_t id, uint16_t dev_address, 282 uint16_t mem_address, uint16_t mem_addr_size, 283 uint8_t *p_data, uint16_t size, uint32_t timeout); 284 285 /** 286 **************************************************************************************** 287 * @brief Read an amount of data in non-blocking mode with Interrupt/DMA from a specific memory address 288 * 289 * @param[in] id: I2C module ID. 290 * @param[in] dev_address: Target device address: The device 7 bits address value in 291 * datasheet must be shifted at right before call interface 292 * @param[in] mem_address: Internal memory address 293 * @param[in] mem_addr_size: Size of internal memory address 294 * @param[in] p_data: Pointer to data buffer 295 * @param[in] size: Amount of data to be sent 296 * 297 * @return Result of operation. 298 **************************************************************************************** 299 */ 300 uint16_t app_i2c_mem_read_async(app_i2c_id_t id, uint16_t dev_address, 301 uint16_t mem_address, uint16_t mem_addr_size, 302 uint8_t *p_data, uint16_t size); 303 304 /** 305 **************************************************************************************** 306 * @brief Write an amount of data in blocking mode to a specific memory address 307 * 308 * @param[in] id: I2C module ID. 309 * @param[in] dev_address: Target device address: The device 7 bits address value in 310 * datasheet must be shifted at right before call interface 311 * @param[in] mem_address: Internal memory address 312 * @param[in] mem_addr_size: Size of internal memory address 313 * @param[in] p_data: Pointer to data buffer 314 * @param[in] size: Amount of data to be sent 315 * @param[in] timeout: Timeout duration 316 * 317 * @return Result of operation. 318 **************************************************************************************** 319 */ 320 uint16_t app_i2c_mem_write_sync(app_i2c_id_t id, uint16_t dev_address, 321 uint16_t mem_address, uint16_t mem_addr_size, 322 uint8_t *p_data, uint16_t size, uint32_t timeout); 323 324 /** 325 **************************************************************************************** 326 * @brief Write an amount of data in non-blocking mode with Interrupt/DMA to a specific memory address 327 * 328 * @param[in] id: I2C module ID. 329 * @param[in] dev_address: Target device address: The device 7 bits address value in 330 * datasheet must be shifted at right before call interface 331 * @param[in] mem_address: Internal memory address 332 * @param[in] mem_addr_size: Size of internal memory address 333 * @param[in] p_data: Pointer to data buffer 334 * @param[in] size: Amount of data to be sent 335 * 336 * @return Result of operation. 337 **************************************************************************************** 338 */ 339 uint16_t app_i2c_mem_write_async(app_i2c_id_t id, uint16_t dev_address, 340 uint16_t mem_address, uint16_t mem_addr_size, 341 uint8_t *p_data, uint16_t size); 342 343 /** 344 **************************************************************************************** 345 * @brief Return the I2C handle. 346 * 347 * @param[in] id: I2C module ID. 348 * 349 * @return Pointer to the specified ID's I2C handle. 350 **************************************************************************************** 351 */ 352 i2c_handle_t *app_i2c_get_handle(app_i2c_id_t id); 353 354 #ifdef ENV_RTOS_USE_SEMP 355 356 /** 357 **************************************************************************************** 358 * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode. 359 * 360 * @param[in] id: I2C module ID. 361 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 362 must be shifted at right before call interface. 363 * @param[in] p_data: Pointer to data buffer 364 * @param[in] size: Amount of data to be sent 365 * 366 * @return Result of operation. 367 **************************************************************************************** 368 */ 369 uint16_t app_i2c_receive_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size); 370 371 /** 372 **************************************************************************************** 373 * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode. 374 * 375 * @param[in] id: I2C module ID. 376 * @param[in] target_address: Target device address: The device 7 bits address value in datasheet 377 must be shifted at right before call interface. 378 * @param[in] p_data: Pointer to data buffer 379 * @param[in] size: Amount of data to be sent 380 * 381 * @return Result of operation. 382 **************************************************************************************** 383 */ 384 uint16_t app_i2c_transmit_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size); 385 386 #endif 387 388 /** @} */ 389 390 391 #endif 392 393 #ifdef __cplusplus 394 } 395 #endif 396 397 #endif 398 399 /** @} */ 400 /** @} */ 401 /** @} */ 402 403