Recommendations for GPIO Interfaces

Pin types are zero-sized by default (C-ZST-PIN)

GPIO Interfaces exposed by the HAL should provide dedicated zero-sized types for each pin on every interface or port, resulting in a zero-cost GPIO abstraction when all pin assignments are statically known.

Each GPIO Interface or Port should implement a split method returning a struct with every pin.

Example:

  1. #![allow(unused)]
  2. fn main() {
  3. pub struct PA0;
  4. pub struct PA1;
  5. // ...
  7. pub struct PortA;
  9. impl PortA {
  10.     pub fn split(self) -> PortAPins {
  11.         PortAPins {
  12.             pa0: PA0,
  13.             pa1: PA1,
  14.             // ...
  15.         }
  16.     }
  17. }
  19. pub struct PortAPins {
  20.     pub pa0: PA0,
  21.     pub pa1: PA1,
  22.     // ...
  23. }
  24. }

Pin types provide methods to erase pin and port (C-ERASED-PIN)

Pins should provide type erasure methods that move their properties from compile time to runtime, and allow more flexibility in applications.

Example:

  1. #![allow(unused)]
  2. fn main() {
  3. /// Port A, pin 0.
  4. pub struct PA0;
  6. impl PA0 {
  7.     pub fn erase_pin(self) -> PA {
  8.         PA { pin: 0 }
  9.     }
  10. }
  12. /// A pin on port A.
  13. pub struct PA {
  14.     /// The pin number.
  15.     pin: u8,
  16. }
  18. impl PA {
  19.     pub fn erase_port(self) -> Pin {
  20.         Pin {
  21.             port: Port::A,
  22.             pin: self.pin,
  23.         }
  24.     }
  25. }
  27. pub struct Pin {
  28.     port: Port,
  29.     pin: u8,
  30.     // (these fields can be packed to reduce the memory footprint)
  31. }
  33. enum Port {
  34.     A,
  35.     B,
  36.     C,
  37.     D,
  38. }
  39. }

Pin state should be encoded as type parameters (C-PIN-STATE)

Pins may be configured as input or output with different characteristics depending on the chip or family. This state should be encoded in the type system to prevent use of pins in incorrect states.

Additional, chip-specific state (eg. drive strength) may also be encoded in this way, using additional type parameters.

Methods for changing the pin state should be provided as into_input and into_output methods.

Additionally, with_{input,output}_state methods should be provided that temporarily reconfigure a pin in a different state without moving it.

The following methods should be provided for every pin type (that is, both erased and non-erased pin types should provide the same API):

  • pub fn into_input<N: InputState>(self, input: N) -> Pin<N>
  • pub fn into_output<N: OutputState>(self, output: N) -> Pin<N>

  • pub fn with_input_state<N: InputState, R>( &mut self, input: N, f: impl FnOnce(&mut PA1<N>) -> R, ) -> R

  • pub fn with_output_state<N: OutputState, R>( &mut self, output: N, f: impl FnOnce(&mut PA1<N>) -> R, ) -> R

Pin state should be bounded by sealed traits. Users of the HAL should have no need to add their own state. The traits can provide HAL-specific methods required to implement the pin state API.

Example:

  1. #![allow(unused)]
  2. fn main() {
  3. use std::marker::PhantomData;
  4. mod sealed {
  5.     pub trait Sealed {}
  6. }
  8. pub trait PinState: sealed::Sealed {}
  9. pub trait OutputState: sealed::Sealed {}
  10. pub trait InputState: sealed::Sealed {
  11.     // ...
  12. }
  14. pub struct Output<S: OutputState> {
  15.     _p: PhantomData<S>,
  16. }
  18. impl<S: OutputState> PinState for Output<S> {}
  19. impl<S: OutputState> sealed::Sealed for Output<S> {}
  21. pub struct PushPull;
  22. pub struct OpenDrain;
  24. impl OutputState for PushPull {}
  25. impl OutputState for OpenDrain {}
  26. impl sealed::Sealed for PushPull {}
  27. impl sealed::Sealed for OpenDrain {}
  29. pub struct Input<S: InputState> {
  30.     _p: PhantomData<S>,
  31. }
  33. impl<S: InputState> PinState for Input<S> {}
  34. impl<S: InputState> sealed::Sealed for Input<S> {}
  36. pub struct Floating;
  37. pub struct PullUp;
  38. pub struct PullDown;
  40. impl InputState for Floating {}
  41. impl InputState for PullUp {}
  42. impl InputState for PullDown {}
  43. impl sealed::Sealed for Floating {}
  44. impl sealed::Sealed for PullUp {}
  45. impl sealed::Sealed for PullDown {}
  47. pub struct PA1<S: PinState> {
  48.     _p: PhantomData<S>,
  49. }
  51. impl<S: PinState> PA1<S> {
  52.     pub fn into_input<N: InputState>(self, input: N) -> PA1<Input<N>> {
  53.         todo!()
  54.     }
  56.     pub fn into_output<N: OutputState>(self, output: N) -> PA1<Output<N>> {
  57.         todo!()
  58.     }
  60.     pub fn with_input_state<N: InputState, R>(
  61.         &mut self,
  62.         input: N,
  63.         f: impl FnOnce(&mut PA1<N>) -> R,
  64.     ) -> R {
  65.         todo!()
  66.     }
  68.     pub fn with_output_state<N: OutputState, R>(
  69.         &mut self,
  70.         output: N,
  71.         f: impl FnOnce(&mut PA1<N>) -> R,
  72.     ) -> R {
  73.         todo!()
  74.     }
  75. }
  77. // Same for `PA` and `Pin`, and other pin types.
  78. }