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 */ 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 */ 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