app_i2s.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_i2s.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of I2S 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_I2S I2S
47  * @brief I2S APP module driver.
48  * @{
49  */
50 
51 
52 #ifndef _APP_I2S_H_
53 #define _APP_I2S_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_I2S_MODULE_ENABLED
67 
68 /** @addtogroup APP_I2S_ENUM Enumerations
69  * @{
70  */
71 
72 /**
73  * @brief I2S module Enumerations definition
74  */
75 typedef enum
76 {
77  APP_I2S_ID_SLAVE, /**< I2S slave module. */
78  APP_I2S_ID_MASTER, /**< I2S master module. */
79  APP_I2S_ID_MAX /**< Only for check parameter, not used as input parameters. */
81 
82 /**
83  * @brief I2S operating mode Enumerations definition
84  */
85 typedef enum
86 {
87  APP_I2S_TYPE_INTERRUPT, /**< Interrupt operation mode */
88  APP_I2S_TYPE_POLLING, /**< Polling operation mode */
89  APP_I2S_TYPE_DMA, /**< DMA operation mode */
90  APP_I2S_TYPE_MAX /**< Only for check parameter, not used as input parameters. */
92 
93 /**
94  * @brief I2S event Enumerations definition
95  */
96 typedef enum
97 {
98  APP_I2S_EVT_ERROR, /**< Error reported by UART peripheral. */
99  APP_I2S_EVT_TX_CPLT, /**< Requested TX transfer completed. */
100  APP_I2S_EVT_RX_DATA, /**< Requested RX transfer completed. */
101  APP_I2S_EVT_TX_RX, /**< Requested TX/RX transfer completed. */
103 /** @} */
104 
105 
106 /** @addtogroup APP_I2S_STRUCTURES Structures
107  * @{
108  */
109 
110 /**
111  * @brief I2S IO Structures
112  */
113 typedef struct
114 {
115  app_io_type_t type; /**< Specifies the type of I2S IO. */
116  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
117  uint32_t pin; /**< Specifies the IO pins to be configured.
118  This parameter can be any value of @ref GR551x_pins. */
119  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
120 } app_i2s_pin_t;
121 
122 /**
123  * @brief I2S IO configuration Structures
124  */
125 typedef struct
126 {
127  app_i2s_pin_t ws; /**< Set the configuration of I2S WS pin. */
128  app_i2s_pin_t sdo; /**< Set the configuration of I2S SDO pin. */
129  app_i2s_pin_t sdi; /**< Set the configuration of I2S SDI pin. */
130  app_i2s_pin_t sclk; /**< Set the configuration of I2S SCLK pin. */
132 
133 /**
134  * @brief I2S operate mode Enumerations definition
135  */
136 typedef struct
137 {
138  app_i2s_type_t type; /**< Specifies the operation mode of I2S. */
139  dma_channel_t tx_dma_channel; /**< Specifies the dma channel of I2S TX. */
140  dma_channel_t rx_dma_channel; /**< Specifies the dma channel of I2S RX. */
142 
143 /**
144  * @brief I2S parameters structure definition
145  */
146 typedef struct
147 {
148  app_i2s_id_t id; /**< specified I2S module ID. */
149  app_i2s_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified I2S module. */
150  app_i2s_mode_t use_mode; /**< I2S operate mode. */
151  i2s_init_t init; /**< I2S communication parameters. */
153 
154 /**
155  * @brief I2S event structure definition
156  */
157 typedef struct
158 {
159  app_i2s_evt_type_t type; /**< Type of event. */
160  union
161  {
162  uint32_t error_code; /**< I2S Error code . */
163  uint16_t size; /**< I2S transmitted/received counter. */
164  } data; /**< I2S data. */
165 } app_i2s_evt_t;
166 
167 /**
168  * @brief I2S event callback definition
169  */
170 typedef void (*app_i2s_evt_handler_t)(app_i2s_evt_t *p_evt);
171 
172 /** @} */
173 
174 /* Exported functions --------------------------------------------------------*/
175 /** @addtogroup HAL_APP_I2S_DRIVER_FUNCTIONS Functions
176  * @{
177  */
178 
179 /**
180  ****************************************************************************************
181  * @brief Initialize the APP I2S DRIVER according to the specified parameters
182  * in the app_i2s_params_t and app_i2s_evt_handler_t.
183  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
184  * is set, you can't use interrupt mode.
185  *
186  * @param[in] p_params: Pointer to app_i2s_params_t parameter which contains the
187  * configuration information for the specified I2S module.
188  * @param[in] evt_handler: I2S user callback function.
189  *
190  * @return Result of initialization.
191  ****************************************************************************************
192  */
193 uint16_t app_i2s_init(app_i2s_params_t *p_params, app_i2s_evt_handler_t evt_handler);
194 
195 /**
196  ****************************************************************************************
197  * @brief De-initialize the APP I2S DRIVER peripheral.
198  *
199  * @param[in] id: De-initialize for a specific ID.
200  *
201  * @return Result of De-initialization.
202  ****************************************************************************************
203  */
205 
206 /**
207  ****************************************************************************************
208  * @brief Receive in master or slave mode an amount of data in blocking mode.
209  *
210  * @param[in] id: which I2S module want to receive.
211  * @param[in] p_data: Pointer to data buffer
212  * @param[in] size: Amount of data to be sent
213  * @param[in] timeout: Timeout duration
214  *
215  * @return Result of operation.
216  ****************************************************************************************
217  */
218 uint16_t app_i2s_receive_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size, uint32_t timeout);
219 
220 /**
221  ****************************************************************************************
222  * @brief Receive in master or slave mode an amount of data in non-blocking mode with Interrupt
223  *
224  * @param[in] id: which I2S module want to receive.
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_i2s_receive_async(app_i2s_id_t id, uint16_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 I2S module want to transmit.
238  * @param[in] p_data: Pointer to data buffer
239  * @param[in] size: Amount of data to be sent
240  * @param[in] timeout: Timeout duration
241  *
242  * @return Result of operation.
243  ****************************************************************************************
244  */
245 uint16_t app_i2s_transmit_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size, uint32_t timeout);
246 
247 /**
248  ****************************************************************************************
249  * @brief Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt
250  *
251  * @param[in] id: which I2S module want to transmit.
252  * @param[in] p_data: Pointer to data buffer
253  * @param[in] size: Amount of data to be sent
254  *
255  * @return Result of operation.
256  ****************************************************************************************
257  */
258 uint16_t app_i2s_transmit_async(app_i2s_id_t id, uint16_t *p_data, uint16_t size);
259 
260 /**
261  ****************************************************************************************
262  * @brief Enable the I2S moudle.
263  *
264  * @param[in] id: The I2S module id.
265  *
266  * @return Result of operation.
267  ****************************************************************************************
268  */
269 
271 
272 /**
273  ****************************************************************************************
274  * @brief Disable the I2S moudle.
275  *
276  * @param[in] id: The I2S module id.
277  *
278  * @return Result of operation.
279  ****************************************************************************************
280  */
282 
283 /**
284  ****************************************************************************************
285  * @brief Enable the master I2S clock.
286  *
287  * @param[in] id: The I2S master module id.
288  *
289  * @return Result of operation.
290  ****************************************************************************************
291  */
293 
294 /**
295  ****************************************************************************************
296  * @brief Disable the master I2S clock.
297  *
298  * @param[in] id: The I2S master module id.
299  *
300  * @return Result of operation.
301  ****************************************************************************************
302  */
304 
305 /**
306  ****************************************************************************************
307  * @brief Flush the I2S transmitter FIFO.
308  *
309  * @param[in] id: which I2S module want to flush.
310  *
311  * @return Result of operation.
312  ****************************************************************************************
313  */
315 
316 /**
317  ****************************************************************************************
318  * @brief Flush the I2S receiver FIFO.
319  *
320  * @param[in] id: which I2S module want to flush.
321  *
322  * @return Result of operation.
323  ****************************************************************************************
324  */
326 
327 /**
328  ****************************************************************************************
329  * @brief Return the I2S handle.
330  *
331  * @param[in] id: I2S Channel ID.
332  *
333  * @return Pointer to the specified ID's I2S handle.
334  ****************************************************************************************
335  */
337 
338 #ifdef ENV_RTOS_USE_SEMP
339 
340 /**
341  ****************************************************************************************
342  * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode.
343  *
344  * @param[in] id: which I2S module want to receive.
345  * @param[in] p_data: Pointer to data buffer
346  * @param[in] size: Amount of data to be sent
347  *
348  * @return Result of operation.
349  ****************************************************************************************
350  */
351 uint16_t app_i2s_receive_sem_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size);
352 
353 /**
354  ****************************************************************************************
355  * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode.
356  *
357  * @param[in] id: which I2S module want to transmit.
358  * @param[in] p_data: Pointer to data buffer
359  * @param[in] size: Amount of data to be sent
360  *
361  * @return Result of operation.
362  ****************************************************************************************
363  */
364 uint16_t app_i2s_transmit_sem_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size);
365 
366 #endif
367 
368 /** @} */
369 
370 #endif
371 
372 #ifdef __cplusplus
373 }
374 #endif
375 
376 #endif
377 
378 /** @} */
379 /** @} */
380 /** @} */
381 
382 
app_i2s_params_t::id
app_i2s_id_t id
specified I2S module ID.
Definition: app_i2s.h:148
app_i2s_pin_t::mux
app_io_mux_t mux
Specifies the Peripheral to be connected to the selected pins.
Definition: app_i2s.h:116
app_i2s_transmit_sync
uint16_t app_i2s_transmit_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size, uint32_t timeout)
Transmits in master or slave mode an amount of data in blocking mode.
app_i2s_pin_cfg_t
I2S IO configuration Structures.
Definition: app_i2s.h:126
app_i2s_enable_clock
uint16_t app_i2s_enable_clock(app_i2s_id_t id)
Enable the master I2S clock.
app_i2s_flush_tx_fifo
uint16_t app_i2s_flush_tx_fifo(app_i2s_id_t id)
Flush the I2S transmitter FIFO.
APP_I2S_TYPE_INTERRUPT
@ APP_I2S_TYPE_INTERRUPT
Interrupt operation mode.
Definition: app_i2s.h:87
app_i2s_params_t
I2S parameters structure definition.
Definition: app_i2s.h:147
APP_I2S_TYPE_DMA
@ APP_I2S_TYPE_DMA
DMA operation mode
Definition: app_i2s.h:89
APP_I2S_ID_MAX
@ APP_I2S_ID_MAX
Only for check parameter, not used as input parameters.
Definition: app_i2s.h:79
app_i2s_evt_t::error_code
uint32_t error_code
I2S Error code .
Definition: app_i2s.h:162
APP_I2S_TYPE_POLLING
@ APP_I2S_TYPE_POLLING
Polling operation mode
Definition: app_i2s.h:88
app_i2s_pin_cfg_t::sdi
app_i2s_pin_t sdi
Set the configuration of I2S SDI pin.
Definition: app_i2s.h:129
app_i2s_type_t
app_i2s_type_t
I2S operating mode Enumerations definition.
Definition: app_i2s.h:86
app_i2s_evt_type_t
app_i2s_evt_type_t
I2S event Enumerations definition.
Definition: app_i2s.h:97
app_i2s_params_t::use_mode
app_i2s_mode_t use_mode
I2S operate mode.
Definition: app_i2s.h:150
app_i2s_evt_t::size
uint16_t size
I2S transmitted/received counter.
Definition: app_i2s.h:163
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_i2s_deinit
uint16_t app_i2s_deinit(app_i2s_id_t id)
De-initialize the APP I2S DRIVER peripheral.
app_i2s_pin_cfg_t::sdo
app_i2s_pin_t sdo
Set the configuration of I2S SDO pin.
Definition: app_i2s.h:128
app_i2s_mode_t::type
app_i2s_type_t type
Specifies the operation mode of I2S.
Definition: app_i2s.h:138
app_i2s_disable
uint16_t app_i2s_disable(app_i2s_id_t id)
Disable the I2S moudle.
app_i2s_flush_rx_fifo
uint16_t app_i2s_flush_rx_fifo(app_i2s_id_t id)
Flush the I2S receiver FIFO.
APP_I2S_ID_SLAVE
@ APP_I2S_ID_SLAVE
I2S slave module.
Definition: app_i2s.h:77
APP_I2S_ID_MASTER
@ APP_I2S_ID_MASTER
I2S master module.
Definition: app_i2s.h:78
app_i2s_receive_sync
uint16_t app_i2s_receive_sync(app_i2s_id_t id, uint16_t *p_data, uint16_t size, uint32_t timeout)
Receive in master or slave mode an amount of data in blocking mode.
APP_I2S_EVT_RX_DATA
@ APP_I2S_EVT_RX_DATA
Requested RX transfer completed.
Definition: app_i2s.h:100
app_io.h
Header file containing functions prototypes of GPIO app library.
app_i2s_transmit_async
uint16_t app_i2s_transmit_async(app_i2s_id_t id, uint16_t *p_data, uint16_t size)
Transmits in master or slave mode an amount of data in non-blocking mode with Interrupt.
app_i2s_pin_t::pin
uint32_t pin
Specifies the IO pins to be configured.
Definition: app_i2s.h:117
app_i2s_evt_t::type
app_i2s_evt_type_t type
Type of event.
Definition: app_i2s.h:159
app_i2s_id_t
app_i2s_id_t
I2S module Enumerations definition.
Definition: app_i2s.h:76
app_i2s_params_t::pin_cfg
app_i2s_pin_cfg_t pin_cfg
the pin configuration information for the specified I2S module.
Definition: app_i2s.h:149
app_i2s_pin_t::pull
app_io_pull_t pull
Specifies the Pull-up or Pull-Down activation for the selected pins.
Definition: app_i2s.h:119
app_i2s_evt_t
I2S event structure definition.
Definition: app_i2s.h:158
app_i2s_mode_t::tx_dma_channel
dma_channel_t tx_dma_channel
Specifies the dma channel of I2S TX.
Definition: app_i2s.h:139
app_i2s_pin_cfg_t::ws
app_i2s_pin_t ws
Set the configuration of I2S WS pin.
Definition: app_i2s.h:127
_i2s_handle
I2S handle Structure definition.
Definition: gr55xx_hal_i2s.h:130
app_i2s_pin_t::type
app_io_type_t type
Specifies the type of I2S IO.
Definition: app_i2s.h:115
app_i2s_pin_t
I2S IO Structures.
Definition: app_i2s.h:114
APP_I2S_EVT_TX_CPLT
@ APP_I2S_EVT_TX_CPLT
Requested TX transfer completed.
Definition: app_i2s.h:99
app_i2s_pin_cfg_t::sclk
app_i2s_pin_t sclk
Set the configuration of I2S SCLK pin.
Definition: app_i2s.h:130
app_i2s_init
uint16_t app_i2s_init(app_i2s_params_t *p_params, app_i2s_evt_handler_t evt_handler)
Initialize the APP I2S DRIVER according to the specified parameters in the app_i2s_params_t and app_i...
app_i2s_params_t::init
i2s_init_t init
I2S communication parameters.
Definition: app_i2s.h:151
_i2s_init
I2S init Structure definition.
Definition: gr55xx_hal_i2s.h:104
app_i2s_mode_t::rx_dma_channel
dma_channel_t rx_dma_channel
Specifies the dma channel of I2S RX.
Definition: app_i2s.h:140
app_i2s_mode_t
I2S operate mode Enumerations definition.
Definition: app_i2s.h:137
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_i2s_enable
uint16_t app_i2s_enable(app_i2s_id_t id)
Enable the I2S moudle.
app_i2s_get_handle
i2s_handle_t * app_i2s_get_handle(app_i2s_id_t id)
Return the I2S handle.
APP_I2S_EVT_TX_RX
@ APP_I2S_EVT_TX_RX
Requested TX/RX transfer completed.
Definition: app_i2s.h:101
app_i2s_disable_clock
uint16_t app_i2s_disable_clock(app_i2s_id_t id)
Disable the master I2S clock.
app_i2s_evt_handler_t
void(* app_i2s_evt_handler_t)(app_i2s_evt_t *p_evt)
I2S event callback definition.
Definition: app_i2s.h:170
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:198
APP_I2S_EVT_ERROR
@ APP_I2S_EVT_ERROR
Error reported by UART peripheral.
Definition: app_i2s.h:98
app_rtos_cfg.h
Header file of app rtos config code.
app_drv_error.h
Header file of app driver error code.
app_i2s_receive_async
uint16_t app_i2s_receive_async(app_i2s_id_t id, uint16_t *p_data, uint16_t size)
Receive in master or slave mode an amount of data in non-blocking mode with Interrupt.
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
APP_I2S_TYPE_MAX
@ APP_I2S_TYPE_MAX
Only for check parameter, not used as input parameters.
Definition: app_i2s.h:90