From 001adebce5be4ee1387e7ff3be6f6f7a9ecc691e Mon Sep 17 00:00:00 2001 From: David Sawatzke Date: Fri, 10 Apr 2020 06:04:17 +0200 Subject: [PATCH 1/2] Improve & unify documentation for implemented embededd-hal traits As proposed in https://github.com/lpc-rs/lpc8xx-hal/pull/233#issuecomment-611881482 --- src/adc.rs | 5 +++++ src/ctimer.rs | 8 ++++++++ src/delay.rs | 13 +++++++++++++ src/gpio.rs | 21 +++++++++++---------- src/i2c.rs | 6 ++++++ src/mrt.rs | 6 ++++++ src/spi.rs | 9 +++++++++ src/usart/peripheral.rs | 21 +++++++++++++-------- src/usart/rx.rs | 6 ++++-- src/usart/tx.rs | 10 +++++----- src/wkt.rs | 6 ++++++ 11 files changed, 86 insertions(+), 25 deletions(-) diff --git a/src/adc.rs b/src/adc.rs index a1daab926..fb06981a6 100644 --- a/src/adc.rs +++ b/src/adc.rs @@ -49,8 +49,12 @@ use crate::{ /// /// Please refer to the [module documentation] for more information. /// +/// # `embedded-hal` traits +/// - [`embedded_hal::adc::OneShot`] for measuring the voltage on a pin +/// /// [`Peripherals`]: ../struct.Peripherals.html /// [module documentation]: index.html +/// [`embedded_hal::adc::OneShot`]: #impl-OneShot%3CADC%3CEnabled%3C()%3E%3E%2C%20u16%2C%20PIN%3E pub struct ADC { adc: pac::ADC0, _state: State, @@ -153,6 +157,7 @@ where { type Error = (); + /// Request that the ADC begin a conversion on the specified pin fn read(&mut self, _: &mut PIN) -> nb::Result { // Start the measurement of the given channel // Follows the description in the um diff --git a/src/ctimer.rs b/src/ctimer.rs index 84e260fa3..20c4e7c44 100644 --- a/src/ctimer.rs +++ b/src/ctimer.rs @@ -81,6 +81,11 @@ pub struct DetachedPwmPin { } /// Represents a pwm channel assigned to an output pin +/// +/// # `embedded-hal` traits +/// - [`embedded_hal::PwmPin`] +/// +/// [`embedded_hal::PwmPin`]: #impl-PwmPin pub struct CTimerPwmPin { mr: RegProxy, msr: RegProxy, @@ -195,14 +200,17 @@ impl PwmPin for CTimerPwmPin { // and would involve a hidden `CriticalSection` fn disable(&mut self) {} + /// Returns the current duty cycle fn get_duty(&self) -> Self::Duty { self.msr[self.number as usize].read().match_shadow().bits() } + /// Returns the maximum duty cycle value fn get_max_duty(&self) -> Self::Duty { self.mr[3].read().match_().bits() } + /// Sets a new duty cycle fn set_duty(&mut self, duty: Self::Duty) { unsafe { self.msr[self.number as usize] diff --git a/src/delay.rs b/src/delay.rs index c6c5ed42f..5fd9246ea 100644 --- a/src/delay.rs +++ b/src/delay.rs @@ -29,6 +29,13 @@ const SYSTICK_RANGE: u32 = 0x0100_0000; const SYSTEM_CLOCK: u32 = 12_000_000; /// System timer (SysTick) as a delay provider +/// +/// # `embedded-hal` traits +/// - [`embedded_hal::blocking::delay::DelayUs`] +/// - [`embedded_hal::blocking::delay::DelayMs`] +/// +/// [`embedded_hal::blocking::delay::DelayUs`]: #impl-DelayUs%3Cu32%3E +/// [`embedded_hal::blocking::delay::DelayMs`]: #impl-DelayMs%3Cu32%3E #[derive(Clone)] pub struct Delay { scale: u32, @@ -52,6 +59,7 @@ impl Delay { } impl DelayMs for Delay { + /// Pauses execution for `ms` milliseconds // At 30 MHz (the maximum frequency), calling delay_us with ms * 1_000 directly overflows at 0x418937 (over the max u16 value) // So we implement a separate, higher level, delay loop fn delay_ms(&mut self, mut ms: u32) { @@ -65,6 +73,7 @@ impl DelayMs for Delay { } impl DelayMs for Delay { + /// Pauses execution for `ms` milliseconds fn delay_ms(&mut self, ms: u16) { // Call delay_us directly, since we don't have to use the additional // delay loop the u32 variant uses @@ -73,6 +82,7 @@ impl DelayMs for Delay { } impl DelayMs for Delay { + /// Pauses execution for `ms` milliseconds fn delay_ms(&mut self, ms: u8) { self.delay_ms(ms as u16); } @@ -80,6 +90,7 @@ impl DelayMs for Delay { // At 30MHz (the maximum frequency), this overflows at approx. 2^32 / 30 = 146 seconds impl DelayUs for Delay { + /// Pauses execution for `us` milliseconds fn delay_us(&mut self, us: u32) { // The SysTick Reload Value register supports values between 1 and 0x00FFFFFF. // Here half the maximum is used so we have some play if there's a long running interrupt. @@ -108,12 +119,14 @@ impl DelayUs for Delay { } impl DelayUs for Delay { + /// Pauses execution for `us` milliseconds fn delay_us(&mut self, us: u16) { self.delay_us(us as u32) } } impl DelayUs for Delay { + /// Pauses execution for `us` milliseconds fn delay_us(&mut self, us: u8) { self.delay_us(us as u32) } diff --git a/src/gpio.rs b/src/gpio.rs index c7c4dda0a..6279d7241 100644 --- a/src/gpio.rs +++ b/src/gpio.rs @@ -183,19 +183,20 @@ impl GPIO { /// You can get access to an instance of this struct by switching a pin to the /// GPIO state, using [`Pin::into_input_pin`] or [`Pin::into_output_pin`]. /// -/// While in input mode, this struct implements the [`InputPin`] trait. -/// -/// While in output mode, this struct implements the following traits: -/// - [`OutputPin`] -/// - [`StatefulOutputPin`] -/// - [`ToggleableOutputPin`] +/// # `embedded-hal` traits +/// - While in input mode +/// - [`embedded_hal::digital::v2::InputPin`] for reading the pin state +/// - While in output mode +/// - [`embedded_hal::digital::v2::OutputPin`] for setting the pin state +/// - [`embedded_hal::digital::v2::StatefulOutputPin`] for reading the pin output state +/// - [`embedded_hal::digital::v2::ToggleableOutputPin`] for toggling the pin state /// /// [`Pin::into_input_pin`]: ../pins/struct.Pin.html#method.into_input_pin /// [`Pin::into_output_pin`]: ../pins/struct.Pin.html#method.into_output_pin -/// [`InputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.InputPin.html -/// [`OutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.OutputPin.html -/// [`StatefulOutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.StatefulOutputPin.html -/// [`ToggleableOutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.ToggleableOutputPin.html +/// [`embedded_hal::digital::v2::InputPin`]: #impl-InputPin +/// [`embedded_hal::digital::v2::OutputPin`]: #impl-OutputPin +/// [`embedded_hal::digital::v2::StatefulOutputPin`]: #impl-StatefulOutputPin +/// [`embedded_hal::digital::v2::ToggleableOutputPin`]: #impl-ToggleableOutputPin pub struct GpioPin { token: pins::Token, _direction: D, diff --git a/src/i2c.rs b/src/i2c.rs index ca9e5e6b3..a5d70f05d 100644 --- a/src/i2c.rs +++ b/src/i2c.rs @@ -81,6 +81,12 @@ use crate::{ /// Additional limitations are documented on the specific methods that they /// apply to. /// +/// # `embedded-hal` traits +/// - [`embedded_hal::blocking::i2c::Read`] for synchronous reading +/// - [`embedded_hal::blocking::i2c::Write`] for synchronous writing +/// +/// [`embedded_hal::blocking::i2c::Read`]: #impl-Read +/// [`embedded_hal::blocking::i2c::Write`]: #impl-Write /// [module documentation]: index.html pub struct I2C { i2c: I, diff --git a/src/mrt.rs b/src/mrt.rs index 55b45bfd6..d9d5c5b6a 100644 --- a/src/mrt.rs +++ b/src/mrt.rs @@ -59,6 +59,11 @@ impl MRT { pub const MAX_VALUE: u32 = 0x7fff_ffff - 1; /// Represents a MRT0 channel +/// +/// # `embedded-hal` traits +/// - [`embedded_hal::timer::CountDown`] +/// +/// [`embedded_hal::timer::CountDown`]: #impl-CountDown pub struct Channel(RegProxy); impl Channel @@ -109,6 +114,7 @@ where .write(|w| unsafe { w.ivalue().bits(reload + 1) }); } + /// Non-blockingly "waits" until the count down finishes fn wait(&mut self) -> Result<(), Void> { if self.0.stat.read().intflag().is_pending_interrupt() { // Reset the interrupt flag diff --git a/src/spi.rs b/src/spi.rs index 125fc43f5..49d773f66 100644 --- a/src/spi.rs +++ b/src/spi.rs @@ -75,8 +75,17 @@ use crate::{ /// /// Please refer to the [module documentation] for more information. /// +/// # `embedded-hal` traits +/// +/// - [`embedded_hal::spi::FullDuplex`] for asynchronous transfers +/// - [`embedded_hal::blocking::spi::Transfer`] for synchronous transfers +/// - [`embedded_hal::blocking::spi::Write`] for synchronous writes +/// /// [`Peripherals`]: ../struct.Peripherals.html /// [module documentation]: index.html +/// [`embedded_hal::spi::FullDuplex`]: #impl-FullDuplex%3Cu8%3E +/// [`embedded_hal::blocking::spi::Transfer`]: #impl-Transfer%3CW%3E +/// [`embedded_hal::blocking::spi::Write`]: #impl-Write%3CW%3E pub struct SPI { spi: I, _state: State, diff --git a/src/usart/peripheral.rs b/src/usart/peripheral.rs index 608494599..3a7231a49 100644 --- a/src/usart/peripheral.rs +++ b/src/usart/peripheral.rs @@ -30,18 +30,19 @@ use super::{ /// same place, or you can move the `rx` and `tx` fields out of this struct, to /// use the sender and receiver from different contexts. /// -/// This struct implement the following traits: -/// - [`embedded_hal::serial::Read`] -/// - [`embedded_hal::serial::Write`] -/// - [`embedded_hal::blocking::serial::Write`] -/// /// Please refer to the [module documentation] for more information. /// +/// # `embedded-hal` traits +/// - [`embedded_hal::serial::Read`] for asynchronous receiving +/// - [`embedded_hal::serial::Write`] for asynchronous sending +/// - [`embedded_hal::blocking::serial::Write`] for synchronous sending +/// +/// /// [`Peripherals`]: ../struct.Peripherals.html -/// [`embedded_hal::serial::Read`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Read.html -/// [`embedded_hal::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Write.html -/// [`embedded_hal::blocking::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/blocking/serial/trait.Write.html /// [module documentation]: index.html +/// [`embedded_hal::serial::Read`]: #impl-Read%3Cu8%3E +/// [`embedded_hal::serial::Write`]: #impl-Write%3Cu8%3E +/// [`embedded_hal::blocking::serial::Write`]: #impl-Write pub struct USART { /// The USART Receiver pub rx: Rx, @@ -267,6 +268,7 @@ where { type Error = Error; + /// Reads a single word from the serial interface fn read(&mut self) -> nb::Result { self.rx.read() } @@ -278,10 +280,12 @@ where { type Error = Void; + /// Writes a single word to the serial interface fn write(&mut self, word: u8) -> nb::Result<(), Self::Error> { self.tx.write(word) } + /// Ensures that none of the previously written words are still buffered fn flush(&mut self) -> nb::Result<(), Self::Error> { self.tx.flush() } @@ -297,6 +301,7 @@ where Self: BlockingWriteDefault, I: Instance, { + /// Writes a string slice into this writer, returning whether the write succeeded. fn write_str(&mut self, s: &str) -> fmt::Result { self.tx.write_str(s) } diff --git a/src/usart/rx.rs b/src/usart/rx.rs index 5b4256660..bbc99d531 100644 --- a/src/usart/rx.rs +++ b/src/usart/rx.rs @@ -6,9 +6,11 @@ use super::instances::Instance; /// USART receiver /// -/// This struct implements the [`embedded_hal::serial::Read`] trait. +/// # `embedded-hal` traits +/// - [`embedded_hal::serial::Read`] for asynchronous receiving /// -/// [`embedded_hal::serial::Read`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Read.html +/// +/// [`embedded_hal::serial::Read`]: #impl-Read%3Cu8%3E pub struct Rx { _instance: PhantomData, _state: PhantomData, diff --git a/src/usart/tx.rs b/src/usart/tx.rs index 14084e68c..c2a579b75 100644 --- a/src/usart/tx.rs +++ b/src/usart/tx.rs @@ -12,12 +12,12 @@ use super::instances::Instance; /// USART transmitter /// -/// This struct implements the following traits: -/// - [`embedded_hal::serial::Write`] -/// - [`embedded_hal::blocking::serial::Write`] +/// # `embedded-hal` traits +/// - [`embedded_hal::serial::Write`] for asynchronous sending +/// - [`embedded_hal::blocking::serial::Write`] for synchronous receiving /// -/// [`embedded_hal::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Write.html -/// [`embedded_hal::blocking::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/blocking/serial/trait.Write.html +/// [`embedded_hal::serial::Write`]: #impl-Write%3Cu8%3E +/// [`embedded_hal::blocking::serial::Write`]: #impl-Write pub struct Tx { _instance: PhantomData, _state: PhantomData, diff --git a/src/wkt.rs b/src/wkt.rs index d6d315744..173c16fa0 100644 --- a/src/wkt.rs +++ b/src/wkt.rs @@ -48,8 +48,12 @@ use crate::{ /// /// Please refer to the [module documentation] for more information. /// +/// # `embedded-hal` traits +/// - [`embedded_hal::timer::CountDown`] +/// /// [`Peripherals`]: ../struct.Peripherals.html /// [module documentation]: index.html +/// [`embedded_hal::timer::CountDown`]: #impl-CountDown pub struct WKT { wkt: pac::WKT, _state: State, @@ -142,6 +146,7 @@ impl WKT { impl timer::CountDown for WKT { type Time = u32; + /// Starts a new count down fn start(&mut self, timeout: T) where T: Into, @@ -159,6 +164,7 @@ impl timer::CountDown for WKT { .write(|w| unsafe { w.value().bits(timeout.into()) }); } + /// Non-blockingly "waits" until the count down finishes fn wait(&mut self) -> nb::Result<(), Void> { if self.wkt.ctrl.read().alarmflag().bit_is_set() { return Ok(()); From 354476fc73014a7138121622167314f202deaf8a Mon Sep 17 00:00:00 2001 From: David Sawatzke Date: Fri, 17 Apr 2020 18:31:01 +0200 Subject: [PATCH 2/2] Remove outdated comment about i2c limitations This works in an i2c example --- src/i2c.rs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/i2c.rs b/src/i2c.rs index a5d70f05d..2b1b4c454 100644 --- a/src/i2c.rs +++ b/src/i2c.rs @@ -170,10 +170,6 @@ where /// /// Please refer to the [embedded-hal documentation] for details. /// - /// # Limitations - /// - /// Writing multiple bytes should work, but has not been tested. - /// /// [embedded-hal documentation]: https://docs.rs/embedded-hal/0.2.1/embedded_hal/blocking/i2c/trait.Write.html#tymethod.write fn write(&mut self, address: u8, data: &[u8]) -> Result<(), Self::Error> { // Wait until peripheral is idle