1 /*
2 * Copyright (c) 2015 - 2020, Nordic Semiconductor ASA
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this
9 * list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 * POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #ifndef NRFX_PDM_H__
33 #define NRFX_PDM_H__
34
35 #include <nrfx.h>
36 #include <hal/nrf_pdm.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /**
43 * @defgroup nrfx_pdm PDM driver
44 * @{
45 * @ingroup nrf_pdm
46 * @brief Pulse Density Modulation (PDM) peripheral driver.
47 */
48
49 /** @brief Maximum supported PDM buffer size. */
50 #define NRFX_PDM_MAX_BUFFER_SIZE 32767
51
52 /** @brief PDM error type. */
53 typedef enum
54 {
55 NRFX_PDM_NO_ERROR = 0, ///< No error.
56 NRFX_PDM_ERROR_OVERFLOW = 1 ///< Overflow error.
57 } nrfx_pdm_error_t;
58
59 /** @brief PDM event structure. */
60 typedef struct
61 {
62 bool buffer_requested; ///< Buffer request flag.
63 int16_t * buffer_released; ///< Pointer to the released buffer. Can be NULL.
64 nrfx_pdm_error_t error; ///< Error type.
65 } nrfx_pdm_evt_t;
66
67 /** @brief PDM interface driver configuration structure. */
68 typedef struct
69 {
70 nrf_pdm_mode_t mode; ///< Interface operation mode.
71 nrf_pdm_edge_t edge; ///< Sampling mode.
72 uint8_t pin_clk; ///< CLK pin.
73 uint8_t pin_din; ///< DIN pin.
74 nrf_pdm_freq_t clock_freq; ///< Clock frequency.
75 nrf_pdm_gain_t gain_l; ///< Left channel gain.
76 nrf_pdm_gain_t gain_r; ///< Right channel gain.
77 uint8_t interrupt_priority; ///< Interrupt priority.
78 #if NRF_PDM_HAS_RATIO_CONFIG
79 nrf_pdm_ratio_t ratio; ///< Ratio between PDM_CLK and output sample rate.
80 #endif
81 #if NRF_PDM_HAS_MCLKCONFIG
82 nrf_pdm_mclksrc_t mclksrc; ///< Master clock source selection.
83 #endif
84 } nrfx_pdm_config_t;
85
86
87 #if NRF_PDM_HAS_RATIO_CONFIG || defined(__NRFX_DOXYGEN__)
88 /** @brief PDM additional ratio configuration. */
89 #define NRFX_PDM_DEFAULT_EXTENDED_RATIO_CONFIG \
90 .ratio = NRF_PDM_RATIO_64X,
91 #else
92 #define NRFX_PDM_DEFAULT_EXTENDED_RATIO_CONFIG
93 #endif
94
95 #if NRF_PDM_HAS_MCLKCONFIG || defined(__NRFX_DOXYGEN__)
96 /** @brief PDM additional master clock source configuration. */
97 #define NRFX_PDM_DEFAULT_EXTENDED_MCLKSRC_CONFIG \
98 .mclksrc = NRF_PDM_MCLKSRC_PCLK32M,
99 #else
100 #define NRFX_PDM_DEFAULT_EXTENDED_MCLKSRC_CONFIG
101 #endif
102
103 /**
104 * @brief PDM driver default configuration.
105 *
106 * This configuration sets up PDM with the following options:
107 * - mono mode
108 * - data sampled on the clock falling edge
109 * - frequency: 1.032 MHz
110 * - standard gain
111 *
112 * @param[in] _pin_clk CLK output pin.
113 * @param[in] _pin_din DIN input pin.
114 */
115 #define NRFX_PDM_DEFAULT_CONFIG(_pin_clk, _pin_din) \
116 { \
117 .mode = NRF_PDM_MODE_MONO, \
118 .edge = NRF_PDM_EDGE_LEFTFALLING, \
119 .pin_clk = _pin_clk, \
120 .pin_din = _pin_din, \
121 .clock_freq = NRF_PDM_FREQ_1032K, \
122 .gain_l = NRF_PDM_GAIN_DEFAULT, \
123 .gain_r = NRF_PDM_GAIN_DEFAULT, \
124 .interrupt_priority = NRFX_PDM_DEFAULT_CONFIG_IRQ_PRIORITY, \
125 NRFX_PDM_DEFAULT_EXTENDED_RATIO_CONFIG \
126 NRFX_PDM_DEFAULT_EXTENDED_MCLKSRC_CONFIG \
127 }
128
129 /**
130 * @brief Handler for the PDM interface ready events.
131 *
132 * This event handler is called on a buffer request, an error or when a buffer
133 * is full and ready to be processed.
134 *
135 * @param[in] p_evt Pointer to the PDM event structure.
136 */
137 typedef void (*nrfx_pdm_event_handler_t)(nrfx_pdm_evt_t const * p_evt);
138
139
140 /**
141 * @brief Function for initializing the PDM interface.
142 *
143 * @param[in] p_config Pointer to the structure with the initial configuration.
144 * @param[in] event_handler Event handler provided by the user. Cannot be NULL.
145 *
146 * @retval NRFX_SUCCESS Initialization was successful.
147 * @retval NRFX_ERROR_INVALID_STATE The driver is already initialized.
148 * @retval NRFX_ERROR_INVALID_PARAM Invalid configuration was specified.
149 */
150 nrfx_err_t nrfx_pdm_init(nrfx_pdm_config_t const * p_config,
151 nrfx_pdm_event_handler_t event_handler);
152
153 /**
154 * @brief Function for uninitializing the PDM interface.
155 *
156 * This function stops PDM sampling, if it is in progress.
157 */
158 void nrfx_pdm_uninit(void);
159
160 /**
161 * @brief Function for getting the address of a PDM interface task.
162 *
163 * @param[in] task Task.
164 *
165 * @return Task address.
166 */
167 NRFX_STATIC_INLINE uint32_t nrfx_pdm_task_address_get(nrf_pdm_task_t task);
168
169 /**
170 * @brief Function for getting the state of the PDM interface.
171 *
172 * @retval true The PDM interface is enabled.
173 * @retval false The PDM interface is disabled.
174 */
175 NRFX_STATIC_INLINE bool nrfx_pdm_enable_check(void);
176
177 /**
178 * @brief Function for starting the PDM sampling.
179 *
180 * @retval NRFX_SUCCESS Sampling was started successfully or was already in progress.
181 * @retval NRFX_ERROR_BUSY Previous start/stop operation is in progress.
182 */
183 nrfx_err_t nrfx_pdm_start(void);
184
185 /**
186 * @brief Function for stopping the PDM sampling.
187 *
188 * When this function is called, the PDM interface is stopped after finishing
189 * the current frame.
190 * The event handler function might be called once more after calling this function.
191 *
192 * @retval NRFX_SUCCESS Sampling was stopped successfully or was already stopped before.
193 * @retval NRFX_ERROR_BUSY Previous start/stop operation is in progress.
194 */
195 nrfx_err_t nrfx_pdm_stop(void);
196
197 /**
198 * @brief Function for supplying the sample buffer.
199 *
200 * Call this function after every buffer request event.
201 *
202 * @param[in] buffer Pointer to the receive buffer. Cannot be NULL.
203 * @param[in] buffer_length Length of the receive buffer in 16-bit words.
204 *
205 * @retval NRFX_SUCCESS The buffer was applied successfully.
206 * @retval NRFX_ERROR_BUSY The buffer was already supplied or the peripheral is currently being stopped.
207 * @retval NRFX_ERROR_INVALID_STATE The driver was not initialized.
208 * @retval NRFX_ERROR_INVALID_PARAM Invalid parameters were provided.
209 */
210 nrfx_err_t nrfx_pdm_buffer_set(int16_t * buffer, uint16_t buffer_length);
211
212 #ifndef NRFX_DECLARE_ONLY
nrfx_pdm_task_address_get(nrf_pdm_task_t task)213 NRFX_STATIC_INLINE uint32_t nrfx_pdm_task_address_get(nrf_pdm_task_t task)
214 {
215 return nrf_pdm_task_address_get(NRF_PDM0, task);
216 }
217
nrfx_pdm_enable_check(void)218 NRFX_STATIC_INLINE bool nrfx_pdm_enable_check(void)
219 {
220 return nrf_pdm_enable_check(NRF_PDM0);
221 }
222 #endif // NRFX_DECLARE_ONLY
223
224 /** @} */
225
226
227 void nrfx_pdm_irq_handler(void);
228
229
230 #ifdef __cplusplus
231 }
232 #endif
233
234 #endif // NRFX_PDM_H__
235