Rework ADC implementation

This also supports all devices now, instead of only f303 variants.

The channel information of the channels where generated automatically,
with help of the stm32cubemx "database" (xml files),
and `xq` a xml wrapper program for `jq`.

As a rework of codegen is needed to support the ADC channel generation
the easier route was taken, including checking in the scripts used
for that.

- Support most important configurations.
- Better OneShot implementation support.
- Interrupt support.

Author: Sh3Rm4n

CHANGELOG.md

@@ -60,6 +60,22 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   and ADC2, which the old API did not resemble.
   - The API provides no clock configuration for ADC peripherals yet, but
   correctly acts upon changes done through the `pac`. ([#281])
+- Major rework of the ADC implementation: ([#281])
+  - Add `CommonAdc` support.
+  - Add internal sensor peripheral support like `TemeperaturSensor` and similar.
+  - Lift restriction of the ADC implementation for `stm32f303`, though
+  `stm32f373` is still not supported.
+  - Enable manual configuration of the Adc peripheral of most important features
+    - `ConversionMode`
+    - `Sequence` length
+    - `OverrunMode`
+    - etc.
+  - Leverage type states to:
+    - Allow a `Disabled` ADC, which can be manually calibrated.
+    - Allow a `OneShot` ADC implementation through `into_oneshot` with an
+    optimal configuration for the `OneShot` embedded-hal trait.
+  - Support every possible ADC channel.
+  - Add interrupt support.
 
 ## [v0.8.2] - 2021-12-14
 

Cargo.toml

@@ -56,6 +56,7 @@ bare-metal = "1.0.0"
 
 [dev-dependencies]
 cortex-m-semihosting = "0.3.7"
+defmt = "0.3.0"
 defmt-rtt = "0.3.0"
 defmt-test = "0.3.0"
 panic-probe = "0.3.0"

codegen/tools/.gitignore

@@ -0,0 +1,2 @@
+gen.py
+__pycache__

codegen/tools/NOTES.md

@@ -0,0 +1,14 @@
+# ADC Channels
+
+The ADC channel approach did not use the current codegen code, as
+it was more convenient to query the xml database with a commandline tool,
+to get an idea how it was structured.
+
+This code **should** be integrated into the codegen rust source in the future.
+But to make this happen codegen has to be refactored, as it is heavily
+tailored to the `IP` resolution right now.
+
+What really should happen though, is to integrate all those features into
+[**`cube-parse`**](https://github.com/stm32-rs/cube-parse/)
+and only have a shim of processing code, which tailors the output to our
+macros.

codegen/tools/adc_channel.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+
+"""
+This script generates the ADC channel! macro with arguents for all pins
+of all chip subfamilies.
+
+The strategy is, to get the maximum possible support for the most
+finest currently possible chip subfamily distinction.
+
+That means, that some impls for some chips are more than the actual
+chip is actually capable of.
+"""
+
+import re
+
+import subprocess
+
+# Hacky way to create a dict variable with a bash script
+# which is then saved to a file which then can be directly imported.
+channel = subprocess.check_output(['bash', 'adc_channel.sh'])
+with open("gen.py", "wb") as f:
+    f.write(channel)
+
+import gen
+
+CHIP_SELECT = {
+    "stm32f301x6": r".*STM32F301.(6|8|\(6-8\)).*\.xml",
+    "stm32f302x6": r".*STM32F302.(6|8|\(6-8\)).*\.xml",
+    "stm32f303x6": r".*STM32F303.(6|8|\(6-8\)).*\.xml",
+    "stm32f302xb": r".*STM32F302.(B|C|\(B-C\)|\(8-B-C\)).*\.xml",
+    "stm32f303xb": r".*STM32F303.(B|C|\(B-C\)|\(8-B-C\)).*\.xml",
+    "stm32f302xd": r".*STM32F302.(D|E|\(D-E\)).*\.xml",
+    "stm32f303xd": r".*STM32F303.(D|E).*\.xml",
+    "stm32f328": r".*STM32F328.*\.xml",
+    "stm32f358": r".*STM32F358.*\.xml",
+    "stm32f398": r".*STM32F398.*\.xml",
+    "stm32f373": r".*STM32F37(3|8).*\.xml",
+    "stm32f334": r".*STM32F334.*\.xml",
+}
+
+
+def main():
+    chip_post = {}
+
+    # Split ADC into adc and channel
+    for chip_name, pin_list in gen.CHANNELS.items():
+        pins = []
+        for pin in pin_list:
+            adc_list = []
+            for i in [1, 2]:
+                try:
+                    (adc, channel) = pin[i].split("_")
+                except IndexError:
+                    continue
+                adc_list.append((adc, int(channel)))
+            pins.append((pin[0], adc_list))
+        chip_post[chip_name] = pins
+
+    chip_results = {}
+
+    # Group into chip categories and select chip with max entries
+    # Choosing the maximum list is a compromise right now:
+    # 1. The stm32cubemx database is much more fine-grained about
+    #    the types of chips than our current feature is
+    # 2. Only allowing the minimal subset of all chip-subfamilies
+    #    is can be pretty annoying and would severly restrict the
+    #    channel implementation for the stm32f303xc and st32f303xd
+    #    for example.
+    # 3. This goes a little against the current impl strategy,
+    #    that is, allowing more than a chip might be possible to use.
+    #    But the alternative of finer feature selection is a pretty
+    #    big change and gives no real benefit, other than annoying
+    #    the user.
+    for chip, regex in CHIP_SELECT.items():
+        grouping = []
+        for chip_name, _ in chip_post.items():
+            if re.search(regex, chip_name):
+                grouping.append(chip_post[chip_name])
+        grouping = list(max(grouping))
+        chip_results[chip] = grouping
+
+    # Print the resulintg dictionary in a format, compatible with the
+    # `channel!` macro.
+    for type, result in chip_results.items():
+        type_variant_map = {
+            'x6': 'x8',
+            'xb': 'xc',
+            'xd': 'xe',
+        }
+        for key, value in type_variant_map.items():
+            if type[-2:] == key:
+                type_variant = type[:-2] + value
+                print(f'}} else if #[cfg(any(feature = "{type}", feature = "{type_variant}"))] {{')
+                break
+        else:
+            print(f'}} else if #[cfg(feature = "{type}")] {{')
+        print("    channel!([")
+        for elem in result:
+            line = f"        ({', '.join([str(e) for e in elem])})"
+            line = str(elem).replace("'", "")
+            print("        " + line + ",")
+        print("    ]);")
+
+
+if __name__ == "__main__":
+    main()

codegen/tools/adc_channel.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Using xq to query the stm32cubemx database for adc channels
+# xq beeing a wrapper of jq converting xml to a json representation internally.
+#
+# This is the source of the CHANNELS dict in adc_channel.py
+# TODO(Sh3Rm4n): This should probably be rewritten in the codegen part.
+# Though therefor the codegen should be refactored.
+
+set -euo pipefail
+
+echo "CHANNELS = {"
+for xml in /opt/stm32cubemx/db/mcu/STM32F3*.xml; do
+    echo '"'$xml'": ['
+    xq '.Mcu.Pin[]
+        | select(.Signal[]?."@Name"? | startswith("ADC"))
+        | [."@Name", (.Signal[]? | select(."@Name" | startswith("ADC")))."@Name"]
+        | @csv' --raw-output < $xml \
+        | rg -v EXTI \
+        | rg -v OSC32 \
+        | rg -v 'jq:' \
+        | sed 's/IN//g'  \
+        | sort -u \
+        | awk '{print "("$0"),"}'
+    echo '],'
+done
+echo "}"

examples/adc.rs

@@ -3,30 +3,51 @@
 
 //! Example usage for ADC on STM32F303
 
-use panic_semihosting as _;
+use defmt_rtt as _;
+use panic_probe as _;
+
+use defmt;
 
 use cortex_m::asm;
 use cortex_m_rt::entry;
-use cortex_m_semihosting::hprintln;
 
+use embedded_hal::adc::OneShot;
 use stm32f3xx_hal::{adc, pac, prelude::*};
 
 #[entry]
-/// Main Thread
 fn main() -> ! {
     // Get peripherals, clocks and freeze them
-    let mut dp = pac::Peripherals::take().unwrap();
+    let dp = pac::Peripherals::take().unwrap();
     let mut rcc = dp.RCC.constrain();
     let clocks = rcc.cfgr.freeze(&mut dp.FLASH.constrain().acr);
 
+    let mut adc_common = adc::CommonAdc::new(dp.ADC1_2, &clocks, &mut rcc.ahb);
+
+    let mut tuple = (dp.ADC1, dp.ADC2);
+    let mut ts = adc::TemperatureSensor::new(&mut adc_common, &mut tuple);
+
     // set up adc1
     let mut adc = adc::Adc::new(
-        dp.ADC1, // The ADC we are going to control
+        tuple.0, // The ADC we are going to control
+        adc::config::Config::default(),
         // The following is only needed to make sure the clock signal for the ADC is set up
         // correctly.
-        clocks,
-        &mut rcc.ahb,
-    );
+        &clocks,
+        &adc_common,
+    )
+    // Convert the ADC into `OneShot` mode.
+    //
+    // This is not necessary, as the normal ADC does also implement the `OneShot` trait, which can
+    // call `read`. But this conversion implies less overhead for the trait implementation. The
+    // consequence is, that in this mode nothing can be configured manually.
+    .into_oneshot();
+
+    // You can also create an ADC, which is initially disabled and uncalibrated and calibrate
+    // it later:
+    let mut adc2 = adc::Adc::new_disabled(tuple.1);
+    adc2.calibrate(&clocks, &adc_common);
+    adc2.set_config(adc::config::Config::default());
+    let _ = adc2.into_enabled();
 
     // Set up pin PA0 as analog pin.
     // This pin is connected to the user button on the stm32f3discovery board.
@@ -39,7 +60,7 @@ fn main() -> ! {
     // Also know that integer division and the ADC hardware unit always round down.
     // To make up for those errors, see this forum entry:
     // [https://forum.allaboutcircuits.com/threads/why-adc-1024-is-correct-and-adc-1023-is-just-plain-wrong.80018/]
-    hprintln!("
+    defmt::info!("
     The ADC has a 12 bit resolution, i.e. if your reference Value is 3V:
         approx. ADC value | approx. volt value
         ==================+===================
@@ -49,11 +70,15 @@ fn main() -> ! {
 
     If you are using a STM32F3Discovery, PA0 is connected to the User Button.
     Pressing it should connect the user Button to to HIGH and the value should change from 0 to 4095.
-    ").expect("Error using hprintln.");
+    ");
 
     loop {
-        let adc_data: u16 = adc.read(&mut analog_pin).expect("Error reading adc1.");
-        hprintln!("PA0 reads {}", adc_data).ok();
+        let adc_data: u16 = adc.read(&mut analog_pin).unwrap();
+        defmt::trace!("PA0 reads {}", adc_data);
+        let adc_data: u16 = adc.read(&mut ts).unwrap();
+        defmt::trace!("TemperatureSensor reads {}", adc_data);
         asm::delay(2_000_000);
     }
 }
+
+// TODO: Add adc example, which uses Continuous or Discontinous and interrupts.