From 080ec9d1419b6288575c6964ada8e67040f3e73c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1niel=20Buga?= Date: Wed, 6 Nov 2024 19:36:31 +0100 Subject: [PATCH 1/2] Move I2S drivers to i2s::master and i2s::parallel --- esp-hal/CHANGELOG.md | 3 +- esp-hal/MIGRATING-0.21.md | 59 +++++++++++-------- esp-hal/src/{i2s.rs => i2s/master.rs} | 4 +- esp-hal/src/i2s/mod.rs | 6 ++ .../src/{i2s_parallel.rs => i2s/parallel.rs} | 2 +- esp-hal/src/lib.rs | 2 - examples/src/bin/embassy_i2s_parallel.rs | 2 +- examples/src/bin/embassy_i2s_read.rs | 2 +- examples/src/bin/embassy_i2s_sound.rs | 2 +- examples/src/bin/i2s_parallel.rs | 2 +- examples/src/bin/i2s_read.rs | 2 +- examples/src/bin/i2s_sound.rs | 2 +- hil-test/tests/i2s.rs | 2 +- 13 files changed, 51 insertions(+), 39 deletions(-) rename esp-hal/src/{i2s.rs => i2s/master.rs} (99%) create mode 100644 esp-hal/src/i2s/mod.rs rename esp-hal/src/{i2s_parallel.rs => i2s/parallel.rs} (99%) diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md index d112b9a9f65..5ac411649a3 100644 --- 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 index d490ce16778..e803f1377e9 100644 --- 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` now In case of any error you should drop the transfer and restart it. diff --git a/esp-hal/src/i2s.rs b/esp-hal/src/i2s/master.rs similarity index 99% rename from esp-hal/src/i2s.rs rename to esp-hal/src/i2s/master.rs index 0a44a75fa6d..6244821c3c9 100644 --- a/esp-hal/src/i2s.rs +++ b/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}; diff --git a/esp-hal/src/i2s/mod.rs b/esp-hal/src/i2s/mod.rs new file mode 100644 index 00000000000..2b0bfd6eb6a --- /dev/null +++ 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 b/esp-hal/src/i2s/parallel.rs similarity index 99% rename from esp-hal/src/i2s_parallel.rs rename to esp-hal/src/i2s/parallel.rs index 37fd6585d43..d8888f25379 100644 --- a/esp-hal/src/i2s_parallel.rs +++ b/esp-hal/src/i2s/parallel.rs @@ -395,7 +395,7 @@ fn calculate_clock(sample_rate: impl Into, 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 index 8ff2815bc70..aa8dda2a86c 100644 --- 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 index 509f7183595..322b5e4a95b 100644 --- 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 index afb796c1c42..196793e9c23 100644 --- 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 index 2c807a4755c..dd48f782738 100644 --- 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 index 0634b8cbe9a..4effbf654f0 100644 --- 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 index 8274fb69d71..4e2278ff632 100644 --- 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 index 72e2d7b8e12..8058ef82361 100644 --- 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 index 0156c26b88d..7610e7791ff 100644 --- 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, From 0317a08b03ab461e968b2ea61e92a99ce133bae0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1niel=20Buga?= Date: Thu, 7 Nov 2024 09:46:02 +0100 Subject: [PATCH 2/2] Remove mention of master mode --- esp-hal/src/i2s/master.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/esp-hal/src/i2s/master.rs b/esp-hal/src/i2s/master.rs index 6244821c3c9..78728ac36a2 100644 --- a/esp-hal/src/i2s/master.rs +++ b/esp-hal/src/i2s/master.rs @@ -73,7 +73,7 @@ //! ``` //! //! ## Implementation State -//! - Only master mode is supported. +//! //! - Only TDM Philips standard is supported. use core::marker::PhantomData;