From be190b586d408dd641dc2dbd37982b32a366d95b Mon Sep 17 00:00:00 2001
From: Scott Mabin <scott@mabez.dev>
Date: Sat, 23 Nov 2024 14:29:10 +0000
Subject: [PATCH] changelog and migration guide

---
 esp-hal/CHANGELOG.md      |  5 +++++
 esp-hal/MIGRATING-0.22.md | 33 ++++++++++++++++++++++++++++++---
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
index 881da60a16..63581b6837 100644
--- a/esp-hal/CHANGELOG.md
+++ b/esp-hal/CHANGELOG.md
@@ -20,6 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ESP32-C6, H2, S3: Added `split` function to the `DmaChannel` trait. (#2526)
 - Added PSRAM configuration to `esp_hal::Config` if `quad-psram` or `octal-psram` is enabled (#2546)
 - Added `esp_hal::psram::psram_raw_parts` (#2546)
+- The timer drivers `OneShotTimer` & `PeriodicTimer` have `into_async` and `new_typed` methods (#2586)
+- `timer::Timer` trait has three new methods, `wait`, `async_interrupt_handler` and `peripheral_interrupt` (#2586)
 
 ### Changed
 
@@ -35,6 +37,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `SystemTimer`s `Alarm`s are now type erased (#2576)
 - `TimerGroup` `Timer`s are now type erased (#2581)
 - PSRAM is now initialized automatically if `quad-psram` or `octal-psram` is enabled (#2546)
+- The timer drivers `OneShotTimer` & `PeriodicTimer` now have a `Mode` parameter and type erase the underlying driver by default (#2586)
+- `timer::Timer` has new trait requirements of `Into<AnyTimer>`, `'static` and `InterruptConfigurable` (#2586)
+- `systimer::etm::Event` no longer borrows the alarm indefinitely (#2586)
 
 ### Fixed
 
diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md
index 671618ac1c..2a41d9c310 100644
--- a/esp-hal/MIGRATING-0.22.md
+++ b/esp-hal/MIGRATING-0.22.md
@@ -103,6 +103,17 @@ If you are writing a driver and need to store a channel in a structure, you can
 
 The low level timers, `SystemTimer` and `TimerGroup` are now "dumb". They contain no logic for operating modes or trait implementations (except the low level `Timer` trait).
 
+### Timer drivers - `OneShotTimer` & `PeriodicTimer`
+
+Both drivers now have a `Mode` parameter. Both also type erase the underlying driver by default, call `new_typed` to retain the type.
+
+```diff
+- OneShotTimer<'static, systimer::Alarm>;
++ OneShotTimer<'static, Blocking>;
+- PeriodicTimer<'static, systimer::Alarm>;
++ PeriodicTimer<'static, Blocking>;
+```
+
 ### SystemTimer
 
 ```diff
@@ -126,6 +137,24 @@ Timer group timers have been type erased.
 + timg::Timer
 ```
 
+The usage of `esp_alloc::psram_allocator!` remains unchanged.
+### ETM usage has changed
+
+Timer dependant ETM events should be created _prior_ to initializing the timer with the chosen driver.
+
+```diff
+let task = ...; // ETM task
+let syst = SystemTimer::new(peripherals.SYSTIMER);
+let alarm0 = syst.alarm0;
+- alarm0.load_value(1u64.millis()).unwrap();
+- alarm0.start();
+- let event = Event::new(&mut alarm0);
++ let event = Event::new(&alarm0);
++ let timer = OneShotTimer::new(alarm0);
++ timer.schedule(1u64.millis()).unwrap();
+let _configured_channel = channel0.setup(&event, &task);
+```
+
 ## PSRAM is now initialized automatically
 
 Calling `esp_hal::initialize` will now configure PSRAM if either the `quad-psram` or `octal-psram`
@@ -141,6 +170,4 @@ is enabled. To retrieve the address and size of the initialized external memory,
 +    config
 +});
 +let (start, size) = esp_hal::psram::psram_raw_parts(&peripherals.PSRAM, psram);
-```
-
-The usage of `esp_alloc::psram_allocator!` remains unchanged.
+```
\ No newline at end of file