Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_i2s.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_I2S_H__
6 #define __QM_I2S_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #include "qm_dma.h"
11 
12 /**
13  * I2S.
14  *
15  * @defgroup groupI2S I2S
16  * @{
17  */
18 
19 /**
20  * I2S master/slave configuration.
21  */
22 typedef enum {
23  QM_I2S_MASTER = 0, /**< Master configuration selection */
24  QM_I2S_SLAVE /**< Slave configuration selection */
26 
27 /**
28  * I2S Audio stream identifiers.
29  */
30 typedef enum {
31  QM_I2S_AUDIO_STREAM_TRANSMIT = 0, /**< Playback audio stream */
32  QM_I2S_AUDIO_STREAM_RECEIVE /**< Capture audio stream */
34 
35 /**
36  * I2S audio formats.
37  */
38 typedef enum {
39  QM_I2S_AUDIO_FORMAT_I2S_MODE = 0, /**< I2S Mode audio format */
40  QM_I2S_AUDIO_FORMAT_RIGHT_J, /**< Right justified audio format */
41  QM_I2S_AUDIO_FORMAT_LEFT_J, /**< Left justified audio format */
42  QM_I2S_AUDIO_FORMAT_DSP_MODE /**< DSP mode audio format */
44 
45 /**
46  * I2S Audio sample resolution. Resolution ranges between 12 bits and 32 bits.
47  */
48 typedef enum {
49  /** 12 bits audio sample resolution */
51  /** 13 bits audio sample resolution */
53  /** 14 bits audio sample resolution */
55  /** 15 bits audio sample resolution */
57  /** 16 bits audio sample resolution */
59  /** 17 bits audio sample resolution */
61  /** 18 bits audio sample resolution */
63  /** 19 bits audio sample resolution */
65  /** 20 bits audio sample resolution */
67  /** 21 bits audio sample resolution */
69  /** 22 bits audio sample resolution */
71  /** 23 bits audio sample resolution */
73  /** 24 bits audio sample resolution */
75  /** 25 bits audio sample resolution */
77  /** 26 bits audio sample resolution */
79  /** 27 bits audio sample resolution */
81  /** 28 bits audio sample resolution */
83  /** 29 bits audio sample resolution */
85  /** 30 bits audio sample resolution */
87  /** 31 bits audio sample resolution */
89  /** 32 bits audio sample resolution */
92 
93 /**
94  * I2S Audio rates available.
95  */
96 typedef enum {
97  QM_I2S_RATE_4000KHZ = 0, /**< 4kHz audio rate */
98  QM_I2S_RATE_8000KHZ, /**< 8kHz audio rate */
99  QM_I2S_RATE_11025KHZ, /**< 11.025kHz audio rate */
100  QM_I2S_RATE_16000KHZ, /**< 16kHz audio rate */
101  QM_I2S_RATE_22050KHZ, /**< 22.05kHz audio rate */
102  QM_I2S_RATE_32000KHZ, /**< 32kHz audio rate */
103  QM_I2S_RATE_44100KHZ, /**< 44.1kHz audio rate */
104  QM_I2S_RATE_48000KHZ, /**< 48kHz audio rate */
106 
107 /**
108  * I2S Audio buffer termination.
109  */
110 typedef enum {
111  /** Used for single audio playback/recording. */
113  QM_I2S_RING_BUFFER /**< Used for continuous audio playback/recording. */
115 
116 /**
117  * I2S Reference Clock Source Select
118  */
119 typedef enum {
120  QM_I2S_INT_CLK = 0, /**< Use internal clock. */
121  QM_I2S_MCLK, /**< Take in clock from external source. */
123 
124 /**
125  * I2S status type.
126  */
127 typedef enum {
128  /** Indicates that a FIFO overflow error was detected. */
130  /** Indicates that a FIFO underrun error was detected. */
132  /** Indicates TX FIFO full interrupt occurred */
134  /** Indicates TX FIFO almost full interrupt occurred */
136  /** Indicates TX FIFO almost empty interrupt occurred */
138  /** Indicates TX FIFO empty interrupt occurred */
140  /** Indicates RX FIFO full interrupt occurred */
142  /** Indicates RX FIFO almost full interrupt occurred */
144  /** Indicates RX FIFO almost empty interrupt occurred */
146  /** Indicates RX FIFO empty interrupt occurred */
148  /** Indicates that a DMA error was detected */
149  QM_I2S_DMA_ERROR = BIT(10),
150  /** Indicates that DMA operation was completed */
153 
154 /**
155  * Ring buffer link definition.
156  */
157 typedef struct qm_i2s_buffer_link {
158  uint32_t *buff; /**< Pointer to the buffer base address. */
159  /** Pointer to the head of the DMA link list for the buffer link. */
160  qm_dma_lli_item_t *dma_link_head;
161  /** Link list item's pointer to the next link. */
164 
165 /**
166  * I2S controller configuration.
167  * Driver instantiates one of these with given parameters for each I2S
168  * channel configured using the "qm_i2s_set_channel_config" function.
169  */
170 typedef struct {
171  qm_dma_channel_id_t dma_channel; /**< DMA controller Channel ID */
172  qm_i2s_audio_stream_t audio_stream; /**< I2S audio stream identifier */
173  /** I2S audio format configuration */
175  /** I2S Master or Slave configuration */
177  /** Sampling resolution */
179  qm_i2s_audio_rate_t audio_rate; /**< Audio rate */
180  /** Terminated link list or ring buffer configuration */
182  /**
183  * DMA block size configuration:
184  * The source and destination transfer width is 32-bits for I2S.
185  * Min = 1, Max = see DMA configuration
186  */
187  uint32_t block_size;
188  uint32_t num_dma_links; /**< Total number of DMA links. */
189  qm_dma_lli_item_t *dma_link; /**< Pointer to the DMA link list */
190  /** Number of buffer links in the ring buffer. */
192  qm_i2s_buffer_link_t *buffer_link; /**< Ring buffer head pointer. */
193  /** Number of DMA links per audio buffer. */
195  uint32_t buffer_len; /**< Length of a buffer in the ring buffer. */
196  uint32_t afull_thresh; /**< TX/RX almost full threshold. */
197  uint32_t aempty_thresh; /**< TX/RX almost empty threshold. */
198 
199  /**
200  * Transfer callback.
201  *
202  * @param[in] data Callback user data
203  * @param[in] i2s_status I2S status
204  */
205  void (*callback)(void *data, qm_i2s_status_t i2s_status);
206  void *callback_data; /**< Callback user data. */
208 
209 /**
210  * I2S Clock Configuration
211  */
212 typedef struct {
213  /** Select Internal NCO or external reference clock for I2S block */
215  /**
216  * Used by the driver when configuring I2S reference clock from
217  * the NCO.
218  */
219  uint32_t i2s_clk_freq;
220  /** Enable MCLK output. */
222  /**
223  * MCLK output is generated from the Internal
224  * NCO output, normally \@24.576Mhz, using a divisor.
225  * Valid divisor range is 0 to 4095.
226  * E.g. with a 48kHz data rate, and NCO =
227  * 24.576Mhz, then required MCLK = 256 * data rate = 12.288MHz
228  * MCLK divisor = 2 (24.576Mhz/2 = 12.288MHz)
229  */
231  /**
232  * Informs the driver of frequency of external clock
233  * when it is enabled.
234  */
237 
238 /**
239  * Function to configure specified I2S controller stream
240  * Configuration parameters must be valid or an error is returned - see return
241  * values below.
242  *
243  * @param [in] i2s I2S controller identifier
244  * @param [in] audio_stream I2S audio_stream identifier
245  * @param [in] config Pointer to configuration structure
246  *
247  * @return Standard errno return type for QMSI.
248  * @retval 0 on success.
249  * @retval Negative @ref errno for possible error codes.
250  */
251 int qm_i2s_dma_channel_config(const qm_i2s_t i2s,
252  const qm_i2s_audio_stream_t audio_stream,
253  const qm_i2s_channel_cfg_data_t *const config);
254 
255 /**
256  * Function to place I2S controller into a disabled state.
257  * This function assumes that there is no pending transaction on the I2S
258  * interface in question.
259  * It is the responsibility of the calling application to do so.
260  *
261  * @param [in] i2s I2S controller identifier
262  * @param [in] audio_stream I2S audio_stream identifier
263  *
264  * @return Standard errno return type for QMSI.
265  * @retval 0 on success.
266  * @retval Negative @ref errno for possible error codes.
267  */
268 int qm_i2s_channel_disable(const qm_i2s_t i2s,
269  const qm_i2s_audio_stream_t audio_stream);
270 
271 /**
272  * Function to configure and enable I2S clocks
273  * Configuration parameters must be valid or an error is returned - see return
274  * values below.
275  *
276  * @param [in] i2s I2S controller identifier
277  * @param [in] i2s_clk_cfg I2S Clock configuration
278  *
279  * @return Standard errno return type for QMSI.
280  * @retval 0 on success.
281  * @retval Negative @ref errno for possible error codes.
282  */
283 int qm_i2s_set_clock_config(const qm_i2s_t i2s,
284  const qm_i2s_clock_cfg_data_t *const i2s_clk_cfg);
285 
286 /**
287  * Function to transmit a block of data to the specified I2S channel.
288  *
289  * @param [in] i2s I2S controller identifier
290  * @param [in] audio_stream I2S audio_stream identifier
291  *
292  * @return Standard errno return type for QMSI.
293  * @retval 0 on success.
294  * @retval Negative @ref errno for possible error codes.
295  */
296 int qm_i2s_dma_transfer(const qm_i2s_t i2s,
297  const qm_i2s_audio_stream_t audio_stream);
298 
299 /**
300  * Terminate the current DMA transfer on the given I2S peripheral channel.
301  *
302  * Terminate the current DMA transfer on the I2S channel.
303  * This will cause the relevant callbacks to be invoked.
304  *
305  * In the case the user is doing a continuous transfer using a circular linked
306  * list, it might be useful to fine control at which point in the linked list
307  * that we stop the transfer. To do this, set the relevant linked list item's
308  * "next" item to NULL.
309  *
310  * @param [in] i2s I2S controller identifier
311  * @param [in] config Pointer to configuration structure
312  *
313  * @return Standard errno return type for QMSI.
314  * @retval 0 on success.
315  * @retval Negative @ref errno for possible error codes.
316  */
317 int qm_i2s_dma_transfer_terminate(const qm_i2s_t i2s,
318  qm_i2s_channel_cfg_data_t *const config);
319 
320 /**
321  * @}
322  */
323 
324 #endif /* __QM_I2S_H__ */
48kHz audio rate
Definition: qm_i2s.h:104
Indicates that a FIFO underrun error was detected.
Definition: qm_i2s.h:131
Indicates that a FIFO overflow error was detected.
Definition: qm_i2s.h:129
13 bits audio sample resolution
Definition: qm_i2s.h:52
qm_i2s_clk_src_t
I2S Reference Clock Source Select.
Definition: qm_i2s.h:119
18 bits audio sample resolution
Definition: qm_i2s.h:62
17 bits audio sample resolution
Definition: qm_i2s.h:60
Master configuration selection.
Definition: qm_i2s.h:23
8kHz audio rate
Definition: qm_i2s.h:98
uint32_t num_buffer_links
Number of buffer links in the ring buffer.
Definition: qm_i2s.h:191
Indicates TX FIFO almost full interrupt occurred.
Definition: qm_i2s.h:135
26 bits audio sample resolution
Definition: qm_i2s.h:78
22.05kHz audio rate
Definition: qm_i2s.h:101
qm_i2s_audio_format_t
I2S audio formats.
Definition: qm_i2s.h:38
Indicates that a DMA error was detected.
Definition: qm_i2s.h:149
21 bits audio sample resolution
Definition: qm_i2s.h:68
24 bits audio sample resolution
Definition: qm_i2s.h:74
qm_i2s_sample_resolution_t
I2S Audio sample resolution.
Definition: qm_i2s.h:48
I2S Mode audio format.
Definition: qm_i2s.h:39
DSP mode audio format.
Definition: qm_i2s.h:42
16 bits audio sample resolution
Definition: qm_i2s.h:58
uint32_t i2s_clk_freq
Used by the driver when configuring I2S reference clock from the NCO.
Definition: qm_i2s.h:219
Indicates RX FIFO empty interrupt occurred.
Definition: qm_i2s.h:147
27 bits audio sample resolution
Definition: qm_i2s.h:80
Indicates RX FIFO almost empty interrupt occurred.
Definition: qm_i2s.h:145
uint32_t i2s_mclk_divisor
MCLK output is generated from the Internal NCO output, normally @24.576Mhz, using a divisor...
Definition: qm_i2s.h:230
14 bits audio sample resolution
Definition: qm_i2s.h:54
Indicates that DMA operation was completed.
Definition: qm_i2s.h:151
uint32_t num_dma_links
Total number of DMA links.
Definition: qm_i2s.h:188
32 bits audio sample resolution
Definition: qm_i2s.h:90
Indicates TX FIFO empty interrupt occurred.
Definition: qm_i2s.h:139
I2S controller configuration.
Definition: qm_i2s.h:170
qm_i2s_audio_stream_t audio_stream
I2S audio stream identifier.
Definition: qm_i2s.h:172
Indicates TX FIFO full interrupt occurred.
Definition: qm_i2s.h:133
qm_i2s_master_slave_t
I2S master/slave configuration.
Definition: qm_i2s.h:22
Used for single audio playback/recording.
Definition: qm_i2s.h:112
qm_i2s_status_t
I2S status type.
Definition: qm_i2s.h:127
int qm_i2s_dma_transfer_terminate(const qm_i2s_t i2s, qm_i2s_channel_cfg_data_t *const config)
Terminate the current DMA transfer on the given I2S peripheral channel.
uint32_t afull_thresh
TX/RX almost full threshold.
Definition: qm_i2s.h:196
int qm_i2s_set_clock_config(const qm_i2s_t i2s, const qm_i2s_clock_cfg_data_t *const i2s_clk_cfg)
Function to configure and enable I2S clocks Configuration parameters must be valid or an error is ret...
Left justified audio format.
Definition: qm_i2s.h:41
I2S Clock Configuration.
Definition: qm_i2s.h:212
qm_i2s_audio_format_t audio_format
I2S audio format configuration.
Definition: qm_i2s.h:174
31 bits audio sample resolution
Definition: qm_i2s.h:88
qm_dma_channel_id_t dma_channel
DMA controller Channel ID.
Definition: qm_i2s.h:171
Slave configuration selection.
Definition: qm_i2s.h:24
28 bits audio sample resolution
Definition: qm_i2s.h:82
uint32_t buffer_len
Length of a buffer in the ring buffer.
Definition: qm_i2s.h:195
int qm_i2s_dma_channel_config(const qm_i2s_t i2s, const qm_i2s_audio_stream_t audio_stream, const qm_i2s_channel_cfg_data_t *const config)
Function to configure specified I2S controller stream Configuration parameters must be valid or an er...
int qm_i2s_channel_disable(const qm_i2s_t i2s, const qm_i2s_audio_stream_t audio_stream)
Function to place I2S controller into a disabled state.
4kHz audio rate
Definition: qm_i2s.h:97
19 bits audio sample resolution
Definition: qm_i2s.h:64
qm_i2s_buffer_mode_t
I2S Audio buffer termination.
Definition: qm_i2s.h:110
25 bits audio sample resolution
Definition: qm_i2s.h:76
uint32_t aempty_thresh
TX/RX almost empty threshold.
Definition: qm_i2s.h:197
22 bits audio sample resolution
Definition: qm_i2s.h:70
qm_i2s_buffer_link_t * buffer_link
Ring buffer head pointer.
Definition: qm_i2s.h:192
bool i2s_mclk_output_en
Enable MCLK output.
Definition: qm_i2s.h:221
qm_dma_lli_item_t * dma_link
Pointer to the DMA link list.
Definition: qm_i2s.h:189
qm_i2s_audio_stream_t
I2S Audio stream identifiers.
Definition: qm_i2s.h:30
qm_i2s_buffer_mode_t audio_buff_cfg
Terminated link list or ring buffer configuration.
Definition: qm_i2s.h:181
12 bits audio sample resolution
Definition: qm_i2s.h:50
32kHz audio rate
Definition: qm_i2s.h:102
Playback audio stream.
Definition: qm_i2s.h:31
uint32_t i2s_ext_clk_freq
Informs the driver of frequency of external clock when it is enabled.
Definition: qm_i2s.h:235
44.1kHz audio rate
Definition: qm_i2s.h:103
Indicates RX FIFO almost full interrupt occurred.
Definition: qm_i2s.h:143
Use internal clock.
Definition: qm_i2s.h:120
qm_i2s_sample_resolution_t sample_resolution
Sampling resolution.
Definition: qm_i2s.h:178
uint32_t num_dma_link_per_buffer
Number of DMA links per audio buffer.
Definition: qm_i2s.h:194
15 bits audio sample resolution
Definition: qm_i2s.h:56
Right justified audio format.
Definition: qm_i2s.h:40
30 bits audio sample resolution
Definition: qm_i2s.h:86
20 bits audio sample resolution
Definition: qm_i2s.h:66
qm_i2s_clk_src_t i2s_clock_sel
Select Internal NCO or external reference clock for I2S block.
Definition: qm_i2s.h:214
struct qm_i2s_buffer_link qm_i2s_buffer_link_t
Ring buffer link definition.
Indicates TX FIFO almost empty interrupt occurred.
Definition: qm_i2s.h:137
Capture audio stream.
Definition: qm_i2s.h:32
qm_dma_channel_id_t
DMA channel IDs.
Definition: qm_soc_regs.h:1486
Indicates RX FIFO full interrupt occurred.
Definition: qm_i2s.h:141
qm_i2s_master_slave_t master_slave
I2S Master or Slave configuration.
Definition: qm_i2s.h:176
11.025kHz audio rate
Definition: qm_i2s.h:99
16kHz audio rate
Definition: qm_i2s.h:100
qm_i2s_audio_rate_t
I2S Audio rates available.
Definition: qm_i2s.h:96
int qm_i2s_dma_transfer(const qm_i2s_t i2s, const qm_i2s_audio_stream_t audio_stream)
Function to transmit a block of data to the specified I2S channel.
Used for continuous audio playback/recording.
Definition: qm_i2s.h:113
23 bits audio sample resolution
Definition: qm_i2s.h:72
void * callback_data
Callback user data.
Definition: qm_i2s.h:206
Take in clock from external source.
Definition: qm_i2s.h:121
uint32_t block_size
DMA block size configuration: The source and destination transfer width is 32-bits for I2S...
Definition: qm_i2s.h:187
29 bits audio sample resolution
Definition: qm_i2s.h:84
qm_i2s_audio_rate_t audio_rate
Audio rate.
Definition: qm_i2s.h:179