esp-rs · MabezDev · Nov 7, 2024 · Nov 6, 2024 · Nov 7, 2024
diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Spi::half_duplex_read` and `Spi::half_duplex_write` (#2373)
 - `Cpu::COUNT` and `Cpu::current()` (#2411)
 - `UartInterrupt` and related functions (#2406)
-- I2S Parallel output driver for ESP32. (#2348, #2436)
+- I2S Parallel output driver for ESP32. (#2348, #2436, #2472)
 - Add an option to configure `WDT` action (#2330)
 - `DmaDescriptor` is now `Send` (#2456)
 - `into_async` and `into_blocking` functions for most peripherals (#2430, #2461)
@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - UART configuration types have been moved to `esp_hal::uart` (#2449)
 - `spi::master::Spi::new()` no longer takes `frequency` and `mode` as a parameter. (#2448)
 - Peripheral interconnections via GPIO pins now use the GPIO matrix. (#2419)
+- The I2S driver has been moved to `i2s::master` (#2472)
 
 ### Fixed
 

diff --git a/esp-hal/MIGRATING-0.21.md b/esp-hal/MIGRATING-0.21.md
@@ -1,28 +1,5 @@
 # Migration Guide from 0.21.x to v0.22.x
 
-## Removed `i2s` traits
-
-The following traits have been removed:
-
-- `I2sWrite`
-- `I2sWriteDma`
-- `I2sRead`
-- `I2sReadDma`
-- `I2sWriteDmaAsync`
-- `I2sReadDmaAsync`
-
-You no longer have to import these to access their respective APIs. If you used these traits
-in your functions as generic parameters, you can use the `I2s` type directly instead.
-
-For example:
-
-```diff
--fn foo(i2s: &mut impl I2sWrite) {
-+fn foo(i2s: &mut I2s<'_, I2S0, Blocking>) {
-     // ...
- }
-```
-
 ## Removed `async`-specific constructors
 
 The following async-specific constuctors have been removed:
@@ -55,8 +32,8 @@ You can use the blocking counterparts, then call `into_async` on the returned pe
 Some drivers were implicitly configured to the asyncness of the DMA channel used to construct them.
 This is no longer the case, and the following drivers will always be created in blocking mode:
 
-- `I2s`
-- `master::SpiDma` and `master::SpiDmaBus`
+- `i2s::master::I2s`
+- `spi::master::SpiDma` and `spi::master::SpiDmaBus`
 
 ## Peripheral types are now optional
 
@@ -196,6 +173,38 @@ You can now listen/unlisten multiple interrupt bits at once:
 +uart0.listen(UartInterrupt::AtCmd | UartConterrupt::RxFifoFull);
 ```
 
+## I2S changes
+
+### The I2S driver has been moved to `i2s::master`
+
+```diff
+-use esp_hal::i2s::{DataFormat, I2s, Standard};
++use esp_hal::i2s::master::{DataFormat, I2s, Standard};
+```
+
+### Removed `i2s` traits
+
+The following traits have been removed:
+
+- `I2sWrite`
+- `I2sWriteDma`
+- `I2sRead`
+- `I2sReadDma`
+- `I2sWriteDmaAsync`
+- `I2sReadDmaAsync`
+
+You no longer have to import these to access their respective APIs. If you used these traits
+in your functions as generic parameters, you can use the `I2s` type directly instead.
+
+For example:
+
+```diff
+-fn foo(i2s: &mut impl I2sWrite) {
++fn foo(i2s: &mut I2s<'_, I2S0, Blocking>) {
+     // ...
+ }
+```
+
 ## Circular DMA transfer's `available` returns `Result<usize, DmaError>` now
 
 In case of any error you should drop the transfer and restart it.

diff --git a/esp-hal/src/i2s.rs → esp-hal/src/i2s/master.rs b/esp-hal/src/i2s.rs → esp-hal/src/i2s/master.rs
@@ -29,9 +29,7 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use esp_hal::i2s::I2s;
-//! # use esp_hal::i2s::Standard;
-//! # use esp_hal::i2s::DataFormat;
+//! # use esp_hal::i2s::master::{I2s, Standard, DataFormat};
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
@@ -75,7 +73,7 @@
 //! ```
 //! 
 //! ## Implementation State
-//! - Only master mode is supported.
+//!
 //! - Only TDM Philips standard is supported.
 
 use core::marker::PhantomData;

diff --git a/esp-hal/src/i2s/mod.rs b/esp-hal/src/i2s/mod.rs
@@ -0,0 +1,6 @@
+//! # Inter-IC Sound (I2S)
+
+pub mod master;
+
+#[cfg(esp32)]
+pub mod parallel;
diff --git a/esp-hal/src/i2s_parallel.rs → esp-hal/src/i2s/parallel.rs b/esp-hal/src/i2s_parallel.rs → esp-hal/src/i2s/parallel.rs
@@ -395,7 +395,7 @@ fn calculate_clock(sample_rate: impl Into<fugit::HertzU32>, data_bits: u8) -> I2
         } else {
             let mut min: u32 = !0;
 
-            for a in 2..=crate::i2s::I2S_LL_MCLK_DIVIDER_MAX {
+            for a in 2..=crate::i2s::master::I2S_LL_MCLK_DIVIDER_MAX {
                 let b = (a as u64) * (freq_diff as u64 * 10000u64 / mclk as u64) + 5000;
                 ma = ((freq_diff as u64 * 10000u64 * a as u64) / 10000) as u32;
                 mb = (mclk as u64 * (b / 10000)) as u32;

diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs
@@ -191,8 +191,6 @@ pub mod hmac;
 pub mod i2c;
 #[cfg(any(i2s0, i2s1))]
 pub mod i2s;
-#[cfg(esp32)]
-pub mod i2s_parallel;
 #[cfg(any(dport, interrupt_core0, interrupt_core1))]
 pub mod interrupt;
 #[cfg(lcd_cam)]

diff --git a/examples/src/bin/embassy_i2s_parallel.rs b/examples/src/bin/embassy_i2s_parallel.rs
@@ -21,7 +21,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority, DmaTxBuf},
     dma_buffers,
     gpio::Io,
-    i2s_parallel::{I2sParallel, TxEightBits},
+    i2s::parallel::{I2sParallel, TxEightBits},
     prelude::*,
     timer::timg::TimerGroup,
 };

diff --git a/examples/src/bin/embassy_i2s_read.rs b/examples/src/bin/embassy_i2s_read.rs
@@ -23,7 +23,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
-    i2s::{DataFormat, I2s, Standard},
+    i2s::master::{DataFormat, I2s, Standard},
     prelude::*,
     timer::timg::TimerGroup,
 };

diff --git a/examples/src/bin/embassy_i2s_sound.rs b/examples/src/bin/embassy_i2s_sound.rs
@@ -37,7 +37,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
-    i2s::{DataFormat, I2s, Standard},
+    i2s::master::{DataFormat, I2s, Standard},
     prelude::*,
     timer::timg::TimerGroup,
 };

diff --git a/examples/src/bin/i2s_parallel.rs b/examples/src/bin/i2s_parallel.rs
@@ -19,7 +19,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority, DmaTxBuf},
     dma_buffers,
     gpio::Io,
-    i2s_parallel::{I2sParallel, TxEightBits},
+    i2s::parallel::{I2sParallel, TxEightBits},
     prelude::*,
 };
 use log::info;

diff --git a/examples/src/bin/i2s_read.rs b/examples/src/bin/i2s_read.rs
@@ -21,7 +21,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
-    i2s::{DataFormat, I2s, Standard},
+    i2s::master::{DataFormat, I2s, Standard},
     prelude::*,
 };
 use esp_println::println;

diff --git a/examples/src/bin/i2s_sound.rs b/examples/src/bin/i2s_sound.rs
@@ -35,7 +35,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::Io,
-    i2s::{DataFormat, I2s, Standard},
+    i2s::master::{DataFormat, I2s, Standard},
     prelude::*,
 };
 

diff --git a/hil-test/tests/i2s.rs b/hil-test/tests/i2s.rs
@@ -15,7 +15,7 @@ use esp_hal::{
     dma::{Dma, DmaPriority},
     dma_buffers,
     gpio::{Io, NoPin},
-    i2s::{DataFormat, I2s, I2sTx, Standard},
+    i2s::master::{DataFormat, I2s, I2sTx, Standard},
     peripherals::I2S0,
     prelude::*,
     Async,