docs

va108xx-hal/src/gpio/mod.rs

@@ -1,4 +1,17 @@
 //! GPIO support module.
+//!
+//! Contains abstractions to use the pins provided by the [crate::pins] module as GPIO or
+//! IO peripheral pins.
+//!
+//! The core data structures provided for this are the
+//!
+//! - [Output] for push-pull output pins.
+//! - [Input] for input pins.
+//! - [Flex] for pins with flexible configuration requirements.
+//! - [IoPeriphPin] for IO peripheral pins.
+//!
+//! The [crate::pins] module exposes singletons to access the [Pin]s required by this module
+//! in a type-safe way.
 pub use vorago_shared_periphs::gpio::*;
 
 pub use vorago_shared_periphs::gpio::asynch;

va108xx-hal/src/pins.rs

@@ -1,3 +1,8 @@
+//! Pin resource management singletons.
+//!
+//! This module contains the pin singletons. It allows creating those singletons
+//! to access the [Pin] structures of individual ports in a safe way with checked ownership
+//! rules.
 use vorago_shared_periphs::sysconfig::reset_peripheral_for_cycles;
 
 pub use crate::gpio::{Pin, PinId, PinIdProvider, Port};

vorago-shared-periphs/src/gpio/ll.rs

@@ -10,6 +10,9 @@ pub use crate::Port;
 pub use crate::ioconfig::regs::Pull;
 use crate::ioconfig::regs::{FunSel, IoConfig, MmioIoConfig};
 
+use super::Pin;
+use super::PinIdProvider;
+
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum InterruptEdge {
@@ -25,14 +28,17 @@ pub enum InterruptLevel {
     High = 1,
 }
 
+/// Pin identifier for all physical pins exposed by Vorago MCUs.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct PinId {
     port: Port,
+    /// Offset within the port.
     offset: u8,
 }
 
 impl PinId {
+    /// Unchecked constructor which panics on invalid offsets.
     pub const fn new_unchecked(port: Port, offset: usize) -> Self {
         if offset >= port.max_offset() {
             panic!("Pin ID construction: offset is out of range");
@@ -62,6 +68,7 @@ impl PinId {
     }
 }
 
+/// Low-level driver structure for GPIO pins.
 pub struct LowLevelGpio {
     gpio: super::regs::MmioGpio<'static>,
     ioconfig: MmioIoConfig<'static>,
@@ -78,6 +85,14 @@ impl core::fmt::Debug for LowLevelGpio {
 }
 
 impl LowLevelGpio {
+    /// Create a new low-level GPIO pin instance from a given [Pin].
+    ///
+    /// Can be used for performing resource management of the [Pin]s.
+    pub fn new_with_pin<I: PinIdProvider>(_pin: Pin<I>) -> Self {
+        Self::new(I::ID)
+    }
+
+    /// Create a new low-level GPIO pin instance using only the [PinId].
     pub fn new(id: PinId) -> Self {
         LowLevelGpio {
             gpio: super::regs::Gpio::new_mmio(id.port),

vorago-shared-periphs/src/gpio/mod.rs

@@ -1,3 +1,4 @@
+//! GPIO support module.
 use core::convert::Infallible;
 
 pub use crate::ioconfig::{FilterClkSel, FilterType, regs::FunSel};
@@ -8,10 +9,15 @@ pub mod asynch;
 pub mod ll;
 pub mod regs;
 
+/// Trait implemented by data structures assocaited with pin identifiacation.
 pub trait PinIdProvider {
     const ID: ll::PinId;
 }
 
+/// Primary Pin structure for the physical pins exposed by Vorago MCUs.
+///
+/// This pin structure is only used for resource management and does not do anything on its
+/// own.
 pub struct Pin<I: PinIdProvider> {
     phantom: core::marker::PhantomData<I>,
 }
@@ -23,8 +29,19 @@ impl<I: PinIdProvider> Pin<I> {
             phantom: core::marker::PhantomData,
         }
     }
+
+    /// Create a new pin instance.
+    ///
+    /// # Safety
+    ///
+    /// This circumvents ownership rules of the HAL and allows creating multiple instances
+    /// of the same pins.
+    pub const unsafe fn steal() -> Self {
+        Self::new()
+    }
 }
 
+/// Push-Pull output pin.
 #[derive(Debug)]
 pub struct Output(ll::LowLevelGpio);
 
@@ -104,6 +121,9 @@ impl embedded_hal::digital::StatefulOutputPin for Output {
     }
 }
 
+/// Input pin.
+///
+/// Can be created as a floating input pin or as an input pin with pull-up or pull-down.
 #[derive(Debug)]
 pub struct Input(ll::LowLevelGpio);
 
@@ -194,6 +214,16 @@ impl PinMode {
     }
 }
 
+/// Flex pin abstraction which can be dynamically re-configured.
+///
+/// The following functions can be configured at run-time:
+///
+///  - Input Floating
+///  - Input with Pull-Up
+///  - Output Push-Pull
+///  - Output Open-Drain.
+///
+/// Flex pins are always floating input pins after construction.
 #[derive(Debug)]
 pub struct Flex {
     ll: ll::LowLevelGpio,
@@ -304,6 +334,9 @@ impl embedded_hal::digital::StatefulOutputPin for Flex {
     }
 }
 
+/// IO peripheral pin structure.
+///
+/// Can be used to configure pins as IO peripheral pins.
 pub struct IoPeriphPin {
     ll: ll::LowLevelGpio,
     fun_sel: FunSel,

vorago-shared-periphs/src/lib.rs

@@ -45,6 +45,7 @@ cfg_if::cfg_if! {
     }
 }
 
+/// GPIO port enumeration.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Port {