New ADC V2 with Async support

[rnd-ash]

Summary

This PR adds a new ADC API, based around a similar system to channels used by EIC and DMA peripherals.

At the moment I'll keep this as a draft PR for feedback whilst I am still finalizing bits and also adding SAMD11/21 support

Features

• A new settings builder system for configuring the ADC
• Channels system (Each Analog capable pin has its own channel)
• Both blocking and Async read support
• Buffer filling support (Free running continuous mode)
• CPU temperature reading
• Internal voltages reading

Progress checklist

• SAMx51 support
• SAMx11/21 support
• Channels API
• Settings builder (Mostly completed, need to add settings for Vref calibration)
• Async/Blocking single reads
• Async/Blocking buffer reads
• CPU temperature reading (Restricted to primary ADC if applicable to chip)
• CPU internal voltages reading (Restricted to primary ADC if applicable to chip)

[jbeaurivage]

I just finished a first pass at reviewing this. In general, I would say this is an excellent implementation. Given your willingness to learn best practices, my review is more detailed than usual, so feel free to ignore some of these comments if you feel they're too nitpicky.

That being said, I do have some other comments that I feel deserve some attention:

• SAMD11 support. I feel we're so close it makes sense to finish the implementation for SAMD11 chips as well. As far as I can tell, the ADC is exactly the same between D21 and D11 targets. The only thing that might change and that I'm unsure of, is the maximum supported clock speed.
• We've already discussed this a little, but I'm not so sure the Channel API is so necessary after all. When I initially suggested this, I was under the impression that the ADC could perform conversions simultaneously on multiple channels, similar to EIC or DAMC. That's obviously not the case. As far as I can tell, there is also a 1:1 relationship between ADC channels and physical pins. So while the ADC can mux between channels, there is no pin-channel muxing going on. I think the ADC could simply take &mut refs to already-configured pins instead. This would cut down on complexity a whole bunch.
• Before merging, the Tier 1 BSP examples will have to be updated, and clippy warnings resolved. Ideally we would show examples where the CPU clock is ran at full speed, and a second GCLK is started at a slower speed to clock the ADC.
• I like that the d51 implementation takes advantage of the v2 clock system. However, it seems like the new adc module is not taking fully advantage of the typesafe clocking system: one needs to (unsafely) steal the peripherals to create a MCLK instance in order to configure the ADC. We should instead use the clocks system in its intended way, which is to exchange an ApbToken<Adcx> using Apb::enable to get a configured clock type, which can then be passed to the Adc peripheral, thus proving the clock is enabled. This is somewhat inverse to what the module is currently doing, which is enabling the ADC clock inside the constructor using the MCLK peripheral.

[jbeaurivage]

Here's a proof of concept of what I mean by using the typesafe clocking system. It's still untested and needs some more feature gating to accomodate D11 and D21 targets, but I think it gets the idea across: https://github.com/jbeaurivage/atsamd/tree/adc-v2-clocking

With an example usage:

let pins = Pins::new(cx.device.port);
let (buses, clocks, tokens) = clock_system_at_reset(
    cx.device.oscctrl,
    cx.device.osc32kctrl,
    cx.device.gclk,
    cx.device.mclk,
    &mut cx.device.nvmctrl,
);
let mut apb = buses.apb;
let adc0_clk = apb.enable(tokens.apbs.adc0);

let adc0_settings = Config::new()
    .clock_cycles_per_sample(5)
    .clock_divider(Prescalerselect::Div2)
    .sample_resolution(AdcResolution::_12bit)
    .accumulation_method(AdcAccumulation::Single);

let gclk0 = clocks.gclk0;
let (pclk_adc0, gclk0) = Pclk::enable(tokens.pclks.adc0, gclk0);
let (_pclk_adc1, _gclk0) = Pclk::enable(tokens.pclks.adc1, gclk0);

let (adc0, channels_adc0) =
    Adc::new(cx.device.adc0, adc0_settings, adc0_clk, pclk_adc0.into()).unwrap();

[jbeaurivage]

@rnd-ash, your additional commits look good.

You can check out This PR, which implements some of the larger changes mentioned here

I also want to point out that when testing on a SAMD51 board (metro M4), I regularly get the ADC stalling on waiting for the RESRDY flag to get set. So far the only way I managed to get ADC readings was:

• Using the clocks at reset (48 MHz), and
• Compiling in release mode.

To me this sounds like there is still a clock synchronization issue or a race condition somewhere.

So, among the things left to do:

• Merge ADC v2: Remove Channel machinery, fully use v2 clocks rnd-ash/atsamd#5 if you agree with this approach
• Document tl and th
• Fix the RESRDY bug - looks like it's related to the discarded read in read_blocking_channel See fix in this PR
• Add calibration code for D11/D21
• Merge ADC improvements (continued) rnd-ash/atsamd#6
• Update the T1 examples (see clock::v2: DPLL bug, potential UB? #819)

[jbeaurivage]

@rnd-ash, if you're happy with this, I am too. I think you've been doing extensive testing recently. Only two things to get CI green and get this merged:

• Fix a small clippy lint in calibration/d11.rs (line 44).
• Fix the pygamer examples

[rnd-ash]

I'll be able to fix these next week or this weekend when I'm back in the UK and have access to all my test boards (SAMD21 I need to verify it doesn't read old results in the ADC during sequential reads)

[rnd-ash]

@ianrrees @jbeaurivage As far as I am concerned now, this is ready to Merge. If you guys want to do 1 final review feel free.

As discussed with Ian, I fixed the pygamer example my deleting the neopixel examples

[ianrrees]

With stable Rust, I note cargo doc flags several dead links in the documentation, so please do have a look at those and ensure the rendered docs are what you intend.

Thanks for all this work! Looks pretty good.

[ianrrees]

What is the maximum value, and assuming it's not 8b what happens if a config is specified that's over it?

[jbeaurivage]

@rnd-ash, @ianrrees still had a few comments that are worth being addressed. I've fixed a bunch in rnd-ash#10. The only outstanding item that might require more discussion is the handling of the sampling parameters, ie, if we should force users to explicitly specify everything or not.

To simplify things a bit, I suggest that if you want add convenience methods to setup the ADC to a specific number of cycles per sample, it could be done in a follow-up PR.

[ianrrees]

I've been working on an ESP32 based project for a couple weeks now, and TBF it's reinforced my feelings that for things like UARTs (and I'd say ADC/DAC as well - just haven't used them in ESP32), it's really best to make the API explicit about settings where there is no clear default. However, I'm just one person, and I respect that the ESP32 HAL is quite successful, so maybe it's not worth worrying too much about...

@rnd-ash - it would be great to get this merged, what's your feeling about the next steps with it? If changing the config builder is too much of a pain, I'm happy either leaving it as-is or having a crack at it myself if you'd like.

[rnd-ash]

@ianrrees i think we are ready to merge this, just 1 minor bug with the SAMD21's temperature sensor not reading accurately, but I can (For now at least), just disable the cpu temperature function for SAMD21 if it proves to be a blocker.

I have not tested this on a D11 target either, as I don't have one, would it be possible for you to verify functionality?

[ianrrees]

Awesome, thanks! Yep, my next few days are going to be a bit variable in terms of computer time, but will try to get to it soon.

[ianrrees]

Alrighty, have put a little bit of time in to this and have a few thoughts in no particular order:

1. The work looks really good!
2. I've fiddled with the Git history of this work, making a branch that's as-if this work was all done using rebases instead of merges, then rebased that on to the current master and made a couple slight improvements. The new branch is at https://github.com/ianrrees/atsamd/tree/adcv2_rebase . I'd suggest that we look at whether it makes sense to keep the work in >1 commit (I guess it does, in particular removing the problematic examples) and if so clean up the history. Regardless, we should update as needed via rebasing on to master. Happy for it to live in my GH, or @rnd-ash if you'd like to update your branch that would look like (presuming you've not added more commits in the mean time):

git checkout adc_v2
git branch adc_v2_backup
git remote add ianrrees [email protected]:ianrrees/atsamd.git
git fetch ianrrees
git reset ianrrees/adcv2_rebase
git push --force

3. Unless it gets fixed in the meantime, I'd like to have a play with the SAMD21 temperature sensor issue before merging - should be able to put some time in to it in the next couple days. Not really a show stopper, just while we're in the area it seems like a good thing to sort out.

[rnd-ash]

Done @ianrrees , should be up to date with your branch