Make sure that HAL users don't need to depend on esp-hal-common

esp-hal-common/src/gpio.rs

@@ -1,17 +1,15 @@
-//! GPIO driver
+//! GPIO Types
 //!
-//! Defines a series of macros which allow for the definition of each chip's
-//! GPIO pins in a generic manner. Implements the various traits defined by
-//! [embedded-hal].
-//!
-//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
+//! Various traits and enums to work with GPIO
 
 use core::marker::PhantomData;
 
+#[doc(hidden)]
 pub use paste::paste;
 
 use crate::pac::GPIO;
 
+#[doc(hidden)]
 #[cfg_attr(feature = "esp32", path = "gpio/esp32.rs")]
 #[cfg_attr(feature = "esp32c3", path = "gpio/esp32c3.rs")]
 #[cfg_attr(feature = "esp32s2", path = "gpio/esp32s2.rs")]
@@ -182,9 +180,12 @@ pub trait OutputPin: Pin {
     fn internal_pull_down(&mut self, on: bool) -> &mut Self;
 }
 
+#[doc(hidden)]
 pub struct SingleCoreInteruptStatusRegisterAccess {}
+#[doc(hidden)]
 pub struct DualCoreInteruptStatusRegisterAccess {}
 
+#[doc(hidden)]
 pub trait InteruptStatusRegisterAccess {
     fn pro_cpu_interrupt_status_read() -> u32;
 
@@ -236,6 +237,7 @@ impl InteruptStatusRegisterAccess for DualCoreInteruptStatusRegisterAccess {
     }
 }
 
+#[doc(hidden)]
 pub trait InterruptStatusRegisters<RegisterAccess>
 where
     RegisterAccess: InteruptStatusRegisterAccess,
@@ -257,9 +259,12 @@ where
     }
 }
 
+#[doc(hidden)]
 pub struct Bank0GpioRegisterAccess {}
+#[doc(hidden)]
 pub struct Bank1GpioRegisterAccess {}
 
+#[doc(hidden)]
 pub trait BankGpioRegisterAccess {
     fn write_out_en_clear(word: u32);
 
@@ -316,6 +321,7 @@ impl BankGpioRegisterAccess for Bank0GpioRegisterAccess {
     }
 }
 
+#[doc(hidden)]
 #[cfg(not(feature = "esp32c3"))]
 impl BankGpioRegisterAccess for Bank1GpioRegisterAccess {
     fn write_out_en_clear(word: u32) {
@@ -357,6 +363,7 @@ impl BankGpioRegisterAccess for Bank1GpioRegisterAccess {
     }
 }
 
+#[doc(hidden)]
 pub trait GpioRegisters<RegisterAccess>
 where
     RegisterAccess: BankGpioRegisterAccess,
@@ -390,6 +397,7 @@ where
     }
 }
 
+#[doc(hidden)]
 pub fn connect_low_to_peripheral(signal: InputSignal) {
     unsafe { &*GPIO::PTR }.func_in_sel_cfg[signal as usize].modify(|_, w| unsafe {
         w.sel()
@@ -401,6 +409,7 @@ pub fn connect_low_to_peripheral(signal: InputSignal) {
     });
 }
 
+#[doc(hidden)]
 pub fn connect_high_to_peripheral(signal: InputSignal) {
     unsafe { &*GPIO::PTR }.func_in_sel_cfg[signal as usize].modify(|_, w| unsafe {
         w.sel()
@@ -413,6 +422,7 @@ pub fn connect_high_to_peripheral(signal: InputSignal) {
 }
 
 // Only for ESP32 in order to workaround errata 3.6
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_errata36 {
     (None, $pull_down:expr, $pull_up:expr) => {
@@ -476,6 +486,7 @@ macro_rules! impl_errata36 {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_input {
     (
@@ -689,6 +700,7 @@ macro_rules! impl_input {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_output {
     (
@@ -923,6 +935,7 @@ macro_rules! impl_output {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_output_wrap {
     (
@@ -949,6 +962,7 @@ macro_rules! impl_output_wrap {
     ) => {};
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_gpio_register_access {
     (Bank0, $pxi:ident) => {
@@ -962,6 +976,7 @@ macro_rules! impl_gpio_register_access {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! impl_interrupt_status_register_access {
     (SingleCore, $pxi:ident) => {
@@ -975,6 +990,7 @@ macro_rules! impl_interrupt_status_register_access {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! gpio {
     (

esp32-hal/examples/gpio_interrupt.rs

@@ -6,20 +6,16 @@ use core::{cell::RefCell, fmt::Write};
 use esp32_hal::{
     clock::ClockControl,
     gpio::{Gpio0, IO},
+    gpio_types::{Event, Input, Pin, PullDown},
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    gpio::{Event, Pin},
-    interrupt,
-    Cpu,
-    Input,
-    PullDown,
-};
 use panic_halt as _;
 use xtensa_lx::mutex::{Mutex, SpinLockMutex};
 use xtensa_lx_rt::entry;

esp32-hal/examples/timer_interrupt.rs

@@ -4,13 +4,14 @@
 use core::{cell::RefCell, fmt::Write};
 
 use esp32_hal::{
+    interrupt,
     pac::{self, Peripherals, TIMG0, TIMG1, UART0},
     prelude::*,
+    Cpu,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{interrupt, Cpu};
 use panic_halt as _;
 use xtensa_lx::mutex::{Mutex, SpinLockMutex};
 use xtensa_lx_rt::entry;

esp32-hal/src/gpio.rs

@@ -1,3 +1,13 @@
+//! General Purpose I/Os
+//!
+//! To get access to the pins, you first need to convert them into a HAL
+//! designed struct from the pac struct `GPIO` and `IO_MUX` using `IO::new`.
+//!
+//! ```no_run
+//! let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let mut led = io.pins.gpio5.into_push_pull_output();
+//! ```
+
 use esp_hal_common::gpio::{types::*, *};
 
 gpio! {

esp32-hal/src/lib.rs

@@ -3,6 +3,7 @@
 pub use embedded_hal as ehal;
 pub use esp_hal_common::{
     clock,
+    gpio as gpio_types,
     i2c,
     interrupt,
     pac,

esp32c3-hal/examples/gpio_interrupt.rs

@@ -7,21 +7,16 @@ use bare_metal::Mutex;
 use esp32c3_hal::{
     clock::ClockControl,
     gpio::{Gpio9, IO},
+    gpio_types::{Event, Input, Pin, PullDown},
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    interrupt::{self},
-    Cpu,
-    Event,
-    Input,
-    Pin,
-    PullDown,
-};
 use panic_halt as _;
 use riscv_rt::entry;
 

esp32c3-hal/examples/systimer.rs

@@ -5,17 +5,15 @@ use core::{cell::RefCell, fmt::Write};
 
 use bare_metal::Mutex;
 use esp32c3_hal::{
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    systimer::{Alarm, SystemTimer, Target},
+    Cpu,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    interrupt::{self},
-    systimer::{Alarm, SystemTimer, Target},
-    Cpu,
-};
 use panic_halt as _;
 use riscv_rt::entry;
 

esp32c3-hal/examples/timer_interrupt.rs

@@ -5,16 +5,14 @@ use core::{cell::RefCell, fmt::Write};
 
 use bare_metal::Mutex;
 use esp32c3_hal::{
+    interrupt,
     pac::{self, Peripherals, TIMG0, TIMG1, UART0},
     prelude::*,
+    Cpu,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    interrupt::{self},
-    Cpu,
-};
 use panic_halt as _;
 use riscv_rt::entry;
 

esp32c3-hal/src/gpio.rs

@@ -1,3 +1,12 @@
+//! General Purpose I/Os
+//!
+//! To get access to the pins, you first need to convert them into a HAL
+//! designed struct from the pac struct `GPIO` and `IO_MUX` using `IO::new`.
+//!
+//! ```no_run
+//! let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let mut led = io.pins.gpio5.into_push_pull_output();
+//! ```
 use esp_hal_common::gpio::{types::*, *};
 
 gpio! {

esp32c3-hal/src/lib.rs

@@ -5,6 +5,7 @@ use core::arch::global_asm;
 pub use embedded_hal as ehal;
 pub use esp_hal_common::{
     clock,
+    gpio as gpio_types,
     i2c,
     interrupt,
     pac,

esp32s2-hal/examples/gpio_interrupt.rs

@@ -6,20 +6,16 @@ use core::{cell::RefCell, fmt::Write};
 use esp32s2_hal::{
     clock::ClockControl,
     gpio::{Gpio0, IO},
+    gpio_types::{Event, Input, Pin, PullDown},
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    gpio::{Event, Pin},
-    interrupt,
-    Cpu,
-    Input,
-    PullDown,
-};
 use panic_halt as _;
 use xtensa_lx::mutex::{CriticalSectionMutex, Mutex};
 use xtensa_lx_rt::entry;

esp32s2-hal/examples/systimer.rs

@@ -5,20 +5,18 @@ use core::{cell::RefCell, fmt::Write};
 
 use esp32s2_hal::{
     clock::ClockControl,
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    systimer::{Alarm, SystemTimer, Target},
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    interrupt,
-    Cpu,
-    systimer::{SystemTimer, Alarm, Target}
-};
 use panic_halt as _;
-use xtensa_lx::mutex::{Mutex, CriticalSectionMutex};
+use xtensa_lx::mutex::{CriticalSectionMutex, Mutex};
 use xtensa_lx_rt::entry;
 
 static mut SERIAL: CriticalSectionMutex<RefCell<Option<Serial<UART0>>>> =
@@ -92,7 +90,7 @@ fn main() -> ! {
     let mut delay = Delay::new(&clocks);
 
     unsafe {
-        xtensa_lx::interrupt::enable_mask(1 << 19 | 1 << 0 | 1 << 23 );
+        xtensa_lx::interrupt::enable_mask(1 << 19 | 1 << 0 | 1 << 23);
     }
 
     loop {
@@ -115,7 +113,7 @@ pub fn level1_interrupt() {
         interrupt::CpuInterrupt::Interrupt0LevelPriority1,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM0).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();
@@ -139,7 +137,7 @@ pub fn level2_interrupt() {
         interrupt::CpuInterrupt::Interrupt19LevelPriority2,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM1).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();
@@ -163,7 +161,7 @@ pub fn level3_interrupt() {
         interrupt::CpuInterrupt::Interrupt23LevelPriority3,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM2).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();

esp32s2-hal/examples/timer_interrupt.rs

@@ -4,13 +4,14 @@
 use core::{cell::RefCell, fmt::Write};
 
 use esp32s2_hal::{
+    interrupt,
     pac::{self, Peripherals, TIMG0, TIMG1, UART0},
     prelude::*,
+    Cpu,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{interrupt, Cpu};
 use panic_halt as _;
 use xtensa_lx::mutex::{CriticalSectionMutex, Mutex};
 use xtensa_lx_rt::entry;

esp32s2-hal/src/gpio.rs

@@ -1,3 +1,13 @@
+//! General Purpose I/Os
+//!
+//! To get access to the pins, you first need to convert them into a HAL
+//! designed struct from the pac struct `GPIO` and `IO_MUX` using `IO::new`.
+//!
+//! ```no_run
+//! let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let mut led = io.pins.gpio5.into_push_pull_output();
+//! ```
+
 use esp_hal_common::gpio::{types::*, *};
 
 gpio! {

esp32s2-hal/src/lib.rs

@@ -3,6 +3,7 @@
 pub use embedded_hal as ehal;
 pub use esp_hal_common::{
     clock,
+    gpio as gpio_types,
     i2c::{self, I2C},
     interrupt,
     pac,
@@ -10,6 +11,7 @@ pub use esp_hal_common::{
     pulse_control,
     ram,
     spi,
+    systimer,
     utils,
     Cpu,
     Delay,

esp32s3-hal/examples/gpio_interrupt.rs

@@ -6,20 +6,16 @@ use core::{cell::RefCell, fmt::Write};
 use esp32s3_hal::{
     clock::ClockControl,
     gpio::{Gpio0, IO},
+    gpio_types::{Event, Input, Pin, PullDown},
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    gpio::{Event, Pin},
-    interrupt,
-    Cpu,
-    Input,
-    PullDown,
-};
 use panic_halt as _;
 use xtensa_lx::mutex::{Mutex, SpinLockMutex};
 use xtensa_lx_rt::entry;

esp32s3-hal/examples/systimer.rs

@@ -5,18 +5,16 @@ use core::{cell::RefCell, fmt::Write};
 
 use esp32s3_hal::{
     clock::ClockControl,
+    interrupt,
     pac::{self, Peripherals, UART0},
     prelude::*,
+    systimer::{Alarm, SystemTimer, Target},
+    Cpu,
     Delay,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{
-    interrupt,
-    Cpu,
-    systimer::{SystemTimer, Alarm, Target}
-};
 use panic_halt as _;
 use xtensa_lx::mutex::{Mutex, SpinLockMutex};
 use xtensa_lx_rt::entry;
@@ -88,7 +86,7 @@ fn main() -> ! {
     let mut delay = Delay::new(&clocks);
 
     unsafe {
-        xtensa_lx::interrupt::enable_mask(1 << 19 | 1 << 0 | 1 << 23 );
+        xtensa_lx::interrupt::enable_mask(1 << 19 | 1 << 0 | 1 << 23);
     }
 
     loop {
@@ -111,7 +109,7 @@ pub fn level1_interrupt() {
         interrupt::CpuInterrupt::Interrupt0LevelPriority1,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM0).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();
@@ -135,7 +133,7 @@ pub fn level2_interrupt() {
         interrupt::CpuInterrupt::Interrupt19LevelPriority2,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM1).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();
@@ -159,7 +157,7 @@ pub fn level3_interrupt() {
         interrupt::CpuInterrupt::Interrupt23LevelPriority3,
     );
 
-    unsafe { 
+    unsafe {
         (&ALARM2).lock(|data| {
             let mut alarm = data.borrow_mut();
             let alarm = alarm.as_mut().unwrap();

esp32s3-hal/examples/timer_interrupt.rs

@@ -4,13 +4,14 @@
 use core::{cell::RefCell, fmt::Write};
 
 use esp32s3_hal::{
+    interrupt,
     pac::{self, Peripherals, TIMG0, TIMG1, UART0},
     prelude::*,
+    Cpu,
     RtcCntl,
     Serial,
     Timer,
 };
-use esp_hal_common::{interrupt, Cpu};
 use panic_halt as _;
 use xtensa_lx::mutex::{Mutex, SpinLockMutex};
 use xtensa_lx_rt::entry;

esp32s3-hal/src/gpio.rs

@@ -1,3 +1,13 @@
+//! General Purpose I/Os
+//!
+//! To get access to the pins, you first need to convert them into a HAL
+//! designed struct from the pac struct `GPIO` and `IO_MUX` using `IO::new`.
+//!
+//! ```no_run
+//! let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let mut led = io.pins.gpio5.into_push_pull_output();
+//! ```
+
 use esp_hal_common::gpio::{types::*, *};
 
 // ESP32S3 is a dual-core chip however pro cpu and app cpu shares the same

esp32s3-hal/src/lib.rs

@@ -3,6 +3,7 @@
 pub use embedded_hal as ehal;
 pub use esp_hal_common::{
     clock,
+    gpio as gpio_types,
     i2c,
     interrupt,
     pac,