Rework GPIO API and fix a few inconsistencies (#585)

* Leverage typelevel implementation in i2c, pwm (and a little bit in uart).

This notably makes the documentation more readable.

* Use an enum for core identification

* Overhaul pin modules and related changes.

- Added `AdcPin` wrapper to disable digital function for ADC operations
- Added `Sealed` supertrait to `PIOExt`
- Added pins to `Spi` to fix inconsistencies in gpio bounds in peripheral (i2c, uart, spi)
- Merge DynPin and Pin into Pin. The type class used in Pin now have a runtime variant allowing for
  the creation of uniform array of pins (eg: `[Pin<DynPinId, PinFnSio, PullDown>]`).
- Fix miss defined ValidPinMode bound allowing any Bank0 pin to be Xip and any Qspi pin to be any
  other function (except for clock).
- Use `let _ = ` to ignore result rather than `.ok();` as this gives a false sense the result is
  checked.

Addresses: #140, #446, #481, #485, #556

* Address first review round from @thejpster.

* Add a few inline to enable better optimisation.

* Expand documentation for the `Adc`

Co-authored-by: Jonathan 'theJPster' Pallant <github@thejpster.org.uk>

* Refactor the ADC module and remove redundant ts_en.set_bit()

- The channel types and their traits impl have been moved to the top of the
file and reassembled following the "Type -> impl Trait for Type" pattern.
- The temperature sensor bias was enabled twice, `enable_temp_sensor` and
  in the Adc::read function. The latter has now been removed because reading
  the Temp channel requires to call `enable_temp_sensor` anyway.

* Spacersssss :) and unicity -> uniqueness

* Add sio bypass when pin is in Sio Function

* Rename `DontInvert` to `Normal`

* Prevent the creation of multiple instances of TempSensor

* Add missing updates on on-target-tests

* rename `PullBoth` to the more accurate `PullBusKeep`

* Enable dyn-pin to be used with peripherals

* update deprecation notice.

* Add `try_into_function` for dynpin'ed Pins.

* Fix some doc warnings

* Implement `PinGroup`

* Update type-level documentation.

There was too many changes required to keep it in sync with the current
implementation. However, this is not required to understand the essence
of the type-level techniques. Therefore it is less maintenance costly to
forward the reader to the upstream of the idea where the documentation is
already excellent.

* rename `Pin::into()` to `Pin::into_typestate()` to avoid conflicts with `Into::into`

* Update rp2040-hal/src/gpio/mod.rs

Co-authored-by: Jan Niehusmann <jan@gondor.com>

* Remove unused NoneT and fix AnyKind documentation's link

* Remove remaining occurences of "into_mode" in examples

* Enhance documentation

* doc: fix placeholder names

* Rename `into_typestate` to the more explicit `reconfigure`.

---------

Co-authored-by: Jonathan 'theJPster' Pallant <github@thejpster.org.uk>
Co-authored-by: Jan Niehusmann <jan@gondor.com>

on-target-tests/tests/dma_spi_loopback_u16.rs

@@ -7,6 +7,7 @@
 use crate::hal::dma::Channels;
 use defmt_rtt as _; // defmt transport
 use defmt_test as _;
+use hal::gpio::{self, Pin};
 use panic_probe as _;
 use rp2040_hal as hal; // memory layout // panic handler
 use rp2040_hal::pac::SPI0;
@@ -24,9 +25,12 @@ pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_GENERIC_03H;
 /// if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
+type MISO = Pin<gpio::bank0::Gpio4, gpio::FunctionSpi, gpio::PullNone>;
+type MOSI = Pin<gpio::bank0::Gpio7, gpio::FunctionSpi, gpio::PullNone>;
+type SCLK = Pin<gpio::bank0::Gpio6, gpio::FunctionSpi, gpio::PullNone>;
 struct State {
     channels: Option<Channels>,
-    spi: Option<spi::Spi<spi::Enabled, SPI0, 16>>,
+    spi: Option<spi::Spi<spi::Enabled, SPI0, (MOSI, MISO, SCLK), 16>>,
 }
 
 mod testdata {
@@ -91,10 +95,10 @@ mod tests {
         );
 
         // These are implicitly used by the spi driver if they are in the correct mode
-        let _spi_sclk = pins.gpio6.into_mode::<hal::gpio::FunctionSpi>();
-        let _spi_mosi = pins.gpio7.into_mode::<hal::gpio::FunctionSpi>();
-        let _spi_miso = pins.gpio4.into_mode::<hal::gpio::FunctionSpi>();
-        let spi = hal::spi::Spi::<_, _, 16>::new(pac.SPI0);
+        let spi_sclk = pins.gpio6.into();
+        let spi_mosi = pins.gpio7.into();
+        let spi_miso = pins.gpio4.into();
+        let spi = hal::spi::Spi::new(pac.SPI0, (spi_mosi, spi_miso, spi_sclk));
 
         // Exchange the uninitialised SPI driver for an initialised one
         let spi = spi.init(

on-target-tests/tests/dma_spi_loopback_u8.rs

@@ -9,6 +9,7 @@ use defmt_rtt as _; // defmt transport
 use defmt_test as _;
 use panic_probe as _;
 use rp2040_hal as hal; // memory layout // panic handler
+use rp2040_hal::gpio::{self, Pin};
 use rp2040_hal::pac::SPI0;
 use rp2040_hal::spi;
 
@@ -24,9 +25,12 @@ pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_GENERIC_03H;
 /// if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
+type MISO = Pin<gpio::bank0::Gpio4, gpio::FunctionSpi, gpio::PullNone>;
+type MOSI = Pin<gpio::bank0::Gpio7, gpio::FunctionSpi, gpio::PullNone>;
+type SCLK = Pin<gpio::bank0::Gpio6, gpio::FunctionSpi, gpio::PullNone>;
 struct State {
     channels: Option<Channels>,
-    spi: Option<spi::Spi<spi::Enabled, SPI0, 8>>,
+    spi: Option<spi::Spi<spi::Enabled, SPI0, (MOSI, MISO, SCLK), 8>>,
 }
 
 mod testdata {
@@ -92,10 +96,10 @@ mod tests {
         );
 
         // These are implicitly used by the spi driver if they are in the correct mode
-        let _spi_sclk = pins.gpio6.into_mode::<hal::gpio::FunctionSpi>();
-        let _spi_mosi = pins.gpio7.into_mode::<hal::gpio::FunctionSpi>();
-        let _spi_miso = pins.gpio4.into_mode::<hal::gpio::FunctionSpi>();
-        let spi = hal::spi::Spi::<_, _, 8>::new(pac.SPI0);
+        let spi_sclk = pins.gpio6.into();
+        let spi_mosi = pins.gpio7.into();
+        let spi_miso = pins.gpio4.into();
+        let spi = hal::spi::Spi::new(pac.SPI0, (spi_mosi, spi_miso, spi_sclk));
 
         // Exchange the uninitialised SPI driver for an initialised one
         let spi = spi.init(

rp2040-hal/CHANGELOG.md

@@ -19,17 +19,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - multicore: remove the requirement on the closure to never return - #594 @ithinuel
 - Updated dependency on rp2040-boot2 to version 0.3.0. - @jannic
-  - This doubles the flash access speed to the value used by the C SDK by
-    default. So it should usually be safe. However, if you are overclocking
-    the RP2040, you might need to lower the flash speed accordingly.
-- timer: Make sure clocks are initialized before creating a timer - #618 @jannic
+  This doubles the flash access speed to the value used by the C SDK by
+  default. So it should usually be safe. However, if you are overclocking
+  the RP2040, you might need to lower the flash speed accordingly.
 - Doc: Several improvements have been made to documentation: #607 #597
 - DMA: Check for valid word sizes at compile time - #600 @jannic
+- Use an enum for core identification. - @ithinuel
+- Merge DynPin and Pin into Pin. The type class used in Pin now have a runtime variant allowing for
+  the creation of uniform array of pins (eg: `[Pin<DynPinId, PinFnSio, PullDown>]`). - @ithinuel
+- Fix miss defined ValidPinMode bound allowing any Bank0 pin to be Xip and any Qspi pin to be any
+  other function (except for clock). - @ithinuel
+- Use `let _ =` to ignore result rather than `.ok();` as this gives a false sense the result is
+  checked. - @ithinuel
+- Reduce code repetition in i2c modules. - @ithinuel
+- Rename `DontInvert` to `Normal`. - @ithinuel
+- Prevent the creation of multiple instances of `adc::TempSensor` - @ithinuel
 
 ### Added
 
 - timer::Timer implements the embedded-hal delay traits and Copy/Clone - #614 @ithinuel @jannic
 - DMA: Allow access to the DMA engine's byteswapping feature - #603 @Gip-Gip
+- Added `AdcPin` wrapper to disable digital function for ADC operations - @ithinuel
+- Added `Sealed` supertrait to `PIOExt` - @ithinuel
+- Added pins to `Spi` to fix inconsistencies in gpio bounds in peripheral (i2c, uart, spi) - @ithinuel
+- Added `sio::Sio::read_bank0() -> u32` to provide single instruction multiple io read.
 
 ## [0.8.1] - 2023-05-05
 

rp2040-hal/Cargo.toml

@@ -40,6 +40,8 @@ defmt = { version = ">=0.2.0, <0.4", optional = true }
 
 rtic-monotonic = { version = "1.0.0", optional = true }
 
+frunk = { version = "0.4.1", default-features = false }
+
 [dev-dependencies]
 cortex-m-rt = "0.7"
 panic-halt = "0.2.0"

rp2040-hal/examples/adc.rs

@@ -88,8 +88,8 @@ fn main() -> ! {
 
     // UART TX (characters sent from pico) on pin 1 (GPIO0) and RX (on pin 2 (GPIO1)
     let uart_pins = (
-        pins.gpio0.into_mode::<hal::gpio::FunctionUart>(),
-        pins.gpio1.into_mode::<hal::gpio::FunctionUart>(),
+        pins.gpio0.into_function::<hal::gpio::FunctionUart>(),
+        pins.gpio1.into_function::<hal::gpio::FunctionUart>(),
     );
 
     // Create a UART driver
@@ -107,10 +107,10 @@ fn main() -> ! {
     let mut adc = hal::Adc::new(pac.ADC, &mut pac.RESETS);
 
     // Enable the temperature sense channel
-    let mut temperature_sensor = adc.enable_temp_sensor();
+    let mut temperature_sensor = adc.take_temp_sensor().unwrap();
 
     // Configure GPIO26 as an ADC input
-    let mut adc_pin_0 = pins.gpio26.into_floating_input();
+    let mut adc_pin_0 = hal::adc::AdcPin::new(pins.gpio26);
     loop {
         // Read the raw ADC counts from the temperature sensor channel.
         let temp_sens_adc_counts: u16 = adc.read(&mut temperature_sensor).unwrap();

rp2040-hal/examples/dht11.rs

@@ -24,9 +24,7 @@ use rp2040_hal as hal;
 use hal::pac;
 
 // Some traits we need
-use embedded_hal::digital::v2::InputPin;
 use embedded_hal::digital::v2::OutputPin;
-use hal::gpio::dynpin::DynPin;
 use hal::Clock;
 
 /// The linker will place this boot block at the start of our program image. We
@@ -43,48 +41,6 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 use dht_sensor::{dht11, DhtReading};
 
-/// A wrapper for DynPin, implementing both InputPin and OutputPin, to simulate
-/// an open-drain pin as needed by the wire protocol the DHT11 sensor speaks.
-/// https://how2electronics.com/interfacing-dht11-temperature-humidity-sensor-with-raspberry-pi-pico/
-struct InOutPin {
-    inner: DynPin,
-}
-
-impl InOutPin {
-    fn new(inner: DynPin) -> Self {
-        Self { inner }
-    }
-}
-
-impl InputPin for InOutPin {
-    type Error = rp2040_hal::gpio::Error;
-    fn is_high(&self) -> Result<bool, <Self as embedded_hal::digital::v2::InputPin>::Error> {
-        self.inner.is_high()
-    }
-    fn is_low(&self) -> Result<bool, <Self as embedded_hal::digital::v2::InputPin>::Error> {
-        self.inner.is_low()
-    }
-}
-
-impl OutputPin for InOutPin {
-    type Error = rp2040_hal::gpio::Error;
-    fn set_low(&mut self) -> Result<(), <Self as embedded_hal::digital::v2::OutputPin>::Error> {
-        // To actively pull the pin low, it must also be configured as a (readable) output pin
-        self.inner.into_readable_output();
-        // In theory, we should set the pin to low first, to make sure we never actively
-        // pull it up. But if we try it on the input pin, we get Err(Gpio(InvalidPinType)).
-        self.inner.set_low()?;
-        Ok(())
-    }
-    fn set_high(&mut self) -> Result<(), <Self as embedded_hal::digital::v2::OutputPin>::Error> {
-        // To set the open-drain pin to high, just disable the output driver by changing the
-        // pin to input mode with pull-up. That way, the DHT11 can still pull the data line down
-        // to send its response.
-        self.inner.into_pull_up_input();
-        Ok(())
-    }
-}
-
 /// Entry point to our bare-metal application.
 ///
 /// The `#[rp2040_hal::entry]` macro ensures the Cortex-M start-up code calls this function
@@ -128,8 +84,8 @@ fn main() -> ! {
     let mut delay = cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().to_Hz());
 
     // Use GPIO 28 as an InOutPin
-    let mut pin = InOutPin::new(pins.gpio28.into());
-    pin.set_high().ok();
+    let mut pin = hal::gpio::InOutPin::new(pins.gpio28);
+    let _ = pin.set_high();
 
     // Perform a sensor reading
     let _measurement = dht11::Reading::read(&mut delay, &mut pin);

rp2040-hal/examples/gpio_irq_example.rs

@@ -63,11 +63,11 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 // We'll create some type aliases using `type` to help with that
 
 /// This pin will be our output - it will drive an LED if you run this on a Pico
-type LedPin = gpio::Pin<gpio::bank0::Gpio25, gpio::PushPullOutput>;
+type LedPin = gpio::Pin<gpio::bank0::Gpio25, gpio::FunctionSioOutput, gpio::PullNone>;
 
 /// This pin will be our interrupt source.
 /// It will trigger an interrupt if pulled to ground (via a switch or jumper wire)
-type ButtonPin = gpio::Pin<gpio::bank0::Gpio26, gpio::PullUpInput>;
+type ButtonPin = gpio::Pin<gpio::bank0::Gpio26, gpio::FunctionSioInput, gpio::PullUp>;
 
 /// Since we're always accessing these pins together we'll store them in a tuple.
 /// Giving this tuple a type alias means we won't need to use () when putting them
@@ -119,12 +119,12 @@ fn main() -> ! {
     );
 
     // Configure GPIO 25 as an output to drive our LED.
-    // we can use into_mode() instead of into_pull_up_input()
+    // we can use reconfigure() instead of into_pull_up_input()
     // since the variable we're pushing it into has that type
-    let led = pins.gpio25.into_mode();
+    let led = pins.gpio25.reconfigure();
 
     // Set up the GPIO pin that will be our input
-    let in_pin = pins.gpio26.into_mode();
+    let in_pin = pins.gpio26.reconfigure();
 
     // Trigger on the 'falling edge' of the input pin.
     // This will happen as the button is being pressed

rp2040-hal/examples/i2c.rs

@@ -75,9 +75,9 @@ fn main() -> ! {
     );
 
     // Configure two pins as being I²C, not GPIO
-    let sda_pin = pins.gpio18.into_mode::<hal::gpio::FunctionI2C>();
-    let scl_pin = pins.gpio19.into_mode::<hal::gpio::FunctionI2C>();
-    // let not_an_scl_pin = pins.gpio20.into_mode::<hal::gpio::FunctionI2C>();
+    let sda_pin = pins.gpio18.into_function::<hal::gpio::FunctionI2C>();
+    let scl_pin = pins.gpio19.into_function::<hal::gpio::FunctionI2C>();
+    // let not_an_scl_pin = pins.gpio20.into_function::<hal::gpio::FunctionI2C>();
 
     // Create the I²C drive, using the two pre-configured pins. This will fail
     // at compile time if the pins are in the wrong mode, or if this I²C

rp2040-hal/examples/pio_blink.rs

@@ -38,9 +38,9 @@ fn main() -> ! {
     );
 
     // configure LED pin for Pio0.
-    let _led: Pin<_, FunctionPio0> = pins.gpio25.into_mode();
+    let led: Pin<_, FunctionPio0, _> = pins.gpio25.into_function();
     // PIN id for use inside of PIO
-    let led_pin_id = 25;
+    let led_pin_id = led.id().num;
 
     // Define some simple PIO program.
     const MAX_DELAY: u8 = 31;

rp2040-hal/examples/pio_dma.rs

@@ -35,9 +35,9 @@ fn main() -> ! {
     );
 
     // configure LED pin for Pio0.
-    let _led: Pin<_, FunctionPio0> = pins.gpio25.into_mode();
+    let led: Pin<_, FunctionPio0, _> = pins.gpio25.into_function();
     // PIN id for use inside of PIO
-    let led_pin_id = 25;
+    let led_pin_id = led.id().num;
 
     // HELLO WORLD in morse code:
     // .... . .-.. .-.. --- / .-- --- .-. .-.. -..

rp2040-hal/examples/pio_proc_blink.rs

@@ -36,9 +36,9 @@ fn main() -> ! {
     );
 
     // configure LED pin for Pio0.
-    let _led: Pin<_, FunctionPio0> = pins.gpio25.into_mode();
+    let led: Pin<_, FunctionPio0, _> = pins.gpio25.into_function();
     // PIN id for use inside of PIO
-    let led_pin_id = 25;
+    let led_pin_id = led.id().num;
 
     // Define some simple PIO program.
     let program = pio_proc::pio_asm!(

rp2040-hal/examples/pio_side_set.rs

@@ -38,7 +38,7 @@ fn main() -> ! {
     );
 
     // configure LED pin for Pio0.
-    let led: Pin<_, FunctionPio0> = pins.gpio25.into_mode();
+    let led: Pin<_, FunctionPio0, _> = pins.gpio25.into_function();
     // PIN id for use inside of PIO
     let led_pin_id = led.id().num;
 

rp2040-hal/examples/pio_synchronized.rs

@@ -38,12 +38,12 @@ fn main() -> ! {
     );
 
     // configure pins for Pio0.
-    let _: Pin<_, FunctionPio0> = pins.gpio0.into_mode();
-    let _: Pin<_, FunctionPio0> = pins.gpio1.into_mode();
+    let gp0: Pin<_, FunctionPio0, _> = pins.gpio0.into_function();
+    let gp1: Pin<_, FunctionPio0, _> = pins.gpio1.into_function();
 
     // PIN id for use inside of PIO
-    let pin0 = 0;
-    let pin1 = 1;
+    let pin0 = gp0.id().num;
+    let pin1 = gp1.id().num;
 
     // Define some simple PIO program.
     let program = pio_proc::pio_asm!(

rp2040-hal/examples/pwm_irq_input.rs

@@ -63,10 +63,10 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 /// We'll create some type aliases using `type` to help with that
 
 /// This pin will be our output - it will drive an LED if you run this on a Pico
-type LedPin = gpio::Pin<gpio::bank0::Gpio25, gpio::PushPullOutput>;
+type LedPin = gpio::Pin<gpio::bank0::Gpio25, gpio::FunctionSio<gpio::SioOutput>, gpio::PullNone>;
 
 /// This pin will be our input for a 50 Hz servo PWM signal
-type InputPwmPin = gpio::Pin<gpio::bank0::Gpio1, gpio::FunctionPwm>;
+type InputPwmPin = gpio::Pin<gpio::bank0::Gpio1, gpio::FunctionPwm, gpio::PullNone>;
 
 /// This will be our PWM Slice - it will interpret the PWM signal from the pin
 type PwmSlice = pwm::Slice<pwm::Pwm0, pwm::InputHighRunning>;
@@ -134,17 +134,17 @@ fn main() -> ! {
     pwm.enable();
 
     // Connect to GPI O1 as the input to channel B on PWM0
+    let input_pin = pins.gpio1.reconfigure();
     let channel = &mut pwm.channel_b;
-    let input_pin = channel.input_from(pins.gpio1);
     channel.enable();
 
     // Enable an interrupt whenever GPI O1 goes from high to low (the end of a pulse)
     input_pin.set_interrupt_enabled(gpio::Interrupt::EdgeLow, true);
 
     // Configure GPIO 25 as an output to drive our LED.
-    // we can use into_mode() instead of into_pull_up_input()
+    // we can use reconfigure() instead of into_pull_up_input()
     // since the variable we're pushing it into has that type
-    let led = pins.gpio25.into_mode();
+    let led = pins.gpio25.reconfigure();
 
     // Give away our pins by moving them into the `GLOBAL_PINS` variable.
     // We won't need to access them in the main thread again
@@ -193,14 +193,14 @@ fn IO_IRQ_BANK0() {
             // if the PWM signal indicates low, turn off the LED
             if pulse_width_us < LOW_US {
                 // set_low can't fail, but the embedded-hal traits always allow for it
-                // we can discard the Result by transforming it to an Option
-                led.set_low().ok();
+                // we can discard the Result
+                let _ = led.set_low();
             }
             // if the PWM signal indicates low, turn on the LED
             else if pulse_width_us > HIGH_US {
                 // set_high can't fail, but the embedded-hal traits always allow for it
-                // we can discard the Result by transforming it to an Option
-                led.set_high().ok();
+                // we can discard the Result
+                let _ = led.set_high();
             }
 
             // If the PWM signal was in the dead-zone between LOW and HIGH, don't change the LED's

rp2040-hal/examples/rom_funcs.rs

@@ -86,9 +86,9 @@ fn main() -> ! {
 
     let uart_pins = (
         // UART TX (characters sent from RP2040) on pin 1 (GPIO0)
-        pins.gpio0.into_mode::<hal::gpio::FunctionUart>(),
+        pins.gpio0.into_function::<hal::gpio::FunctionUart>(),
         // UART RX (characters received by RP2040) on pin 2 (GPIO1)
-        pins.gpio1.into_mode::<hal::gpio::FunctionUart>(),
+        pins.gpio1.into_function::<hal::gpio::FunctionUart>(),
     );
     let mut uart = hal::uart::UartPeripheral::new(pac.UART0, uart_pins, &mut pac.RESETS)
         .enable(

rp2040-hal/examples/spi.rs

@@ -80,10 +80,10 @@ fn main() -> ! {
     );
 
     // These are implicitly used by the spi driver if they are in the correct mode
-    let _spi_sclk = pins.gpio6.into_mode::<hal::gpio::FunctionSpi>();
-    let _spi_mosi = pins.gpio7.into_mode::<hal::gpio::FunctionSpi>();
-    let _spi_miso = pins.gpio4.into_mode::<hal::gpio::FunctionSpi>();
-    let spi = hal::Spi::<_, _, 8>::new(pac.SPI0);
+    let spi_mosi = pins.gpio7.into_function::<hal::gpio::FunctionSpi>();
+    let spi_miso = pins.gpio4.into_function::<hal::gpio::FunctionSpi>();
+    let spi_sclk = pins.gpio6.into_function::<hal::gpio::FunctionSpi>();
+    let spi = hal::spi::Spi::<_, _, _, 8>::new(pac.SPI0, (spi_mosi, spi_miso, spi_sclk));
 
     // Exchange the uninitialised SPI driver for an initialised one
     let mut spi = spi.init(