1 /*
2 * Copyright (c) 2015 - 2018, 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
50 #define NRFX_PDM_MAX_BUFFER_SIZE 32767
51
52
53 /**
54 * @brief PDM error type.
55 */
56 typedef enum
57 {
58 NRFX_PDM_NO_ERROR = 0,
59 NRFX_PDM_ERROR_OVERFLOW = 1
60 } nrfx_pdm_error_t;
61
62 /**
63 * @brief PDM event structure.
64 */
65 typedef struct
66 {
67 bool buffer_requested; ///< Buffer request flag.
68 int16_t * buffer_released; ///< Pointer to the released buffer. Can be NULL.
69 nrfx_pdm_error_t error; ///< Error type.
70 } nrfx_pdm_evt_t;
71
72 /**
73 * @brief PDM interface driver configuration structure.
74 */
75 typedef struct
76 {
77 nrf_pdm_mode_t mode; ///< Interface operation mode.
78 nrf_pdm_edge_t edge; ///< Sampling mode.
79 uint8_t pin_clk; ///< CLK pin.
80 uint8_t pin_din; ///< DIN pin.
81 nrf_pdm_freq_t clock_freq; ///< Clock frequency.
82 nrf_pdm_gain_t gain_l; ///< Left channel gain.
83 nrf_pdm_gain_t gain_r; ///< Right channel gain.
84 uint8_t interrupt_priority; ///< Interrupt priority.
85 } nrfx_pdm_config_t;
86
87 /**
88 * @brief Macro for setting @ref nrfx_pdm_config_t to default settings
89 * in single ended mode.
90 *
91 * @param _pin_clk CLK output pin.
92 * @param _pin_din DIN input pin.
93 */
94 #define NRFX_PDM_DEFAULT_CONFIG(_pin_clk, _pin_din) \
95 { \
96 .mode = (nrf_pdm_mode_t)NRFX_PDM_CONFIG_MODE, \
97 .edge = (nrf_pdm_edge_t)NRFX_PDM_CONFIG_EDGE, \
98 .pin_clk = _pin_clk, \
99 .pin_din = _pin_din, \
100 .clock_freq = (nrf_pdm_freq_t)NRFX_PDM_CONFIG_CLOCK_FREQ, \
101 .gain_l = NRF_PDM_GAIN_DEFAULT, \
102 .gain_r = NRF_PDM_GAIN_DEFAULT, \
103 .interrupt_priority = NRFX_PDM_CONFIG_IRQ_PRIORITY \
104 }
105
106 /**
107 * @brief Handler for PDM interface ready events.
108 *
109 * This event handler is called on a buffer request, an error or when a buffer
110 * is full and ready to be processed.
111 *
112 * @param[in] p_evt Pointer to the PDM event structure.
113 */
114 typedef void (*nrfx_pdm_event_handler_t)(nrfx_pdm_evt_t const * const p_evt);
115
116
117 /**
118 * @brief Function for initializing the PDM interface.
119 *
120 * @param[in] p_config Pointer to the structure with initial configuration.
121 * @param[in] event_handler Event handler provided by the user. Cannot be NULL.
122 *
123 * @retval NRFX_SUCCESS If initialization was successful.
124 * @retval NRFX_ERROR_INVALID_STATE If the driver is already initialized.
125 * @retval NRFX_ERROR_INVALID_PARAM If invalid configuration was specified.
126 */
127 nrfx_err_t nrfx_pdm_init(nrfx_pdm_config_t const * p_config,
128 nrfx_pdm_event_handler_t event_handler);
129
130 /**
131 * @brief Function for uninitializing the PDM interface.
132 *
133 * This function stops PDM sampling, if it is in progress.
134 */
135 void nrfx_pdm_uninit(void);
136
137 /**
138 * @brief Function for getting the address of a PDM interface task.
139 *
140 * @param[in] task Task.
141 *
142 * @return Task address.
143 */
nrfx_pdm_task_address_get(nrf_pdm_task_t task)144 __STATIC_INLINE uint32_t nrfx_pdm_task_address_get(nrf_pdm_task_t task)
145 {
146 return nrf_pdm_task_address_get(task);
147 }
148
149 /**
150 * @brief Function for getting the state of the PDM interface.
151 *
152 * @retval true If the PDM interface is enabled.
153 * @retval false If the PDM interface is disabled.
154 */
nrfx_pdm_enable_check(void)155 __STATIC_INLINE bool nrfx_pdm_enable_check(void)
156 {
157 return nrf_pdm_enable_check();
158 }
159
160 /**
161 * @brief Function for starting PDM sampling.
162 *
163 * @retval NRFX_SUCCESS If sampling was started successfully or was already in progress.
164 * @retval NRFX_ERROR_BUSY If a previous start/stop operation is in progress.
165 */
166 nrfx_err_t nrfx_pdm_start(void);
167
168 /**
169 * @brief Function for stopping PDM sampling.
170 *
171 * When this function is called, the PDM interface is stopped after finishing
172 * the current frame.
173 * The event handler function might be called once more after calling this function.
174 *
175 * @retval NRFX_SUCCESS If sampling was stopped successfully or was already stopped before.
176 * @retval NRFX_ERROR_BUSY If a previous start/stop operation is in progress.
177 */
178 nrfx_err_t nrfx_pdm_stop(void);
179
180 /**
181 * @brief Function for supplying the sample buffer.
182 *
183 * Call this function after every buffer request event.
184 *
185 * @param[in] buffer Pointer to the receive buffer. Cannot be NULL.
186 * @param[in] buffer_length Length of the receive buffer in 16-bit words.
187 *
188 * @retval NRFX_SUCCESS If the buffer was applied successfully.
189 * @retval NRFX_ERROR_BUSY If the buffer was already supplied or the peripheral is currently being stopped.
190 * @retval NRFX_ERROR_INVALID_STATE If the driver was not initialized.
191 * @retval NRFX_ERROR_INVALID_PARAM If invalid parameters were provided.
192 */
193 nrfx_err_t nrfx_pdm_buffer_set(int16_t * buffer, uint16_t buffer_length);
194
195
196 void nrfx_pdm_irq_handler(void);
197
198
199 /** @} */
200
201 #ifdef __cplusplus
202 }
203 #endif
204
205 #endif // NRFX_PDM_H__
206