#![cfg_attr(docsrs, procmacros::doc_replace)]

//! Dedicated GPIO access.

//!

//! This module implements fast GPIO access using special-purpose CPU features.

//! Dedicated GPIO access works by connecting peripheral signals between the CPU

//! and the GPIO pins, instead of using the GPIO registers via the peripheral bus.

//!

//! To use dedicated GPIOs, first you must obtain the channel objects. The channels

//! are created by calling the [`DedicatedGpio::new`] function. The fields of the

//! [`DedicatedGpio`] struct represent the channels. The channels are [`DedicatedGpioChannel`]

//! objects, which by default represent both input and output channels. The channels can be split

//! into [`DedicatedGpioInputChannel`] and [`DedicatedGpioOutputChannel`] halves, or may be

//! used unsplit.

#![doc = concat!(r#"

 > "#, chip!() , r#" specific: There are "#, property!("dedicated_gpio.channel_count", str) , r#" dedicated GPIO channels available.

 "#)]

//! Next, configure the pins you want to use as normal GPIO pin drivers. Then you can wrap them

//! into the dedicated GPIO drivers:

//! - [`DedicatedGpioInput`]

//! - [`DedicatedGpioOutput`]

//! - [`DedicatedGpioFlex`]

//!

//! The drivers can take channels and pins by value or by reference. Pass these objects by reference

//! if you plan on reusing them again, after dropping the dedicated driver.

//!

//! [`DedicatedGpioOutput`] can drive any number of GPIO pins. Each connected pin follows the

//! current dedicated GPIO channel level immediately.

//!

//! ## Bundles

//!

//! If you need to read or update multiple channels together, you can use the bundle helpers:

//! - [`DedicatedGpioInputBundle`]

//! - [`DedicatedGpioOutputBundle`]

//! - [`DedicatedGpioFlexBundle`]

//!

//! Bundles are lightweight objects that precompute a channel mask from one or more drivers,

//! allowing multi-channel operations with a single low-level read/write.

//!

//! ## Low-level functions

//!

//! This module also exposes low-level helpers for direct, channel-bitmask-based access:

//! - [`write_ll`]: write output levels for a selected set of channels in one operation

//! - [`read_all_ll`]: read the current input levels of all channels

//! - [`output_levels_ll`]: read the current output levels of all channels

//!

//! These functions operate purely on channel bitmasks (bit 0 -> channel 0, bit 1 -> channel 1, ...)

//! and do not track pin configuration. Prefer the higher-level drivers and bundles unless you

//! specifically need the lowest overhead.

#![cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

Dedicated GPIOs are tied to CPU cores and a driver must only be used on the core that has created it.

Do not send the drivers to another core, either directly, or indirectly via a thread that is not pinned to a core.

</section>

"#

)]

//! ## Examples

//! ### sharing drivers across multiple bundles

//!

//! The same driver can be borrowed by multiple bundles at the same time.

//!

//! In this example, we build two *input* bundles:

//! - `bundle_a` reads channels 0, 1, 2

//! - `bundle_b` reads channels 0, 2, 4

//!

//! Both bundles share the same `in0` and `in2` drivers, and we use

//! [`DedicatedGpioInputBundle::all_high`] to check if all channels in each bundle are currently

//! high.

//!

//! ```rust, no_run

//! # {before_snippet}

//! use esp_hal::gpio::{

//!     Input,

//!     InputConfig,

//!     dedicated::{DedicatedGpio, DedicatedGpioInput, DedicatedGpioInputBundle},

//! };

//!

//! // Create channels.

//! let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

//!

//! // Configure GPIO inputs

//! let p0 = Input::new(peripherals.GPIO0, InputConfig::default());

//! let p1 = Input::new(peripherals.GPIO1, InputConfig::default());

//! let p2 = Input::new(peripherals.GPIO2, InputConfig::default());

//! let p4 = Input::new(peripherals.GPIO4, InputConfig::default());

//!

//! let in0 = DedicatedGpioInput::new(channels.channel0.input, p0);

//! let in1 = DedicatedGpioInput::new(channels.channel1.input, p1);

//! let in2 = DedicatedGpioInput::new(channels.channel2.input, p2);

//! let in4 = DedicatedGpioInput::new(channels.channel4.input, p4);

//!

//! // Bundle A reads channels 0, 1, 2.

//! let mut bundle_a = DedicatedGpioInputBundle::new();

//! bundle_a

//!     .enable_input(&in0)

//!     .enable_input(&in1)

//!     .enable_input(&in2);

//!

//! // Bundle B reads channels 0, 2, 4.

//! // Note: `in0` and `in2` are *shared* with bundle A.

//! let mut bundle_b = DedicatedGpioInputBundle::new();

//! bundle_b

//!     .enable_input(&in0)

//!     .enable_input(&in2)

//!     .enable_input(&in4);

//!

//! // Check whether all channels in each bundle are currently high.

//! let a_all_high = bundle_a.all_high(); // true if ch0, ch1, ch2 are all high

//! let b_all_high = bundle_b.all_high(); // true if ch0, ch2, ch4 are all high

//!

//! # {after_snippet}

//! ```

//!

//! This pattern is useful when different subsystems want different views of the same set of

//! input channels without duplicating driver setup.

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

use procmacros::doc_replace;

use strum::EnumCount as _;

#[cfg_attr(dedicated_gpio_version = "esp32s2", path = "low_level/esp32s2.rs")]

#[cfg_attr(dedicated_gpio_version = "esp32s3", path = "low_level/esp32s3.rs")]

#[cfg_attr(dedicated_gpio_version = "riscv_v1", path = "low_level/riscv_v1.rs")]

#[cfg_attr(dedicated_gpio_version = "riscv_v2", path = "low_level/riscv_v2.rs")]

mod low_level;

use crate::{

    gpio::{

        AnyPin,

        GpioBank,

        InputSignal,

        Level,

        OutputSignal,

        interconnect::{PeripheralOutput, PeripheralSignal},

    },

    peripherals::GPIO_DEDICATED,

    private::Sealed,

    system::Cpu,

};

for_each_dedicated_gpio!(

    (channels $(($ch:literal)),*) => {

        paste::paste!(

            /// Dedicated GPIO channels.

            pub struct DedicatedGpio<'lt> {

                $(

                    #[doc = concat!("Channel ", stringify!($ch))]

                    pub [< channel $ch >]: DedicatedGpioChannel<'lt, $ch>,

                )*

            }

        );

        impl<'lt> DedicatedGpio<'lt> {

            /// Initializes the dedicated GPIO features and returns the channels.

            pub fn new(_: GPIO_DEDICATED<'lt>) -> Self {

                #[cfg(dedicated_gpio_needs_initialization)]

                Self::initialize();

                paste::paste!(

                    Self {

                        $([<channel $ch>]: DedicatedGpioChannel {

                            input: DedicatedGpioInputChannel { _marker: PhantomData },

                            output: DedicatedGpioOutputChannel { _marker: PhantomData },

                        },)*

                    }

                )

            }

        }

    };

);

impl DedicatedGpio<'_> {

    #[cfg(dedicated_gpio_needs_initialization)]

    fn initialize() {

        use crate::system::{Peripheral, PeripheralClockControl};

        if PeripheralClockControl::enable(Peripheral::DedicatedGpio) {

            PeripheralClockControl::reset(Peripheral::DedicatedGpio);

        } else {

            // Refcount was more than 0. Decrement to avoid overflow because we don't handle

            // dropping the driver.

            PeripheralClockControl::disable(Peripheral::DedicatedGpio);

        }

        low_level::initialize();

    }

}

// Channel traits allow us to implement DedicatedInputOutput, and users can choose to work with 8 IO

// channels for inputs/outputs instead of 8+8.

/// Marker trait for dedicated GPIO input channels.

pub trait InputChannel: Sealed {

    #[doc(hidden)]

    const CH: u8;

    #[doc(hidden)]

    fn mask(&self) -> u32 {

        1 << Self::CH

    }

    #[doc(hidden)]

    fn input_signal(&self) -> InputSignal {

        for_each_dedicated_gpio!(

            (signals $( ($cpu:literal, $signal_idx:literal, $signal_name:ident) ),*) => {

                const CHANNEL_COUNT: usize = property!("dedicated_gpio.channel_count");

                const SIGNALS: [[InputSignal; CHANNEL_COUNT]; Cpu::COUNT] = const {

                    let mut signals = [[core::mem::MaybeUninit::uninit(); CHANNEL_COUNT]; Cpu::COUNT];

                    $(

                        signals[$cpu][$signal_idx].write(InputSignal::$signal_name);

                    )*

                    unsafe { core::mem::transmute(signals) }

                };

            };

        );

        SIGNALS[Cpu::current() as usize][Self::CH as usize]

    }

}

/// Marker trait for dedicated GPIO output channels.

pub trait OutputChannel: Sealed {

    #[doc(hidden)]

    const CH: u8;

    #[doc(hidden)]

    fn mask(&self) -> u32 {

        1 << Self::CH

    }

    #[doc(hidden)]

    fn output_signal(&self) -> OutputSignal {

        for_each_dedicated_gpio!(

            (signals $( ($cpu:literal, $signal_idx:literal, $signal_name:ident) ),* ) => {

                const CHANNEL_COUNT: usize = property!("dedicated_gpio.channel_count");

                const SIGNALS: [[OutputSignal; CHANNEL_COUNT]; Cpu::COUNT] = const {

                    let mut signals = [[core::mem::MaybeUninit::uninit(); CHANNEL_COUNT]; Cpu::COUNT];

                    $(

                        signals[$cpu][$signal_idx].write(OutputSignal::$signal_name);

                    )*

                    unsafe { core::mem::transmute(signals) }

                };

            };

        );

        SIGNALS[Cpu::current() as usize][Self::CH as usize]

    }

}

// Driver traits, to allow working with Flex. These are implemented for both owned types and

// references, so that the user is not forced to give up the pin driver, and that we're not forced

// to figure out Drop semantics with `reborrow`, and the pins aren't remembered by the dedicated

// drivers anyway.

// We can't use the interconnect traits, because we want them to be implemented for references, too.

/// Marker trait for GPIO input drivers.

pub trait InputDriver: Sealed {

    #[doc(hidden)]

    fn pin(&self) -> u8;

    /// Connects the pin's peripheral input to an input signal source.

    #[doc(hidden)]

    fn set_input_connection(&self, signal: InputSignal);

}

#[instability::unstable]

impl InputDriver for super::Input<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin.pin

    }

        self.connect_input_to_peripheral(signal);

    }

}

#[instability::unstable]

impl InputDriver for &mut super::Input<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin.pin

    }

    fn set_input_connection(&self, signal: InputSignal) {

        self.connect_input_to_peripheral(signal);

    }

}

#[instability::unstable]

impl InputDriver for super::Flex<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin

    }

    fn set_input_connection(&self, signal: InputSignal) {

        self.connect_input_to_peripheral(signal);

    }

}

#[instability::unstable]

impl InputDriver for &mut super::Flex<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin

    }

    fn set_input_connection(&self, signal: InputSignal) {

        self.connect_input_to_peripheral(signal);

    }

}

/// Marker trait for GPIO output drivers.

pub trait OutputDriver: Sealed {

    #[doc(hidden)]

    fn pin(&self) -> u8;

    #[doc(hidden)]

    fn set_output_connection(&self, signal: OutputSignal);

}

#[instability::unstable]

impl OutputDriver for super::Output<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin.pin

    }

}

#[instability::unstable]

impl OutputDriver for &mut super::Output<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin.pin

    }

    fn set_output_connection(&self, signal: OutputSignal) {

        self.pin.pin.connect_peripheral_to_output(signal);

    }

}

#[instability::unstable]

impl OutputDriver for super::Flex<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin

    }

    fn set_output_connection(&self, signal: OutputSignal) {

        self.pin.connect_peripheral_to_output(signal);

    }

}

#[instability::unstable]

impl OutputDriver for &mut super::Flex<'_> {

    fn pin(&self) -> u8 {

        self.pin.pin

    }

    fn set_output_connection(&self, signal: OutputSignal) {

        self.pin.connect_peripheral_to_output(signal);

    }

}

/// A single dedicated GPIO channel, both input and output.

///

/// The channel can be split by moving its fields into separate input/output channel variables.

pub struct DedicatedGpioChannel<'lt, const CH: u8> {

    /// Channel input

    pub input: DedicatedGpioInputChannel<'lt, CH>,

    /// Channel output

    pub output: DedicatedGpioOutputChannel<'lt, CH>,

}

impl<const CH: u8> Sealed for DedicatedGpioChannel<'_, CH> {}

impl<const CH: u8> Sealed for &mut DedicatedGpioChannel<'_, CH> {}

impl<const CH: u8> DedicatedGpioChannel<'_, CH> {

    /// Conjures a new dedicated GPIO channel out of thin air.

    ///

    /// # Safety

    ///

    /// The [`DedicatedGpio`] struct must be initialized before this function is called. There

    /// should only be one reference to the channel in use at one time.

    pub unsafe fn steal() -> Self {

        unsafe {

            Self {

                input: DedicatedGpioInputChannel::steal(),

                output: DedicatedGpioOutputChannel::steal(),

            }

        }

    }

}

impl<const CH: u8> InputChannel for DedicatedGpioChannel<'_, CH> {

    const CH: u8 = CH;

}

impl<const CH: u8> OutputChannel for DedicatedGpioChannel<'_, CH> {

    const CH: u8 = CH;

}

impl<const CH: u8> InputChannel for &mut DedicatedGpioChannel<'_, CH> {

    const CH: u8 = CH;

}

impl<const CH: u8> OutputChannel for &mut DedicatedGpioChannel<'_, CH> {

    const CH: u8 = CH;

}

/// A single dedicated GPIO input channel.

pub struct DedicatedGpioInputChannel<'lt, const CH: u8> {

    _marker: PhantomData<&'lt mut ()>,

}

impl<const CH: u8> Sealed for DedicatedGpioInputChannel<'_, CH> {}

impl<const CH: u8> Sealed for &mut DedicatedGpioInputChannel<'_, CH> {}

impl<const CH: u8> DedicatedGpioInputChannel<'_, CH> {

    /// Conjures a new dedicated GPIO input channel out of thin air.

    ///

    /// # Safety

    ///

    /// The [`DedicatedGpio`] struct must be initialized before this function is called. There

    /// should only be one reference to the channel in use at one time.

    pub unsafe fn steal() -> Self {

        Self {

            _marker: PhantomData,

        }

    }

}

impl<const CH: u8> InputChannel for DedicatedGpioInputChannel<'_, CH> {

    const CH: u8 = CH;

}

impl<const CH: u8> InputChannel for &mut DedicatedGpioInputChannel<'_, CH> {

    const CH: u8 = CH;

}

/// A single dedicated GPIO output channel.

pub struct DedicatedGpioOutputChannel<'lt, const CH: u8> {

    _marker: PhantomData<&'lt mut ()>,

}

impl<const CH: u8> Sealed for DedicatedGpioOutputChannel<'_, CH> {}

impl<const CH: u8> Sealed for &mut DedicatedGpioOutputChannel<'_, CH> {}

impl<const CH: u8> DedicatedGpioOutputChannel<'_, CH> {

    /// Conjures a new dedicated GPIO output channel out of thin air.

    ///

    /// # Safety

    ///

    /// The [`DedicatedGpio`] struct must be initialized before this function is called. There

    /// should only be one reference to the channel in use at one time.

    pub unsafe fn steal() -> Self {

        Self {

            _marker: PhantomData,

        }

    }

}

impl<const CH: u8> OutputChannel for DedicatedGpioOutputChannel<'_, CH> {

    const CH: u8 = CH;

}

impl<const CH: u8> OutputChannel for &mut DedicatedGpioOutputChannel<'_, CH> {

    const CH: u8 = CH;

}

#[doc_replace]

/// A dedicated GPIO input driver.

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

The driver must only be used on the core that has created it. Do not send the driver to

another core, either directly, or indirectly via a thread that is not pinned to a core.

</section>

"#

)]

#[doc = ""]

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Input,

///     InputConfig,

///     Level,

///     dedicated::{DedicatedGpio, DedicatedGpioInput},

/// };

///

/// // Create an input pin driver:

/// let input = Input::new(peripherals.GPIO0, InputConfig::default());

///

/// // Create a dedicated GPIO driver:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

/// let mut dedicated_input = DedicatedGpioInput::new(channels.channel0, input);

///

/// // Now you can use the pin:

/// let level = dedicated_input.level();

/// #

/// # {after_snippet}

/// ```

pub struct DedicatedGpioInput<'lt> {

    _marker: PhantomData<&'lt mut ()>,

    mask: u32,

    #[cfg(all(debug_assertions, multi_core))]

    core: Cpu,

}

impl<'lt> DedicatedGpioInput<'lt> {

    /// Creates a new dedicated GPIO input driver.

    pub fn new<CH, P>(channel: CH, pin: P) -> Self

    where

        CH: InputChannel + 'lt,

        P: InputDriver + 'lt,

    {

        Self {

            mask: channel.mask(),

            _marker: PhantomData,

            #[cfg(all(debug_assertions, multi_core))]

            core: Cpu::current(),

        }

    }

    /// Reads the current state of the GPIO pins.

    #[inline(always)]

    pub fn level(&self) -> Level {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        let bits = low_level::read_in();

    }

}

impl embedded_hal::digital::ErrorType for DedicatedGpioInput<'_> {

    type Error = Infallible;

}

impl embedded_hal::digital::InputPin for DedicatedGpioInput<'_> {

    #[inline(always)]

    fn is_high(&mut self) -> Result<bool, Self::Error> {

        Ok(self.level() == Level::High)

    }

    #[inline(always)]

    fn is_low(&mut self) -> Result<bool, Self::Error> {

        Ok(self.level() == Level::Low)

    }

}

#[doc_replace]

/// A dedicated GPIO output driver.

///

/// Due to how the hardware works, [`DedicatedGpioOutput`] can drive any number of GPIO pins. Use

/// [`DedicatedGpioOutput::new`] to create a driver, then [`DedicatedGpioOutput::with_pin`] to add

/// output drivers.

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

The driver must only be used on the core that has created it. Do not send the driver to

another core, either directly, or indirectly via a thread that is not pinned to a core.

</section>

"#

)]

#[doc = ""]

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Level,

///     Output,

///     OutputConfig,

///     dedicated::{DedicatedGpio, DedicatedGpioOutput},

/// };

///

/// // Create a dedicated GPIO driver:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

/// let dedicated_output = DedicatedGpioOutput::new(channels.channel0);

///

/// // Add any number of output pin drivers:

/// let output = Output::new(peripherals.GPIO0, Level::Low, OutputConfig::default());

/// let mut dedicated_output = dedicated_output.with_pin(output);

///

/// // Now you can use the pin.

/// dedicated_output.set_level(Level::High);

/// #

/// # {after_snippet}

/// ```

pub struct DedicatedGpioOutput<'lt> {

    _marker: PhantomData<&'lt mut ()>,

    mask: u32,

    signal: OutputSignal,

    contained_gpios: [u32; GpioBank::COUNT],

    #[cfg(all(debug_assertions, multi_core))]

    core: Cpu,

}

impl<'lt> DedicatedGpioOutput<'lt> {

    /// Creates a new dedicated GPIO output driver.

    ///

    /// Returns an empty driver. Output drivers must be added with the [`Self::with_pin`] method.

    pub fn new<CH>(channel: CH) -> Self

    where

        CH: OutputChannel + 'lt,

    {

        low_level::set_output_enabled(channel.mask(), true);

        Self {

            mask: channel.mask(),

            signal: channel.output_signal(),

            contained_gpios: [0; GpioBank::COUNT],

            _marker: PhantomData,

            #[cfg(all(debug_assertions, multi_core))]

            core: Cpu::current(),

        }

    }

    /// Adds a GPIO output pin to this dedicated GPIO output.

    ///

    /// A dedicated GPIO output can drive any number of GPIO pins. The driver releases the pins when

    /// it is dropped.

    ///

    /// The GPIO matrix routes the current output of the dedicated GPIO channel to the pin. The pin

    /// follows the channel level immediately. The GPIO output register of the pin does not change.

    pub fn with_pin(mut self, pin: impl OutputDriver + 'lt) -> Self {

        let bank = pin.pin() / 32;

        let pin_in_bank = pin.pin() % 32;

    }

    /// Changes the current state of the GPIO pins.

    #[inline(always)]

    pub fn set_level(&mut self, level: Level) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        if level == Level::High {

            low_level::write(self.mask, self.mask);

        } else {

            low_level::write(self.mask, 0);

        }

    }

    /// Returns the current output state of the GPIO pins.

    ///

    /// Returns [`Level::High`] if any of the GPIO pins are set high, otherwise [`Level::Low`].

    #[inline(always)]

    pub fn output_level(&self) -> Level {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

    }

}

impl Drop for DedicatedGpioOutput<'_> {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        // Set the contained GPIOs back to GPIO mode.

            let bank_offset = bank as u8 * 32;

                let pin = pins.trailing_zeros() as u8;

                pins &= !(1 << pin);

                let gpio = unsafe { AnyPin::steal(bank_offset + pin) };

                gpio.disconnect_from_peripheral_output();

                gpio.connect_peripheral_to_output(OutputSignal::GPIO);

            }

        }

}

impl embedded_hal::digital::ErrorType for DedicatedGpioOutput<'_> {

    type Error = Infallible;

}

impl embedded_hal::digital::OutputPin for DedicatedGpioOutput<'_> {

    #[inline(always)]

    fn set_low(&mut self) -> Result<(), Self::Error> {

        self.set_level(Level::Low);

        Ok(())

    }

    #[inline(always)]

    fn set_high(&mut self) -> Result<(), Self::Error> {

        self.set_level(Level::High);

        Ok(())

    }

}

#[doc_replace]

/// A dedicated GPIO input and output driver.

#[cfg_attr(

    xtensa,

    doc = r#"

On ESP32-S2 and ESP32-S3, the GPIO's output is always enabled.

"#

)]

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

The driver must only be used on the core that has created it. Do not send the driver to

another core, either directly, or indirectly via a thread that is not pinned to a core.

</section>

"#

)]

#[doc = ""]

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Flex,

///     Input,

///     Level,

///     dedicated::{DedicatedGpio, DedicatedGpioFlex},

/// };

///

/// // Create a pin driver:

/// let flex = Flex::new(peripherals.GPIO0);

///

/// // Create a dedicated GPIO driver:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

/// let mut dedicated_io = DedicatedGpioFlex::new(channels.channel0, flex);

///

/// // Now you can use the pin:

/// let level = dedicated_io.level();

/// #

/// # {after_snippet}

/// ```

pub struct DedicatedGpioFlex<'lt> {

    _marker: PhantomData<&'lt mut ()>,

    mask: u32,

    pin: u8,

    #[cfg(all(debug_assertions, multi_core))]

    core: Cpu,

}

impl<'lt> DedicatedGpioFlex<'lt> {

    /// Creates a new dedicated GPIO input/output driver.

    pub fn new<CH, P>(channel: CH, pin: P) -> Self

    where

        CH: InputChannel + OutputChannel + 'lt,

        P: InputDriver + OutputDriver + 'lt,

    {

        pin.set_input_connection(channel.input_signal());

        pin.set_output_connection(channel.output_signal());

        Self {

            mask: <CH as OutputChannel>::mask(&channel),

            pin: <P as OutputDriver>::pin(&pin),

            _marker: PhantomData,

            #[cfg(all(debug_assertions, multi_core))]

            core: Cpu::current(),

        }

    }

    /// Enables or disables the output buffer of the GPIO pin.

    #[cfg(riscv)] // Xtensas always have the output enabled.

    pub fn set_output_enabled(&mut self, enabled: bool) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        low_level::set_output_enabled(self.mask, enabled);

    }

    /// Changes the current state of the GPIO pin.

    #[inline(always)]

    pub fn set_level(&mut self, level: Level) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        if level == Level::High {

            low_level::write(self.mask, self.mask);

        } else {

            low_level::write(self.mask, 0);

        }

    }

    /// Returns the current output state of the GPIO pin.

    #[inline(always)]

    pub fn output_level(&self) -> Level {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        Level::from(low_level::read_out() & self.mask != 0)

    }

    /// Reads the current state of the GPIO pins.

    #[inline(always)]

    pub fn level(&self) -> Level {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        let bits = low_level::read_in();

        Level::from(bits & self.mask != 0)

    }

}

impl Drop for DedicatedGpioFlex<'_> {

    fn drop(&mut self) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        let gpio = unsafe { AnyPin::steal(self.pin) };

        gpio.disconnect_from_peripheral_output();

        gpio.connect_peripheral_to_output(OutputSignal::GPIO);

    }

}

#[doc_replace]

/// Low-level function to write any number of dedicated output channels at once.

///

/// The `mask` selects which channels to write to. Channel positions are in

/// order: bit 0 marks channel 0, bit 1 marks channel 1, etc.

///

/// `value` is the value to write to the selected channels. A 0 bit sets the

/// channel's output to low, a 1 bit sets it to high.

///

/// # Examples

///

/// ```rust,no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Level,

///     Output,

///     OutputConfig,

///     dedicated::{DedicatedGpio, DedicatedGpioOutput, write_ll},

/// };

///

/// // Create dedicated GPIO drivers:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

/// let dedicated_output0 = DedicatedGpioOutput::new(channels.channel0);

/// let dedicated_output1 = DedicatedGpioOutput::new(channels.channel1);

/// let dedicated_output2 = DedicatedGpioOutput::new(channels.channel2);

///

/// // Configure output drivers:

/// let output0 = Output::new(peripherals.GPIO0, Level::Low, OutputConfig::default());

/// let output1 = Output::new(peripherals.GPIO1, Level::Low, OutputConfig::default());

/// let output2 = Output::new(peripherals.GPIO2, Level::Low, OutputConfig::default());

/// let output3 = Output::new(peripherals.GPIO3, Level::Low, OutputConfig::default());

///

/// // Configure dedicated output drivers:

/// let dedicated_output0 = dedicated_output0.with_pin(output0).with_pin(output1);

/// let dedicated_output1 = dedicated_output1.with_pin(output2);

/// let dedicated_output2 = dedicated_output2.with_pin(output3);

///

/// // Write all pins at once:

/// const MASK: u32 = 0b00000111;

/// const VALUE: u32 = 0b00000101; // Set GPIOs 0, 1, and 3 to high, 2 to low.

/// write_ll(MASK, VALUE);

/// #

/// # {after_snippet}

/// ```

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

Only channels configured on the current CPU core can be used.

</section>

"#

)]

#[inline(always)]

pub fn write_ll(mask: u32, value: u32) {

    low_level::write(mask, value);

}

/// Low-level function to read the current state of all dedicated input channels.

///

/// The returned value is a bitmask where each bit represents the state of a

/// channel. Bit 0 represents channel 0, bit 1 represents channel 1, etc.

#[inline(always)]

pub fn read_all_ll() -> u32 {

    low_level::read_in()

}

/// Low-level function to read the current output levels of all dedicated GPIO channels.

///

/// The returned value is a bitmask where each bit represents the output level of a channel:

/// bit 0 -> channel 0, bit 1 -> channel 1, etc. A bit value of 1 means the channel output is high.

#[inline(always)]

pub fn output_levels_ll() -> u32 {

    low_level::read_out()

}

#[doc_replace]

/// A bundle of dedicated GPIO output drivers.

///

/// An output bundle precomputes a channel mask from one or more

/// [`DedicatedGpioOutput`] drivers. Enables updating multiple dedicated output channels with a

/// single low-level write.

///

/// Attaching a driver does **not** change any output state. Dropping the output

/// drivers still controls when the underlying GPIO pins are released back to

/// normal GPIO mode.

///

/// ## Relationship to pins

///

/// Dedicated output channels can be connected to multiple GPIO pins via

/// [`DedicatedGpioOutput::with_pin`]. The bundle operates on *channels*, not

/// individual pins: writing channel bits affects every pin connected to that

/// channel.

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

Dedicated GPIO channels are tied to CPU cores. All output drivers attached to a bundle must be

configured on the same core, and the bundle must only be used on the core that created it.

</section>

"#

)]

#[doc = ""]

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Level,

///     Output,

///     OutputConfig,

///     dedicated::{DedicatedGpio, DedicatedGpioOutput, DedicatedGpioOutputBundle},

/// };

///

/// // Create channels:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

///

/// // Create output drivers for three channels:

/// let out0 = DedicatedGpioOutput::new(channels.channel0);

/// let out1 = DedicatedGpioOutput::new(channels.channel1);

/// let out2 = DedicatedGpioOutput::new(channels.channel2);

///

/// // Attach GPIO pins to the dedicated outputs (any number of pins per channel):

/// let p0 = Output::new(peripherals.GPIO0, Level::Low, OutputConfig::default());

/// let p1 = Output::new(peripherals.GPIO1, Level::Low, OutputConfig::default());

/// let p2 = Output::new(peripherals.GPIO2, Level::Low, OutputConfig::default());

///

/// let out0 = out0.with_pin(p0);

/// let out1 = out1.with_pin(p1);

/// let out2 = out2.with_pin(p2);

///

/// // Build a bundle that controls channels 0..=2:

/// let mut bundle = DedicatedGpioOutputBundle::new();

/// bundle

///     .enable_output(&out0)

///     .enable_output(&out1)

///     .enable_output(&out2);

///

/// // Set channel 0 and 2 high, keep channel 1 unchanged:

/// bundle.set_high(0b101);

///

/// // Now drive all channels in the bundle at once:

/// // - ch0 = 0

/// // - ch1 = 1

/// // - ch2 = 0

/// bundle.write_bits(0b010);

/// #

/// # {after_snippet}

/// ```

pub struct DedicatedGpioOutputBundle<'lt> {

    _marker: PhantomData<&'lt ()>,

    mask: u32,

    #[cfg(all(debug_assertions, multi_core))]

    core: Cpu,

}

impl<'lt> DedicatedGpioOutputBundle<'lt> {

    /// Creates a new, empty dedicated GPIO output bundle.

    ///

    /// A bundle is a *logical* grouping of one or more [`DedicatedGpioOutput`] drivers.

    /// Internally, it stores a precomputed channel mask (see [`Self::mask`]) which allows

    /// writing multiple dedicated GPIO channels efficiently.

    ///

    /// The returned bundle initially contains no channels. Add outputs using

    /// [`Self::enable_output`].

    ///

    /// Creating a bundle does **not** configure any hardware by itself.

    pub fn new() -> Self {

        Self {

            _marker: PhantomData,

            mask: 0,

            #[cfg(all(debug_assertions, multi_core))]

            core: Cpu::current(),

        }

    }

    #[doc_replace]

    /// Returns the channel mask of this bundle.

    ///

    /// Each bit corresponds to one dedicated GPIO channel:

    /// - bit 0 -> channel 0

    /// - bit 1 -> channel 1

    /// - ...

    ///

    /// A bit is set to 1 if that channel is currently included in the bundle.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    ///

    /// use esp_hal::gpio::{

    ///     Level,

    ///     Output,

    ///     OutputConfig,

    ///     dedicated::{DedicatedGpio, DedicatedGpioOutput, DedicatedGpioOutputBundle},

    /// };

    ///

    /// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

    /// let out0 = DedicatedGpioOutput::new(channels.channel0).with_pin(Output::new(

    ///     peripherals.GPIO0,

    ///     Level::Low,

    ///     OutputConfig::default(),

    /// ));

    /// let out2 = DedicatedGpioOutput::new(channels.channel2).with_pin(Output::new(

    ///     peripherals.GPIO2,

    ///     Level::Low,

    ///     OutputConfig::default(),

    /// ));

    /// let mut bundle = DedicatedGpioOutputBundle::new();

    /// bundle.enable_output(&out0).enable_output(&out2);

    ///

    /// let mask = bundle.mask(); // bit 0 -> ch0, bit 2 -> ch2, ...

    /// // For this bundle: mask == 0b0000_0101 (channels 0 and 2).

    ///

    /// # {after_snippet}

    /// ```

    #[inline(always)]

    pub fn mask(&self) -> u32 {

        self.mask

    }

    /// Attaches (enables) a dedicated output driver in this bundle. After enabling, the output

    /// channels of `out` can be controlled via this bundle.

    ///

    /// Logically borrows the provided [`DedicatedGpioOutput`] for the lifetime `'lt`.

    /// Multiple bundles may borrow the same output driver at the same time. Check examples in the

    /// module-level documentation for more.

    ///

    /// Does not change any GPIO output state.

    #[cfg_attr(

        multi_core,

        doc = r#"

<section class="warning">

All dedicated GPIO drivers in a bundle must be configured on the same core as the bundle itself

</section>

        "#

    )]

    pub fn enable_output<'d>(&mut self, out: &'lt DedicatedGpioOutput<'d>) -> &mut Self {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            out.core, self.core,

            "Trying to enable a dedicated GPIO driver configured on a different core from the bundle."

        );

        self.mask |= out.mask;

        self

    }

    /// Disables a dedicated output driver in this bundle.

    ///

    /// This updates the internal mask by clearing the channel bit(s) of `out`. After disabling,

    /// future *bundle* operations will no longer touch those channels.

    ///

    /// - This does **not** affect `out` itself. It only changes which channels future *bundle*

    ///   operations will touch.

    /// - This does **not** end the lifetime-based borrow of `out`. Even after disabling, `out`

    ///   still cannot be moved or dropped while this bundle exists.

    /// - Can be re-enabled later via [`Self::enable_output`]

    #[cfg_attr(

        multi_core,

        doc = r#"

<section class="warning">

Dedicated GPIO drivers must only be disabled if configured on the same core as the bundle itself.

</section>

"#

    )]

    pub fn disable_output<'d>(&mut self, out: &'lt DedicatedGpioOutput<'d>) -> &mut Self {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            out.core, self.core,

            "Trying to disable a dedicated GPIO driver configured on a different core from the bundle."

        );

        self.mask &= !out.mask;

        self

    }

    /// Sets selected channels **high**.

    ///

    /// For every bit set to 1 in `bits`, the corresponding dedicated output channel is driven

    /// high. Bits set to 0 are left unchanged.

    ///

    /// # Examples

    ///

    /// `bundle.set_high(0b1011_0001)` sets channels 0, 4, 5, and 7 high.

    ///

    /// <section class="warning">

    ///

    /// The caller must ensure that `bits` only contains channels included in this bundle,

    /// i.e. `bits & !self.mask() == 0`.

    ///

    /// For example, if the bundle mask is `0b0000_1011` (channels 0, 1, and 3), then `bits`

    /// must not set bit 2 (e.g. `0b0000_0100`), or channel 2 outside the bundle would be modified

    ///

    /// When compiled with `debug-assertions`, this condition is checked at runtime.

    /// </section>

    #[inline(always)]

    pub fn set_high(&mut self, bits: u32) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

            (bits & !self.mask) == 0,

            "Trying to set bits outside of the bundle mask"

        );

        low_level::write(bits, bits); // or low_level::write(self.mask, bits);

    }

    /// Sets selected channels **low**.

    ///

    /// For every bit set to 1 in `bits`, the corresponding dedicated output channel is driven

    /// low. Bits set to 0 are left unchanged.

    ///

    /// # Examples

    ///

    /// `bundle.set_low(0b1011_0001)` sets channels 0, 4, 5, and 7 low.

    ///

    /// <section class="warning">

    ///

    /// The caller must ensure that `bits` only contains channels included in this bundle,

    /// i.e. `bits & !self.mask() == 0`.

    ///

    /// For example, if the bundle mask is `0b0000_1011` (channels 0, 1, and 3), then `bits`

    /// must not set bit 7 (e.g. `0b1000_0000`), or channel 7 outside the bundle would be cleared

    ///

    /// When compiled with `debug-assertions`, this condition is checked at runtime.

    /// </section>

    #[inline(always)]

    pub fn set_low(&mut self, bits: u32) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

            (bits & !self.mask) == 0,

            "Trying to clear bits outside of the bundle mask"

        );

        low_level::write(bits, 0);

        // or low_level::write(bits & self.mask, 0);

        // the latter is safer (preventing writing to channels outside of the bundle) but slower

    }

    /// Writes output levels for **all channels included by this bundle**.

    ///

    /// Updates the output state of every channel whose bit is set in

    /// [`Self::mask`]. Channels not included in the bundle are not modified.

    ///

    /// `bits` provides the level for each channel in the bundle:

    /// - bit = 0 -> low

    /// - bit = 1 -> high

    ///

    /// # Examples

    ///

    /// If `self.mask()` is `0b1111_0000` (bundle contains channels 4..=7), then

    /// `bundle.write_bits(0b0001_0000)` sets channel 4 high and channels 5..=7 low,

    /// while leaving channels 0..=3 unchanged.

    ///

    /// <section class="warning">

    ///

    /// Only writes channels selected by [`Self::mask`]. Does **not** change channels outside the

    /// mask, even if `bits` contains 1s there

    ///

    /// The masked write only updates channels selected by the mask.

    ///

    /// </section>

    #[inline(always)]

    pub fn write_bits(&mut self, bits: u32) {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

        low_level::write(self.mask, bits);

    }

    /// Returns the current output levels of the channels included by this bundle.

    ///

    /// For channels outside the bundle mask, the corresponding bits are always 0.

    ///

    /// # Examples

    ///

    /// If the bundle mask is `0b0000_1011` (channels 0, 1, and 3), then

    /// `output_levels()` will only contain bits 0, 1, and 3, regardless of the output

    /// state of other channels.

    #[inline(always)]

    pub fn output_levels(&self) -> u32 {

        #[cfg(all(debug_assertions, multi_core))]

        debug_assert_eq!(

            self.core,

            Cpu::current(),

            "Dedicated GPIO used on a different CPU core than it was created on"

        );

    }

}

impl<'lt> Default for DedicatedGpioOutputBundle<'lt> {

    fn default() -> Self {

        Self::new()

    }

}

#[doc_replace]

/// A bundle of dedicated GPIO input drivers.

///

/// An input bundle precomputes a channel mask from one or more [`DedicatedGpioInput`]

/// drivers. Enables reading multiple dedicated input channels with a single low-level read (see

/// [`DedicatedGpioInputBundle::levels`])

///

/// Attaching a driver does **not** change any pin state. The bundle only stores a

/// channel mask; it does not own pins or remember which GPIOs were connected.

///

/// ## Relationship to pins

///

/// Dedicated input channels are fed by GPIO pins that were connected when creating

/// [`DedicatedGpioInput`]. The bundle operates on *channels*, not individual pins:

/// each bit in the returned mask corresponds to a dedicated input channel.

///

/// If a GPIO pin is later reconfigured (e.g. connected to a different peripheral input), that

/// changes what the channel reads. The bundle does not prevent such reconfiguration.

#[cfg_attr(

    multi_core,

    doc = r#"

<section class="warning">

Dedicated GPIO channels are tied to CPU cores. All input drivers attached to a bundle must be

configured on the same core, and the bundle must only be used on the core that created it.

</section>

"#

)]

#[doc = ""]

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// #

/// use esp_hal::gpio::{

///     Input,

///     InputConfig,

///     dedicated::{DedicatedGpio, DedicatedGpioInput, DedicatedGpioInputBundle},

/// };

///

/// // Create channels:

/// let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

///

/// // Create input drivers for two channels:

/// let p0 = Input::new(peripherals.GPIO0, InputConfig::default());

/// let p1 = Input::new(peripherals.GPIO1, InputConfig::default());

/// let in0 = DedicatedGpioInput::new(channels.channel0, p0);