1 /** 2 * @file i2s.h 3 * @brief I2S (Inter-Integrated Sound) driver function prototypes and data types. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2017 Maxim Integrated Products, Inc., All Rights Reserved. 8 * 9 * Permission is hereby granted, free of charge, to any person obtaining a 10 * copy of this software and associated documentation files (the "Software"), 11 * to deal in the Software without restriction, including without limitation 12 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 13 * and/or sell copies of the Software, and to permit persons to whom the 14 * Software is furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be included 17 * in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 20 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES 23 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 25 * OTHER DEALINGS IN THE SOFTWARE. 26 * 27 * Except as contained in this notice, the name of Maxim Integrated 28 * Products, Inc. shall not be used except as stated in the Maxim Integrated 29 * Products, Inc. Branding Policy. 30 * 31 * The mere transfer of this software does not imply any licenses 32 * of trade secrets, proprietary technology, copyrights, patents, 33 * trademarks, maskwork rights, or any other form of intellectual 34 * property whatsoever. Maxim Integrated Products, Inc. retains all 35 * ownership rights. 36 * 37 * $Date: 2018-12-18 15:37:22 -0600 (Tue, 18 Dec 2018) $ 38 * $Revision: 40072 $ 39 * 40 *************************************************************************** */ 41 42 #ifndef _I2S_H_ 43 #define _I2S_H_ 44 45 /* **** Includes **** */ 46 #include "mxc_config.h" 47 #include "dma.h" 48 #include "spimss_regs.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @defgroup i2s Inter-Integrated Sound (I2S) 56 * @ingroup spi 57 * @{ 58 */ 59 60 /* **** Definitions **** */ 61 62 /** @brief I2S audio directions */ 63 typedef enum { 64 AUDIO_OUT = 1, 65 AUDIO_IN = 2, 66 } i2s_direction_t; 67 68 /** @brief I2S Configuration Struct */ 69 typedef struct { 70 uint8_t left_justify; 71 uint8_t mono_audio; 72 i2s_direction_t audio_direction; 73 unsigned int sample_rate; 74 unsigned int start_immediately; 75 void *dma_src_addr; 76 void *dma_dst_addr; 77 unsigned int dma_cnt; 78 unsigned int dma_reload_en; 79 } i2s_cfg_t; 80 81 /* **** Function Prototypes **** */ 82 83 /** 84 * @brief Initialize I2S resources 85 * @param cfg I2S Configuration Struct 86 * @param dma_ctz_cb Optional function to be called when the DMA completes 87 a transfer. Set to NULL if unused. 88 * @param sys_cfg_i2s System configuration object 89 * @details This initialization is required before using the I2S driver functions. 90 * @return \c #E_NO_ERROR if successful 91 */ 92 int I2S_Init(const i2s_cfg_t *cfg, void (*dma_ctz_cb)(int, int), const sys_cfg_i2s_t* sys_cfg_i2s); 93 94 /** 95 * @brief Release I2S 96 * @details De-configures the I2S protocol and stops DMA request 97 * @return \c #E_BAD_PARAM if DMA cannot be stopped, #E_NO_ERROR otherwise 98 */ 99 int I2S_Shutdown(void); 100 101 /** 102 * @brief Mute I2S Output 103 * @details Sets I2S data to zero, continues sending clock and accessing DMA 104 * @return \c #E_NO_ERROR 105 */ 106 int I2S_Mute(void); 107 108 /** 109 * @brief Unmute I2S Output 110 * @details Restores I2S data 111 * @return \c #E_NO_ERROR 112 */ 113 int I2S_Unmute(void); 114 115 /** 116 * @brief Pause I2S Output 117 * @details Similar to mute, but stops FIFO and DMA access, clocks continue 118 * @return \c #E_NO_ERROR 119 */ 120 int I2S_Pause(void); 121 122 /** 123 * @brief Unpause I2S Output 124 * @details Similar to mute, but restarts FIFO and DMA access 125 * @return \c #E_NO_ERROR 126 */ 127 int I2S_Unpause(void); 128 129 /** 130 * @brief Stops I2S Output 131 * @details Similar to pause, but also halts clock 132 * @return \c #E_NO_ERROR 133 */ 134 int I2S_Stop(void); 135 136 /** 137 * @brief Starts I2S Output 138 * @details Starts I2S Output, automatically called by configure if requested 139 * @return \c #E_NO_ERROR 140 */ 141 int I2S_Start(void); 142 143 /** 144 * @brief Clears DMA Interrupt Flags 145 * @details Clears the DMA Interrupt flags, should be called at the end of a dma_ctz_cb 146 * @return \c #E_NO_ERROR 147 */ 148 int I2S_DMA_ClearFlags(void); 149 150 /** 151 * @brief Set DMA Addr (Source or Dest) and bytes to transfer 152 * @param src_addr The address to read data from (Audio Out) 153 * @param dst_addr The address to write data to (Audio In) 154 * @param count The length of the transfer in bytes 155 * @details Sets the address to read/write data in memory and the length of 156 * the transfer. The unused addr parameter is ignored. 157 * @return \c #E_NO_ERROR 158 */ 159 int I2S_DMA_SetAddrCnt(void *src_addr, void *dst_addr, unsigned int count); 160 161 /** 162 * @brief Sets the DMA reload address and count 163 * @param src_addr The address to read data from (Audio Out) 164 * @param dst_addr The address to write data to (Audio In) 165 * @param count The length of the transfer in bytes 166 * @details If DMA reload is enabled, when the DMA has transfered $count bytes 167 * (a CTZ event occurs) the src, dst, and count registers will be 168 * set to these. The DMA reload flag clears after a reload occurs. 169 * @return \c #E_NO_ERROR 170 */ 171 int I2S_DMA_SetReload(void *src_addr, void *dst_addr, unsigned int count); 172 /**@} end of group i2s */ 173 174 175 #ifdef __cplusplus 176 } 177 #endif 178 179 #endif /* _I2S_H_ */ 180