RTIC v2 RTC monotonic drivers #804

kyp44 · 2024-12-21T00:08:43Z

Summary

Adds RTC-based RTIC v2 monotonics drivers.

This addresses issue #765 and is the culmination of a lot of discussion there.

Note that it was decided along with the RTIC team that ATSAMD RTIC monotonics should be released as part of the HAL instead of in rtic-monotonics.

Note that this release of the monotonics is opinionated in the sense that only the best monotonic is provided for each chip variant. See the module documentation of rtc::rtic for details. For reference, the alternative of releasing two monotonics, one for each RTC mode, is preserved in the rtic-v2-rtc-monotonics-full branch. Compare the module documentation of rtc::rtic in that branch for details on why there is clearly a best choice for each chip variant.

Checklist

All new or modified code is well documented, especially public items
No new warnings or clippy suggestions have been introduced - CI will deny clippy warnings by default!

kyp44 · 2024-12-21T18:08:59Z

Ok, I just discovered a stress test freezing issue when building in release mode, which I had not really tested before. Please do not merge until I get this fixed.

jbeaurivage · 2024-12-22T23:46:14Z

@kyp44 does the last commit address all the freezing issues? I'm hoping to have the time to read the PR in detail soon™.

kyp44 · 2024-12-23T02:11:52Z

@jbeaurivage Yeah, this does fix the issue, which, despite taking me hours to troubleshoot, was a very simple fix. I am still letting the stress test run for a long period of time, but I am 98% confident that there will not be further issues. I like to wait at least 36 hours to get a hardware counter rollover to be sure. Here is a timer showing how much time is left. If you want to be sure not to waste any of your time, wait until this timer is done, and I will check in and confirm that it's still going.

jbeaurivage

I have a few comments, some of which require changes, and some of which are at your discretion. But overall well done, this is some quality work!

Ideally I'd like to somehow get this tested on a thumbv6 target as a sanity check before merging.

By the way @kyp44, am I correct in my understanding that there are no breaking changes in this PR?

hal/src/rtc/modes.rs

hal/src/rtc/rtic/mod.rs

jbeaurivage · 2024-12-23T03:37:16Z

hal/src/rtc/rtic/mod.rs

+const fn cortex_logical2hw(logical: u8, nvic_prio_bits: u8) -> u8 {
+    ((1 << nvic_prio_bits) - logical) << (8 - nvic_prio_bits)
+}


There is already a very similar function in the HAL (here). If you're up for it, it would be nice to consolidate them to avoid duplication.

The similar function is gated behind the async feature. Currently, the rtic feature is independent from this, but perhaps it makes sense for rtic to also enable async?

Also, I wanted to point out that here defines NVIC_PRIO_BITS based on the chip variant, but this is actually defined in the PAC (e.g. here or here), so does not need to be defined manually in the HAL. I'll note that the modified set_monotonic_prio would also need to depend on NVIC_PRIO_BITS.

Well, if we're going to be in the business of managing interrupts, I think it should make sense to have an interrupts module (outside of the async feature gate) to keep all the functionality in one place. I guess technically one could use the Monotonic trait without async, if they limited themselves only to the now() method.

but this is actually defined in the PAC

Sweet, I never noticed, let's use that instead then.

I made a PR that moves the interrupt functionality not specific to async into its own module - check out #807.

Sounds good, we'll wait for #807 to be merged, then keep the rtic and async features independent.

I'll note that you could definitely use rtic without async if you just want to use async for delays, but don't necessarily need async interfaces to other peripherals. This may actually be the case for my project, especially since the drivers for the devices I need do not have async interfaces.

hal/src/rtc/rtic/mod.rs

jbeaurivage · 2024-12-23T04:01:31Z

Oh also, not a big deal at all, but #[hal_macro_helper] is meant to be able to add the #[hal_cfg] attribute to blocks and statements inside functions, since that's not currently supported by the compiler (apart from the #[cfg] attribute) . For items outside of functions, simply doing use atsamd_hal_macros::hal_cfg is sufficient.

…ing the PR (atsamd-rs#804) * Adds #[hal_macro_helper] to functions as required and removes them from other, non-function items. * Adds documentation to `rtc::rtic::set_monotonic_prio` about the dependence on the RTIC static variable `RTIC_ASYNC_MAX_LOGICAL_PRIO`.

kyp44 · 2025-01-02T22:26:46Z

@jbeaurivage I just added comments to the particular items above as some require further discussion I think.

The latest commit (f43a341d) addresses/fixes some items as noted above, including your note about #[hal_macro_helper].

Regarding testing on thumbv6 targets, I may be getting a Feather M0 in the next couple of weeks to carry out and test the clocks v2 API work. If someone is able to test the monotonic in the meantime that would be great! I will also note that I just had the monotonic on the PyGamer running for over a week straight with no issues.

As for breaking changes, this PR does technically have breaking changes, but it is something minor and silly. In particular, in the current master with rtic enabled, the types rtc::Duration and rtc::Instant are publicly defined, I suppose to support the the RTIC v1 Monotonic implementation. In the current PR branch, these are moved to rtc::rtic::v1 as they are specific to RTIC v1.

…ing the PR (atsamd-rs#804) * Deprecates the entire `rtc::rtic::v1` module, which primarily just implements the old RTIC v1 `Monotonic` trait for `Rtc<Count32Mode>`. * Adds #[hal_macro_helper] to functions as required and removes them from other, non-function items. * Adds documentation to `rtc::rtic::set_monotonic_prio` about the dependence on the RTIC static variable `RTIC_ASYNC_MAX_LOGICAL_PRIO`.

jbeaurivage

Ok, I've tested this on a SAMD21, and found it to be reasonably accurate. I found a few other minor discussion points. Once we've addressed all remaining items I'll definitely be ready to merge this.

hal/src/rtc/rtic/mod.rs

…d mode1 monotonics.

… and macros, now uses type-level programming to specify the RTC clock source at compile time.

…lication in the HAL. * Moves the two monotonics into their own files so that the `rtc::rtic` main module file is not so large and unwieldy. * Adds thorough documentation to the `rtc::rtic` module and its items, discussing the differences between the two monotonics, and how to use the macros to create them.

…lication. * Finally achieves ostensibly robust operation for both monotonics in which they can operate solidly for at least 12 hours under very heavy task load. * Adds in instrumentation to monitor the monotonics and panic with useful debugging messages if an abnormal condition or stall is detected.

…lication. * Major refactor to decouple the RTC mode from the monotonic backend type (basic or half-period counting). * This enables using half-period counting in mode 0 for SAMx5x chips without duplicating as much mode. * Updates and expands the documentation to account for the changes. * Leaves in the monitor instrumentation so it is captured in the new form.

… that the monotonics have been thoroughly tested.

…ons and moves RTIC-specific things, so they can be used for other purposes as well.

…sing the best RTC mode for the chip variant. Updates the documentation accordingly.

…ng things with the `build-all.py` script. * Renames the `wait_for_count_change` to `_wait_for_count_change` function name to suppress an unused warning for SAMD11/21 chips. * Fixes the `metro_m0` example `blinky_rtic.rs` to fix an RTIC v1 item location change.

…ess a freezing issue in release builds.

…ing the PR (atsamd-rs#804) * Deprecates the entire `rtc::rtic::v1` module, which primarily just implements the old RTIC v1 `Monotonic` trait for `Rtc<Count32Mode>`. * Adds #[hal_macro_helper] to functions as required and removes them from other, non-function items. * Adds documentation to `rtc::rtic::set_monotonic_prio` about the dependence on the RTIC static variable `RTIC_ASYNC_MAX_LOGICAL_PRIO`.

…ing the PR (atsamd-rs#804) * Adds safety documentation to the `RtcMode` trait methods, and makes all methods safe to call. * Removes the RTIC-specific prelude and adjusts RTIC items in the crate-level prelude. * Updates the `rtic` module example to include notes about the `RTIC_ASYNC_MAX_LOGICAL_PRIO` static variable.

kyp44 · 2025-01-08T19:38:55Z

Just pushed a new commit (d3f23c79), which addresses additional items as noted above. Note that this rebases against some new commits in master, which seems to resolve the automated checks that were failing before. Commit hash references above have been updated.

It also occurred to me that, as far as I am tracking, breaking changes are confined to the rtic feature. Of course a breaking change is still a breaking change overall.

Lastly, I think the only is pending issue is waiting for PR #807 to merge for the interrupt stuff.

jbeaurivage · 2025-01-09T00:52:50Z

Awesome, thanks for the effort @kyp44! Let's wait for #804 and then I'll get this merged.

kyp44 mentioned this pull request Dec 21, 2024

atsamd21: initial implementation usign TC4/5 rtic-rs/rtic#994

Open

jbeaurivage requested changes Dec 23, 2024

View reviewed changes

kyp44 force-pushed the rtic-v2-rtc-monotonics branch from 78700c6 to 71b308c Compare January 2, 2025 22:28

jbeaurivage mentioned this pull request Jan 5, 2025

Tracking issue - remove deprecated code #784

Open

4 tasks

jbeaurivage reviewed Jan 5, 2025

View reviewed changes

hal/src/rtc/rtic/mod.rs Show resolved Hide resolved

hal/src/rtc/rtic/mod.rs Show resolved Hide resolved

jbeaurivage mentioned this pull request Jan 5, 2025

changed: Break non-async specific interrupt functionality out of async_hal module #807

Merged

2 tasks

Dan Whitman and others added 11 commits January 7, 2025 11:14

feat(rtic-v2-rtc-monotonics): Initial import of both the RTC mode0 an…

5dce49a

…d mode1 monotonics.

feat(rtic-v2-rtc-monotonics): Refactors and simplifies the monotonics…

fd03463

… and macros, now uses type-level programming to specify the RTC clock source at compile time.

feat(rtic-v2-rtc-monotonics): Removes the monitor instrumentation now…

b66a99e

… that the monotonics have been thoroughly tested.

feat(rtic-v2-rtc-monotonics): Factors out the low-level RTC abstracti…

05a0bc7

…ons and moves RTIC-specific things, so they can be used for other purposes as well.

feat(rtic-v2-rtc-monotonics): Only includes a single RTC monotonic, u…

e675d6a

…sing the best RTC mode for the chip variant. Updates the documentation accordingly.

feat(rtic-v2-rtc-monotonics): Extends the MIN_COMPARE_TICKS to addr…

5047d94

…ess a freezing issue in release builds.

kyp44 force-pushed the rtic-v2-rtc-monotonics branch from 71b308c to f43a341 Compare January 7, 2025 16:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RTIC v2 RTC monotonic drivers #804

RTIC v2 RTC monotonic drivers #804

kyp44 commented Dec 21, 2024 •

edited

Loading

kyp44 commented Dec 21, 2024

jbeaurivage commented Dec 22, 2024

kyp44 commented Dec 23, 2024 •

edited

Loading

jbeaurivage left a comment •

edited

Loading

jbeaurivage Dec 23, 2024

kyp44 Jan 2, 2025

jbeaurivage Jan 5, 2025 •

edited

Loading

kyp44 Jan 5, 2025

jbeaurivage commented Dec 23, 2024

kyp44 commented Jan 2, 2025 •

edited

Loading

jbeaurivage left a comment

kyp44 commented Jan 8, 2025 •

edited

Loading

jbeaurivage commented Jan 9, 2025

RTIC v2 RTC monotonic drivers #804

Are you sure you want to change the base?

RTIC v2 RTC monotonic drivers #804

Conversation

kyp44 commented Dec 21, 2024 • edited Loading

Summary

Checklist

kyp44 commented Dec 21, 2024

jbeaurivage commented Dec 22, 2024

kyp44 commented Dec 23, 2024 • edited Loading

jbeaurivage left a comment • edited Loading

Choose a reason for hiding this comment

jbeaurivage Dec 23, 2024

Choose a reason for hiding this comment

kyp44 Jan 2, 2025

Choose a reason for hiding this comment

jbeaurivage Jan 5, 2025 • edited Loading

Choose a reason for hiding this comment

kyp44 Jan 5, 2025

Choose a reason for hiding this comment

jbeaurivage commented Dec 23, 2024

kyp44 commented Jan 2, 2025 • edited Loading

jbeaurivage left a comment

Choose a reason for hiding this comment

kyp44 commented Jan 8, 2025 • edited Loading

jbeaurivage commented Jan 9, 2025

kyp44 commented Dec 21, 2024 •

edited

Loading

kyp44 commented Dec 23, 2024 •

edited

Loading

jbeaurivage left a comment •

edited

Loading

jbeaurivage Jan 5, 2025 •

edited

Loading

kyp44 commented Jan 2, 2025 •

edited

Loading

kyp44 commented Jan 8, 2025 •

edited

Loading