app_pdm.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_pdm.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of PDM 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 #ifndef _APP_PDM_H_
39 #define _APP_PDM_H_
40 
41 #include "grx_hal.h"
42 #include "app_drv_error.h"
43 #include "app_drv_config.h"
44 #include "app_io.h"
45 #include "app_dma.h"
46 
47 /** @addtogroup PERIPHERAL Peripheral Driver
48  * @{
49  */
50 
51 /** @addtogroup APP_DRIVER APP DRIVER
52  * @{
53  */
54 
55 /** @defgroup APP_PDM PDM
56  * @brief PDM APP module driver.
57  * @{
58  */
59 
60 #ifdef HAL_PDM_MODULE_ENABLED
61 
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65 
66 /** @addtogroup APP_PDM_ENUMS Enumerations
67  * @{
68  */
69 
70 /**
71  * @brief PDM event Enumerations definition
72  */
73 typedef enum
74 {
75  APP_PDM_EVT_DMA_ERROR, /**< The event of dma error interrupt. */
76  APP_PDM_EVT_DMA_TFR, /**< The event of transfer complete interrupt. */
77  APP_PDM_EVT_DMA_BLK, /**< The event of dma block interrupt. */
78  APP_PDM_EVT_LEFT_OVERFLOW, /**< The event of left channel overflow. */
79  APP_PDM_EVT_RIGHT_OVERFLOW, /**< The event of right channel overflow. */
81 
82 /** @} */
83 
84 /** @addtogroup APP_PDM_STRUCTURES Structures
85  * @{
86  */
87 
88 /**
89  * @brief PDM IO configuration Structures
90  */
91 typedef struct
92 {
93  app_io_type_t type; /**< Specifies the type of PDM IO. */
94  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
95  uint32_t pin; /**< Specifies the IO pins to be configured. */
96  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
98 
99 /**
100  * @brief PDM IO Structures
101  */
102 typedef struct
103 {
104  app_pdm_pin_t clk; /**< Set the configuration of PDM CLK pin. */
105  app_pdm_pin_t data; /**< Set the configuration of PDM DATA pin. */
107 
108 /**
109  * @brief PDM operate mode Enumerations definition
110  */
111 typedef struct
112 {
113  dma_regs_t *dma_instance; /**< Specifies the DMA instance. */
114  dma_channel_t dma_channel; /**< Specifies the channel of PDM. */
116 
117 /**
118  * @brief PDM event structure definition
119  */
120 typedef struct
121 {
122  app_pdm_evt_type_t type; /**< Type of event. */
123 
124  uint32_t error_code; /**< PDM error code . */
125 } app_pdm_evt_t;
126 
127 /** @} */
128 
129 /** @addtogroup APP_PDM_TYPEDEFS Type definitions
130  * @{
131  */
132 
133 /**
134  * @brief PDM event callback definition
135  */
136 typedef void (*app_pdm_evt_handler_t)(app_pdm_evt_t *type);
137 
138 /** @} */
139 
140 /** @addtogroup APP_PDM_ENUMS Enumerations
141  * @{
142  */
143 
144 /**
145  * @brief pdm state types.
146  */
147 typedef enum
148 {
151 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
152  APP_PDM_SLEEP,
153 #endif
155 
156 /** @} */
157 
158 /** @addtogroup APP_PDM_STRUCTURES Structures
159  * @{
160  */
161 
162 /**
163  * @brief app pdm instance structure.
164  */
165 typedef struct
166 {
167  app_pdm_evt_handler_t evt_handler; /**< Pdm event callback. */
168  pdm_handle_t handle; /**< Pdm handle Structure. */
169  app_pdm_pin_cfg_t *p_pin_cfg; /**< Pdm IO Structures. */
170  dma_id_t dma_id; /**< Dma id. */
171  app_pdm_state_t pdm_state; /**< Pdm state types. */
172 } pdm_env_t;
173 
174 /**
175  * @brief PDM parameters structure definition
176  */
177 typedef struct
178 {
179  app_pdm_pin_cfg_t pin_cfg; /**< The pin configuration information .*/
180  app_pdm_dma_t dma_cfg; /**< The dma configuration information. */
181  pdm_init_t init; /**< The pdm configuration information. */
182  pdm_env_t pdm_env; /**< App pdm instance structure. */
184 
185 /** @} */
186 /* Exported functions --------------------------------------------------------*/
187 /** @addtogroup APP_PDM_DRIVER_FUNCTIONS Functions
188  * @{
189  */
190 /**
191  ****************************************************************************************
192  * @brief Initialize the APP PDM DRIVER according to the specified parameters
193  * in the app_pdm_params_t and app_pdm_evt_handler_t.
194  *
195  * @param[in] p_params: Pointer to app_pdm_params_t parameter which contains the
196  * configuration information for the specified PDM module.
197  * @param[in] evt_handler: PDM user callback function.
198  *
199  * @return Result of initialization.
200  ****************************************************************************************
201  */
202 uint16_t app_pdm_init(app_pdm_params_t *p_params, app_pdm_evt_handler_t evt_handler);
203 
204 /**
205  ****************************************************************************************
206  * @brief De-initialize the APP PDM DRIVER peripheral.
207  *
208  * @return Result of De-initialization.
209  ****************************************************************************************
210  */
211 uint16_t app_pdm_deinit(void);
212 
213 /**
214  ****************************************************************************************
215  * @brief Start the pdm left channel transfer with dma.
216  *
217  * @param[in] p_data: Point to the data buffer.
218  * @param[in] length: The length of data,ranging between 0 and 4095.
219  ****************************************************************************************
220  */
221 uint16_t app_pdm_left_start_dma(uint16_t *p_data, uint32_t length);
222 
223 /**
224  ****************************************************************************************
225  * @brief Start the pdm right channel transfer with dma.
226  *
227  * @param[in] p_data: Point to the data buffer.
228  * @param[in] length: The length of data,ranging between 0 and 4095.
229  ****************************************************************************************
230  */
231 uint16_t app_pdm_right_start_dma(uint16_t *p_data, uint32_t length);
232 
233 /**
234  ****************************************************************************************
235  * @brief Start the pdm dual channel transfer with dma.
236  *
237  * @param[in] p_data: Point to the data buffer.
238  * @param[in] length: The length of data,ranging between 0 and 4095.
239  ****************************************************************************************
240  */
241 uint16_t app_pdm_stereo_start_dma(uint32_t *p_data, uint32_t length);
242 
243 /**
244  ****************************************************************************************
245  * @brief Start the pdm left channel transfer with dma's sg and llp functions.
246  *
247  * @param[in] p_data: Point to the data buffer.
248  * @param[in] length: The length of data,ranging between 0 and 4095.
249  * @param[in] sg_llp_config: The config of source and destination's sg and llp fuction.
250  ****************************************************************************************
251  */
252 uint16_t app_pdm_left_start_dma_sg_llp(uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config);
253 
254 /**
255  ****************************************************************************************
256  * @brief Start the pdm right channel transfer with dma's sg and llp functions.
257  *
258  * @param[in] p_data: Point to the data buffer.
259  * @param[in] length: The length of data,ranging between 0 and 4095.
260  * @param[in] sg_llp_config: The config of source and destination's sg and llp fuction.
261  ****************************************************************************************
262  */
263 uint16_t app_pdm_right_start_dma_sg_llp(uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config);
264 
265 /**
266  ****************************************************************************************
267  * @brief Start the pdm dual channel transfer with dma's sg and llp functions.
268  *
269  * @param[in] p_data: Point to the data buffer.
270  * @param[in] length: The length of data,ranging between 0 and 4095.
271  * @param[in] sg_llp_config: The config of source and destination's sg and llp fuction.
272  ****************************************************************************************
273  */
274 uint16_t app_pdm_stereo_start_dma_sg_llp(uint32_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config);
275 
276 /**
277  ****************************************************************************************
278  * @brief Abort the pdm transfer.
279  *
280  * @return Result of abort.
281  ****************************************************************************************
282  */
283 uint16_t app_pdm_abort(void);
284 
285 /**
286  ****************************************************************************************
287  * @brief Return the PDM handle.
288  *
289  * @return Pointer to the specified PDM handle.
290  ****************************************************************************************
291  */
293 
294 /** @} */
295 
296 
297 
298 #ifdef __cplusplus
299 }
300 #endif
301 
302 
303 #endif //#ifdef HAL_PDM_MODULE_ENABLED
304 #endif //#ifndef _APP_PDM_H_
305 
306 /** @} */
307 
308 /** @} */
309 
310 /** @} */
app_pdm_params_t::init
pdm_init_t init
Definition: app_pdm.h:181
app_pdm_evt_type_t
app_pdm_evt_type_t
PDM event Enumerations definition.
Definition: app_pdm.h:74
app_pdm_stereo_start_dma
uint16_t app_pdm_stereo_start_dma(uint32_t *p_data, uint32_t length)
Start the pdm dual channel transfer with dma.
app_pdm_pin_t::type
app_io_type_t type
Definition: app_pdm.h:93
app_pdm_pin_t::pin
uint32_t pin
Definition: app_pdm.h:95
pdm_env_t
app pdm instance structure.
Definition: app_pdm.h:166
app_pdm_init
uint16_t app_pdm_init(app_pdm_params_t *p_params, app_pdm_evt_handler_t evt_handler)
Initialize the APP PDM DRIVER according to the specified parameters in the app_pdm_params_t and app_p...
app_pdm_params_t::pdm_env
pdm_env_t pdm_env
Definition: app_pdm.h:182
app_pdm_abort
uint16_t app_pdm_abort(void)
Abort the pdm transfer.
app_pdm_evt_t::type
app_pdm_evt_type_t type
Definition: app_pdm.h:122
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:183
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:147
pdm_env_t::pdm_state
app_pdm_state_t pdm_state
Definition: app_pdm.h:171
app_pdm_params_t
PDM parameters structure definition.
Definition: app_pdm.h:178
app_pdm_pin_cfg_t::clk
app_pdm_pin_t clk
Definition: app_pdm.h:104
app_pdm_pin_cfg_t::data
app_pdm_pin_t data
Definition: app_pdm.h:105
pdm_env_t::evt_handler
app_pdm_evt_handler_t evt_handler
Definition: app_pdm.h:167
dma_sg_llp_config
LL DMA sg and llp config definition.
Definition: gr55xx_hal_dma.h:219
app_pdm_left_start_dma_sg_llp
uint16_t app_pdm_left_start_dma_sg_llp(uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config)
Start the pdm left channel transfer with dma's sg and llp functions.
app_pdm_get_handle
pdm_handle_t * app_pdm_get_handle(void)
Return the PDM handle.
pdm_env_t::handle
pdm_handle_t handle
Definition: app_pdm.h:168
app_io.h
Header file containing functions prototypes of GPIO app library.
APP_PDM_INACTIVITY
@ APP_PDM_INACTIVITY
Definition: app_pdm.h:149
app_pdm_pin_t::mux
app_io_mux_t mux
Definition: app_pdm.h:94
app_pdm_evt_t::error_code
uint32_t error_code
Definition: app_pdm.h:124
APP_PDM_EVT_LEFT_OVERFLOW
@ APP_PDM_EVT_LEFT_OVERFLOW
Definition: app_pdm.h:78
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_pdm_right_start_dma_sg_llp
uint16_t app_pdm_right_start_dma_sg_llp(uint16_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config)
Start the pdm right channel transfer with dma's sg and llp functions.
app_pdm_right_start_dma
uint16_t app_pdm_right_start_dma(uint16_t *p_data, uint32_t length)
Start the pdm right channel transfer with dma.
APP_PDM_EVT_DMA_ERROR
@ APP_PDM_EVT_DMA_ERROR
Definition: app_pdm.h:75
APP_PDM_EVT_DMA_TFR
@ APP_PDM_EVT_DMA_TFR
Definition: app_pdm.h:76
app_pdm_state_t
app_pdm_state_t
pdm state types.
Definition: app_pdm.h:148
_pdm_handle
PDM handle Structure definition.
Definition: gr55xx_hal_pdm.h:97
app_pdm_pin_cfg_t
PDM IO Structures.
Definition: app_pdm.h:103
app_pdm_dma_t::dma_channel
dma_channel_t dma_channel
Definition: app_pdm.h:114
app_pdm_dma_t
PDM operate mode Enumerations definition.
Definition: app_pdm.h:112
app_dma.h
Header file containing functions prototypes of DMA app library.
APP_PDM_ACTIVITY
@ APP_PDM_ACTIVITY
Definition: app_pdm.h:150
app_pdm_evt_t
PDM event structure definition.
Definition: app_pdm.h:121
pdm_env_t::dma_id
dma_id_t dma_id
Definition: app_pdm.h:170
app_pdm_left_start_dma
uint16_t app_pdm_left_start_dma(uint16_t *p_data, uint32_t length)
Start the pdm left channel transfer with dma.
app_pdm_dma_t::dma_instance
dma_regs_t * dma_instance
Definition: app_pdm.h:113
app_pdm_evt_handler_t
void(* app_pdm_evt_handler_t)(app_pdm_evt_t *type)
PDM event callback definition.
Definition: app_pdm.h:136
app_pdm_params_t::pin_cfg
app_pdm_pin_cfg_t pin_cfg
Definition: app_pdm.h:179
app_pdm_pin_t::pull
app_io_pull_t pull
Definition: app_pdm.h:96
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:255
APP_PDM_EVT_DMA_BLK
@ APP_PDM_EVT_DMA_BLK
Definition: app_pdm.h:77
app_pdm_deinit
uint16_t app_pdm_deinit(void)
De-initialize the APP PDM DRIVER peripheral.
APP_PDM_EVT_RIGHT_OVERFLOW
@ APP_PDM_EVT_RIGHT_OVERFLOW
Definition: app_pdm.h:79
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
app_pdm_pin_t
PDM IO configuration Structures.
Definition: app_pdm.h:92
dma_id_t
int16_t dma_id_t
DMA id definition.
Definition: app_dma.h:98
app_pdm_stereo_start_dma_sg_llp
uint16_t app_pdm_stereo_start_dma_sg_llp(uint32_t *p_data, uint32_t length, dma_sg_llp_config_t *sg_llp_config)
Start the pdm dual channel transfer with dma's sg and llp functions.
app_pdm_params_t::dma_cfg
app_pdm_dma_t dma_cfg
Definition: app_pdm.h:180
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:94
pdm_env_t::p_pin_cfg
app_pdm_pin_cfg_t * p_pin_cfg
Definition: app_pdm.h:169
pdm_init_t
ll_pdm_init_t pdm_init_t
PDM init structure definition.
Definition: gr55xx_hal_pdm.h:86