embedded_i2s/lib.rs
1//! An embedded [Inter-IC Sound (I2S)][wikipedia] abstraction layer.
2//!
3//! This crate defines generic traits to be implemented by MCU HAL crates.
4//!
5//! For implementations see [here](https://crates.io/crates/embedded-i2s/reverse_dependencies).
6//!
7//! [wikipedia]: https://en.wikipedia.org/wiki/I%C2%B2S
8//!
9
10#![deny(unsafe_code, missing_docs)]
11#![no_std]
12
13/// Blocking I2S traits
14pub mod blocking {
15
16 /// Blocking I2S trait
17 pub trait I2s<W> {
18 /// Error type
19 type Error: core::fmt::Debug;
20
21 /// Reads enough bytes to fill `left_words` and `right_words`.
22 ///
23 /// It is allowed for `left_words` and `right_words` to have different lengths.
24 /// The read runs for `max(left_words.len(), right_words.len())` words.
25 /// Incoming words after the shorter buffer has been filled will be discarded.
26 fn read<'w>(
27 &mut self,
28 left_words: &'w mut [W],
29 right_words: &'w mut [W],
30 ) -> Result<(), Self::Error>;
31
32 /// Sends `left_words` and `right_words`.
33 ///
34 /// It is allowed for `left_words` and `right_words` to have different lengths.
35 /// The write runs for `max(left_words.len(), right_words.len())` words.
36 /// The value of words sent for the shorter channel after its buffer has been sent
37 /// is implementation-defined, typically `0x00`, `0xFF`, or configurable.
38 fn write<'w>(
39 &mut self,
40 left_words: &'w [W],
41 right_words: &'w [W],
42 ) -> Result<(), Self::Error>;
43
44 /// Sends `left_words` and `right_words` getting the data from iterators.
45 ///
46 /// It is allowed for `left_words` and `right_words` to have different lengths.
47 /// The write runs for `max(left_words.len(), right_words.len())` words.
48 /// The value of words sent for the shorter channel after its buffer has been sent
49 /// is implementation-defined, typically `0x00`, `0xFF`, or configurable.
50 fn write_iter<LW, RW>(
51 &mut self,
52 left_words: LW,
53 right_words: RW,
54 ) -> Result<(), Self::Error>
55 where
56 LW: IntoIterator<Item = W>,
57 RW: IntoIterator<Item = W>;
58 }
59}