RMT: Various cleanups, small API enhancements

esp-hal/CHANGELOG.md

@@ -8,14 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- All public RMT types now derive `Debug`. (#4302)
 
 
 ### Changed
 
 - `work_queue` is no longer public (#4357)
 - UART memory is now powered down when the driver is no longer in use. (#4354)
+- `rmt::SingleShotTxTransaction` has been renamed to `rmt::TxTransaction`. (#4302)
+- `rmt::ChannelCreator::configure_tx` and `rmt::ChannelCreator::configure_rx` now take the configuration by reference (#4302)
 
 ### Fixed
+- RMT: All blocking methods now return the channel on failure (#4302)
+- RMT: the `place_rmt_driver_in_ram` option now also places the async interrupt handler in RAM (#4302)
 
 
 ### Removed

esp-hal/MIGRATING-1.0.0-rc.0.md

@@ -133,9 +133,9 @@ The corresponding parameter of the transaction structs has been removed as well
 (`SingleShotTxTransaction`, `ContinuousTxTransaction`, `RxTransaction`).
 
 Transmit and receive methods are now directly implemented by
-`Channel<Dm: DriverMode, Tx>`
+`Channel<'_, Dm: DriverMode, Tx>`
 and
-`Channel<Dm: DriverMode, Rx>`
+`Channel<'_, Dm: DriverMode, Rx>`
 respectively and the `RxChannel`, `TxChannel`, `RxChannelAsync` and `TxChannelAsync`
 traits have been removed.
 Several related types that were previously exported have been removed from the
@@ -145,8 +145,8 @@ API as well.
 -use esp_hal::rmt::{ConstChannelAccess, DynChannelAccess, RawChannelAccess};
 -let mut tx: Channel<Blocking, ConstChannelAccess<Tx, 0>> = rmt.channel0.configure_tx(NoPin, TxChannelConfig::default());
 -let mut rx: Channel<Blocking, ConstChannelAccess<Rx, 2>> = rmt.channel2.configure_rx(NoPin, RxChannelConfig::default());
-+let mut tx: Channel<Blocking, Tx> = rmt.channel0.configure_tx(NoPin, TxChannelConfig::default());
-+let mut rx: Channel<Blocking, Rx> = rmt.channel2.configure_rx(NoPin, RxChannelConfig::default());
++let mut tx: Channel<'_, Blocking, Tx> = rmt.channel0.configure_tx(NoPin, TxChannelConfig::default());
++let mut rx: Channel<'_, Blocking, Rx> = rmt.channel2.configure_rx(NoPin, RxChannelConfig::default());
 
 -let mut tx: Channel<Blocking, DynChannelAccess<Tx>> = tx.degrade();
 -let mut rx: Channel<Blocking, DynChannelAccess<Rx>> = rx.degrade();
@@ -160,20 +160,7 @@ API as well.
 +let rx_transaction: RxTransaction<'_, PulseCode> = rx.transmit(&data);
 ```
 
-### RMT method changes
-
-The `rmt::Channel::transmit_continuously` and
-`rmt::Channel::transmit_continuously_with_loopcount` methods have been merged:
-
-```diff
--let tx_trans0 = tx_channel0.transmit_continuously(&data);
--let tx_trans1 = tx_channel1.transmit_continuously_with_loopcount(&data, count);
-+use core::num::NonZeroU16;
-+use esp_hal::rmt::LoopCount;
-+let tx_trans0 = tx_channel0.transmit_continuously(&data, LoopCount::Infinite);
-+let count = NonZeroU16::new(count).unwrap();
-+let tx_trans1 = tx_channel1.transmit_continuously(&data, LoopCount::Finite(count));
-```
+### RMT Receiver Changes
 
 The receiver methods `rmt::Channel::<'_, Blocking>::receive` and
 `rmt::Channel::<'_, Async>::receive` now return the actual amount of data read,
@@ -208,25 +195,25 @@ Additionally, RMT transaction types
 - `RxTransaction`
 - futures returned by the async API
 are marked as `#[must_use]` to account for the fact that it is in general required to poll them to ensure progress.
-Additionally, they now implement `Drop` and stop the ongoing transfer as quickly as possible when dropped,
+All of them now implement `Drop` and stop the ongoing transfer as quickly as possible when dropped,
 ensuring that subsequent transactions start from a well-defined state.
 
 ### RMT continuous transmit changes
 
-The behavior of `Channel::transmit_continuously` has been clarified to account
-for the varying hardware support between devices: It now takes an additional
-`LoopStop` argument.
+The `rmt::Channel::transmit_continuously` and
+`rmt::Channel::transmit_continuously_with_loopcount` methods have been merged,
+and their signature has been modified to account for the varying hardware
+support between devices: It now takes an additional `LoopMode` argument, the variants
+of which are only defined when the hardware supports them.
 
 ```diff
-- let transaction = channel.transmit_continuously(&data, LoopCount::Finite(count))?;
-+ let transaction = channel.transmit_continuously(&data, LoopCount::Finite(count), LoopStop::Manual)?;
+-let tx_trans0 = tx_channel0.transmit_continuously(&data);
+-let tx_trans1 = tx_channel1.transmit_continuously_with_loopcount(&data, count);
++use esp_hal::rmt::LoopMode;
++let tx_trans0 = tx_channel0.transmit_continuously(&data, LoopMode::Infinite);
++let tx_trans1 = tx_channel1.transmit_continuously(&data, LoopMode::InfiniteWithInterrupt(count));
 ```
 
-Additionally, some enum variants and methods are only defined when the hardware supports them:
-
-- `LoopCount::Finite` and `ContinuousTxTransaction::is_tx_loopcount_interrupt_set` (all except ESP32),
-- `LoopStop::Auto` (ESP32-C6, ESP32-H2, ESP32-S3).
-
 ## DMA changes
 
 DMA buffers now have a `Final` associated type parameter. For the publicly available buffer, this is `Self`,

esp-hal/MIGRATING-1.0.0-rc.1.md

@@ -1 +1,31 @@
 # Migration Guide from 1.0.0-rc.1 to {{currentVersion}}
+
+## RMT Changes
+
+Several details of the driver structs and their methods have changed:
+
+- `SingleShotTxTransaction` has been renamed to `TxTransaction`.
+- All `Channel` and `ChannelCreator` methods that take their arguments (channels and pins) by value now return them on failure; this might require changed to error handling. Changed methods are
+    - `ChannelCreator<'_, _, _>::configure_tx` and `ChannelCreator<'_, _, _>::configure_rx`,
+    - `Channel<'_, Blocking, Tx>::transmit`,
+    - `Channel<'_, Blocking, Tx>::transmit_continuously`,
+    - `Channel<'_, Blocking, Rx>::receive`.
+- The `ChannelCreator::configure_tx` and `ChannelCreator::configure_rx` methods now take the configuration by reference.
+
+```diff
+-let mut tx = rmt.channel0.configure_tx(tx_pin, TxChannelConfig::default());
+-let mut rx = rmt.channel2.configure_rx(rx_pin, RxChannelConfig::default());
++let mut tx = rmt.channel0.configure_tx(tx_pin, &TxChannelConfig::default());
++let mut rx = rmt.channel2.configure_rx(rx_pin, &RxChannelConfig::default());
+
+-let tx_transaction: SingleShotTxTransaction<'_, PulseCode> = tx.transmit(&data)?;
++let tx_transaction: TxTransaction<'_, PulseCode> = match tx.transmit(&data) {
++    Ok(t) => t,
++    Err((e, channel)) => {
++        // Now, the `channel` is not lost permanently, but can continue to be used
++        // (e.g. to retry configuration with different parameters)
++        e?
++    }
++};
+```
+