1 /*
2 * Copyright (c) 2017 Piotr Mienkowski
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public APIs for the I2S (Inter-IC Sound) bus drivers.
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_I2S_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_I2S_H_
14
15 /**
16 * @defgroup i2s_interface I2S Interface
17 * @since 1.9
18 * @version 1.0.0
19 * @ingroup io_interfaces
20 * @brief I2S (Inter-IC Sound) Interface
21 *
22 * The I2S API provides support for the standard I2S interface standard as well
23 * as common non-standard extensions such as PCM Short/Long Frame Sync,
24 * Left/Right Justified Data Format.
25 * @{
26 */
27
28 #include <zephyr/types.h>
29 #include <zephyr/device.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /*
36 * The following #defines are used to configure the I2S controller.
37 */
38
39 /** I2S data stream format options */
40 typedef uint8_t i2s_fmt_t;
41
42 /** Data Format bit field position. */
43 #define I2S_FMT_DATA_FORMAT_SHIFT 0
44 /** Data Format bit field mask. */
45 #define I2S_FMT_DATA_FORMAT_MASK (0x7 << I2S_FMT_DATA_FORMAT_SHIFT)
46
47 /** @brief Standard I2S Data Format.
48 *
49 * Serial data is transmitted in two's complement with the MSB first. Both
50 * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
51 * of the clock signal (SCK). The MSB is always sent one clock period after the
52 * WS changes. Left channel data are sent first indicated by WS = 0, followed
53 * by right channel data indicated by WS = 1.
54 *
55 * -. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
56 * SCK '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '
57 * -. .-------------------------------.
58 * WS '-------------------------------' '----
59 * -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.
60 * SD | |MSB| |...| |LSB| x |...| x |MSB| |...| |LSB| x |...| x |
61 * -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'
62 * | Left channel | Right channel |
63 */
64 #define I2S_FMT_DATA_FORMAT_I2S (0 << I2S_FMT_DATA_FORMAT_SHIFT)
65
66 /** @brief PCM Short Frame Sync Data Format.
67 *
68 * Serial data is transmitted in two's complement with the MSB first. Both
69 * Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge
70 * of the clock signal (SCK). The falling edge of the frame sync signal (WS)
71 * indicates the start of the PCM word. The frame sync is one clock cycle long.
72 * An arbitrary number of data words can be sent in one frame.
73 *
74 * .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
75 * SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
76 * .---. .---.
77 * WS -' '- -' '-
78 * -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
79 * SD | |MSB| |...| |LSB|MSB| |...| |LSB|MSB| |...| |LSB|
80 * -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
81 * | Word 1 | Word 2 | Word 3 | Word n |
82 */
83 #define I2S_FMT_DATA_FORMAT_PCM_SHORT (1 << I2S_FMT_DATA_FORMAT_SHIFT)
84
85 /** @brief PCM Long Frame Sync Data Format.
86 *
87 * Serial data is transmitted in two's complement with the MSB first. Both
88 * Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge
89 * of the clock signal (SCK). The rising edge of the frame sync signal (WS)
90 * indicates the start of the PCM word. The frame sync has an arbitrary length,
91 * however it has to fall before the start of the next frame. An arbitrary
92 * number of data words can be sent in one frame.
93 *
94 * .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
95 * SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
96 * .--- ---. ---. ---. .---
97 * WS -' '- '- '- -'
98 * -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
99 * SD | |MSB| |...| |LSB|MSB| |...| |LSB|MSB| |...| |LSB|
100 * -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
101 * | Word 1 | Word 2 | Word 3 | Word n |
102 */
103 #define I2S_FMT_DATA_FORMAT_PCM_LONG (2 << I2S_FMT_DATA_FORMAT_SHIFT)
104
105 /**
106 * @brief Left Justified Data Format.
107 *
108 * Serial data is transmitted in two's complement with the MSB first. Both
109 * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
110 * of the clock signal (SCK). The bits within the data word are left justified
111 * such that the MSB is always sent in the clock period following the WS
112 * transition. Left channel data are sent first indicated by WS = 1, followed
113 * by right channel data indicated by WS = 0.
114 *
115 * .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
116 * SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
117 * .-------------------------------. .-
118 * WS ---' '-------------------------------'
119 * ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
120 * SD |MSB| |...| |LSB| x |...| x |MSB| |...| |LSB| x |...| x |
121 * ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
122 * | Left channel | Right channel |
123 */
124 #define I2S_FMT_DATA_FORMAT_LEFT_JUSTIFIED (3 << I2S_FMT_DATA_FORMAT_SHIFT)
125
126 /**
127 * @brief Right Justified Data Format.
128 *
129 * Serial data is transmitted in two's complement with the MSB first. Both
130 * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
131 * of the clock signal (SCK). The bits within the data word are right justified
132 * such that the LSB is always sent in the clock period preceding the WS
133 * transition. Left channel data are sent first indicated by WS = 1, followed
134 * by right channel data indicated by WS = 0.
135 *
136 * .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
137 * SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
138 * .-------------------------------. .-
139 * WS ---' '-------------------------------'
140 * ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
141 * SD | x |...| x |MSB| |...| |LSB| x |...| x |MSB| |...| |LSB|
142 * ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
143 * | Left channel | Right channel |
144 */
145 #define I2S_FMT_DATA_FORMAT_RIGHT_JUSTIFIED (4 << I2S_FMT_DATA_FORMAT_SHIFT)
146
147 /** Send MSB first */
148 #define I2S_FMT_DATA_ORDER_MSB (0 << 3)
149 /** Send LSB first */
150 #define I2S_FMT_DATA_ORDER_LSB BIT(3)
151 /** Invert bit ordering, send LSB first */
152 #define I2S_FMT_DATA_ORDER_INV I2S_FMT_DATA_ORDER_LSB
153
154 /** Data Format bit field position. */
155 #define I2S_FMT_CLK_FORMAT_SHIFT 4
156 /** Data Format bit field mask. */
157 #define I2S_FMT_CLK_FORMAT_MASK (0x3 << I2S_FMT_CLK_FORMAT_SHIFT)
158
159 /** Invert bit clock */
160 #define I2S_FMT_BIT_CLK_INV BIT(4)
161 /** Invert frame clock */
162 #define I2S_FMT_FRAME_CLK_INV BIT(5)
163
164 /** Normal Frame, Normal Bit Clk */
165 #define I2S_FMT_CLK_NF_NB (0 << I2S_FMT_CLK_FORMAT_SHIFT)
166 /** Normal Frame, Inverted Bit Clk */
167 #define I2S_FMT_CLK_NF_IB (1 << I2S_FMT_CLK_FORMAT_SHIFT)
168 /** Inverted Frame, Normal Bit Clk */
169 #define I2S_FMT_CLK_IF_NB (2 << I2S_FMT_CLK_FORMAT_SHIFT)
170 /** Inverted Frame, Inverted Bit Clk */
171 #define I2S_FMT_CLK_IF_IB (3 << I2S_FMT_CLK_FORMAT_SHIFT)
172
173 /** I2S configuration options */
174 typedef uint8_t i2s_opt_t;
175
176 /** Run bit clock continuously */
177 #define I2S_OPT_BIT_CLK_CONT (0 << 0)
178 /** Run bit clock when sending data only */
179 #define I2S_OPT_BIT_CLK_GATED BIT(0)
180 /** I2S driver is bit clock master */
181 #define I2S_OPT_BIT_CLK_MASTER (0 << 1)
182 /** I2S driver is bit clock slave */
183 #define I2S_OPT_BIT_CLK_SLAVE BIT(1)
184 /** I2S driver is frame clock master */
185 #define I2S_OPT_FRAME_CLK_MASTER (0 << 2)
186 /** I2S driver is frame clock slave */
187 #define I2S_OPT_FRAME_CLK_SLAVE BIT(2)
188
189 /** @brief Loop back mode.
190 *
191 * In loop back mode RX input will be connected internally to TX output.
192 * This is used primarily for testing.
193 */
194 #define I2S_OPT_LOOPBACK BIT(7)
195
196 /** @brief Ping pong mode
197 *
198 * In ping pong mode TX output will keep alternating between a ping buffer
199 * and a pong buffer. This is normally used in audio streams when one buffer
200 * is being populated while the other is being played (DMAed) and vice versa.
201 * So, in this mode, 2 sets of buffers fixed in size are used. Static Arrays
202 * are used to achieve this and hence they are never freed.
203 */
204 #define I2S_OPT_PINGPONG BIT(6)
205
206 /**
207 * @brief I2C Direction
208 */
209 enum i2s_dir {
210 /** Receive data */
211 I2S_DIR_RX,
212 /** Transmit data */
213 I2S_DIR_TX,
214 /** Both receive and transmit data */
215 I2S_DIR_BOTH,
216 };
217
218 /** Interface state */
219 enum i2s_state {
220 /** @brief The interface is not ready.
221 *
222 * The interface was initialized but is not yet ready to receive /
223 * transmit data. Call i2s_configure() to configure interface and change
224 * its state to READY.
225 */
226 I2S_STATE_NOT_READY,
227 /** The interface is ready to receive / transmit data. */
228 I2S_STATE_READY,
229 /** The interface is receiving / transmitting data. */
230 I2S_STATE_RUNNING,
231 /** The interface is draining its transmit queue. */
232 I2S_STATE_STOPPING,
233 /** TX buffer underrun or RX buffer overrun has occurred. */
234 I2S_STATE_ERROR,
235 };
236
237 /** Trigger command */
238 enum i2s_trigger_cmd {
239 /** @brief Start the transmission / reception of data.
240 *
241 * If I2S_DIR_TX is set some data has to be queued for transmission by
242 * the i2s_write() function. This trigger can be used in READY state
243 * only and changes the interface state to RUNNING.
244 */
245 I2S_TRIGGER_START,
246 /** @brief Stop the transmission / reception of data.
247 *
248 * Stop the transmission / reception of data at the end of the current
249 * memory block. This trigger can be used in RUNNING state only and at
250 * first changes the interface state to STOPPING. When the current TX /
251 * RX block is transmitted / received the state is changed to READY.
252 * Subsequent START trigger will resume transmission / reception where
253 * it stopped.
254 */
255 I2S_TRIGGER_STOP,
256 /** @brief Empty the transmit queue.
257 *
258 * Send all data in the transmit queue and stop the transmission.
259 * If the trigger is applied to the RX queue it has the same effect as
260 * I2S_TRIGGER_STOP. This trigger can be used in RUNNING state only and
261 * at first changes the interface state to STOPPING. When all TX blocks
262 * are transmitted the state is changed to READY.
263 */
264 I2S_TRIGGER_DRAIN,
265 /** @brief Discard the transmit / receive queue.
266 *
267 * Stop the transmission / reception immediately and discard the
268 * contents of the respective queue. This trigger can be used in any
269 * state other than NOT_READY and changes the interface state to READY.
270 */
271 I2S_TRIGGER_DROP,
272 /** @brief Prepare the queues after underrun/overrun error has occurred.
273 *
274 * This trigger can be used in ERROR state only and changes the
275 * interface state to READY.
276 */
277 I2S_TRIGGER_PREPARE,
278 };
279
280 /** @struct i2s_config
281 * @brief Interface configuration options.
282 *
283 * Memory slab pointed to by the mem_slab field has to be defined and
284 * initialized by the user. For I2S driver to function correctly number of
285 * memory blocks in a slab has to be at least 2 per queue. Size of the memory
286 * block should be multiple of frame_size where frame_size = (channels *
287 * word_size_bytes). As an example 16 bit word will occupy 2 bytes, 24 or 32
288 * bit word will occupy 4 bytes.
289 *
290 * Please check Zephyr Kernel Primer for more information on memory slabs.
291 *
292 * @remark When I2S data format is selected parameter channels is ignored,
293 * number of words in a frame is always 2.
294 */
295 struct i2s_config {
296 /** Number of bits representing one data word. */
297 uint8_t word_size;
298 /** Number of words per frame. */
299 uint8_t channels;
300 /** Data stream format as defined by I2S_FMT_* constants. */
301 i2s_fmt_t format;
302 /** Configuration options as defined by I2S_OPT_* constants. */
303 i2s_opt_t options;
304 /** Frame clock (WS) frequency, this is sampling rate. */
305 uint32_t frame_clk_freq;
306 /** Memory slab to store RX/TX data. */
307 struct k_mem_slab *mem_slab;
308 /** Size of one RX/TX memory block (buffer) in bytes. */
309 size_t block_size;
310 /** Read/Write timeout. Number of milliseconds to wait in case TX queue
311 * is full or RX queue is empty, or 0, or SYS_FOREVER_MS.
312 */
313 int32_t timeout;
314 };
315
316 /**
317 * @cond INTERNAL_HIDDEN
318 *
319 * For internal use only, skip these in public documentation.
320 */
321 __subsystem struct i2s_driver_api {
322 int (*configure)(const struct device *dev, enum i2s_dir dir,
323 const struct i2s_config *cfg);
324 const struct i2s_config *(*config_get)(const struct device *dev,
325 enum i2s_dir dir);
326 int (*read)(const struct device *dev, void **mem_block, size_t *size);
327 int (*write)(const struct device *dev, void *mem_block, size_t size);
328 int (*trigger)(const struct device *dev, enum i2s_dir dir,
329 enum i2s_trigger_cmd cmd);
330 };
331 /**
332 * @endcond
333 */
334
335 /**
336 * @brief Configure operation of a host I2S controller.
337 *
338 * The dir parameter specifies if Transmit (TX) or Receive (RX) direction
339 * will be configured by data provided via cfg parameter.
340 *
341 * The function can be called in NOT_READY or READY state only. If executed
342 * successfully the function will change the interface state to READY.
343 *
344 * If the function is called with the parameter cfg->frame_clk_freq set to 0
345 * the interface state will be changed to NOT_READY.
346 *
347 * @param dev Pointer to the device structure for the driver instance.
348 * @param dir Stream direction: RX, TX, or both, as defined by I2S_DIR_*.
349 * The I2S_DIR_BOTH value may not be supported by some drivers.
350 * For those, the RX and TX streams need to be configured separately.
351 * @param cfg Pointer to the structure containing configuration parameters.
352 *
353 * @retval 0 If successful.
354 * @retval -EINVAL Invalid argument.
355 * @retval -ENOSYS I2S_DIR_BOTH value is not supported.
356 */
357 __syscall int i2s_configure(const struct device *dev, enum i2s_dir dir,
358 const struct i2s_config *cfg);
359
z_impl_i2s_configure(const struct device * dev,enum i2s_dir dir,const struct i2s_config * cfg)360 static inline int z_impl_i2s_configure(const struct device *dev,
361 enum i2s_dir dir,
362 const struct i2s_config *cfg)
363 {
364 const struct i2s_driver_api *api =
365 (const struct i2s_driver_api *)dev->api;
366
367 return api->configure(dev, dir, cfg);
368 }
369
370 /**
371 * @brief Fetch configuration information of a host I2S controller
372 *
373 * @param dev Pointer to the device structure for the driver instance
374 * @param dir Stream direction: RX or TX as defined by I2S_DIR_*
375 * @retval Pointer to the structure containing configuration parameters,
376 * or NULL if un-configured
377 */
i2s_config_get(const struct device * dev,enum i2s_dir dir)378 static inline const struct i2s_config *i2s_config_get(const struct device *dev,
379 enum i2s_dir dir)
380 {
381 const struct i2s_driver_api *api =
382 (const struct i2s_driver_api *)dev->api;
383
384 return api->config_get(dev, dir);
385 }
386
387 /**
388 * @brief Read data from the RX queue.
389 *
390 * Data received by the I2S interface is stored in the RX queue consisting of
391 * memory blocks preallocated by this function from rx_mem_slab (as defined by
392 * i2s_configure). Ownership of the RX memory block is passed on to the user
393 * application which has to release it.
394 *
395 * The data is read in chunks equal to the size of the memory block. If the
396 * interface is in READY state the number of bytes read can be smaller.
397 *
398 * If there is no data in the RX queue the function will block waiting for
399 * the next RX memory block to fill in. This operation can timeout as defined
400 * by i2s_configure. If the timeout value is set to K_NO_WAIT the function
401 * is non-blocking.
402 *
403 * Reading from the RX queue is possible in any state other than NOT_READY.
404 * If the interface is in the ERROR state it is still possible to read all the
405 * valid data stored in RX queue. Afterwards the function will return -EIO
406 * error.
407 *
408 * @param dev Pointer to the device structure for the driver instance.
409 * @param mem_block Pointer to the RX memory block containing received data.
410 * @param size Pointer to the variable storing the number of bytes read.
411 *
412 * @retval 0 If successful.
413 * @retval -EIO The interface is in NOT_READY or ERROR state and there are no
414 * more data blocks in the RX queue.
415 * @retval -EBUSY Returned without waiting.
416 * @retval -EAGAIN Waiting period timed out.
417 */
i2s_read(const struct device * dev,void ** mem_block,size_t * size)418 static inline int i2s_read(const struct device *dev, void **mem_block,
419 size_t *size)
420 {
421 const struct i2s_driver_api *api =
422 (const struct i2s_driver_api *)dev->api;
423
424 return api->read(dev, mem_block, size);
425 }
426
427 /**
428 * @brief Read data from the RX queue into a provided buffer
429 *
430 * Data received by the I2S interface is stored in the RX queue consisting of
431 * memory blocks preallocated by this function from rx_mem_slab (as defined by
432 * i2s_configure). Calling this function removes one block from the queue
433 * which is copied into the provided buffer and then freed.
434 *
435 * The provided buffer must be large enough to contain a full memory block
436 * of data, which is parameterized for the channel via i2s_configure().
437 *
438 * This function is otherwise equivalent to i2s_read().
439 *
440 * @param dev Pointer to the device structure for the driver instance.
441 * @param buf Destination buffer for read data, which must be at least the
442 * as large as the configured memory block size for the RX channel.
443 * @param size Pointer to the variable storing the number of bytes read.
444 *
445 * @retval 0 If successful.
446 * @retval -EIO The interface is in NOT_READY or ERROR state and there are no
447 * more data blocks in the RX queue.
448 * @retval -EBUSY Returned without waiting.
449 * @retval -EAGAIN Waiting period timed out.
450 */
451 __syscall int i2s_buf_read(const struct device *dev, void *buf, size_t *size);
452
453 /**
454 * @brief Write data to the TX queue.
455 *
456 * Data to be sent by the I2S interface is stored first in the TX queue. TX
457 * queue consists of memory blocks preallocated by the user from tx_mem_slab
458 * (as defined by i2s_configure). This function takes ownership of the memory
459 * block and will release it when all data are transmitted.
460 *
461 * If there are no free slots in the TX queue the function will block waiting
462 * for the next TX memory block to be send and removed from the queue. This
463 * operation can timeout as defined by i2s_configure. If the timeout value is
464 * set to K_NO_WAIT the function is non-blocking.
465 *
466 * Writing to the TX queue is only possible if the interface is in READY or
467 * RUNNING state.
468 *
469 * @param dev Pointer to the device structure for the driver instance.
470 * @param mem_block Pointer to the TX memory block containing data to be sent.
471 * @param size Number of bytes to write. This value has to be equal or smaller
472 * than the size of the memory block.
473 *
474 * @retval 0 If successful.
475 * @retval -EIO The interface is not in READY or RUNNING state.
476 * @retval -EBUSY Returned without waiting.
477 * @retval -EAGAIN Waiting period timed out.
478 */
i2s_write(const struct device * dev,void * mem_block,size_t size)479 static inline int i2s_write(const struct device *dev, void *mem_block,
480 size_t size)
481 {
482 const struct i2s_driver_api *api =
483 (const struct i2s_driver_api *)dev->api;
484
485 return api->write(dev, mem_block, size);
486 }
487
488 /**
489 * @brief Write data to the TX queue from a provided buffer
490 *
491 * This function acquires a memory block from the I2S channel TX queue
492 * and copies the provided data buffer into it. It is otherwise equivalent
493 * to i2s_write().
494 *
495 * @param dev Pointer to the device structure for the driver instance.
496 * @param buf Pointer to a buffer containing the data to transmit.
497 * @param size Number of bytes to write. This value has to be equal or smaller
498 * than the size of the channel's TX memory block configuration.
499 *
500 * @retval 0 If successful.
501 * @retval -EIO The interface is not in READY or RUNNING state.
502 * @retval -EBUSY Returned without waiting.
503 * @retval -EAGAIN Waiting period timed out.
504 * @retval -ENOMEM No memory in TX slab queue.
505 * @retval -EINVAL Size parameter larger than TX queue memory block.
506 */
507 __syscall int i2s_buf_write(const struct device *dev, void *buf, size_t size);
508
509 /**
510 * @brief Send a trigger command.
511 *
512 * @param dev Pointer to the device structure for the driver instance.
513 * @param dir Stream direction: RX, TX, or both, as defined by I2S_DIR_*.
514 * The I2S_DIR_BOTH value may not be supported by some drivers.
515 * For those, triggering need to be done separately for the RX
516 * and TX streams.
517 * @param cmd Trigger command.
518 *
519 * @retval 0 If successful.
520 * @retval -EINVAL Invalid argument.
521 * @retval -EIO The trigger cannot be executed in the current state or a DMA
522 * channel cannot be allocated.
523 * @retval -ENOMEM RX/TX memory block not available.
524 * @retval -ENOSYS I2S_DIR_BOTH value is not supported.
525 */
526 __syscall int i2s_trigger(const struct device *dev, enum i2s_dir dir,
527 enum i2s_trigger_cmd cmd);
528
z_impl_i2s_trigger(const struct device * dev,enum i2s_dir dir,enum i2s_trigger_cmd cmd)529 static inline int z_impl_i2s_trigger(const struct device *dev,
530 enum i2s_dir dir,
531 enum i2s_trigger_cmd cmd)
532 {
533 const struct i2s_driver_api *api =
534 (const struct i2s_driver_api *)dev->api;
535
536 return api->trigger(dev, dir, cmd);
537 }
538
539 /**
540 * @}
541 */
542
543 #ifdef __cplusplus
544 }
545 #endif
546
547 #include <zephyr/syscalls/i2s.h>
548
549 #endif /* ZEPHYR_INCLUDE_DRIVERS_I2S_H_ */
550
