psoc-drivers 0.1.0

//! GPIO (General Purpose Input/Output)
//!
//! This module provides drivers for working with GPIO ports and
//! HSIOM (High-Speed I/O Multiplexer) routing.
//!
//! # Pin modes
//!
//! Each pin has an associated type parameter for a pin mode. The pin mode is a combination of
//! the following configuration elements:
//!
// Copyright (c) 2026, Infineon Technologies AG or an affiliate of Infineon Technologies AG.
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
// in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the
// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
// express or implied. See the License for the specific language governing permissions and
// limitations under the License.

pub mod asynch;

mod access;
use access::*;

use core::{convert::Infallible, fmt::Debug, marker::PhantomData};

use critical_section::CriticalSection;
pub use embedded_hal::digital::PinState;
use psoc_macros::hsiom;

use crate::{
    NonExhaustive,
    regs::{self, RegisterValue},
    security::{self, Security, SecurityAttribute, WithSecurity},
};

/// A strongly-typed GPIO pin. The pin's port number, pin number, and mode are known at compile
/// time.
#[non_exhaustive]
pub struct Pin<const PORT: u8, const PIN: u8, Mode: PinMode, Sec: Security = security::Default> {
    /// The pin's configuration mode.
    pub mode: Mode,

    /// The pin's security attribute.
    security: Sec,
}

/// A type-erased pin. The pin's port and pin number are tracked at runtime.
#[derive(Debug)]
pub struct AnyPin<'a> {
    port: u8,
    pin: u8,
    security: SecurityAttribute,
    _p: PhantomData<&'a ()>,
}

/// A configuration mode that defines the input/output and routing mode of a GPIO pin.
///
/// Each peripheral (e.g. GPIO, SCB, TCPWM) defines the set of pin modes that can be used to route
/// signals to and from that peripheral.
pub trait PinMode: Default + Copy {
    /// The drive mode for the pin (e.g. strongly driven, high-impedance, pull-up/pull-down, etc.).
    const DRIVE_MODE: DriveMode;

    /// Whether the input buffer is enabled, allowing the pin to be read.
    const INPUT_BUFFER: bool;

    /// The HSIOM routing destination for this pin.
    const IO_SELECTOR: IoSelector;
}

/// A [PinMode] that can be used as a digital input.
pub trait InputMode: PinMode {}

/// A [PinMode] that can be used as a digital ouput.
pub trait OutputMode: PinMode {}

pub mod mode {
    //! Pin modes for firmware-controlled GPIO.

    use super::*;

    // Helper macros to declare pin modes.
    macro_rules! mode {
        ($mode:ident, $default_buffered:expr, $doc:literal) => {
            #[derive(Default, Copy, Clone, Debug)]
            #[doc = $doc]
            pub struct $mode<const INPUT_BUFFER: bool = $default_buffered>;
            impl<const INPUT_BUFFER: bool> PinMode for $mode<INPUT_BUFFER> {
                const DRIVE_MODE: DriveMode = DriveMode::$mode;
                const INPUT_BUFFER: bool = INPUT_BUFFER;
                const IO_SELECTOR: IoSelector = IoSelector::Gpio;
            }
        };
    }
    macro_rules! in_mode {
        ($mode:ident, $default_buffered:expr, $doc:literal) => {
            mode!($mode, $default_buffered, $doc);
            impl InputMode for $mode<true> {}
        };
    }
    macro_rules! out_mode {
        ($mode:ident, $default_buffered:expr, $doc:literal) => {
            mode!($mode, $default_buffered, $doc);
            impl OutputMode for $mode<true> {}
            impl OutputMode for $mode<false> {}
        };
    }
    macro_rules! inout_mode {
        ($mode:ident, $default_buffered:expr, $doc:literal) => {
            mode!($mode, $default_buffered, $doc);
            impl InputMode for $mode<true> {}
            impl OutputMode for $mode<true> {}
            impl OutputMode for $mode<false> {}
        };
    }

    in_mode!(HighZ, true, "A [high-impedance](DriveMode::HighZ) pin.");
    inout_mode!(PullUp, true, "A [pull-up](DriveMode::PullUp) pin.");
    inout_mode!(PullDown, true, "A [pull-down](DriveMode::PullUp) pin.");
    inout_mode!(
        OpenDrainDrivesLow,
        true,
        "An [open-drain high, strongly-driven low](DriveMode::OpenDrainDrivesLow) pin."
    );
    inout_mode!(
        OpenDrainDrivesHigh,
        true,
        "An [open-drain low, strongly-driven high](DriveMode::OpenDrainDrivesHigh) pin."
    );
    out_mode!(Strong, false, "A [strongly-driven](DriveMode::Strong) pin.");
    inout_mode!(
        PullUpPullDown,
        true,
        "A [pull-up pull-down](DriveMode::PullUpPullDown) pin."
    );

    /// A disabled GPIO pin.
    pub type Disabled = HighZ<false>;

    pub mod debug {
        //! Pin modes for JTAG/SWD debug pins.
        use super::*;

        cfg_select! {
            mxs40ioss => {
                hsiom!(SwclkTck, cpuss.swj_swclk_tclk, PullDown::<true>, "SWD/JTAG clock pin");
                hsiom!(SwdioTms, cpuss.swj_swdio_tms, PullUp::<true>, "SWD/JTAG SWDIO/Tms pin");
                hsiom!(Tdi, cpuss.swj_swdoe_tdi, PullUp::<true>, "JTAG Tdi pin");
                hsiom!(SwoTdo, cpuss.swj_swo_tdo, Strong::<false>, "SWD/JTAG SWO/Tdo pin");
            },
            mxs40sioss => {
                hsiom!(SwclkTck, debug600.clk_swj_swclk_tclk, PullDown::<true>, "SWD/JTAG clock pin");
                hsiom!(SwdioTms, debug600.swj_swdio_tms, PullUp::<true>, "SWD/JTAG SWDIO/Tms pin");
                hsiom!(Tdi, debug600.swj_swdoe_tdi, PullUp::<true>, "JTAG Tdi pin");
                hsiom!(SwoTdo, debug600.swj_swo_tdo, Strong::<false>, "SWD/JTAG SWO/Tdo pin");
            }
        }
    }
}

/// A pin's drive mode.
///
/// ![Schematic diagrams of the available drive modes](https://infineon.github.io/mtb-pdl-cat1/pdl_api_reference_manual/html/gpio_periio_dm_block_diagram.png)
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum DriveMode {
    /// The standard high-impedance (High-Z) mode recommended for analog and digital inputs. For
    /// digital signals, the input buffer is enabled; for analog signals, the input buffer is
    /// typically disabled to reduce crowbar current and leakage in low-power designs. To achieve
    /// the lowest device current, unused GPIOs must be configured to the high-impedance drive mode
    /// with input buffer disabled. High-impedance drive mode with input buffer disabled is also
    /// the default pin reset mode.
    HighZ = 0,

    /// Reserved; do not use.
    Reserved = 1,

    /// Provides a series resistance when the pin is set high and strong drive when set low.
    PullUp = 2,

    /// Provides a series resistance when the pin is set low and strong drive when set high.
    PullDown = 3,

    /// Provides high-impedance when the pin is set high and strong drive when set low. Used when
    /// the signal is externally pulled high. Commonly used when driving I2C bus signal lines.
    OpenDrainDrivesLow = 4,

    /// Provides high-impedance when the pin is set low and strong drive when set high. Used when
    /// the signal is externally pulled low.
    OpenDrainDrivesHigh = 5,

    /// The standard digital output mode for pins; it provides a strong CMOS output drive in both
    /// high and low states. Strong drive mode pins should not be used as inputs under normal
    /// circumstances. This mode is often used for digital output signals or to drive external
    /// devices
    Strong = 6,

    /// Provides a series resistance in both high and low output states. The high data state is
    /// pulled up while the low data state is pulled down. This mode is useful when the pin is
    /// driven by other signals that may cause shorts.
    PullUpPullDown = 7,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
/// HSIOM (High-speed I/O matrix) routing destinations.
///
/// The high-speed I/O matrix is a set of high-speed multiplexers that route internal CPU and
/// peripheral signals to and from GPIOs. HSIOM allows GPIOs to be shared with multiple functions
/// and multiplexes the pin connection to a user-selected peripheral.
pub enum IoSelector {
    /// GPIO registers control this pin.
    Gpio = 0,

    /// Active functionality 0 (see the datasheet for specific pin connectivity).
    Act0 = 8,
    /// Active functionality 1 (see the datasheet for specific pin connectivity).
    Act1,
    /// Active functionality 2 (see the datasheet for specific pin connectivity).
    Act2,
    /// Active functionality 3 (see the datasheet for specific pin connectivity).
    Act3,

    /// Deep Sleep functionality 0 (see the datasheet for specific pin connectivity).
    Ds0 = 12,
    /// Deep Sleep functionality 1 (see the datasheet for specific pin connectivity).
    Ds1,
    /// Deep Sleep functionality 2 (see the datasheet for specific pin connectivity).
    Ds2,
    /// Deep Sleep functionality 3 (see the datasheet for specific pin connectivity).
    Ds3,

    /// Active functionality 4 (see the datasheet for specific pin connectivity).
    Act4 = 16,
    /// Active functionality 5 (see the datasheet for specific pin connectivity).
    Act5,
    /// Active functionality 6 (see the datasheet for specific pin connectivity).
    Act6,
    /// Active functionality 7 (see the datasheet for specific pin connectivity).
    Act7,
    /// Active functionality 8 (see the datasheet for specific pin connectivity).
    Act8,
    /// Active functionality 9 (see the datasheet for specific pin connectivity).
    Act9,
    /// Active functionality 10 (see the datasheet for specific pin connectivity).
    Act10,
    /// Active functionality 11 (see the datasheet for specific pin connectivity).
    Act11,
    /// Active functionality 12 (see the datasheet for specific pin connectivity).
    Act12,
    /// Active functionality 13 (see the datasheet for specific pin connectivity).
    Act13,
    /// Active functionality 14 (see the datasheet for specific pin connectivity).
    Act14,
    /// Active functionality 15 (see the datasheet for specific pin connectivity).
    Act15,

    /// Deep Sleep functionality 4 (see the datasheet for specific pin connectivity).
    Ds4 = 28,
    /// Deep Sleep functionality 5 (see the datasheet for specific pin connectivity).
    Ds5,
    /// Deep Sleep functionality 6 (see the datasheet for specific pin connectivity).
    Ds6,
    /// Deep Sleep functionality 7 (see the datasheet for specific pin connectivity).
    Ds7,
}

/// Additional configuration options that can be applied to a pin.
#[derive(Clone, Debug)]
pub struct PinConfig {
    /// The ouptut state to be applied upon initial configuration. Defaults to low.
    pub initial_output: PinState,
    /// Interrupt configuration for this pin. Defaults to `Disabled`.
    pub interrupt_edge: InterruptEdge,
    /// Interrupt mask.
    ///
    /// If set to true, edge interrupts are forwarded to the CPU. If false, edge interrupts are
    /// still detected (and reflected in the interrupt register) if enabled, but are not forwarded
    /// to the CPU.
    ///
    /// Defaults to false.
    pub interrupt_enabled: bool,

    /// The trip point for the input buffer. Defaults to `Cmos`.
    pub threshold: VtripMode,

    /// The slew rate for the output driver. Defaults to `Fast`.
    pub slew_rate: SlewRate,

    /// The drive strength of the output buffer. Defaults to `Full`.
    pub drive_strength: DriveStrength,

    /// The fields of this structure may vary across hardware revisions.
    pub _ne: NonExhaustive,
}

/// Interrupt configuration for a pin.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum InterruptEdge {
    /// Disable interrupts for this pin.
    Disabled = 0,
    /// Trigger an interrupt on a rising edge.
    Rising,
    /// Trigger an interrupt on a falling edge.
    Falling,
    /// Trigger an interrupt on either edge.
    RisingFalling,
}

/// Voltage trip point for a digital input pin.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum VtripMode {
    /// Input buffer compatible with CMOS and I2C interfaces.
    Cmos = 0,

    /// Input buffer compatible with TTL and MediaLB interfaces.
    Ttl = 1,
}

/// Slew rate configuration for a digital output pin.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum SlewRate {
    /// Fast slew rate.
    Fast = 0,

    /// Slow slew rate. Results in reduced EMI and crosstalk and is recommended for low-frequency
    /// signals or signals without strict timing constraints.
    Slow = 1,
}

#[cfg(mxs40ioss)]
/// Drive strength of a digital output pin.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum DriveStrength {
    /// Full drive strength. Required when using `Slow` slew rate.
    Full = 0,

    /// 1/2 drive strength.
    Half = 1,

    /// 1/4 drive strength.
    Quarter = 2,

    /// 1/8 drive strength.
    Eighth = 3,
}

/// Drive strength of a digital output pin.
#[cfg(mxs40sioss)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u32)]
pub enum DriveStrength {
    /// 4mA/12mA (standard/high-speed I/O ports)
    _0 = 0,
    /// 3mA/9mA (standard/high-speed I/O ports)
    _1,
    /// 2mA/6mA (standard/high-speed I/O ports)
    _2,
    /// 1mA/3mA (standard/high-speed I/O ports)
    _3,
}

#[cfg(mxs40sioss)]
#[allow(non_upper_case_globals)]
impl DriveStrength {
    /// Full drive strength.
    pub const Full: DriveStrength = DriveStrength::_0;

    /// 1/2 drive strength.
    pub const Half: DriveStrength = DriveStrength::_2;

    /// 1/4 drive strength.
    pub const Quarter: DriveStrength = DriveStrength::_3;
}

impl Default for PinConfig {
    fn default() -> Self {
        PinConfig::new()
    }
}

impl PinConfig {
    /// Creates a `PinConfig` with the default configuration.
    pub const fn new() -> Self {
        Self {
            initial_output: PinState::Low,
            interrupt_edge: InterruptEdge::Disabled,
            interrupt_enabled: false,
            threshold: VtripMode::Cmos,
            slew_rate: SlewRate::Fast,
            drive_strength: DriveStrength::Full,
            _ne: NonExhaustive,
        }
    }

    /// Sets the initial digital output state.
    #[must_use]
    pub const fn initial_output(mut self, initial_output: PinState) -> Self {
        self.initial_output = initial_output;
        self
    }
    /// Sets the interrupt edge.
    #[must_use]
    pub const fn interrupt_edge(mut self, interrupt_edge: InterruptEdge) -> Self {
        self.interrupt_edge = interrupt_edge;
        self
    }
    /// Sets the interrupt mask.
    #[must_use]
    pub const fn interrupt_enabled(mut self, interrupt_enabled: bool) -> Self {
        self.interrupt_enabled = interrupt_enabled;
        self
    }
    /// Sets the trip point for the digital input buffer.
    #[must_use]
    pub const fn threshold(mut self, threshold: VtripMode) -> Self {
        self.threshold = threshold;
        self
    }
    /// Sets the slew rate.
    #[must_use]
    pub const fn slew_rate(mut self, slew_rate: SlewRate) -> Self {
        self.slew_rate = slew_rate;
        self
    }
    /// Sets the drive strength.
    #[must_use]
    pub const fn drive_strength(mut self, drive_strength: DriveStrength) -> Self {
        self.drive_strength = drive_strength;
        self
    }
}

impl<const PORT: u8, const PIN: u8, Mode: PinMode> Pin<PORT, PIN, Mode, security::Default> {
    /// Unsafely creates a pin. Does not set its mode or configuration.
    ///
    /// # Safety
    ///
    /// The caller is responsible for ensuring the hardware is present on the device, configured
    /// for the given mode, and not accessed concurrently.
    ///
    /// If the pin's currently configured mode is unknown, you must use [`AnyPin::steal`](AnyPin::steal).
    pub const unsafe fn steal(mode: Mode) -> Self {
        const { assert!(PIN < 8) };
        Pin {
            mode,
            security: security::DEFAULT,
        }
    }
}

impl<const PORT: u8, const PIN: u8, Mode: PinMode, Sec: Security> Pin<PORT, PIN, Mode, Sec> {
    /// Changes the security attribute which will be used to access this pin's registers.
    pub const fn with_security<New: Security>(self, security: New) -> Pin<PORT, PIN, Mode, New> {
        Pin {
            mode: self.mode,
            security,
        }
    }

    /// Type-erases this pin, returning an `AnyPin` with the static lifetime.
    pub fn into_erased(self) -> AnyPin<'static> {
        AnyPin {
            port: PORT,
            pin: PIN,
            security: self.security.into(),
            _p: PhantomData,
        }
    }

    /// Type-erases this pin, returning an `AnyPin` with a borrowed lifetime.
    pub fn as_erased(&mut self) -> AnyPin<'_> {
        unsafe { self.as_erased_ref() }
    }

    /// Unsafely obtains a type-erased pin without checking for exclusivity.
    unsafe fn as_erased_ref(&self) -> AnyPin<'_> {
        AnyPin {
            port: PORT,
            pin: PIN,
            security: self.security.into(),
            _p: PhantomData,
        }
    }

    /// Returns a pointer to the port registers for this pin.
    #[inline(always)]
    pub fn port_regs(&self) -> regs::gpio::Prt {
        unsafe { self.as_erased_ref().port_regs() }
    }

    /// Returns this pin's port number.
    pub fn port_no(&self) -> u8 {
        PORT
    }

    /// Returns this pin's offset within the port.
    pub fn pin_no(&self) -> u8 {
        PIN
    }

    /// Changes this pin's mode.
    pub fn into_mode<M: PinMode>(self, mode: M) -> Pin<PORT, PIN, M, Sec> {
        critical_section::with(|cs| self.into_mode_cs(mode, cs))
    }

    /// Changes this pin's mode.
    pub fn into_mode_cs<M: PinMode>(self, mode: M, cs: CriticalSection) -> Pin<PORT, PIN, M, Sec> {
        let Pin {
            mode: old,
            security,
        } = self;
        self.into_erased().change_mode(old, mode, cs);
        Pin { mode, security }
    }

    /// Temporarily changes this pin's mode.
    pub fn with_mode<M: PinMode, T>(
        &mut self,
        mode: M,
        f: impl FnOnce(&mut Pin<PORT, PIN, M, Sec>) -> T,
    ) -> T {
        let Pin {
            mode: old,
            security,
        } = self;
        let mut pin = Pin {
            mode: *old,
            security: *security,
        }
        .into_mode(mode);
        let result = f(&mut pin);
        pin.into_mode(*old);
        result
    }

    /// Returns this pin's drive mode.
    pub fn drive_mode(&self) -> DriveMode {
        unsafe { self.as_erased_ref().drive_mode() }
    }

    /// Returns whether the pin's input buffer is enabled.
    pub fn input_buffer_enabled(&self) -> bool {
        unsafe { self.as_erased_ref().input_buffer_enabled() }
    }

    /// Returns this pin's HSIOM routing destination.
    pub fn io_selector(&self) -> IoSelector {
        unsafe { self.as_erased_ref().io_selector() }
    }

    /// Returns this pin's trip threshold.
    pub fn threshold(&self) -> VtripMode {
        unsafe { self.as_erased_ref().threshold() }
    }

    /// Sets this pin's trip threshold.
    pub fn set_threshold(&mut self, threshold: VtripMode) {
        self.as_erased().set_threshold(threshold);
    }

    /// Sets this pin's trip threshold.
    pub fn set_threshold_cs(&mut self, threshold: VtripMode, cs: CriticalSection) {
        self.as_erased().set_threshold_cs(threshold, cs);
    }

    /// Returns this pin's slew rate.
    pub fn slew_rate(&self) -> SlewRate {
        unsafe { self.as_erased_ref().slew_rate() }
    }

    /// Sets this pin's slew rate.
    pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
        self.as_erased().set_slew_rate(slew_rate);
    }

    /// Sets this pin's slew rate.
    pub fn set_slew_rate_cs(&mut self, slew_rate: SlewRate, cs: CriticalSection) {
        self.as_erased().set_slew_rate_cs(slew_rate, cs);
    }

    /// Returns this pin's slew rate.
    pub fn drive_strength(&self) -> DriveStrength {
        unsafe { self.as_erased_ref().drive_strength() }
    }

    /// Sets this pin's drive strength.
    pub fn set_drive_strength(&mut self, drive_strength: DriveStrength) {
        self.as_erased().set_drive_strength(drive_strength);
    }

    /// Sets this pin's drive strength.
    pub fn set_drive_strength_cs(&mut self, drive_strength: DriveStrength, cs: CriticalSection) {
        self.as_erased().set_drive_strength_cs(drive_strength, cs);
    }

    /// Returns the value of this pin's interrupt mask.
    pub fn interrupt_enabled(&self) -> bool {
        unsafe { self.as_erased_ref().interrupt_enabled() }
    }

    /// Sets this pin's interrupt mask.
    pub fn set_interrupt_enabled(&mut self, enabled: bool) {
        self.as_erased().set_interrupt_enabled(enabled);
    }

    /// Sets this pin's interrupt mask.
    pub fn set_interrupt_enabled_cs(&mut self, enabled: bool, cs: CriticalSection) {
        self.as_erased().set_interrupt_enabled_cs(enabled, cs);
    }

    /// Returns this pin's interrupt edge.
    pub fn interrupt_edge(&self) -> InterruptEdge {
        unsafe { self.as_erased_ref().interrupt_edge() }
    }

    /// Sets this pin's interrupt edge.
    pub fn set_interrupt_edge(&mut self, interrupt_edge: InterruptEdge) {
        self.as_erased().set_interrupt_edge(interrupt_edge);
    }

    /// Sets this pin's interrupt edge.
    pub fn set_interrupt_edge_cs(&mut self, interrupt_edge: InterruptEdge, cs: CriticalSection) {
        self.as_erased().set_interrupt_edge_cs(interrupt_edge, cs);
    }

    #[cfg(trustzone)]
    /// Returns this pin's nonsecure attribute.
    pub fn nonsecure_mask(&self) -> bool {
        unsafe { self.as_erased_ref().nonsecure_mask() }
    }

    #[cfg(trustzone)]
    /// Sets this pin's nonsecure attribute.
    pub fn set_nonsecure_mask(&mut self, nonsecure: bool) {
        self.as_erased().set_nonsecure_mask(nonsecure);
    }

    #[cfg(trustzone)]
    /// Sets this pin's nonsecure attribute.
    pub fn set_nonsecure_mask_cs(&mut self, nonsecure: bool, cs: CriticalSection) {
        self.as_erased().set_nonsecure_mask_cs(nonsecure, cs);
    }

    /// Returns true if this pin's interrupt is asserted.
    pub fn interrupt_asserted(&self) -> bool {
        unsafe { self.as_erased_ref().interrupt_asserted() }
    }

    /// Clears this pin's interrupt.
    pub fn clear_interrupt(&mut self) {
        self.as_erased().clear_interrupt();
    }
}

impl<const PIN: u8, const PORT: u8, Mode: OutputMode, Sec: Security> Pin<PIN, PORT, Mode, Sec> {
    /// Drives the pin to the logic low state (as configured by the drive mode).
    pub fn set_low(&mut self) {
        self.as_erased().set_low();
    }

    /// Drives the pin to the logic high state (as configured by the drive mode).
    pub fn set_high(&mut self) {
        self.as_erased().set_high();
    }

    /// Drives the pin to the given state (as configured by the drive mode).
    pub fn set_state(&mut self, state: PinState) {
        self.as_erased().set_state(state);
    }

    /// Returns whether the pin's output buffer is being driven high.
    ///
    /// Does *not* read the input state of the pin; use [`is_high`](Pin::is_high).
    pub fn is_set_high(&self) -> bool {
        unsafe { self.as_erased_ref().is_set_high() }
    }

    /// Returns whether the pin's output buffer is being driven low.
    ///
    /// Does *not* read the input state of the pin; use [`is_low`](Pin::is_low).
    pub fn is_set_low(&self) -> bool {
        unsafe { self.as_erased_ref().is_set_low() }
    }

    /// Toggles the pin's output state.
    pub fn toggle(&mut self) {
        unsafe {
            self.as_erased_ref().toggle();
        }
    }
}

impl<const PIN: u8, const PORT: u8, Mode: InputMode, Sec: Security> Pin<PIN, PORT, Mode, Sec> {
    /// Returns whether the pin's input buffer is reading high.
    pub fn is_high(&self) -> bool {
        unsafe { self.as_erased_ref().is_high() }
    }

    /// Returns whether the pin's input buffer is reading low.
    pub fn is_low(&self) -> bool {
        unsafe { self.as_erased_ref().is_low() }
    }
}

impl<const PIN: u8, const PORT: u8, Mode: PinMode, Sec: Security> embedded_hal::digital::ErrorType
    for Pin<PIN, PORT, Mode, Sec>
{
    // TODO: consider changing to ! once never type is stabilized, possibly around Rust 1.96-ish
    // https://github.com/rust-lang/rust/issues/35121
    type Error = Infallible;
}

impl<const PIN: u8, const PORT: u8, Mode: OutputMode, Sec: Security>
    embedded_hal::digital::OutputPin for Pin<PIN, PORT, Mode, Sec>
{
    fn set_low(&mut self) -> Result<(), Infallible> {
        self.set_low();
        Ok(())
    }

    fn set_high(&mut self) -> Result<(), Infallible> {
        self.set_high();
        Ok(())
    }
}

impl<const PORT: u8, const PIN: u8, Mode: PinMode + Debug, Sec: Security> Debug
    for Pin<PORT, PIN, Mode, Sec>
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Pin")
            .field("port", &PORT)
            .field("pin", &PIN)
            .field("mode", &self.mode)
            .finish()
    }
}

impl AnyPin<'_> {
    /// Unsafely creates a pin. Does not set its mode or configuration.
    ///
    /// # Safety
    ///
    /// The caller is responsible for ensuring the hardware is present on the device, not accessed
    /// concurrently, and configured correctly prior to use.
    pub const unsafe fn steal(port: u8, pin: u8) -> Self {
        AnyPin {
            port,
            pin,
            security: security::DEFAULT.as_security_attribute(),
            _p: PhantomData,
        }
    }

    /// Returns this pin's port number.
    pub fn port_no(&self) -> u8 {
        self.port
    }

    /// Returns this pin's offset within the port.
    pub fn pin_no(&self) -> u8 {
        self.pin
    }

    /// Returns a pointer to the port registers for this pin.
    #[inline(always)]
    pub fn port_regs(&self) -> regs::gpio::Prt {
        regs::GPIO.prt()[self.port as usize].with_security(self.security)
    }

    /// Drives the pin to the logic low state (as configured by the drive mode).
    pub fn set_low(&mut self) {
        unsafe {
            self.port_regs().out_clr().write_raw(1 << self.pin);
        }
    }

    /// Drives the pin to the logic high state (as configured by the drive mode).
    pub fn set_high(&mut self) {
        unsafe {
            self.port_regs().out_set().write_raw(1 << self.pin);
        }
    }

    /// Drives the pin to the given state (as configured by the drive mode).
    pub fn set_state(&mut self, state: PinState) {
        match state {
            PinState::Low => self.set_low(),
            PinState::High => self.set_high(),
        }
    }

    /// Returns whether the pin's output buffer is being driven high.
    ///
    /// Does *not* read the input state of the pin; use [`is_high`](AnyPin::is_high).
    pub fn is_set_high(&self) -> bool {
        self.read().out() == PinState::High
    }

    /// Returns whether the pin's output buffer is being driven low.
    ///
    /// Does *not* read the input state of the pin; use [`is_low`](AnyPin::is_low).
    pub fn is_set_low(&self) -> bool {
        self.read().out() == PinState::Low
    }

    /// Toggles the pin's output state.
    pub fn toggle(&mut self) {
        unsafe {
            self.port_regs().out_inv().write_raw(1 << self.pin);
        }
    }

    /// Returns whether the pin's input buffer is reading high.
    pub fn is_high(&self) -> bool {
        self.read().input() == PinState::High
    }

    /// Returns whether the pin's input buffer is reading low.
    pub fn is_low(&self) -> bool {
        self.read().input() == PinState::Low
    }

    /// Sets this pin's mode.
    ///
    /// Can only be used if the pin is not borrowed from a statically-typed Pin.
    pub fn set_mode<Mode: PinMode>(&mut self, mode: Mode)
    where
        Self: 'static,
    {
        critical_section::with(|cs| self.set_mode_cs(mode, cs))
    }

    /// Sets this pin's mode.
    ///
    /// Can only be used if the pin is not borrowed from a statically-typed Pin.
    pub fn set_mode_cs<Mode: PinMode>(&mut self, _mode: Mode, cs: CriticalSection)
    where
        Self: 'static,
    {
        let mut pin = self.modify(cs);
        pin.set_mode(Mode::DRIVE_MODE, Mode::INPUT_BUFFER);
        pin.set_io_sel(Mode::IO_SELECTOR);
    }

    fn change_mode<Old: PinMode, New: PinMode>(
        &mut self,
        _old: Old,
        _new: New,
        cs: CriticalSection,
    ) {
        let mut pin = self.modify(cs);
        if (Old::DRIVE_MODE, Old::INPUT_BUFFER) != (New::DRIVE_MODE, New::INPUT_BUFFER) {
            pin.set_mode(New::DRIVE_MODE, New::INPUT_BUFFER);
        }

        if Old::IO_SELECTOR != New::IO_SELECTOR {
            pin.set_io_sel(New::IO_SELECTOR);
        }
    }

    /// Fully initializes the pin's configuration registers.
    ///
    /// Can only be used if the pin is not borrowed from a statically-typed Pin.
    pub fn initialize<Mode: PinMode>(&mut self, mode: Mode, config: PinConfig)
    where
        Self: 'static,
    {
        critical_section::with(|cs| self.initialize_cs(mode, config, cs))
    }

    /// Fully initializes the pin's configuration registers.
    ///
    /// Can only be used if the pin is not borrowed from a statically-typed Pin.
    pub fn initialize_cs<Mode: PinMode>(
        &mut self,
        mode: Mode,
        config: PinConfig,
        cs: CriticalSection,
    ) where
        Self: 'static,
    {
        let security = self.security;
        self.modify(cs).initialize(mode, config, security);
    }

    /// Returns this pin's drive mode.
    pub fn drive_mode(&self) -> DriveMode {
        self.read().mode().0
    }

    /// Sets this pin's drive mode.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_drive_mode(&mut self, drive_mode: DriveMode)
    where
        Self: 'static,
    {
        critical_section::with(|cs| self.set_drive_mode_cs(drive_mode, cs))
    }
    /// Sets this pin's drive mode.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_drive_mode_cs(&mut self, drive_mode: DriveMode, cs: CriticalSection)
    where
        Self: 'static,
    {
        self.modify(cs).set_drive_mode(drive_mode);
    }

    /// Returns whether the pin's input buffer is enabled.
    pub fn input_buffer_enabled(&self) -> bool {
        self.read().mode().1
    }

    /// Enables or disables this pin's input buffer.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_input_buffer(&mut self, enabled: bool)
    where
        Self: 'static,
    {
        critical_section::with(|cs| self.set_input_buffer_cs(enabled, cs))
    }

    /// Enables or disables this pin's input buffer.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_input_buffer_cs(&mut self, enabled: bool, cs: CriticalSection)
    where
        Self: 'static,
    {
        self.modify(cs).set_input_buffer(enabled);
    }

    /// Returns this pin's HSIOM routing destination.
    pub fn io_selector(&self) -> IoSelector {
        self.read().io_sel()
    }

    /// Sets this pin's HSIOM routing destination.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_io_selector(&mut self, io_sel: IoSelector)
    where
        Self: 'static,
    {
        critical_section::with(|cs| self.set_io_selector_cs(io_sel, cs))
    }

    /// Sets this pin's HSIOM routing destination.
    ///
    /// Since this changes the pin's mode, can only be used if the pin is not borrowed from a
    /// statically-typed Pin.
    pub fn set_io_selector_cs(&mut self, io_sel: IoSelector, cs: CriticalSection)
    where
        Self: 'static,
    {
        self.modify(cs).set_io_sel(io_sel);
    }

    /// Returns this pin's trip threshold.
    pub fn threshold(&self) -> VtripMode {
        self.read().threshold()
    }

    /// Sets this pin's trip threshold.
    pub fn set_threshold(&mut self, threshold: VtripMode) {
        critical_section::with(|cs| self.set_threshold_cs(threshold, cs));
    }

    /// Sets this pin's trip threshold.
    pub fn set_threshold_cs(&mut self, threshold: VtripMode, cs: CriticalSection) {
        self.modify(cs).set_threshold(threshold);
    }

    /// Returns this pin's slew rate.
    pub fn slew_rate(&self) -> SlewRate {
        self.read().slew_rate()
    }

    /// Sets this pin's slew rate.
    pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
        critical_section::with(|cs| self.set_slew_rate_cs(slew_rate, cs));
    }

    /// Sets this pin's slew rate.
    pub fn set_slew_rate_cs(&mut self, slew_rate: SlewRate, cs: CriticalSection) {
        self.modify(cs).set_slew_rate(slew_rate);
    }

    /// Returns this pin's drive strength.
    pub fn drive_strength(&self) -> DriveStrength {
        self.read().drive_strength()
    }

    /// Sets this pin's drive strength.
    pub fn set_drive_strength(&mut self, drive_strength: DriveStrength) {
        critical_section::with(|cs| self.set_drive_strength_cs(drive_strength, cs));
    }

    /// Sets this pin's drive strength.
    pub fn set_drive_strength_cs(&mut self, drive_strength: DriveStrength, cs: CriticalSection) {
        self.modify(cs).set_drive_strength(drive_strength);
    }

    /// Returns this pin's interrupt mask.
    pub fn interrupt_enabled(&self) -> bool {
        self.read().interrupt_mask()
    }

    /// Sets this pin's interrupt mask.
    pub fn set_interrupt_enabled(&mut self, enabled: bool) {
        critical_section::with(|cs| self.set_interrupt_enabled_cs(enabled, cs));
    }

    /// Sets this pin's interrupt mask.
    pub fn set_interrupt_enabled_cs(&mut self, enabled: bool, cs: CriticalSection) {
        self.modify(cs).set_interrupt_mask(enabled);
    }

    /// Returns this pin's interrupt edge.
    pub fn interrupt_edge(&self) -> InterruptEdge {
        self.read().interrupt_edge()
    }

    /// Sets this pin's interrupt edge.
    pub fn set_interrupt_edge(&mut self, interrupt_edge: InterruptEdge) {
        critical_section::with(|cs| self.set_interrupt_edge_cs(interrupt_edge, cs));
    }

    /// Sets this pin's interrupt edge.
    pub fn set_interrupt_edge_cs(&mut self, interrupt_edge: InterruptEdge, cs: CriticalSection) {
        self.modify(cs).set_interrupt_edge(interrupt_edge);
    }

    /// Returns this pin's nonsecure attribute.
    #[cfg(trustzone)]
    pub fn nonsecure_mask(&self) -> bool {
        self.read().nonsecure_mask()
    }

    #[cfg(trustzone)]
    /// Sets this pin's nonsecure attribute.
    pub fn set_nonsecure_mask(&mut self, nonsecure: bool) {
        critical_section::with(|cs| self.set_nonsecure_mask_cs(nonsecure, cs));
    }

    #[cfg(trustzone)]
    /// Sets this pin's nonsecure attribute.
    pub fn set_nonsecure_mask_cs(&mut self, nonsecure: bool, cs: CriticalSection) {
        self.modify(cs).set_nonsecure_mask(nonsecure);
    }

    /// Returns true if this pin's interrupt is asserted.
    pub fn interrupt_asserted(&self) -> bool {
        unsafe {
            regs::GPIO.prt()[self.port as usize].intr().read().get_raw() & (1 << self.pin) != 0
        }
    }

    /// Clears this pin's interrupt.
    pub fn clear_interrupt(&mut self) {
        unsafe {
            self.port_regs().intr().write_raw(1 << self.pin);
        }
    }

    fn read(&self) -> PinAccess<'_, PortRegAccess, Read> {
        // SAFETY: AnyPin invariants guarantee we can safely access this pin
        unsafe { PinAccess::steal_read(PortRegAccess(self.port, self.security), self.pin) }
    }

    fn modify(&mut self, _cs: CriticalSection<'_>) -> PinAccess<'_, PortRegAccess, Modify> {
        // SAFETY: Interrupts are disabled, so we can claim exclusive access to the port
        unsafe { PinAccess::steal_modify(PortRegAccess(self.port, self.security), self.pin) }
    }
}

impl<const PIN: u8, const PORT: u8, Mode: PinMode, Sec: Security> From<Pin<PIN, PORT, Mode, Sec>>
    for AnyPin<'static>
{
    fn from(pin: Pin<PIN, PORT, Mode, Sec>) -> Self {
        pin.into_erased()
    }
}

impl<'a, const PIN: u8, const PORT: u8, Mode: PinMode, Sec: Security>
    From<&'a mut Pin<PIN, PORT, Mode, Sec>> for AnyPin<'a>
{
    fn from(pin: &'a mut Pin<PIN, PORT, Mode, Sec>) -> Self {
        pin.as_erased()
    }
}

impl embedded_hal::digital::ErrorType for AnyPin<'_> {
    type Error = Infallible;
}

impl embedded_hal::digital::OutputPin for AnyPin<'_> {
    fn set_low(&mut self) -> Result<(), Infallible> {
        unsafe {
            self.port_regs().out_clr().write_raw(1 << self.pin);
        }
        Ok(())
    }

    fn set_high(&mut self) -> Result<(), Infallible> {
        unsafe {
            self.port_regs().out_set().write_raw(1 << self.pin);
        }
        Ok(())
    }
}

impl embedded_hal::digital::StatefulOutputPin for AnyPin<'_> {
    fn is_set_high(&mut self) -> Result<bool, Infallible> {
        Ok(self.read().out() == PinState::High)
    }

    fn is_set_low(&mut self) -> Result<bool, Infallible> {
        Ok(self.read().out() == PinState::Low)
    }

    fn toggle(&mut self) -> Result<(), Self::Error> {
        unsafe {
            self.port_regs().out_inv().write_raw(1 << self.pin);
        }
        Ok(())
    }
}

impl embedded_hal::digital::InputPin for AnyPin<'_> {
    fn is_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.read().input() == PinState::High)
    }

    fn is_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.read().input() == PinState::Low)
    }
}

/// A port that has not been initialized.
///
/// This type represents ownership of a GPIO port that has not yet been configured for use, and
/// allows configuring the entire port in one operation, which is much more efficient than
/// configuring each pin individually.
#[non_exhaustive]
#[derive(Debug)]
pub struct UnconfiguredPort<
    const PORT: u8,
    P0: UnconfiguredPinMode = (),
    P1: UnconfiguredPinMode = (),
    P2: UnconfiguredPinMode = (),
    P3: UnconfiguredPinMode = (),
    P4: UnconfiguredPinMode = (),
    P5: UnconfiguredPinMode = (),
    P6: UnconfiguredPinMode = (),
    P7: UnconfiguredPinMode = (),
>(
    pub (P0, PinConfig),
    pub (P1, PinConfig),
    pub (P2, PinConfig),
    pub (P3, PinConfig),
    pub (P4, PinConfig),
    pub (P5, PinConfig),
    pub (P6, PinConfig),
    pub (P7, PinConfig),
);

/// The mode of a pin in an unconfigured port.
///
/// Either a [PinMode] if the pin is present, or `()` if the pin is not present.
pub trait UnconfiguredPinMode: Default {
    /// The type this pin will have once initialized.
    type PinType<const PORT: u8, const PIN: u8>;

    #[doc(hidden)]
    unsafe fn initialize<const PORT: u8, const PIN: u8, A: PortAccess>(
        self,
        config: PinConfig,
        pin: PinAccess<'_, A, Modify>,
    ) -> Self::PinType<PORT, PIN>;
}

impl<M: PinMode> UnconfiguredPinMode for M {
    type PinType<const PORT: u8, const PIN: u8> = Pin<PORT, PIN, Self, security::Default>;

    #[inline(always)]
    unsafe fn initialize<const PORT: u8, const PIN: u8, A: PortAccess>(
        self,
        config: PinConfig,
        mut pin: PinAccess<'_, A, Modify>,
    ) -> Self::PinType<PORT, PIN> {
        pin.initialize(self, config, security::DEFAULT.into());
        unsafe { Pin::steal(self) }
    }
}
impl UnconfiguredPinMode for () {
    type PinType<const PORT: u8, const PIN: u8> = ();

    unsafe fn initialize<const PORT: u8, const PIN: u8, A: PortAccess>(
        self,
        _config: PinConfig,
        _pin: PinAccess<'_, A, Modify>,
    ) -> Self::PinType<PORT, PIN> {
    }
}
impl<
    const PORT: u8,
    P0: UnconfiguredPinMode,
    P1: UnconfiguredPinMode,
    P2: UnconfiguredPinMode,
    P3: UnconfiguredPinMode,
    P4: UnconfiguredPinMode,
    P5: UnconfiguredPinMode,
    P6: UnconfiguredPinMode,
    P7: UnconfiguredPinMode,
> UnconfiguredPort<PORT, P0, P1, P2, P3, P4, P5, P6, P7>
{
    /// Creates an UnconfiguredPort.
    ///
    /// # Safety
    ///
    /// The caller must ensure this port number is present on the given device, all enabled pins
    /// are present on the given device, and this port is not being used concurrently.
    // TODO: constify once const default is stable
    pub unsafe fn steal() -> Self {
        Self(
            Default::default(),
            Default::default(),
            Default::default(),
            Default::default(),
            Default::default(),
            Default::default(),
            Default::default(),
            Default::default(),
        )
    }

    /// Applies the configuration to the pins in the port.
    #[allow(clippy::type_complexity)]
    #[inline(always)]
    pub fn initialize(
        self,
    ) -> (
        P0::PinType<PORT, 0>,
        P1::PinType<PORT, 1>,
        P2::PinType<PORT, 2>,
        P3::PinType<PORT, 3>,
        P4::PinType<PORT, 4>,
        P5::PinType<PORT, 5>,
        P6::PinType<PORT, 6>,
        P7::PinType<PORT, 7>,
    ) {
        #[inline(always)]
        fn initialize<const PORT: u8, const PIN: u8, P: UnconfiguredPinMode>(
            config: (P, PinConfig),
            port: impl PortAccess,
        ) -> P::PinType<PORT, PIN> {
            unsafe {
                config
                    .0
                    .initialize(config.1, PinAccess::steal_modify(port, PIN))
            }
        }
        let mut port = InitPortAccess::new(PortRegAccess(PORT, security::DEFAULT.into()));
        let result = (
            initialize(self.0, &mut port),
            initialize(self.1, &mut port),
            initialize(self.2, &mut port),
            initialize(self.3, &mut port),
            initialize(self.4, &mut port),
            initialize(self.5, &mut port),
            initialize(self.6, &mut port),
            initialize(self.7, &mut port),
        );
        port.finish();
        result
    }

    /// Sets the configuration for pin 0.
    #[must_use]
    pub fn p0<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, Mode, P1, P2, P3, P4, P5, P6, P7> {
        UnconfiguredPort(
            (mode, config),
            self.1,
            self.2,
            self.3,
            self.4,
            self.5,
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 1.
    #[must_use]
    pub fn p1<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, Mode, P2, P3, P4, P5, P6, P7> {
        UnconfiguredPort(
            self.0,
            (mode, config),
            self.2,
            self.3,
            self.4,
            self.5,
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 2.
    #[must_use]
    pub fn p2<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, Mode, P3, P4, P5, P6, P7> {
        UnconfiguredPort(
            self.0,
            self.1,
            (mode, config),
            self.3,
            self.4,
            self.5,
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 3.
    #[must_use]
    pub fn p3<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, P2, Mode, P4, P5, P6, P7> {
        UnconfiguredPort(
            self.0,
            self.1,
            self.2,
            (mode, config),
            self.4,
            self.5,
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 4.
    #[must_use]
    pub fn p4<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, P2, P3, Mode, P5, P6, P7> {
        UnconfiguredPort(
            self.0,
            self.1,
            self.2,
            self.3,
            (mode, config),
            self.5,
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 5.
    #[must_use]
    pub fn p5<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, P2, P3, P4, Mode, P6, P7> {
        UnconfiguredPort(
            self.0,
            self.1,
            self.2,
            self.3,
            self.4,
            (mode, config),
            self.6,
            self.7,
        )
    }

    /// Sets the configuration for pin 6.
    #[must_use]
    pub fn p6<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, P2, P3, P4, P5, Mode, P7> {
        UnconfiguredPort(
            self.0,
            self.1,
            self.2,
            self.3,
            self.4,
            self.5,
            (mode, config),
            self.7,
        )
    }

    /// Sets the configuration for pin 7.
    #[must_use]
    pub fn p7<Mode: PinMode>(
        self,
        mode: Mode,
        config: PinConfig,
    ) -> UnconfiguredPort<PORT, P0, P1, P2, P3, P4, P5, P6, Mode> {
        UnconfiguredPort(
            self.0,
            self.1,
            self.2,
            self.3,
            self.4,
            self.5,
            self.6,
            (mode, config),
        )
    }
}