Fix up docs and features; default to enabling eh1 instead of eh02 (#1313)

* Fix up docs and features; default to enabling eh1 instead of eh02

* Changelog

* Fix twai example

* Fixup from defaulting to eh1

esp-hal/CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Prefer mutable references over moving for DMA transactions (#1238)
 - Support runtime interrupt binding, adapt GPIO driver (#1231)
 - Renamed `eh1` feature to `embedded-hal`, feature-gated `embedded-hal@0.2.x` trait implementations (#1273)
+- Enable `embedded-hal` feature by default, instead of the `embedded-hal-02` feature (#1313)
 
 ### Removed
 

esp-hal/Cargo.toml

@@ -74,7 +74,7 @@ esp-metadata = { version = "0.1.0", path = "../esp-metadata" }
 serde        = { version = "1.0.197", features = ["derive"] }
 
 [features]
-default = ["embedded-hal-02", "rt", "vectored"]
+default = ["embedded-hal", "rt", "vectored"]
 
 riscv  = ["dep:riscv",     "critical-section/restore-state-u8",  "esp-riscv-rt?/zero-bss"]
 xtensa = ["dep:xtensa-lx", "critical-section/restore-state-u32"]
@@ -111,31 +111,31 @@ rt = [
 ]
 ## Enable interrupt vectoring.
 vectored = ["procmacros/interrupt"]
+## Configuration for placing device drivers in the IRAM for faster access.
+place-spi-driver-in-ram = []
 
-#! ### Chip Support Feature Flags
-## Target the ESP32.
+# Chip Support Feature Flags
+# Target the ESP32.
 esp32   = ["dep:esp32",   "xtensa", "xtensa-lx/spin", "xtensa-lx-rt?/esp32"]
-## Target the ESP32-C2.
+# Target the ESP32-C2.
 esp32c2 = ["dep:esp32c2", "riscv",  "portable-atomic/unsafe-assume-single-core"]
-## Target the ESP32-C3.
+# Target the ESP32-C3.
 esp32c3 = ["dep:esp32c3", "riscv",  "portable-atomic/unsafe-assume-single-core", "rv-zero-rtc-bss"]
-## Target the ESP32-C6.
+# Target the ESP32-C6.
 esp32c6 = ["dep:esp32c6", "riscv",  "procmacros/has-lp-core", "rv-zero-rtc-bss"]
-## Target the ESP32-H2.
+# Target the ESP32-H2.
 esp32h2 = ["dep:esp32h2", "riscv", "rv-zero-rtc-bss"]
-## Target the ESP32-P4.
+# Target the ESP32-P4.
 esp32p4 = ["dep:esp32p4", "riscv",  "procmacros/has-lp-core", "rv-zero-rtc-bss"]
-## Target the ESP32-S2.
+# Target the ESP32-S2.
 esp32s2 = ["dep:esp32s2", "xtensa", "portable-atomic/critical-section", "procmacros/has-ulp-core", "xtensa-lx-rt?/esp32s2", "usb-otg"]
-## Target the ESP32-S3.
+# Target the ESP32-S3.
 esp32s3 = ["dep:esp32s3", "xtensa", "procmacros/has-ulp-core", "xtensa-lx/spin", "xtensa-lx-rt?/esp32s3", "usb-otg"]
 
 #! ### RISC-V Exclusive Feature Flags
 ## Move the stack to start of RAM to get zero-cost stack overflow protection
 ## (ESP32-C6 and ESPS32-H2 only!).
 flip-link = ["esp-riscv-rt/fix-sp"]
-## Configuration for placing device drivers in the IRAM for faster access.
-place-spi-driver-in-ram = []
 ## Initialize the `.data` section of memory.
 rv-init-data = ["esp-riscv-rt?/init-data", "esp-riscv-rt?/init-rw-text"]
 ## Zero the `.bss` section of low-power memory.
@@ -164,11 +164,11 @@ defmt = [
     "embedded-io/defmt-03",
     "embedded-io-async?/defmt-03",
 ]
-## Implement the traits defined in the `0.2.x` release of `embedded-hal`.
-embedded-hal-02 = ["dep:embedded-hal-02"]
 ## Implement the traits defined in the `1.0.0` releases of `embedded-hal` and
 ## `embedded-hal-nb` for the relevant peripherals.
 embedded-hal = ["dep:embedded-hal", "dep:embedded-hal-nb", "dep:embedded-can"]
+## Implement the traits defined in the `0.2.x` release of `embedded-hal`.
+embedded-hal-02 = ["dep:embedded-hal-02"]
 ## Implement the traits defined in `embedded-io` for certain peripherals.
 embedded-io = ["dep:embedded-io"]
 ## Implement the `ufmt_write::uWrite` trait for certain peripherals.
@@ -217,6 +217,14 @@ opsram-8m = []
 ## Use externally connected Octal RAM (16MB).
 opsram-16m = []
 
+# This feature is intended for testing; you probably don't want to enable it:
+ci = [
+    "default",
+    "embedded-hal-02",
+    "ufmt",
+    "async",
+]
+
 [lints.clippy]
 mixed_attributes_style = "allow"
 

esp-hal/src/analog/adc/esp32.rs

@@ -249,7 +249,9 @@ impl RegisterAccess for ADC2 {
 /// Analog-to-Digital Converter peripheral driver.
 pub struct ADC<'d, ADC> {
     _adc: PeripheralRef<'d, ADC>,
+    #[allow(dead_code)] // FIXME
     attenuations: [Option<Attenuation>; 10],
+    #[allow(dead_code)] // FIXME
     active_channel: Option<u8>,
 }
 
@@ -418,6 +420,7 @@ macro_rules! impl_adc_interface {
 }
 
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::{ADC1, ADC2};
 
     impl_adc_interface! {

esp-hal/src/analog/adc/riscv.rs

@@ -486,7 +486,9 @@ impl CalibrationAccess for crate::peripherals::ADC2 {
 /// Analog-to-Digital Converter peripheral driver.
 pub struct ADC<'d, ADCI> {
     _adc: PeripheralRef<'d, ADCI>,
+    #[allow(dead_code)] // FIXME
     attenuations: [Option<Attenuation>; NUM_ATTENS],
+    #[allow(dead_code)] // FIXME
     active_channel: Option<u8>,
 }
 
@@ -648,6 +650,7 @@ macro_rules! impl_adc_interface {
 
 #[cfg(esp32c2)]
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::ADC1;
 
     impl_adc_interface! {
@@ -663,6 +666,7 @@ mod adc_implementation {
 
 #[cfg(esp32c3)]
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::{ADC1, ADC2};
 
     impl_adc_interface! {
@@ -684,6 +688,7 @@ mod adc_implementation {
 
 #[cfg(esp32c6)]
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::ADC1;
 
     impl_adc_interface! {
@@ -701,6 +706,7 @@ mod adc_implementation {
 
 #[cfg(esp32h2)]
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::ADC1;
 
     impl_adc_interface! {

esp-hal/src/analog/adc/xtensa.rs

@@ -524,7 +524,9 @@ impl CalibrationAccess for crate::peripherals::ADC2 {
 /// Analog-to-Digital Converter peripheral driver.
 pub struct ADC<'d, ADC> {
     _adc: PeripheralRef<'d, ADC>,
+    #[allow(dead_code)] // FIXME
     attenuations: [Option<Attenuation>; 10],
+    #[allow(dead_code)] // FIXME
     active_channel: Option<u8>,
 }
 
@@ -719,6 +721,7 @@ macro_rules! impl_adc_interface {
 }
 
 mod adc_implementation {
+    #[cfg(feature = "embedded-hal-02")]
     use crate::peripherals::{ADC1, ADC2};
 
     impl_adc_interface! {

esp-hal/src/i2c.rs

@@ -255,10 +255,10 @@ where
         self.peripheral.master_write_read(address, bytes, buffer)
     }
 
-    fn transaction<'a>(
+    fn transaction(
         &mut self,
         _address: u8,
-        _operations: &mut [embedded_hal::i2c::Operation<'a>],
+        _operations: &mut [embedded_hal::i2c::Operation<'_>],
     ) -> Result<(), Self::Error> {
         todo!()
     }

esp-hal/src/rng.rs

@@ -63,7 +63,9 @@
 //! rng.read(&mut buffer).unwrap();
 //! ```
 
-use core::{convert::Infallible, marker::PhantomData};
+#[cfg(feature = "embedded-hal-02")]
+use core::convert::Infallible;
+use core::marker::PhantomData;
 
 use crate::{peripheral::Peripheral, peripherals::RNG};
 

esp-hal/src/rtc_cntl/mod.rs

@@ -805,7 +805,7 @@ impl Rwdt {
         self.set_write_protection(true);
     }
 
-    fn set_timeout(&mut self, timeout: MicrosDurationU64) {
+    pub fn set_timeout(&mut self, timeout: MicrosDurationU64) {
         #[cfg(not(any(esp32c6, esp32h2)))]
         let rtc_cntl = unsafe { &*LPWR::PTR };
         #[cfg(any(esp32c6, esp32h2))]

esp-hal/src/spi/master.rs

@@ -1532,7 +1532,6 @@ pub mod dma {
             }
 
             fn write(&mut self, words: &[u8]) -> Result<(), Self::Error> {
-                Ok(
                 if !crate::soc::is_valid_ram_address(&words[0] as *const _ as u32) {
                     for chunk in words.chunks(SIZE) {
                         self.buffer[..chunk.len()].copy_from_slice(chunk);
@@ -1540,12 +1539,11 @@ pub mod dma {
                     }
                 } else {
                     self.inner.write(words)?;
-                    },
-                )
+                }
+                Ok(())
             }
 
             fn transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Self::Error> {
-                Ok(
                 if !crate::soc::is_valid_ram_address(&write[0] as *const _ as u32) {
                     for (read, write) in read.chunks_mut(SIZE).zip(write.chunks(SIZE)) {
                         self.buffer[..write.len()].copy_from_slice(write);
@@ -1553,8 +1551,8 @@ pub mod dma {
                     }
                 } else {
                     self.inner.transfer(read, write)?;
-                    },
-                )
+                }
+                Ok(())
             }
 
             fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Self::Error> {
@@ -1608,9 +1606,9 @@ mod ehal1 {
 
         fn transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Self::Error> {
             // Optimizations
-            if read.len() == 0 {
+            if read.is_empty() {
                 SpiBus::write(self, write)?;
-            } else if write.len() == 0 {
+            } else if write.is_empty() {
                 SpiBus::read(self, read)?;
             }
 

esp-hal/src/timer.rs

@@ -40,6 +40,7 @@ use core::{
 };
 
 use fugit::{HertzU32, MicrosDurationU64};
+#[cfg(feature = "embedded-hal-02")]
 use void::Void;
 
 #[cfg(timg1)]
@@ -221,6 +222,7 @@ where
 /// General-purpose Timer driver
 pub struct Timer<T> {
     timg: T,
+    #[allow(dead_code)] // FIXME
     apb_clk_freq: HertzU32,
 }
 
@@ -638,6 +640,7 @@ where
     }
 }
 
+#[allow(dead_code)] // FIXME
 fn timeout_to_ticks<T, F>(timeout: T, clock: F, divider: u32) -> u64
 where
     T: Into<MicrosDurationU64>,
@@ -781,7 +784,7 @@ where
             .write(|w| unsafe { w.wdt_wkey().bits(0u32) });
     }
 
-    fn feed(&mut self) {
+    pub fn feed(&mut self) {
         let reg_block = unsafe { &*TG::register_block() };
 
         reg_block
@@ -795,7 +798,7 @@ where
             .write(|w| unsafe { w.wdt_wkey().bits(0u32) });
     }
 
-    fn set_timeout(&mut self, timeout: MicrosDurationU64) {
+    pub fn set_timeout(&mut self, timeout: MicrosDurationU64) {
         let timeout_raw = (timeout.to_nanos() * 10 / 125) as u32;
 
         let reg_block = unsafe { &*TG::register_block() };

examples/Cargo.toml

@@ -21,6 +21,7 @@ embedded-hal-02     = { version = "0.2.7", package = "embedded-hal", features =
 embedded-hal-async  = "1.0.0"
 embedded-hal-bus    = "0.1.0"
 embedded-io-async   = "0.6.1"
+embedded-can        = "0.4.1"
 esp-alloc           = "0.3.0"
 esp-backtrace       = { version = "0.11.1", features = ["exception-handler", "panic-handler", "println"] }
 esp-hal             = { version = "0.16.0", path = "../esp-hal", features = ["log"] }

examples/src/bin/twai.rs

@@ -12,6 +12,7 @@
 //! `IS_FIRST_SENDER` below must be set to false on one of the ESP's
 
 //% CHIPS: esp32c3 esp32s3
+//% FEATURES: embedded-hal
 
 #![no_std]
 #![no_main]
@@ -20,12 +21,12 @@ const IS_FIRST_SENDER: bool = true;
 
 // Run this example with the embedded-hal feature enabled to use embedded-can instead of
 // embedded-hal-0.2.7. embedded-can was split off from embedded-hal before it's
-// upgrade to 1.0.0. cargo run --example twai --features embedded-hal --release
+// upgrade to 1.0.0. cargo run --example twai --release
 #[cfg(feature = "embedded-hal")]
 use embedded_can::{nb::Can, Frame, StandardId};
 // Run this example without the embedded-hal flag to use the embedded-hal 0.2.7 CAN traits.
-// cargo run --example twai --release
-#[cfg(not(feature = "embedded-hal"))]
+// cargo run --example twai --features embedded-hal-02 --release
+#[cfg(feature = "embedded-hal-02")]
 use embedded_hal_02::can::{Can, Frame, StandardId};
 use esp_backtrace as _;
 use esp_hal::{

xtask/src/lib.rs

@@ -150,12 +150,18 @@ pub fn build_documentation(
 
     log::info!("Building '{package_name}' documentation targeting '{chip}'");
 
+    let mut features = vec![chip.to_string()];
+
+    if matches!(package, Package::EspHal) {
+        features.push("ci".to_owned())
+    }
+
     // Build up an array of command-line arguments to pass to `cargo`:
     let mut builder = CargoArgsBuilder::default()
         .subcommand("doc")
         .arg("-Zbuild-std=core") // Required for Xtensa, for some reason
         .target(target)
-        .features(&[chip.to_string()]);
+        .features(&features);
 
     if open {
         builder = builder.arg("--open");