Refactor SERCOM pads, add documentation and port feather_m0 to gpio::…

…v2 (#434)

* Remove warnings

* Add pac alias for target_device

* Update HAL to accept both v1::Pin and v2::Pins everywhere

Update all users of the `gpio` module to accept both `v1::Pin` and
`v2::Pin` types. In most cases, this was fairly straightforward and did
not involve any breaking changes. However, the `thumbv7em::pwm` required
a pretty major syntax hack. What used to be an `enum` is now a `struct`.
Update the few instances of broken code in the BSPs.

* Add .vscode to .gitignore

* Fix feather_m0 build in crates.json

* Overhaul `sercom::pads`, update `bsp_pins!` and add documentation

- Modify `AnyKind` trait bounds to eliminate `unsafe` implementations of
  AsRef and AsMut
- When changing `PinMode`, only write to registers when the starting
  mode is different from the ending mode.
- Consolidate documentation of several type-level programming patterns
  into the `typelevel` module and link to them as needed throughout the
  HAL.
- Add an `OptionalPinId` trait for use in the `sercom::v2::pad` module
  and elsewhere.
- Fix attribute bugs in the `bsp_pins!` macro, and modify it to allow
  documentation on every item.
- Refactor the `sercom::v1::pads` shim. Create a distinct `v1::Pad` type
  that wraps a `v2::Pad` type. This should help clarify the distinction
  between the two types.
- Move the `sercom::v2::pads` module to `sercom::v2::pad` to better
  reflect the principle type it defines.
- Refactor the definition of the `Pad` type.
- Rename `sercom::v2::spi::Mode` to `sercom::v2::spi::OpMode` to help
  distinguish it from the SPI mode (CPOL/CPHA).
- Update the `sercom::v1` APIs to account for the modified definition of
  `v1::Pad` and add implementations to support using `v2::Pad`s.
- Update `sercom::v2::spi` to use the new `v2::Pad` type and simplify
  the `spi::Pads` type. Update and improve documentation.
- For thumbv6 chips, move to a macro-based definition of the
  `v2::spi::DipoDopo` implementations, instead of the previous,
  brute-force approach.
- Do not implement the `AnyKind` pattern for `spi::Pads`, since there is
  no particular use case for it. Instead, use a normal trait.
- Add an `spi_pads_from_pins!` macro to support creating an `spi::Pads`
  type from `Pin` aliases instead of `PinId`s

* Update Wio Terminal to use `sercom::v2::spi`

* Update entire feather_m0 BSP to use `v2` APIs

Completely convert the feather_m0 BSP to use the `gpio::v2` and
`sercom::v2` APIs. It will serve as an example of how to migrate.

* Fix formatting

* Fix typo in typelevel module docs

.gitignore

@@ -10,3 +10,4 @@ Cargo.lock
 **/*.idea
 **/.DS_Store
 *.svd.patched
+.vscode

boards/edgebadge/src/pins.rs

@@ -326,7 +326,7 @@ impl Display {
                 Pb5<Output<PushPull>>,
                 Pa0<Output<PushPull>>,
             >,
-            Pwm2,
+            Pwm2<gpio::v2::PA01>,
         ),
         (),
     > {

boards/feather_m0/Cargo.toml

@@ -132,4 +132,4 @@ required-features = ["dma"]
 
 [[example]]
 name = "clock"
-required-features = ["usb"]
+required-features = ["usb", "unproven"]

boards/feather_m0/examples/adc.rs

@@ -1,21 +1,22 @@
 #![no_std]
 #![no_main]
 
-extern crate cortex_m;
-extern crate cortex_m_semihosting;
-extern crate embedded_hal;
-extern crate feather_m0 as hal;
 #[cfg(not(feature = "use_semihosting"))]
-extern crate panic_halt;
+use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
-extern crate panic_semihosting;
+use panic_semihosting as _;
 
 use cortex_m_semihosting::hprintln;
+
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
+
+use bsp::entry;
 use hal::adc::Adc;
 use hal::clock::GenericClockController;
-use hal::entry;
-use hal::pac::{CorePeripherals, Peripherals};
 use hal::prelude::*;
+use pac::{CorePeripherals, Peripherals};
 
 #[entry]
 fn main() -> ! {
@@ -27,10 +28,10 @@ fn main() -> ! {
         &mut peripherals.SYSCTRL,
         &mut peripherals.NVMCTRL,
     );
-    let mut pins = hal::Pins::new(peripherals.PORT);
+    let pins = bsp::Pins::new(peripherals.PORT);
     let mut delay = hal::delay::Delay::new(core.SYST, &mut clocks);
     let mut adc = Adc::adc(peripherals.ADC, &mut peripherals.PM, &mut clocks);
-    let mut a0 = pins.a0.into_function_b(&mut pins.port);
+    let mut a0: bsp::A0 = pins.a0.into();
 
     loop {
         let data: u16 = adc.read(&mut a0).unwrap();

boards/feather_m0/examples/blinky_basic.rs

@@ -1,19 +1,20 @@
 #![no_std]
 #![no_main]
 
-extern crate cortex_m;
-extern crate cortex_m_semihosting;
-extern crate feather_m0 as hal;
 #[cfg(not(feature = "use_semihosting"))]
-extern crate panic_halt;
+use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
-extern crate panic_semihosting;
+use panic_semihosting as _;
 
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
+
+use bsp::entry;
 use hal::clock::GenericClockController;
 use hal::delay::Delay;
-use hal::entry;
-use hal::pac::{CorePeripherals, Peripherals};
 use hal::prelude::*;
+use pac::{CorePeripherals, Peripherals};
 
 #[entry]
 fn main() -> ! {
@@ -25,8 +26,8 @@ fn main() -> ! {
         &mut peripherals.SYSCTRL,
         &mut peripherals.NVMCTRL,
     );
-    let mut pins = hal::Pins::new(peripherals.PORT);
-    let mut red_led = pins.d13.into_open_drain_output(&mut pins.port);
+    let pins = bsp::Pins::new(peripherals.PORT);
+    let mut red_led: bsp::RedLed = pins.d13.into();
     let mut delay = Delay::new(core.SYST, &mut clocks);
     loop {
         delay.delay_ms(200u8);

boards/feather_m0/examples/clock.rs

@@ -1,27 +1,29 @@
 #![no_std]
 #![no_main]
 
-extern crate feather_m0 as hal;
+use core::fmt::Write;
+
 use panic_halt as _;
 
 use cortex_m::interrupt::free as disable_interrupts;
 use cortex_m::peripheral::NVIC;
+use heapless::consts::U16;
+use heapless::String;
+use usb_device::bus::UsbBusAllocator;
+use usb_device::prelude::*;
+use usbd_serial::{SerialPort, USB_CLASS_CDC};
+
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
 
+use bsp::entry;
 use hal::clock::{ClockGenId, ClockSource, GenericClockController};
 use hal::delay::Delay;
-use hal::pac::{interrupt, CorePeripherals, Peripherals};
 use hal::prelude::*;
-use hal::{entry, Pins};
-
-use core::fmt::Write;
 use hal::rtc;
-use heapless::consts::U16;
-use heapless::String;
-
 use hal::usb::UsbBus;
-use usb_device::bus::UsbBusAllocator;
-use usb_device::prelude::*;
-use usbd_serial::{SerialPort, USB_CLASS_CDC};
+use pac::{interrupt, CorePeripherals, Peripherals};
 
 #[entry]
 fn main() -> ! {
@@ -36,8 +38,8 @@ fn main() -> ! {
     );
 
     let mut delay = Delay::new(core.SYST, &mut clocks);
-    let mut pins = Pins::new(peripherals.PORT);
-    let mut red_led = pins.d13.into_open_drain_output(&mut pins.port);
+    let pins = bsp::Pins::new(peripherals.PORT);
+    let mut red_led: bsp::RedLed = pins.d13.into();
 
     // get the internal 32k running at 1024 Hz for the RTC
     let timer_clock = clocks
@@ -53,7 +55,7 @@ fn main() -> ! {
 
     // initialize USB
     let bus_allocator = unsafe {
-        USB_ALLOCATOR = Some(hal::usb_allocator(
+        USB_ALLOCATOR = Some(bsp::usb_allocator(
             peripherals.USB,
             &mut clocks,
             &mut peripherals.PM,
@@ -80,7 +82,7 @@ fn main() -> ! {
 
     // Print the time forever!
     loop {
-        red_led.toggle();
+        red_led.toggle().ok();
         let time =
             disable_interrupts(|_| unsafe { RTC.as_mut().map(|rtc| rtc.current_time()) }).unwrap();
 

boards/feather_m0/examples/dmac.rs

@@ -5,21 +5,20 @@
 #![no_main]
 
 use cortex_m::asm;
-use feather_m0 as hal;
 use panic_halt as _;
 
-use hal::{
-    clock::GenericClockController,
-    entry,
-    pac::{CorePeripherals, Peripherals},
-};
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
 
+use bsp::entry;
+use hal::clock::GenericClockController;
 use hal::dmac::{DmaController, PriorityLevel, Transfer, TriggerAction, TriggerSource};
+use pac::Peripherals;
 
 #[entry]
 fn main() -> ! {
     let mut peripherals = Peripherals::take().unwrap();
-    let core = CorePeripherals::take().unwrap();
     let _clocks = GenericClockController::with_internal_32kosc(
         peripherals.GCLK,
         &mut peripherals.PM,
@@ -29,7 +28,6 @@ fn main() -> ! {
 
     let mut pm = peripherals.PM;
     let dmac = peripherals.DMAC;
-    let _nvic = core.NVIC;
 
     // Initialize buffers
     const LENGTH: usize = 50;

boards/feather_m0/examples/pwm.rs

@@ -1,17 +1,18 @@
 #![no_std]
 #![no_main]
 
-extern crate cortex_m_rt;
-extern crate feather_m0 as hal;
-extern crate panic_halt;
+use cortex_m_rt::entry;
+use panic_halt as _;
+
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
 
 use hal::clock::GenericClockController;
 use hal::delay::Delay;
-use hal::pac::{CorePeripherals, Peripherals};
 use hal::prelude::*;
 use hal::pwm::Pwm3;
-
-use cortex_m_rt::entry;
+use pac::{CorePeripherals, Peripherals};
 
 #[entry]
 fn main() -> ! {
@@ -25,9 +26,9 @@ fn main() -> ! {
         &mut peripherals.NVMCTRL,
     );
     let mut delay = Delay::new(core.SYST, &mut clocks);
-    let mut pins = hal::Pins::new(peripherals.PORT);
+    let pins = bsp::Pins::new(peripherals.PORT);
 
-    let _d5 = pins.d5.into_function_e(&mut pins.port);
+    let _d5: bsp::D5Pwm = pins.d5.into();
 
     let gclk0 = clocks.gclk0();
     let mut pwm3 = Pwm3::new(

boards/feather_m0/examples/sleeping_timer.rs

@@ -13,22 +13,24 @@
 #![no_std]
 #![no_main]
 
-extern crate cortex_m;
-extern crate feather_m0 as hal;
+use core::sync::atomic;
+
+use cortex_m::peripheral::NVIC;
 #[cfg(not(feature = "use_semihosting"))]
-extern crate panic_halt;
+use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
-extern crate panic_semihosting;
+use panic_semihosting as _;
+
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
 
+use bsp::entry;
 use hal::clock::{enable_internal_32kosc, ClockGenId, ClockSource, GenericClockController};
-use hal::entry;
-use hal::pac::{interrupt, CorePeripherals, Peripherals, TC4};
 use hal::prelude::*;
 use hal::sleeping_delay::SleepingDelay;
 use hal::timer;
-
-use core::sync::atomic;
-use cortex_m::peripheral::NVIC;
+use pac::{interrupt, CorePeripherals, Peripherals, TC4};
 
 /// Shared atomic between TC4 interrupt and sleeping_delay module
 static INTERRUPT_FIRED: atomic::AtomicBool = atomic::AtomicBool::new(false);
@@ -92,8 +94,8 @@ fn main() -> ! {
     peripherals.PM.apbcmask.modify(|_, w| w.adc_().clear_bit());
 
     // Configure our red LED and blink forever, sleeping between!
-    let mut pins = hal::Pins::new(peripherals.PORT);
-    let mut red_led = pins.d13.into_open_drain_output(&mut pins.port);
+    let pins = bsp::Pins::new(peripherals.PORT);
+    let mut red_led: bsp::RedLed = pins.d13.into();
     loop {
         red_led.set_low().unwrap();
         sleeping_delay.delay_ms(1_000u32);

boards/feather_m0/examples/sleeping_timer_rtc.rs

@@ -13,22 +13,24 @@
 #![no_std]
 #![no_main]
 
-extern crate cortex_m;
-extern crate feather_m0 as hal;
+use core::sync::atomic;
+
+use cortex_m::peripheral::NVIC;
 #[cfg(not(feature = "use_semihosting"))]
-extern crate panic_halt;
+use panic_halt as _;
 #[cfg(feature = "use_semihosting")]
-extern crate panic_semihosting;
+use panic_semihosting as _;
+
+use bsp::hal;
+use bsp::pac;
+use feather_m0 as bsp;
 
+use bsp::entry;
 use hal::clock::{enable_internal_32kosc, ClockGenId, ClockSource, GenericClockController};
-use hal::entry;
-use hal::pac::{interrupt, CorePeripherals, Peripherals, RTC};
 use hal::prelude::*;
 use hal::rtc;
 use hal::sleeping_delay::SleepingDelay;
-
-use core::sync::atomic;
-use cortex_m::peripheral::NVIC;
+use pac::{interrupt, CorePeripherals, Peripherals, RTC};
 
 /// Shared atomic between RTC interrupt and sleeping_delay module
 static INTERRUPT_FIRED: atomic::AtomicBool = atomic::AtomicBool::new(false);
@@ -87,8 +89,8 @@ fn main() -> ! {
     peripherals.PM.apbcmask.modify(|_, w| w.adc_().clear_bit());
 
     // Configure our red LED and blink forever, sleeping between!
-    let mut pins = hal::Pins::new(peripherals.PORT);
-    let mut red_led = pins.d13.into_open_drain_output(&mut pins.port);
+    let pins = bsp::Pins::new(peripherals.PORT);
+    let mut red_led: bsp::RedLed = pins.d13.into();
     loop {
         red_led.set_low().unwrap();
         sleeping_delay.delay_ms(1_000u32);