Goodix
GR551x API Reference  V1_6_06_B5676
app_i2c.h
Go to the documentation of this file.
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 {
77  APP_I2C_ID_0, /**< I2C module 0. */
78  APP_I2C_ID_1, /**< I2C module 1. */
79  APP_I2C_ID_MAX /**< Only for check parameter, not used as input parameters. */
81 
82 /**
83  * @brief I2C role Enumerations definition
84  */
85 typedef enum
86 {
87  APP_I2C_ROLE_MASTER, /**< I2C master device. */
88  APP_I2C_ROLE_SLAVE, /**< I2C slave device. */
89  APP_I2C_ROLE_MAX, /**< Only for check parameter, not used as input parameters. */
91 
92 /**
93  * @brief I2C operating mode Enumerations definition
94  */
95 typedef enum
96 {
97  APP_I2C_TYPE_INTERRUPT, /**< Interrupt operation mode */
98  APP_I2C_TYPE_POLLING, /**< Polling operation mode */
99  APP_I2C_TYPE_DMA, /**< DMA operation mode */
100  APP_I2C_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */
102 
103 /**
104  * @brief I2C event Enumerations definition
105  */
106 typedef enum
107 {
108  APP_I2C_EVT_ERROR, /**< Error reported by I2C peripheral. */
109  APP_I2C_EVT_TX_CPLT, /**< Requested TX transfer completed. */
110  APP_I2C_EVT_RX_DATA, /**< Requested RX transfer completed. */
112 /** @} */
113 
114 /** @addtogroup APP_I2C_STRUCTURES Structures
115  * @{
116  */
117 /**
118  * @brief I2C IO Structures
119  */
120 typedef struct
121 {
122  app_io_type_t type; /**< Specifies the type of SPI IO. */
123  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
124  uint32_t pin; /**< Specifies the IO pins to be configured.
125  This parameter can be any value of @ref GR551x_pins. */
126  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
127 } app_i2c_pin_t;
128 
129 /**
130  * @brief I2C IO configuration Structures
131  */
132 typedef struct
133 {
134  app_i2c_pin_t scl; /**< Set the configuration of I2C SCL pin. */
135  app_i2c_pin_t sda; /**< Set the configuration of I2C SDA pin. */
137 
138 /**
139  * @brief I2C operate mode Enumerations definition
140  */
141 typedef struct
142 {
143  app_i2c_type_t type; /**< Specifies the operation mode of I2C. */
144  dma_channel_t tx_dma_channel; /**< Specifies the dma channel of I2C TX. */
145  dma_channel_t rx_dma_channel; /**< Specifies the dma channel of I2C RX. */
147 
148 /**
149  * @brief I2C parameters structure definition
150  */
151 typedef struct
152 {
153  app_i2c_id_t id; /**< specified I2C module ID. */
154  app_i2c_role_t role; /**< specified the role of I2C. */
155  app_i2c_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified I2C module. */
156  app_i2c_mode_t use_mode; /**< I2C operate mode. */
157  i2c_init_t init; /**< I2C communication parameters. */
159 
160 /**
161  * @brief I2C event structure definition
162  */
163 typedef struct
164 {
165  app_i2c_evt_type_t type; /**< Type of event. */
166  union
167  {
168  uint32_t error_code; /**< I2C Error code . */
169  uint16_t size; /**< I2C transmitted/received counter. */
170  } data; /**< I2C data. */
171 } app_i2c_evt_t;
172 
173 /**
174  * @brief I2C event callback definition
175  */
176 typedef void (*app_i2c_evt_handler_t)(app_i2c_evt_t *p_evt);
177 
178 /** @} */
179 
180 /* Exported functions --------------------------------------------------------*/
181 /** @addtogroup HAL_APP_I2C_DRIVER_FUNCTIONS Functions
182  * @{
183  */
184 /**
185  ****************************************************************************************
186  * @brief Initialize the APP I2C DRIVER according to the specified parameters
187  * in the app_i2c_params_t and app_i2c_evt_handler_t.
188  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
189  * is set, you can't use interrupt mode.
190  *
191  * @param[in] p_params: Pointer to app_i2c_params_t parameter which contains the
192  * configuration information for the specified I2C module.
193  * @param[in] evt_handler: I2C user callback function.
194  *
195  * @return Result of initialization.
196  ****************************************************************************************
197  */
198 uint16_t app_i2c_init(app_i2c_params_t *p_params, app_i2c_evt_handler_t evt_handler);
199 
200 /**
201  ****************************************************************************************
202  * @brief De-initialize the APP I2C DRIVER peripheral.
203  *
204  * @param[in] id: De-initialize for a specific ID.
205  *
206  * @return Result of De-initialization.
207  ****************************************************************************************
208  */
210 
211 /**
212  ****************************************************************************************
213  * @brief Receive in master or slave mode an amount of data in blocking mode.
214  *
215  * @param[in] id: which I2C module want to receive.
216  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
217  must be shifted at right before call interface.
218  * @param[in] p_data: Pointer to data buffer
219  * @param[in] size: Amount of data to be sent
220  * @param[in] timeout: Timeout duration
221  *
222  * @return Result of operation.
223  ****************************************************************************************
224  */
225 uint16_t app_i2c_receive_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size, uint32_t timeout);
226 
227 /**
228  ****************************************************************************************
229  * @brief Receive in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
230  *
231  * @param[in] id: which I2C module want to receive.
232  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
233  must be shifted at right before call interface.
234  * @param[in] p_data: Pointer to data buffer
235  * @param[in] size: Amount of data to be sent
236  *
237  * @return Result of operation.
238  ****************************************************************************************
239  */
240 uint16_t app_i2c_receive_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
241 
242 /**
243  ****************************************************************************************
244  * @brief Transmits in master or slave mode an amount of data in blocking mode.
245  *
246  * @param[in] id: which I2C module want to transmit.
247  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
248  must be shifted at right before call interface.
249  * @param[in] p_data: Pointer to data buffer
250  * @param[in] size: Amount of data to be sent
251  * @param[in] timeout: Timeout duration
252  *
253  * @return Result of operation.
254  ****************************************************************************************
255  */
256 uint16_t app_i2c_transmit_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size, uint32_t timeout);
257 
258 /**
259  ****************************************************************************************
260  * @brief Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
261  *
262  * @param[in] id: which I2C module want to transmit.
263  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
264  must be shifted at right before call interface.
265  * @param[in] p_data: Pointer to data buffer
266  * @param[in] size: Amount of data to be sent
267  *
268  * @return Result of operation.
269  ****************************************************************************************
270  */
271 uint16_t app_i2c_transmit_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
272 
273 /**
274  ****************************************************************************************
275  * @brief Read an amount of data in blocking mode from a specific memory address
276  *
277  * @param[in] id: I2C module ID.
278  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
279  * @param[in] mem_address: Internal memory address
280  * @param[in] mem_addr_size: Size of internal memory address
281  * @param[in] p_data: Pointer to data buffer
282  * @param[in] size: Amount of data to be sent
283  * @param[in] timeout: Timeout duration
284  *
285  * @return Result of operation.
286  ****************************************************************************************
287  */
288 uint16_t app_i2c_mem_read_sync(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size, uint32_t timeout);
289 
290 /**
291  ****************************************************************************************
292  * @brief Read an amount of data in non-blocking mode with Interrupt/DMA from a specific memory address
293  *
294  * @param[in] id: I2C module ID.
295  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
296  * @param[in] mem_address: Internal memory address
297  * @param[in] mem_addr_size: Size of internal memory address
298  * @param[in] p_data: Pointer to data buffer
299  * @param[in] size: Amount of data to be sent
300  *
301  * @return Result of operation.
302  ****************************************************************************************
303  */
304 uint16_t app_i2c_mem_read_async(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size);
305 
306 /**
307  ****************************************************************************************
308  * @brief Write an amount of data in blocking mode to a specific memory address
309  *
310  * @param[in] id: I2C module ID.
311  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
312  * @param[in] mem_address: Internal memory address
313  * @param[in] mem_addr_size: Size of internal memory address
314  * @param[in] p_data: Pointer to data buffer
315  * @param[in] size: Amount of data to be sent
316  * @param[in] timeout: Timeout duration
317  *
318  * @return Result of operation.
319  ****************************************************************************************
320  */
321 uint16_t app_i2c_mem_write_sync(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size, uint32_t timeout);
322 
323 /**
324  ****************************************************************************************
325  * @brief Write an amount of data in non-blocking mode with Interrupt/DMA to a specific memory address
326  *
327  * @param[in] id: I2C module ID.
328  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
329  * @param[in] mem_address: Internal memory address
330  * @param[in] mem_addr_size: Size of internal memory address
331  * @param[in] p_data: Pointer to data buffer
332  * @param[in] size: Amount of data to be sent
333  *
334  * @return Result of operation.
335  ****************************************************************************************
336  */
337 uint16_t app_i2c_mem_write_async(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size);
338 
339 /**
340  ****************************************************************************************
341  * @brief Return the I2C handle.
342  *
343  * @param[in] id: I2C module ID.
344  *
345  * @return Pointer to the specified ID's I2C handle.
346  ****************************************************************************************
347  */
349 
350 #ifdef ENV_RTOS_USE_SEMP
351 
352 /**
353  ****************************************************************************************
354  * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode.
355  *
356  * @param[in] id: I2C module ID.
357  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
358  must be shifted at right before call interface.
359  * @param[in] p_data: Pointer to data buffer
360  * @param[in] size: Amount of data to be sent
361  *
362  * @return Result of operation.
363  ****************************************************************************************
364  */
365 uint16_t app_i2c_receive_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
366 
367 /**
368  ****************************************************************************************
369  * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode.
370  *
371  * @param[in] id: I2C module ID.
372  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
373  must be shifted at right before call interface.
374  * @param[in] p_data: Pointer to data buffer
375  * @param[in] size: Amount of data to be sent
376  *
377  * @return Result of operation.
378  ****************************************************************************************
379  */
380 uint16_t app_i2c_transmit_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
381 
382 #endif
383 
384 /** @} */
385 
386 
387 #endif
388 
389 #ifdef __cplusplus
390 }
391 #endif
392 
393 #endif
394 
395 /** @} */
396 /** @} */
397 /** @} */
398 
app_i2c_pin_cfg_t
I2C IO configuration Structures.
Definition: app_i2c.h:133
app_i2c_mode_t
I2C operate mode Enumerations definition.
Definition: app_i2c.h:142
app_i2c_pin_cfg_t::sda
app_i2c_pin_t sda
Set the configuration of I2C SDA pin.
Definition: app_i2c.h:135
app_i2c_pin_t::pin
uint32_t pin
Specifies the IO pins to be configured.
Definition: app_i2c.h:124
app_i2c_mode_t::rx_dma_channel
dma_channel_t rx_dma_channel
Specifies the dma channel of I2C RX.
Definition: app_i2c.h:145
APP_I2C_EVT_ERROR
@ APP_I2C_EVT_ERROR
Error reported by I2C peripheral.
Definition: app_i2c.h:108
app_i2c_evt_t::error_code
uint32_t error_code
I2C Error code .
Definition: app_i2c.h:168
app_i2c_mode_t::type
app_i2c_type_t type
Specifies the operation mode of I2C.
Definition: app_i2c.h:143
APP_I2C_TYPE_MAX
@ APP_I2C_TYPE_MAX
Only for check parameter, not used as input parameters.
Definition: app_i2c.h:100
app_i2c_receive_async
uint16_t app_i2c_receive_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size)
Receive in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
_i2c_init
I2C Configuration Structure definition.
Definition: gr55xx_hal_i2c.h:167
APP_I2C_ROLE_MASTER
@ APP_I2C_ROLE_MASTER
I2C master device.
Definition: app_i2c.h:87
_i2c_handle
I2C handle Structure definition.
Definition: gr55xx_hal_i2c.h:191
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:187
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:141
APP_I2C_TYPE_POLLING
@ APP_I2C_TYPE_POLLING
Polling operation mode
Definition: app_i2c.h:98
app_i2c_transmit_sync
uint16_t app_i2c_transmit_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size, uint32_t timeout)
Transmits in master or slave mode an amount of data in blocking mode.
app_i2c_evt_t::size
uint16_t size
I2C transmitted/received counter.
Definition: app_i2c.h:169
app_i2c_deinit
uint16_t app_i2c_deinit(app_i2c_id_t id)
De-initialize the APP I2C DRIVER peripheral.
app_i2c_pin_t::mux
app_io_mux_t mux
Specifies the Peripheral to be connected to the selected pins.
Definition: app_i2c.h:123
app_i2c_mode_t::tx_dma_channel
dma_channel_t tx_dma_channel
Specifies the dma channel of I2C TX.
Definition: app_i2c.h:144
app_i2c_pin_t::type
app_io_type_t type
Specifies the type of SPI IO.
Definition: app_i2c.h:122
app_io.h
Header file containing functions prototypes of GPIO app library.
APP_I2C_ROLE_MAX
@ APP_I2C_ROLE_MAX
Only for check parameter, not used as input parameters.
Definition: app_i2c.h:89
app_i2c_role_t
app_i2c_role_t
I2C role Enumerations definition.
Definition: app_i2c.h:86
app_i2c_mem_read_sync
uint16_t app_i2c_mem_read_sync(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size, uint32_t timeout)
Read an amount of data in blocking mode from a specific memory address.
app_i2c_params_t::id
app_i2c_id_t id
specified I2C module ID.
Definition: app_i2c.h:153
APP_I2C_TYPE_INTERRUPT
@ APP_I2C_TYPE_INTERRUPT
Interrupt operation mode.
Definition: app_i2c.h:97
app_i2c_id_t
app_i2c_id_t
I2C module Enumerations definition.
Definition: app_i2c.h:76
app_i2c_pin_t
I2C IO Structures.
Definition: app_i2c.h:121
app_i2c_params_t::pin_cfg
app_i2c_pin_cfg_t pin_cfg
the pin configuration information for the specified I2C module.
Definition: app_i2c.h:155
app_i2c_params_t::role
app_i2c_role_t role
specified the role of I2C.
Definition: app_i2c.h:154
app_i2c_mem_read_async
uint16_t app_i2c_mem_read_async(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size)
Read an amount of data in non-blocking mode with Interrupt/DMA from a specific memory address.
app_i2c_receive_sync
uint16_t app_i2c_receive_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size, uint32_t timeout)
Receive in master or slave mode an amount of data in blocking mode.
app_i2c_evt_type_t
app_i2c_evt_type_t
I2C event Enumerations definition.
Definition: app_i2c.h:107
APP_I2C_ID_1
@ APP_I2C_ID_1
I2C module 1.
Definition: app_i2c.h:78
app_i2c_evt_t
I2C event structure definition.
Definition: app_i2c.h:164
app_i2c_pin_cfg_t::scl
app_i2c_pin_t scl
Set the configuration of I2C SCL pin.
Definition: app_i2c.h:134
app_i2c_get_handle
i2c_handle_t * app_i2c_get_handle(app_i2c_id_t id)
Return the I2C handle.
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_i2c_transmit_async
uint16_t app_i2c_transmit_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size)
Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
app_i2c_pin_t::pull
app_io_pull_t pull
Specifies the Pull-up or Pull-Down activation for the selected pins.
Definition: app_i2c.h:126
APP_I2C_EVT_TX_CPLT
@ APP_I2C_EVT_TX_CPLT
Requested TX transfer completed.
Definition: app_i2c.h:109
app_i2c_init
uint16_t app_i2c_init(app_i2c_params_t *p_params, app_i2c_evt_handler_t evt_handler)
Initialize the APP I2C DRIVER according to the specified parameters in the app_i2c_params_t and app_i...
app_i2c_evt_handler_t
void(* app_i2c_evt_handler_t)(app_i2c_evt_t *p_evt)
I2C event callback definition.
Definition: app_i2c.h:176
app_i2c_type_t
app_i2c_type_t
I2C operating mode Enumerations definition.
Definition: app_i2c.h:96
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:198
APP_I2C_EVT_RX_DATA
@ APP_I2C_EVT_RX_DATA
Requested RX transfer completed.
Definition: app_i2c.h:110
app_i2c_evt_t::type
app_i2c_evt_type_t type
Type of event.
Definition: app_i2c.h:165
app_i2c_params_t
I2C parameters structure definition.
Definition: app_i2c.h:152
app_rtos_cfg.h
Header file of app rtos config code.
app_drv_error.h
Header file of app driver error code.
app_i2c_params_t::init
i2c_init_t init
I2C communication parameters.
Definition: app_i2c.h:157
APP_I2C_TYPE_DMA
@ APP_I2C_TYPE_DMA
DMA operation mode
Definition: app_i2c.h:99
app_i2c_mem_write_sync
uint16_t app_i2c_mem_write_sync(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size, uint32_t timeout)
Write an amount of data in blocking mode to a specific memory address.
APP_I2C_ID_0
@ APP_I2C_ID_0
I2C module 0.
Definition: app_i2c.h:77
app_i2c_mem_write_async
uint16_t app_i2c_mem_write_async(app_i2c_id_t id, uint16_t dev_address, uint16_t mem_address, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size)
Write an amount of data in non-blocking mode with Interrupt/DMA to a specific memory address.
app_i2c_params_t::use_mode
app_i2c_mode_t use_mode
I2C operate mode.
Definition: app_i2c.h:156
APP_I2C_ID_MAX
@ APP_I2C_ID_MAX
Only for check parameter, not used as input parameters.
Definition: app_i2c.h:79
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
APP_I2C_ROLE_SLAVE
@ APP_I2C_ROLE_SLAVE
I2C slave device.
Definition: app_i2c.h:88