1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup I2S 11 * @{ 12 * 13 * @brief Defines standard APIs of the (I2S) capabilities. 14 * 15 * The I2S module abstracts the I2S capabilities of different system platforms to provide stable APIs 16 * for driver development. 17 * This module can create and destroy I2S device handles, read and write I2S data, 18 * and obtain and set configuration parameters. 19 * 20 * @since 1.0 21 */ 22 23 /** 24 * @file i2s_if.h 25 * 26 * @brief Defines standard I2S-specific interfaces for driver development. 27 * 28 * A driver needs to use the I2S-specific interfaces for data writing and reading 29 * before performing any operations on an I2S-compliant device. 30 * 31 * @since 1.0 32 */ 33 34 #ifndef I2S_IF_H 35 #define I2S_IF_H 36 37 #include "platform_if.h" 38 39 #ifdef __cplusplus 40 #if __cplusplus 41 extern "C" { 42 #endif 43 #endif /* __cplusplus */ 44 45 /** 46 * @brief Defines the configuration of an I2S device. 47 * 48 * @attention The specific I2S controller determines which variables in this structure are supported. 49 * 50 * @since 1.0 51 */ 52 53 #define I2S_DATA_TRANSFER_PERIOD 20 54 55 enum I2sSampleRate { 56 I2S_SAMPLE_RATE_8K = 8, 57 I2S_SAMPLE_RATE_16K = 16, 58 I2S_SAMPLE_RATE_32K = 32, 59 I2S_SAMPLE_RATE_48K = 48, 60 I2S_SAMPLE_RATE_44_1K = 441, // 44.1k 61 I2S_SAMPLE_RATE_96K = 96, 62 I2S_SAMPLE_RATE_192K = 192, 63 }; 64 65 enum I2sWordWidth { 66 I2S_WORDWIDTH_8BIT = 8, 67 I2S_WORDWIDTH_16BIT = 16, 68 I2S_WORDWIDTH_18BIT = 18, 69 I2S_WORDWIDTH_20BIT = 20, 70 I2S_WORDWIDTH_24BIT = 24, 71 I2S_WORDWIDTH_32BIT = 32, 72 }; 73 74 enum I2sMode { 75 I2S_MODE_HOST_TX_MODE, 76 I2S_MODE_HOST_RX_MODE, 77 I2S_MODE_STANDBY_TX_MODE, 78 I2S_MODE_STANDBY_RX_MODE, 79 }; 80 81 enum I2sLoopMode { 82 I2S_NORMAL_MODE, 83 I2S_LOOPBACK_MODE, 84 }; 85 86 enum I2sChannel { 87 I2S_CHANNEL_LOW_LEFT, 88 I2S_CHANNEL_LOW_RIGHT, 89 }; 90 91 enum I2sFrameLen { 92 I2S_FRAME_LEN_32BIT = 32, 93 I2S_FRAME_LEN_64BIT = 64, 94 }; 95 96 enum I2sProtocolType { 97 I2S_PROTOCOL_I2S_STD, 98 I2S_PROTOCOL_I2S_MSB, 99 I2S_PROTOCOL_I2S_LSB, 100 I2S_PROTOCOL_PCM_STD, 101 I2S_PROTOCOL_PCM_SHORT, 102 I2S_PROTOCOL_PCM_LONG, 103 }; 104 105 enum I2sPcmFscDelay { 106 I2S_PCM_START_1_CYCLE_BEFORE_MSB, /**< PCM FSC starts one cycle before MSB bit */ 107 I2S_PCM_START_SYNC_MSB, /**< PCM FSC starts at the same time as MSB bit */ 108 }; 109 110 enum I2sDataSel { 111 I2S_RISING_EDGE_TX, 112 I2S_RISING_EDGE_RX, 113 I2S_FALLING_EDGE_TX, 114 I2S_FALLING_EDGE_RX, 115 }; 116 117 enum I2sChannelMode { 118 I2S_CHANNEL_MODE_STEREO, 119 I2S_CHANNEL_MODE_MONO, 120 }; 121 122 enum I2sChannelIfMode { 123 I2S_CHANNEL_IF_MODE_I2S, 124 I2S_CHANNEL_IF_MODE_PCM, 125 }; 126 127 enum I2sWriteChannel { 128 I2S_WRITE_CHANNEL_AUDIO, 129 I2S_WRITE_CHANNEL_OUTPUT, 130 }; 131 132 enum I2slFsSel { 133 I2SL_FS_SEL_1024_FS, 134 I2SL_FS_SEL_512_FS, 135 I2SL_FS_SEL_320_FS, 136 I2SL_FS_SEL_256_FS, 137 I2SL_FS_SEL_128_FS, 138 I2SL_FS_SEL_64_FS, 139 }; 140 141 142 struct I2sCfg { 143 enum I2sSampleRate sampleRate; /**< I2S sample rate, 8k,16k,32k... */ 144 enum I2sWordWidth width; /**< I2S word width, 8bit,16bit,20bit,24bit... */ 145 enum I2sMode mode; /**< I2S mode, host/standby, tx/rx */ 146 enum I2sPcmFscDelay syncMode; /**< pcm mode, FSC starts location */ 147 enum I2sLoopMode loopMode; /**< is loopback */ 148 enum I2sProtocolType type; /**< I2S protocol type */ 149 enum I2sChannel channel; 150 enum I2sFrameLen frameLen; 151 enum I2sDataSel dataSel; 152 enum I2sChannelMode channelMode; /**< I2S mode,data channel */ 153 uint8_t samplePrecision; /**< bit */ 154 enum I2sChannelIfMode channelIfMode; 155 uint32_t mclk; /**< KHZ */ 156 uint32_t bclk; /**< KHZ */ 157 enum I2sWriteChannel writeChannel; 158 enum I2slFsSel i2slFsSel; 159 uint8_t Reserved[2]; 160 }; 161 162 /** 163 * @brief Defines the custom I2S transfer message. 164 * 165 * @since 1.0 166 */ 167 struct I2sMsg { 168 uint8_t *wbuf; /**< Address of the write buffer */ 169 uint8_t *rbuf; /**< Address of the read buffer */ 170 uint32_t len; /**< Length of the read and write buffers. The read buffer and the write 171 * buffer have the same length. */ 172 uint32_t *pRlen; 173 }; 174 175 176 /** 177 * @brief Obtains the handle of an I2S controller. 178 * 179 * You must call this function before accessing the I2S bus. 180 * 181 * @param number Indicates the I2S controller ID. 182 * 183 * @return Returns the pointer to the {@link DevHandle} of the I2S controller if the operation is successful; 184 * returns <b>NULL</b> otherwise. 185 * @since 1.0 186 */ 187 DevHandle I2sOpen(int16_t number); 188 189 /** 190 * @brief Releases the handle of an I2S controller. 191 * 192 * If you no longer need to access the I2S controller, you should call this function to close its handle so as 193 * to release unused memory resources. 194 * 195 * @param handle Indicates the pointer to the device handle of the I2S controller. 196 * 197 * @since 1.0 198 */ 199 void I2sClose(DevHandle handle); 200 void I2sEnable(DevHandle handle); 201 void I2sDisable(DevHandle handle); 202 int32_t I2sWrite(DevHandle handle, uint8_t *buf, uint32_t len, uint32_t *pWlen); 203 int32_t I2sRead(DevHandle handle, uint8_t *buf, uint32_t len, uint32_t *pRlen); 204 void I2sStartWrite(DevHandle handle); 205 void I2sStopWrite(DevHandle handle); 206 void I2sStartRead(DevHandle handle); 207 void I2sStopRead(DevHandle handle); 208 void I2sSetCfg(DevHandle handle, struct I2sCfg *cfg); 209 void I2sGetCfg(DevHandle handle, struct I2sCfg *cfg); 210 211 #ifdef __cplusplus 212 #if __cplusplus 213 } 214 #endif 215 #endif /* __cplusplus */ 216 217 #endif /* I2S_IF_H */ 218 /** @} */ 219