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