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;
171  uint16_t slave_addr;
172 } app_i2c_evt_t;
173 
174 /**
175  * @brief I2C event callback definition
176  */
177 typedef void (*app_i2c_evt_handler_t)(app_i2c_evt_t *p_evt);
178 
179 /** @} */
180 
181 /* Exported functions --------------------------------------------------------*/
182 /** @addtogroup HAL_APP_I2C_DRIVER_FUNCTIONS Functions
183  * @{
184  */
185 /**
186  ****************************************************************************************
187  * @brief Initialize the APP I2C DRIVER according to the specified parameters
188  * in the app_i2c_params_t and app_i2c_evt_handler_t.
189  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
190  * is set, you can't use interrupt mode.
191  *
192  * @param[in] p_params: Pointer to app_i2c_params_t parameter which contains the
193  * configuration information for the specified I2C module.
194  * @param[in] evt_handler: I2C user callback function.
195  *
196  * @return Result of initialization.
197  ****************************************************************************************
198  */
199 uint16_t app_i2c_init(app_i2c_params_t *p_params, app_i2c_evt_handler_t evt_handler);
200 
201 /**
202  ****************************************************************************************
203  * @brief De-initialize the APP I2C DRIVER peripheral.
204  *
205  * @param[in] id: De-initialize for a specific ID.
206  *
207  * @return Result of De-initialization.
208  ****************************************************************************************
209  */
211 
212 /**
213  ****************************************************************************************
214  * @brief Receive in master or slave mode an amount of data in blocking mode.
215  *
216  * @param[in] id: which I2C module want to receive.
217  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
218  must be shifted at right before call interface.
219  * @param[in] p_data: Pointer to data buffer
220  * @param[in] size: Amount of data to be sent
221  * @param[in] timeout: Timeout duration
222  *
223  * @return Result of operation.
224  ****************************************************************************************
225  */
226 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);
227 
228 /**
229  ****************************************************************************************
230  * @brief Receive in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
231  *
232  * @param[in] id: which I2C module want to receive.
233  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
234  must be shifted at right before call interface.
235  * @param[in] p_data: Pointer to data buffer
236  * @param[in] size: Amount of data to be sent
237  *
238  * @return Result of operation.
239  ****************************************************************************************
240  */
241 uint16_t app_i2c_receive_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
242 
243 /**
244  ****************************************************************************************
245  * @brief Transmits in master or slave mode an amount of data in blocking mode.
246  *
247  * @param[in] id: which I2C module want to transmit.
248  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
249  must be shifted at right before call interface.
250  * @param[in] p_data: Pointer to data buffer
251  * @param[in] size: Amount of data to be sent
252  * @param[in] timeout: Timeout duration
253  *
254  * @return Result of operation.
255  ****************************************************************************************
256  */
257 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);
258 
259 /**
260  ****************************************************************************************
261  * @brief Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt/DMA.
262  *
263  * @param[in] id: which I2C module want to transmit.
264  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
265  must be shifted at right before call interface.
266  * @param[in] p_data: Pointer to data buffer
267  * @param[in] size: Amount of data to be sent
268  *
269  * @return Result of operation.
270  ****************************************************************************************
271  */
272 uint16_t app_i2c_transmit_async(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
273 
274 /**
275  ****************************************************************************************
276  * @brief Read an amount of data in blocking mode from a specific memory address
277  *
278  * @param[in] id: I2C module ID.
279  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
280  * @param[in] mem_address: Internal memory address
281  * @param[in] mem_addr_size: Size of internal memory address
282  * @param[in] p_data: Pointer to data buffer
283  * @param[in] size: Amount of data to be sent
284  * @param[in] timeout: Timeout duration
285  *
286  * @return Result of operation.
287  ****************************************************************************************
288  */
289 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);
290 
291 /**
292  ****************************************************************************************
293  * @brief Read an amount of data in non-blocking mode with Interrupt/DMA from a specific memory address
294  *
295  * @param[in] id: I2C module ID.
296  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
297  * @param[in] mem_address: Internal memory address
298  * @param[in] mem_addr_size: Size of internal memory address
299  * @param[in] p_data: Pointer to data buffer
300  * @param[in] size: Amount of data to be sent
301  *
302  * @return Result of operation.
303  ****************************************************************************************
304  */
305 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);
306 
307 /**
308  ****************************************************************************************
309  * @brief Write an amount of data in blocking mode to a specific memory address
310  *
311  * @param[in] id: I2C module ID.
312  * @param[in] dev_address: Target device address: The device 7 bits address value in datasheet must be shifted at right before call interface
313  * @param[in] mem_address: Internal memory address
314  * @param[in] mem_addr_size: Size of internal memory address
315  * @param[in] p_data: Pointer to data buffer
316  * @param[in] size: Amount of data to be sent
317  * @param[in] timeout: Timeout duration
318  *
319  * @return Result of operation.
320  ****************************************************************************************
321  */
322 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);
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 datasheet must be shifted at right before call interface
330  * @param[in] mem_address: Internal memory address
331  * @param[in] mem_addr_size: Size of internal memory address
332  * @param[in] p_data: Pointer to data buffer
333  * @param[in] size: Amount of data to be sent
334  *
335  * @return Result of operation.
336  ****************************************************************************************
337  */
338 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);
339 
340 /**
341  ****************************************************************************************
342  * @brief Return the I2C handle.
343  *
344  * @param[in] id: I2C module ID.
345  *
346  * @return Pointer to the specified ID's I2C handle.
347  ****************************************************************************************
348  */
350 
351 #ifdef ENV_RTOS_USE_SEMP
352 
353 /**
354  ****************************************************************************************
355  * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode.
356  *
357  * @param[in] id: I2C module ID.
358  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
359  must be shifted at right before call interface.
360  * @param[in] p_data: Pointer to data buffer
361  * @param[in] size: Amount of data to be sent
362  *
363  * @return Result of operation.
364  ****************************************************************************************
365  */
366 uint16_t app_i2c_receive_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
367 
368 /**
369  ****************************************************************************************
370  * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode.
371  *
372  * @param[in] id: I2C module ID.
373  * @param[in] target_address: Target device address: The device 7 bits address value in datasheet
374  must be shifted at right before call interface.
375  * @param[in] p_data: Pointer to data buffer
376  * @param[in] size: Amount of data to be sent
377  *
378  * @return Result of operation.
379  ****************************************************************************************
380  */
381 uint16_t app_i2c_transmit_sem_sync(app_i2c_id_t id, uint16_t target_address, uint8_t *p_data, uint16_t size);
382 
383 #endif
384 
385 /** @} */
386 
387 
388 #endif
389 
390 #ifdef __cplusplus
391 }
392 #endif
393 
394 #endif
395 
396 /** @} */
397 /** @} */
398 /** @} */
399 
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:177
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_t::slave_addr
uint16_t slave_addr
Definition: app_i2c.h:171
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