Consolidate PinPortIncompatibleError pattern

Return the pin object so the users could try again. We should be able to
share this error return pattern.

Author: mciantyre

src/chip/drivers/adc.rs

@@ -105,10 +105,7 @@ pub enum ResolutionBits {
     Res12,
 }
 
-/// Error returned when a pin is not compatible with an ADC port.
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct PinPortIncompatibleError(());
+pub use crate::PinPortIncompatibleError;
 
 /// A pin representing an analog input for an ADC.
 ///
@@ -192,13 +189,16 @@ impl Adc {
     ///
     /// The pin is consumed to ensure it's properly configured as an
     /// ADC input. If the pin isn't compatible with this ADC bank,
-    /// the return is `None`.
-    pub fn input<P, const N: u8>(&self, mut pin: P) -> Result<AnalogInput, PinPortIncompatibleError>
+    /// the pin is returned inside the error so you can recover it.
+    pub fn input<P, const N: u8>(
+        &self,
+        mut pin: P,
+    ) -> Result<AnalogInput, PinPortIncompatibleError<P>>
     where
         P: Pin<N>,
     {
         if self.instance() != N {
-            return Err(PinPortIncompatibleError(()));
+            return Err(PinPortIncompatibleError(pin));
         }
         prepare(&mut pin);
         Ok(AnalogInput { channel: P::INPUT })

src/chip/drivers/gpio.rs

@@ -34,14 +34,11 @@
 
 use crate::{iomuxc, ral};
 
+pub use crate::PinPortIncompatibleError;
+
 /// Any GPIO instance.
 type AnyInstance = crate::AnyInstance<ral::gpio::RegisterBlock>;
 
-/// Error returned when a pin is not compatible with a GPIO port.
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct PinPortIncompatibleError(());
-
 /// GPIO ports.
 pub struct Port {
     gpio: AnyInstance,
@@ -68,12 +65,16 @@ impl Port {
     ///
     /// Returns an error if the pin is not compatible with this GPIO port
     /// (i.e., the pin's GPIO module number does not match the port's instance).
-    pub fn output<P, const N: u8>(&mut self, mut pin: P) -> Result<Output, PinPortIncompatibleError>
+    /// The pin is returned inside the error so you can recover it.
+    pub fn output<P, const N: u8>(
+        &mut self,
+        mut pin: P,
+    ) -> Result<Output, PinPortIncompatibleError<P>>
     where
         P: iomuxc::gpio::Pin<N>,
     {
         if N != self.instance() {
-            return Err(PinPortIncompatibleError(()));
+            return Err(PinPortIncompatibleError(pin));
         }
         iomuxc::gpio::prepare(&mut pin);
         Ok(Output::new(self.duplicate_instance(), P::OFFSET))
@@ -83,12 +84,16 @@ impl Port {
     ///
     /// Returns an error if the pin is not compatible with this GPIO port
     /// (i.e., the pin's GPIO module number does not match the port's instance).
-    pub fn input<P, const N: u8>(&mut self, mut pin: P) -> Result<Input, PinPortIncompatibleError>
+    /// The pin is returned inside the error so you can recover it.
+    pub fn input<P, const N: u8>(
+        &mut self,
+        mut pin: P,
+    ) -> Result<Input, PinPortIncompatibleError<P>>
     where
         P: iomuxc::gpio::Pin<N>,
     {
         if N != self.instance() {
-            return Err(PinPortIncompatibleError(()));
+            return Err(PinPortIncompatibleError(pin));
         }
         iomuxc::gpio::prepare(&mut pin);
         Ok(Input::new(self.duplicate_instance(), P::OFFSET))
@@ -107,7 +112,7 @@ impl Port {
         &mut self,
         input: &Input,
         trigger: Option<Trigger>,
-    ) -> Result<(), PinPortIncompatibleError> {
+    ) -> Result<(), PinPortIncompatibleError<()>> {
         if !crate::is_same_instance(&self.gpio, &input.gpio) {
             return Err(PinPortIncompatibleError(()));
         }

src/chip/drivers/rgpio.rs

@@ -31,14 +31,11 @@
 
 use crate::{iomuxc, ral};
 
+pub use crate::PinPortIncompatibleError;
+
 /// Any RGPIO instance.
 type AnyInstance = crate::AnyInstance<ral::rgpio::RegisterBlock>;
 
-/// Error returned when a pin is not compatible with a GPIO port.
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct PinPortIncompatibleError(());
-
 /// GPIO ports.
 pub struct Port {
     gpio: AnyInstance,
@@ -65,12 +62,16 @@ impl Port {
     ///
     /// Returns an error if the pin is not compatible with this GPIO port
     /// (i.e., the pin's GPIO module number does not match the port's instance).
-    pub fn output<P, const N: u8>(&mut self, mut pin: P) -> Result<Output, PinPortIncompatibleError>
+    /// The pin is returned inside the error so you can recover it.
+    pub fn output<P, const N: u8>(
+        &mut self,
+        mut pin: P,
+    ) -> Result<Output, PinPortIncompatibleError<P>>
     where
         P: iomuxc::gpio::Pin<N>,
     {
         if N != self.instance() {
-            return Err(PinPortIncompatibleError(()));
+            return Err(PinPortIncompatibleError(pin));
         }
         iomuxc::gpio::prepare(&mut pin);
         Ok(Output::new(self.duplicate_instance(), P::OFFSET))
@@ -80,12 +81,16 @@ impl Port {
     ///
     /// Returns an error if the pin is not compatible with this GPIO port
     /// (i.e., the pin's GPIO module number does not match the port's instance).
-    pub fn input<P, const N: u8>(&mut self, mut pin: P) -> Result<Input, PinPortIncompatibleError>
+    /// The pin is returned inside the error so you can recover it.
+    pub fn input<P, const N: u8>(
+        &mut self,
+        mut pin: P,
+    ) -> Result<Input, PinPortIncompatibleError<P>>
     where
         P: iomuxc::gpio::Pin<N>,
     {
         if N != self.instance() {
-            return Err(PinPortIncompatibleError(()));
+            return Err(PinPortIncompatibleError(pin));
         }
         iomuxc::gpio::prepare(&mut pin);
         Ok(Input::new(self.duplicate_instance(), P::OFFSET))

src/lib.rs

@@ -317,6 +317,31 @@ fn spin_on<F: core::future::Future>(future: F) -> F::Output {
     }
 }
 
+/// The wrapped pin is not compatible with this peripheral instance.
+///
+/// If `P` is `()`, it indicates that the caller's pin was incompatible with the
+/// peripheral, but the method did not take ownership of a pin.
+pub struct PinPortIncompatibleError<P>(P);
+impl<P> PinPortIncompatibleError<P> {
+    /// Acquire the pin from this error.
+    pub fn pin(self) -> P {
+        self.0
+    }
+}
+
+impl<P> core::fmt::Debug for PinPortIncompatibleError<P> {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str("PinPortIncompatibleError")
+    }
+}
+
+#[cfg(feature = "defmt")]
+impl<P> defmt::Format for PinPortIncompatibleError<P> {
+    fn format(&self, f: defmt::Formatter) {
+        defmt::write!(f, "PinPortIncompatibleError")
+    }
+}
+
 /// The peripheral instance for when we don't care.
 const HAL_INST: u8 = 0xff;