From 10931726eb3586c5a790c1a168216c0c704ad53b Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Mon, 10 Jan 2022 15:23:01 -0800 Subject: [PATCH] Begin adding some doc comments, update rustfmt config --- esp-hal-common/src/delay.rs | 23 +++++++++++++++++++---- esp-hal-common/src/gpio.rs | 8 ++++++++ esp-hal-common/src/lib.rs | 18 ++++++++++++++++++ esp-hal-common/src/prelude.rs | 5 +++++ esp-hal-common/src/serial.rs | 5 +++++ esp-hal-common/src/timer.rs | 6 ++++++ rustfmt.toml | 17 +++++++++++------ 7 files changed, 72 insertions(+), 10 deletions(-) diff --git a/esp-hal-common/src/delay.rs b/esp-hal-common/src/delay.rs index 1173237a6..b2763b002 100644 --- a/esp-hal-common/src/delay.rs +++ b/esp-hal-common/src/delay.rs @@ -1,3 +1,9 @@ +//! Delay driver +//! +//! Implement the `DelayMs` and `DelayUs` traits from [embedded-hal]. +//! +//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/ + use embedded_hal::blocking::delay::{DelayMs, DelayUs}; pub use self::delay::Delay; @@ -22,8 +28,6 @@ where } } -// The delay implementation for RISC-V devices (ESP32-C3) uses the `SYSTIMER` -// peripheral, as unfortunately this device does NOT implement the `mcycle` CSR. #[cfg(feature = "esp32c3")] mod delay { use crate::pac::SYSTIMER; @@ -33,15 +37,23 @@ mod delay { // incremented by 1/16 μs on each `CNT_CLK` cycle. const CLK_FREQ_HZ: u64 = 16_000_000; + /// Delay driver + /// + /// Uses the `SYSTIMER` peripheral for counting clock cycles, as + /// unfortunately the ESP32-C3 does NOT implement the `mcycle` CSR, which is + /// how we would normally do this. pub struct Delay { systimer: SYSTIMER, } impl Delay { + /// Instantiate the `Delay` driver, taking ownership of the `SYSTIMER` + /// peripheral struct pub fn new(systimer: SYSTIMER) -> Self { Self { systimer } } + /// Delay for the specified number of microseconds pub fn delay(&self, us: u32) { let t0 = self.unit0_value(); let clocks = (us as u64 * CLK_FREQ_HZ) / 1_000_000; @@ -71,22 +83,25 @@ mod delay { } } -// The delay implementation for Xtensa devices (ESP32, ESP32-S2, ESP32-S3) uses -// the built-in timer from the `xtensa_lx` crate. #[cfg(not(feature = "esp32c3"))] mod delay { // FIXME: The ESP32-S2 and ESP32-S3 have fixed crystal frequencies of 40MHz. // This will not always be the case when using the ESP32. const CLK_FREQ_HZ: u64 = 40_000_000; + /// Delay driver + /// + /// Uses the built-in Xtensa timer from the `xtensa_lx` crate. #[derive(Default)] pub struct Delay; impl Delay { + /// Instantiate the `Delay` driver pub fn new() -> Self { Self } + /// Delay for the specified number of microseconds pub fn delay(&self, us: u32) { let clocks = (us as u64 * CLK_FREQ_HZ) / 1_000_000; xtensa_lx::timer::delay(clocks as u32); diff --git a/esp-hal-common/src/gpio.rs b/esp-hal-common/src/gpio.rs index 4b7602c41..a3208fb67 100644 --- a/esp-hal-common/src/gpio.rs +++ b/esp-hal-common/src/gpio.rs @@ -1,3 +1,11 @@ +//! GPIO driver +//! +//! 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/ + pub use paste::paste; #[macro_export] diff --git a/esp-hal-common/src/lib.rs b/esp-hal-common/src/lib.rs index 5ddd96838..0ce1a65f6 100644 --- a/esp-hal-common/src/lib.rs +++ b/esp-hal-common/src/lib.rs @@ -1,3 +1,21 @@ +//! `no_std` HAL implementations for the peripherals which are common among +//! Espressif devices. Implements a number of the traits defined by +//! [embedded-hal]. +//! +//! This crate should not be used directly; you should use one of the +//! device-specific HAL crates instead: +//! +//! - [esp32-hal] +//! - [esp32c3-hal] +//! - [esp32s2-hal] +//! - [esp32s3-hal] +//! +//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/ +//! [esp32-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32-hal +//! [esp32c3-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32c3-hal +//! [esp32s2-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32s2-hal +//! [esp32s3-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32s3-hal + #![no_std] #[cfg(feature = "esp32")] diff --git a/esp-hal-common/src/prelude.rs b/esp-hal-common/src/prelude.rs index 9380bdf1d..d6bdf629f 100644 --- a/esp-hal-common/src/prelude.rs +++ b/esp-hal-common/src/prelude.rs @@ -1,3 +1,8 @@ +//! The prelude +//! +//! Re-exports all traits required for interacting with the various peripheral +//! drivers implemented in this crate. + pub use embedded_hal::{ blocking::delay::{DelayMs as _, DelayUs as _}, digital::v2::{ diff --git a/esp-hal-common/src/serial.rs b/esp-hal-common/src/serial.rs index 6d727c554..4025d2371 100644 --- a/esp-hal-common/src/serial.rs +++ b/esp-hal-common/src/serial.rs @@ -1,3 +1,5 @@ +//! UART driver + use embedded_hal::serial::{Read, Write}; #[cfg(any(feature = "esp32", feature = "esp32s3"))] @@ -6,9 +8,11 @@ use crate::pac::{uart0::RegisterBlock, UART0, UART1}; const UART_FIFO_SIZE: u16 = 128; +/// Custom serial error type #[derive(Debug)] pub enum Error {} +/// UART driver pub struct Serial { uart: T, } @@ -23,6 +27,7 @@ impl Serial { } } +/// UART peripheral instance pub trait Instance { fn register_block(&self) -> &RegisterBlock; diff --git a/esp-hal-common/src/timer.rs b/esp-hal-common/src/timer.rs index f71cd7bbd..aa1a34117 100644 --- a/esp-hal-common/src/timer.rs +++ b/esp-hal-common/src/timer.rs @@ -1,3 +1,5 @@ +//! General-purpose timers + use embedded_hal::{ timer::{Cancel, CountDown, Periodic}, watchdog::WatchdogDisable, @@ -6,16 +8,19 @@ use void::Void; use crate::pac::{timg0::RegisterBlock, TIMG0, TIMG1}; +/// General-purpose timer pub struct Timer { timg: T, } +/// Custom timer error type pub enum Error { TimerActive, TimerInactive, AlarmInactive, } +/// Timer driver impl Timer where T: Instance, @@ -25,6 +30,7 @@ where } } +/// Timer peripheral instance pub trait Instance { fn register_block(&self) -> &RegisterBlock; diff --git a/rustfmt.toml b/rustfmt.toml index 10a643f39..3b1c22c55 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -1,7 +1,12 @@ -edition = "2018" -enum_discrim_align_threshold = 25 -group_imports = "StdExternalCrate" +# Comments +format_code_in_doc_comments = true +normalize_comments = true +wrap_comments = true + +# Enums +enum_discrim_align_threshold = 35 + +# Imports +group_imports = "StdExternalCrate" imports_granularity = "Crate" -imports_layout = "HorizontalVertical" -normalize_comments = true -wrap_comments = true +imports_layout = "HorizontalVertical"