imxrt-hal 0.5.0

//! General purpose I/O.
//!
//! Create a [`Port`](Port) over a RAL GPIO instance. Then, use the `Port` to
//! allocate GPIO outputs and inputs.
//!
//! Use [`Output`](Output) to drive GPIO outputs. Use [`Input`](Input) to read
//! GPIO pin states, and trigger interrupts when GPIO states change.
//!
//! # Interior mutability
//!
//! Methods on `Output` and `Input` take immutable references, `&self`. The hardware
//! guarantees that these operations can occur without data races. Methods that
//! require multiple operations on a register are implemented on the `Port`, and
//! take the GPIO by reference.
//!
//! # Example
//!
//! ```no_run
//! use imxrt_hal::gpio::Port;
//! use imxrt_ral::gpio::GPIO2;
//!
//! let mut gpio2 = Port::new(unsafe { GPIO2::instance() });
//! let gpio_b0_04 = // Handle to GPIO_B0_04 IOMUXC pin, provided by BSP or higher-level HAL...
//!     # unsafe { imxrt_iomuxc::imxrt1060::gpio_b0::GPIO_B0_04::new() };
//!
//! let output = gpio2.output(gpio_b0_04);
//! output.set();
//! output.clear();
//! output.toggle();
//!
//! let input = gpio2.input(output.release());
//! assert!(input.is_set());
//! ```
//! # TODO
//!
//! - Fast GPIOs

use crate::{iomuxc, ral};

/// GPIO ports.
pub struct Port<const N: u8> {
    gpio: ral::gpio::Instance<N>,
}

impl<const N: u8> Port<N> {
    /// Create a GPIO port that can allocate and convert GPIOs.
    pub fn new(gpio: ral::gpio::Instance<N>) -> Self {
        Self { gpio }
    }

    fn register_block(&self) -> &'static ral::gpio::RegisterBlock {
        let register_block: &ral::gpio::RegisterBlock = &self.gpio;
        // Safety: points to peripheral memory, which is static.
        // Gpio implementation guarantees that memory which needs
        // mutable access to shared GPIO registers passes through
        // the Port type.
        let register_block: &'static ral::gpio::RegisterBlock =
            unsafe { core::mem::transmute(register_block) };
        register_block
    }

    /// Allocate an output GPIO.
    pub fn output<P>(&mut self, mut pin: P) -> Output<P>
    where
        P: iomuxc::gpio::Pin<N>,
    {
        iomuxc::gpio::prepare(&mut pin);
        Output::new(pin, self.register_block(), P::OFFSET)
    }

    /// Allocate an input GPIO.
    pub fn input<P>(&mut self, mut pin: P) -> Input<P>
    where
        P: iomuxc::gpio::Pin<N>,
    {
        iomuxc::gpio::prepare(&mut pin);
        Input::new(pin, self.register_block(), P::OFFSET)
    }

    /// Enable or disable GPIO input interrupts.
    ///
    /// Specify `None` to disable interrupts. Or, provide a trigger
    /// to configure the interrupt.
    pub fn set_interrupt<P>(&mut self, pin: &Input<P>, trigger: Option<Trigger>) {
        self.set_interrupt_enable(pin, false);
        if let Some(trigger) = trigger {
            self.set_interrupt_trigger(pin, trigger);
            self.set_interrupt_enable(pin, true);
        }
    }

    /// Set the GPIO input interrupt trigger for the provided input pin.
    fn set_interrupt_trigger<P>(&mut self, pin: &Input<P>, trigger: Trigger) {
        if Trigger::EitherEdge == trigger {
            ral::modify_reg!(ral::gpio, self.gpio, EDGE_SEL, |edge_sel| {
                edge_sel | pin.mask()
            });
        } else {
            ral::modify_reg!(ral::gpio, self.gpio, EDGE_SEL, |edge_sel| {
                edge_sel & !pin.mask()
            });
            let icr = trigger as u32;
            let icr_modify = |reg| reg & !(0b11 << pin.icr_offset()) | (icr << pin.icr_offset());
            if pin.offset < 16 {
                ral::modify_reg!(ral::gpio, self.gpio, ICR1, icr_modify);
            } else {
                ral::modify_reg!(ral::gpio, self.gpio, ICR2, icr_modify);
            }
        }
    }

    /// Enable (`true`) or disable (`false`) interrupt generation.
    fn set_interrupt_enable<P>(&mut self, pin: &Input<P>, enable: bool) {
        if enable {
            ral::modify_reg!(ral::gpio, self.gpio, IMR, |imr| imr | pin.mask());
        } else {
            ral::modify_reg!(ral::gpio, self.gpio, IMR, |imr| imr & !pin.mask());
        }
    }
}

/// An output GPIO.
pub struct Output<P> {
    pin: P,
    // Logical ownership:
    // - DR: read only
    // - DR_SET, DR_CLEAR, DR_TOGGLE: write 1 to set value in DR
    gpio: &'static ral::gpio::RegisterBlock,
    offset: u32,
}

// Safety: an output pin is safe to send across execution contexts,
// because it points to static memory.
unsafe impl<P: Send> Send for Output<P> {}

impl<P> Output<P> {
    fn new(pin: P, gpio: &'static ral::gpio::RegisterBlock, offset: u32) -> Self {
        let output = Self { pin, gpio, offset };
        ral::modify_reg!(ral::gpio, gpio, GDIR, |gdir| gdir | output.mask());
        output
    }

    const fn mask(&self) -> u32 {
        1 << self.offset
    }

    /// Set the GPIO high.
    pub fn set(&self) {
        // Atomic write, OK to take immutable reference.
        ral::write_reg!(ral::gpio, self.gpio, DR_SET, self.mask());
    }

    /// Set the GPIO low.
    pub fn clear(&self) {
        // Atomic write, OK to take immutable reference.
        ral::write_reg!(ral::gpio, self.gpio, DR_CLEAR, self.mask());
    }

    /// Alternate the GPIO pin output.
    ///
    /// `toggle` is implemented in hardware, so it will be more efficient
    /// than implementing in software.
    pub fn toggle(&self) {
        // Atomic write, OK to take immutable reference.
        ral::write_reg!(ral::gpio, self.gpio, DR_TOGGLE, self.mask());
    }

    /// Returns `true` if the GPIO is set.
    pub fn is_set(&self) -> bool {
        ral::read_reg!(ral::gpio, self.gpio, DR) & self.mask() != 0
    }

    /// Release the underlying pin object.
    pub fn release(self) -> P {
        self.pin
    }

    /// Access the underlying pin.
    pub fn pin(&self) -> &P {
        &self.pin
    }

    /// Mutably access the underling pin.
    pub fn pin_mut(&mut self) -> &mut P {
        &mut self.pin
    }
}

impl Output<()> {
    /// Allocate an output GPIO without a pin.
    ///
    /// Prefer using [`Port::output`](Port::output) to create a GPIO ouptut with a
    /// pin resource. That method ensures that pin resources are managed throughout
    /// your program, and that the pin is configured to operate as a GPIO output.
    ///
    /// You may use this method to allocate duplicate `Output` object for the same
    /// physical GPIO output. This is considered safe, since the `Output` API is
    /// reentrant.
    ///
    /// If you use this constructor, you're responsible for configuring the IOMUX
    /// multiplexer register.
    pub fn without_pin<const N: u8>(port: &mut Port<N>, offset: u32) -> Self {
        Self::new((), port.register_block(), offset)
    }
}

/// An input GPIO.
pub struct Input<P> {
    pin: P,
    // Logical ownership:
    // - PSR: read only
    // - ISR: read, W1C
    gpio: &'static ral::gpio::RegisterBlock,
    offset: u32,
}

// Safety: see impl Send for Output.
unsafe impl<P: Send> Send for Input<P> {}

/// Input interrupt triggers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum Trigger {
    /// Interrupt when GPIO is low
    Low = 0,
    /// Interrupt when GPIO is high
    High = 1,
    /// Interrupt after GPIO rising edge
    RisingEdge = 2,
    /// Interrupt after GPIO falling edge
    FallingEdge = 3,
    /// Interrupt after either a rising or falling edge
    EitherEdge = 4,
}

impl<P> Input<P> {
    fn new(pin: P, gpio: &'static ral::gpio::RegisterBlock, offset: u32) -> Self {
        let input = Self { pin, gpio, offset };
        ral::modify_reg!(ral::gpio, gpio, GDIR, |gdir| gdir & !input.mask());
        input
    }

    const fn mask(&self) -> u32 {
        1 << self.offset
    }

    const fn icr_offset(&self) -> u32 {
        (self.offset % 16) * 2
    }

    /// Returns `true` if the GPIO is set high.
    pub fn is_set(&self) -> bool {
        ral::read_reg!(ral::gpio, self.gpio, PSR) & self.mask() != 0
    }

    /// Returns `true` if the GPIO interrupt has triggered.
    pub fn is_triggered(&self) -> bool {
        ral::read_reg!(ral::gpio, self.gpio, ISR) & self.mask() != 0
    }

    /// Clear the interrupt triggered flag.
    pub fn clear_triggered(&self) {
        // Atomic write; OK to take immutable reference.
        ral::write_reg!(ral::gpio, self.gpio, ISR, self.mask());
    }

    /// Indicates if interrupts are enabled for this input.
    pub fn is_interrupt_enabled(&self) -> bool {
        ral::read_reg!(ral::gpio, self.gpio, IMR) & self.mask() != 0
    }

    /// Release the underlying pin object.
    pub fn release(self) -> P {
        self.pin
    }

    /// Access the underlying pin.
    pub fn pin(&self) -> &P {
        &self.pin
    }

    /// Mutably access the underling pin.
    pub fn pin_mut(&mut self) -> &mut P {
        &mut self.pin
    }
}

impl Input<()> {
    /// Allocate an input GPIO without a pin.
    ///
    /// Prefer using [`Port::input`](Port::input) to create a GPIO ouptut with a
    /// pin resource. That method ensures that pin resources are managed throughout
    /// your program, and that the pin is configured to operate as a GPIO input.
    ///
    /// You may use this method to allocate duplicate `Input` object for the same
    /// physical GPIO input. This is considered safe, since the `Input` API is
    /// reentrant. Any non-reentrant methods are attached to [`Port`], which cannot
    /// be constructed without an `unsafe` constructor of the register block.
    ///
    /// If you use this constructor, you're responsible for configuring the IOMUX
    /// multiplexer register.
    pub fn without_pin<const N: u8>(port: &mut Port<N>, offset: u32) -> Self {
        Self::new((), port.register_block(), offset)
    }
}

impl<P> eh02::digital::v2::OutputPin for Output<P> {
    type Error = core::convert::Infallible;

    fn set_high(&mut self) -> Result<(), Self::Error> {
        self.set();
        Ok(())
    }
    fn set_low(&mut self) -> Result<(), Self::Error> {
        self.clear();
        Ok(())
    }
}

#[cfg(feature = "eh02-unproven")]
impl<P> eh02::digital::v2::StatefulOutputPin for Output<P> {
    fn is_set_high(&self) -> Result<bool, Self::Error> {
        Ok(self.is_set())
    }
    fn is_set_low(&self) -> Result<bool, Self::Error> {
        Ok(!self.is_set())
    }
}

#[cfg(feature = "eh02-unproven")]
impl<P> eh02::digital::v2::ToggleableOutputPin for Output<P> {
    type Error = core::convert::Infallible;

    fn toggle(&mut self) -> Result<(), Self::Error> {
        Output::<P>::toggle(self);
        Ok(())
    }
}

#[cfg(feature = "eh02-unproven")]
impl<P> eh02::digital::v2::InputPin for Input<P> {
    type Error = core::convert::Infallible;

    fn is_high(&self) -> Result<bool, Self::Error> {
        Ok(self.is_set())
    }
    fn is_low(&self) -> Result<bool, Self::Error> {
        Ok(!self.is_set())
    }
}