Document the gpio module and tweak visibility

Author: phil-opp

src/gpio/mod.rs

@@ -1,3 +1,5 @@
+//! Abstractions for GPIO ports.
+
 use core::marker::PhantomData;
 
 pub use self::port::*;
@@ -6,32 +8,41 @@ pub use self::traits::*;
 mod port;
 mod traits;
 
-#[derive(Debug)]
-pub enum Error {
-    PinAlreadyInUse(PinNumber),
-}
-
+/// The different possible modes of a GPIO pin.
 #[derive(Debug, Clone, Copy)]
 pub enum Mode {
+    /// Use the pin for receiving data.
     Input,
+    /// Use the pin for sending data.
     Output,
+    /// Activate an alternate function of the pin to make it usable to some connected device.
     Alternate,
+    /// Use the pin in analog mode.
     Analog,
 }
 
+/// Pull the pin value up or down.
 #[derive(Debug, Clone, Copy)]
 pub enum Resistor {
+    /// Don't pull the value.
     NoPull,
+    /// Pull the value to 1 if no data is sent/received.
     PullUp,
+    /// Pull the value to 0 if no data is sent/received.
     PullDown,
 }
 
+/// The output mode of the pin.
 #[derive(Debug, Clone, Copy)]
 pub enum OutputType {
+    /// Use push-pull mode.
     PushPull,
+    /// Use open drain mode.
     OpenDrain,
 }
 
+/// The different output speeds.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 pub enum OutputSpeed {
     Low,
@@ -40,6 +51,10 @@ pub enum OutputSpeed {
     VeryHigh,
 }
 
+/// The possible alternate functions.
+///
+/// The alternate function number that a device uses is specified in the manual.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 pub enum AlternateFunction {
     AF0,
@@ -60,6 +75,8 @@ pub enum AlternateFunction {
     AF15,
 }
 
+/// The 16 possible pin numbers.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum PinNumber {
@@ -81,10 +98,13 @@ pub enum PinNumber {
     Pin15,
 }
 
+/// High level abstraction of a GPIO pin configured as input.
 pub trait InputPin: Sized {
+    /// Get the current input value of the pin.
     fn get(&self) -> bool;
 }
 
+/// An implementation of the `InputPin` trait for the IDR abstractions of this module.
 pub struct InputPinImpl<'a, IDR: IdrTrait + 'a> {
     pin: PinNumber,
     input_data: ReadOnlyIdr<'a, IDR>,
@@ -111,17 +131,22 @@ impl<'a, IDR: IdrTrait> ReadOnlyIdr<'a, IDR> {
 unsafe impl<'a, IDR: IdrTrait> Sync for ReadOnlyIdr<'a, IDR> {}
 unsafe impl<'a, IDR: IdrTrait> Send for ReadOnlyIdr<'a, IDR> {}
 
+/// High level abstraction of a GPIO pin configured as output.
 pub trait OutputPin: Sized {
+    /// Get the current output value of the pin.
     fn get(&self) -> bool;
 
+    /// Set the output value of the pin.
     fn set(&mut self, value: bool);
 
+    /// Toggle the output value of the pin.
     fn toggle(&mut self) {
         let current = self.get();
         self.set(!current);
     }
 }
 
+/// An implementation of the `OutputPin` trait for the ODR and BSRR abstractions of this module.
 pub struct OutputPinImpl<'a, ODR: OdrTrait + 'a, BSRR: BsrrTrait + 'a> {
     pin: PinNumber,
     output_data: ReadOnlyOdr<'a, ODR>,
@@ -143,7 +168,7 @@ where
     }
 }
 
-pub struct ReadOnlyOdr<'a, ODR: OdrTrait>(&'a ODR);
+struct ReadOnlyOdr<'a, ODR: OdrTrait>(&'a ODR);
 
 impl<'a, ODR: OdrTrait> ReadOnlyOdr<'a, ODR> {
     fn read(&self) -> ODR::R {

src/gpio/port.rs

@@ -2,11 +2,24 @@ use super::*;
 use core::marker::PhantomData;
 use stm32f7::stm32f7x6::{gpioa, gpiob, gpiod};
 
+/// Abstraction for a GPIO port that allows safe configuration of the port's pins.
 pub struct GpioPort<T> {
     pub(super) pin_in_use: [bool; 16],
     register_block: T,
 }
 
+/// Errors that can occur during pin initialization.
+#[derive(Debug)]
+pub enum Error {
+    /// The specified GPIO pin is already in use.
+    PinAlreadyInUse(PinNumber),
+}
+
+/// A generic struct representing a hardware GPIO register block.
+///
+/// This struct is needed because the GPIO A, GPIO B, and the other GPIO ports have slight
+/// differences in their reset values so that the SVD file and svd2rust use different types
+/// for them.
 pub struct RegisterBlock<'a, I: 'a, O: 'a, M: 'a, P: 'a, B: 'a, T: 'a, S: 'a, AH: 'a, AL: 'a> {
     idr: &'a I,
     odr: &'a O,
@@ -19,6 +32,7 @@ pub struct RegisterBlock<'a, I: 'a, O: 'a, M: 'a, P: 'a, B: 'a, T: 'a, S: 'a, AH
     afrl: &'a AL,
 }
 
+/// An instantiation of the generic `RegisterBlock` for GPIO port A.
 pub type RegisterBlockA<'a> = RegisterBlock<
     'a,
     gpioa::IDR,
@@ -31,6 +45,8 @@ pub type RegisterBlockA<'a> = RegisterBlock<
     gpioa::AFRH,
     gpioa::AFRL,
 >;
+
+/// An instantiation of the generic `RegisterBlock` for GPIO port B.
 pub type RegisterBlockB<'a> = RegisterBlock<
     'a,
     gpiob::IDR,
@@ -43,6 +59,8 @@ pub type RegisterBlockB<'a> = RegisterBlock<
     gpiob::AFRH,
     gpiob::AFRL,
 >;
+
+/// An instantiation of the generic `RegisterBlock` for the remaining GPIO ports.
 pub type RegisterBlockD<'a> = RegisterBlock<
     'a,
     gpiod::IDR,
@@ -76,39 +94,64 @@ macro_rules! new_gpio_port {
 }
 
 impl<'a> GpioPort<RegisterBlockA<'a>> {
+    /// Create a new `RegisterBlockA` from the hardware register block.
     pub fn new_a(register_block: &'a gpioa::RegisterBlock) -> Self {
         new_gpio_port!(register_block)
     }
 }
 
 impl<'a> GpioPort<RegisterBlockB<'a>> {
+    /// Create a new `RegisterBlockB` from the hardware register block.
     pub fn new_b(register_block: &'a gpiob::RegisterBlock) -> Self {
         new_gpio_port!(register_block)
     }
 }
 
 impl<'a> GpioPort<RegisterBlockD<'a>> {
+    /// Create a new `RegisterBlockD` from the hardware register block.
     pub fn new(register_block: &'a gpiod::RegisterBlock) -> Self {
         new_gpio_port!(register_block)
     }
 }
 
+/// This trait allows generic functions that work on all three register block types.
 pub trait RegisterBlockTrait<'a> {
+    /// The IDR (input data register) type, returned by the `idr` function.
     type Idr: IdrTrait + 'a;
+
+    /// The ODR (output data register) type, returned by the `odr` function.
     type Odr: OdrTrait + 'a;
+
+    /// The BSRR (bit set and reset register) type, returned by the `bsrr` function.
     type Bsrr: BsrrTrait + 'a;
 
+    /// Returns a reference to the input data register.
     fn idr(&self) -> &'a Self::Idr;
+
+    /// Returns a reference to the output data register.
     fn odr(&self) -> &'a Self::Odr;
+
+    /// Returns a reference to the bit set and reset register.
     fn bsrr(&self) -> &'a Self::Bsrr;
+
+    /// Set the mode register for the specified pins to the given `Mode`.
     fn set_mode(&mut self, pins: &[PinNumber], mode: Mode);
+
+    /// Set the resistor register for the specified pins to the given `Resistor`.
     fn set_resistor(&mut self, pins: &[PinNumber], resistor: Resistor);
+
+    /// Set the output type register for the specified pins to the given `OutputType`.
     fn set_out_type(&mut self, pins: &[PinNumber], out_type: OutputType);
+
+    /// Set the output speed register for the specified pins to the given `OutputSpeed`.
     fn set_out_speed(&mut self, pins: &[PinNumber], out_speed: OutputSpeed);
+
+    /// Set the alternate function register for the specified pins to the given `AlternateFunction`.
     fn set_alternate_fn(&mut self, pins: &[PinNumber], alternate_fn: AlternateFunction);
 }
 
 impl<'a, T: RegisterBlockTrait<'a>> GpioPort<T> {
+    /// Initialize the specified pin as an input pin.
     pub fn to_input(
         &mut self,
         pin: PinNumber,
@@ -125,6 +168,7 @@ impl<'a, T: RegisterBlockTrait<'a>> GpioPort<T> {
         })
     }
 
+    /// Initialize the specified pin as an output pin.
     pub fn to_output(
         &mut self,
         pin: PinNumber,
@@ -150,6 +194,7 @@ impl<'a, T: RegisterBlockTrait<'a>> GpioPort<T> {
         Ok(output_pin)
     }
 
+    /// Initialize the specified pin as an alternate function pin.
     pub fn to_alternate_function(
         &mut self,
         pin: PinNumber,
@@ -161,6 +206,7 @@ impl<'a, T: RegisterBlockTrait<'a>> GpioPort<T> {
         self.to_alternate_function_all(&[pin], alternate_fn, typ, speed, resistor)
     }
 
+    /// Initialize the specified pins as alternate function pins.
     pub fn to_alternate_function_all(
         &mut self,
         pins: &[PinNumber],

src/gpio/traits.rs

@@ -1,37 +1,67 @@
 use super::PinNumber;
 use stm32f7::stm32f7x6::{gpioa, gpiob, gpiod};
 
+/// Abstracts over the three different types of input data registers (IDRs).
+///
+/// The GPIO ports A and B have separate IDR types because they use slightly different
+/// reset values. This trait allows to create generic functions that work with all three
+/// IDR types.
 pub trait IdrTrait {
+    /// Represents an IDR value.
     type R: IdrR;
 
+    /// Read the current value from the IDR register.
     fn read(&self) -> Self::R;
 }
 
+/// Represents an IDR value that specifies the input value of all pins of the port.
 pub trait IdrR {
+    /// Returns the input value of the specified pin.
     fn get(&self, pin: PinNumber) -> bool;
 }
 
+/// Abstracts over the three different types of output data registers (ODRs).
+///
+/// The GPIO ports A and B have separate ODR types because they use slightly different
+/// reset values. This trait allows to create generic functions that work with all three
+/// ODR types.
 pub trait OdrTrait {
+    /// Represents an ODR value.
     type R: OdrR;
 
+    /// Read the current value from the ODR register.
     fn read(&self) -> Self::R;
 }
 
+/// Represents an ODR value that specifies the output value of all pins of the port.
 pub trait OdrR {
+    /// Returns the output value of the specified pin.
     fn get(&self, pin: PinNumber) -> bool;
 }
 
+/// Abstracts over the three different types of bit set and reset registers (BSRRs).
+///
+/// The GPIO ports A and B have separate BSRR types because they use slightly different
+/// reset values. This trait allows to create generic functions that work with all three
+/// BSRR types.
 pub trait BsrrTrait {
+    /// A type that allows BSRR write operations.
     type W: BsrrW;
 
+    /// Perform write operations on the BSRR register.
     fn write<F>(&mut self, f: F)
     where
         F: FnOnce(&mut Self::W) -> &mut Self::W;
 }
 
+/// Allows writing the BSRR register.
+///
+/// Bits that are neither `set` or `reset` keep their previous value.
 pub trait BsrrW {
+    /// Set the output value of the specified pin to 1.
     fn set(&mut self, pin: PinNumber) -> &mut Self;
 
+    /// Set the output value of the specified pin to 0.
     fn reset(&mut self, pin: PinNumber) -> &mut Self;
 }