Harmonize bsp api with an eye towards clean docs

boards/edgebadge/examples/blinky_basic.rs

@@ -3,7 +3,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use hal::clock::GenericClockController;

boards/edgebadge/examples/button_rtic.rs

@@ -1,15 +1,15 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, pins::ButtonReader, pins::Keys, Pins};
+use edgebadge::{hal, ButtonReader, Keys, Pins};
 use panic_halt as _;
 
 use hal::clock::GenericClockController;
 use hal::gpio::{OpenDrain, Output, Pa23};
 use hal::prelude::*;
 use rtic::app;
 
-#[app(device = crate::hal::pac, peripherals = true)]
+#[app(device = edgebadge::pac, peripherals = true)]
 const APP: () = {
     struct Resources {
         red_led: Pa23<Output<OpenDrain>>,

boards/edgebadge/examples/ferris_img.rs

@@ -10,7 +10,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use embedded_graphics::pixelcolor::{Rgb565, RgbColor};

boards/edgebadge/examples/neopixel_adc_battery.rs

@@ -6,7 +6,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use hal::adc::Adc;

boards/edgebadge/examples/neopixel_adc_light.rs

@@ -6,7 +6,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use embedded_hal::digital::v1_compat::OldOutputPin;

boards/edgebadge/examples/neopixel_button.rs

@@ -9,7 +9,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, pins::Keys, Pins};
+use edgebadge::{entry, hal, pac, Keys, Pins};
 use panic_halt as _;
 
 use hal::prelude::*;

boards/edgebadge/examples/neopixel_easing.rs

@@ -6,7 +6,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use core::f32::consts::FRAC_PI_2;

boards/edgebadge/examples/neopixel_rainbow_timer.rs

@@ -9,7 +9,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use hal::prelude::*;

boards/edgebadge/examples/neopixel_tilt.rs

@@ -7,7 +7,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use hal::prelude::*;

boards/edgebadge/examples/usb_poll.rs

@@ -4,7 +4,7 @@
 #![no_std]
 #![no_main]
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use hal::clock::GenericClockController;

boards/edgebadge/examples/usb_serial.rs

@@ -14,7 +14,7 @@
 //! Note leds may appear white during debug. Either build for release or add
 //! opt-level = 2 to profile.dev in Cargo.toml
 
-use edgebadge::{self as hal, entry, pac, Pins};
+use edgebadge::{entry, hal, pac, Pins};
 use panic_halt as _;
 
 use cortex_m::interrupt::free as disable_interrupts;

boards/edgebadge/src/lib.rs

@@ -2,18 +2,18 @@
 #![recursion_limit = "1024"]
 
 #[cfg(feature = "unproven")]
-pub mod buttons;
+mod buttons;
 
-pub mod pins;
-use atsamd_hal as hal;
+// Re-export the HAL and the PAC to give the user lower-level access to the
+// device should they need it.
+pub use atsamd_hal::{self as hal, target_device as pac};
 
 #[cfg(feature = "rt")]
 pub use cortex_m_rt::entry;
 
-pub use pins::Pins;
+mod pins;
+pub use pins::*;
 
-use hal::*;
-
-pub use hal::common::*;
-pub use hal::samd51::*;
-pub use hal::target_device as pac;
+pub mod prelude {
+    pub use atsamd_hal::prelude::*;
+}

boards/edgebadge/src/pins.rs

@@ -1,7 +1,8 @@
 //! EdgeBadge pins
 
-use super::{hal, pac, target_device};
+use super::hal;
 
+use atsamd_hal::target_device::{self, MCLK};
 use embedded_hal::{digital::v1_compat::OldOutputPin, timer::CountDown, timer::Periodic};
 use gpio::{Floating, Input, Output, Port, PushPull};
 use hal::clock::GenericClockController;
@@ -11,16 +12,14 @@ use hal::hal::spi;
 use hal::prelude::*;
 use hal::sercom::{I2CMaster2, PadPin, SPIMaster1, SPIMaster4, UART5};
 use hal::time::Hertz;
-use pac::MCLK;
-use st7735_lcd::{Orientation, ST7735};
 use ws2812_timer_delay as ws2812;
 
 #[cfg(feature = "usb")]
 use hal::usb::usb_device::bus::UsbBusAllocator;
 #[cfg(feature = "usb")]
 pub use hal::usb::UsbBus;
 #[cfg(feature = "usb")]
-use pac::gclk::{genctrl::SRC_A, pchctrl::GEN_A};
+use target_device::gclk::{genctrl::SRC_A, pchctrl::GEN_A};
 
 #[cfg(feature = "unproven")]
 pub use crate::buttons::ButtonReader;
@@ -29,7 +28,9 @@ pub use crate::buttons::Keys;
 #[cfg(feature = "unproven")]
 use hal::pwm::Pwm2;
 #[cfg(feature = "unproven")]
-use pac::ADC0;
+use st7735_lcd::{Orientation, ST7735};
+#[cfg(feature = "unproven")]
+use target_device::ADC0;
 
 define_pins!(
     /// Maps the pins to their arduino names and
@@ -310,9 +311,9 @@ impl Display {
     pub fn init(
         self,
         clocks: &mut GenericClockController,
-        sercom4: pac::SERCOM4,
-        mclk: &mut pac::MCLK,
-        timer2: pac::TC2,
+        sercom4: target_device::SERCOM4,
+        mclk: &mut target_device::MCLK,
+        timer2: target_device::TC2,
         delay: &mut hal::delay::Delay,
         port: &mut Port,
     ) -> Result<
@@ -406,7 +407,7 @@ impl SPI {
         self,
         clocks: &mut GenericClockController,
         bus_speed: F,
-        sercom1: pac::SERCOM1,
+        sercom1: target_device::SERCOM1,
         mclk: &mut MCLK,
         port: &mut Port,
     ) -> SPIMaster1<
@@ -446,7 +447,7 @@ impl I2C {
         self,
         clocks: &mut GenericClockController,
         bus_speed: F,
-        sercom2: pac::SERCOM2,
+        sercom2: target_device::SERCOM2,
         mclk: &mut MCLK,
         port: &mut Port,
     ) -> I2CMaster2<hal::sercom::Sercom2Pad0<Pa12<PfC>>, hal::sercom::Sercom2Pad1<Pa13<PfC>>> {
@@ -480,7 +481,7 @@ impl USB {
     /// as a USB device.
     pub fn init(
         self,
-        usb: pac::USB,
+        usb: target_device::USB,
         clocks: &mut GenericClockController,
         mclk: &mut MCLK,
         port: &mut Port,
@@ -512,7 +513,7 @@ impl UART {
         self,
         clocks: &mut GenericClockController,
         baud: F,
-        sercom5: pac::SERCOM5,
+        sercom5: target_device::SERCOM5,
         mclk: &mut MCLK,
         port: &mut Port,
     ) -> UART5<hal::sercom::Sercom5Pad1<Pb17<PfC>>, hal::sercom::Sercom5Pad0<Pb16<PfC>>, (), ()>

boards/pygamer/examples/blinky_basic.rs

@@ -5,7 +5,7 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, Pins};
+use pygamer::{entry, hal, pac, Pins};
 
 use hal::clock::GenericClockController;
 use hal::delay::Delay;

boards/pygamer/examples/button_rtic.rs

@@ -3,14 +3,14 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, pins::ButtonReader, pins::Keys, Pins};
+use pygamer::{hal, ButtonReader, Keys, Pins};
 
 use hal::clock::GenericClockController;
 use hal::gpio::{OpenDrain, Output, Pa23};
 use hal::prelude::*;
 use rtic::app;
 
-#[app(device = crate::hal::pac, peripherals = true)]
+#[app(device = pygamer::pac, peripherals = true)]
 const APP: () = {
     struct Resources {
         red_led: Pa23<Output<OpenDrain>>,
@@ -50,7 +50,7 @@ const APP: () = {
             &mut device.NVMCTRL,
         );
 
-        let mut pins = Pins::new(device.PORT).split();
+        let mut sets = Pins::new(device.PORT).split();
 
         let gclk0 = clocks.gclk0();
         let timer_clock = clocks.tc2_tc3(&gclk0).unwrap();
@@ -61,8 +61,8 @@ const APP: () = {
         tc3.enable_interrupt();
 
         init::LateResources {
-            buttons: pins.buttons.init(&mut pins.port),
-            red_led: pins.led_pin.into_open_drain_output(&mut pins.port),
+            buttons: sets.buttons.init(&mut sets.port),
+            red_led: sets.led_pin.into_open_drain_output(&mut sets.port),
             timer: tc3,
         }
     }

boards/pygamer/examples/clock_out.rs

@@ -5,7 +5,7 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, Pins};
+use pygamer::{entry, hal, pac, Pins};
 
 use hal::clock::GenericClockController;
 use pac::gclk::genctrl::SRC_A::DPLL0;

boards/pygamer/examples/ferris_img.rs

@@ -12,7 +12,7 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, Pins};
+use pygamer::{entry, hal, pac, Pins};
 
 use embedded_graphics::pixelcolor::{Rgb565, RgbColor};
 use embedded_graphics::prelude::*;
@@ -32,18 +32,18 @@ fn main() -> ! {
         &mut peripherals.OSCCTRL,
         &mut peripherals.NVMCTRL,
     );
-    let mut pins = Pins::new(peripherals.PORT).split();
+    let mut sets = Pins::new(peripherals.PORT).split();
     let mut delay = hal::delay::Delay::new(core.SYST, &mut clocks);
 
-    let (mut display, _backlight) = pins
+    let (mut display, _backlight) = sets
         .display
         .init(
             &mut clocks,
             peripherals.SERCOM4,
             &mut peripherals.MCLK,
             peripherals.TC2,
             &mut delay,
-            &mut pins.port,
+            &mut sets.port,
         )
         .unwrap();
 

boards/pygamer/examples/neopixel_adc_battery.rs

@@ -8,13 +8,13 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, Pins};
+use pygamer::{entry, hal, pac, Pins};
 
 use hal::adc::Adc;
-use hal::pac::gclk::pchctrl::GEN_A::GCLK11;
 use hal::prelude::*;
 use hal::timer::SpinTimer;
 use hal::{clock::GenericClockController, delay::Delay};
+use pac::gclk::pchctrl::GEN_A::GCLK11;
 use pac::{CorePeripherals, Peripherals};
 use smart_leds::{brightness, hsv::RGB8, SmartLedsWrite};
 
@@ -29,14 +29,14 @@ fn main() -> ! {
         &mut peripherals.OSCCTRL,
         &mut peripherals.NVMCTRL,
     );
-    let mut pins = Pins::new(peripherals.PORT).split();
+    let mut sets = Pins::new(peripherals.PORT).split();
 
     let mut adc0 = Adc::adc0(peripherals.ADC0, &mut peripherals.MCLK, &mut clocks, GCLK11);
-    let mut battery = pins.battery.init(&mut pins.port);
+    let mut battery = sets.battery.init(&mut sets.port);
 
     // neopixels
     let timer = SpinTimer::new(4);
-    let mut neopixel = pins.neopixel.init(timer, &mut pins.port);
+    let mut neopixel = sets.neopixel.init(timer, &mut sets.port);
 
     let mut delay = Delay::new(core.SYST, &mut clocks);
 

boards/pygamer/examples/neopixel_adc_light.rs

@@ -8,7 +8,7 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, Pins};
+use pygamer::{entry, hal, pac, Pins};
 
 use embedded_hal::digital::v1_compat::OldOutputPin;
 use hal::adc::Adc;

boards/pygamer/examples/neopixel_button.rs

@@ -12,17 +12,17 @@
 
 #[cfg(not(feature = "panic_led"))]
 use panic_halt as _;
-use pygamer::{self as hal, entry, pac, pins::Keys, Pins};
+use pygamer::{entry, hal, pac, util, Keys, Pins};
 
 use hal::adc::Adc;
 use hal::prelude::*;
 use hal::timer::SpinTimer;
-use hal::util::map_from;
 use hal::{clock::GenericClockController, delay::Delay};
 use pac::gclk::pchctrl::GEN_A::GCLK11;
 use pac::{CorePeripherals, Peripherals};
 use smart_leds::hsv::{hsv2rgb, Hsv, RGB8};
 use smart_leds::SmartLedsWrite;
+use util::map_from;
 
 #[entry]
 fn main() -> ! {
@@ -38,17 +38,17 @@ fn main() -> ! {
     );
 
     let mut delay = Delay::new(core_peripherals.SYST, &mut clocks);
-    let mut pins = Pins::new(peripherals.PORT).split();
+    let mut sets = Pins::new(peripherals.PORT).split();
 
-    let mut buttons = pins.buttons.init(&mut pins.port);
+    let mut buttons = sets.buttons.init(&mut sets.port);
 
     let mut adc1 = Adc::adc1(peripherals.ADC1, &mut peripherals.MCLK, &mut clocks, GCLK11);
-    let mut joystick = pins.joystick.init(&mut pins.port);
+    let mut joystick = sets.joystick.init(&mut sets.port);
 
     // neopixels
     let timer = SpinTimer::new(4);
 
-    let mut neopixel = pins.neopixel.init(timer, &mut pins.port);
+    let mut neopixel = sets.neopixel.init(timer, &mut sets.port);
 
     const NUM_LEDS: usize = 5;
     let mut pos_button: usize = 2;