Struct esp_idf_svc::hal::timer::TimerDriver

source ·

pub struct TimerDriver<'d> { /* private fields */ }

Implementations§

source §

impl<'d> TimerDriver<'d>

source

pub fn new<TIMER>( _timer: impl Peripheral + 'd, config: &Config, ) -> Result<TimerDriver<'d>, EspError>
where TIMER: Timer,

source

pub fn tick_hz(&self) -> u64

Returns the tick rate of the timer.

source

pub fn enable(&mut self, enable: bool) -> Result<(), EspError>

Enable or disable the timer.

Enabling the timer causes it to begin counting up from the current counter.

Disabling the timer effectively pauses the counter.

source

pub fn counter(&self) -> Result<u64, EspError>

Returns the current counter value of the timer

source

pub fn set_counter(&mut self, value: u64) -> Result<(), EspError>

Manually set the current counter value of the timer.

This does not enable or disable the timer.

source

pub fn enable_alarm(&mut self, enable: bool) -> Result<(), EspError>

Enable or disable the alarm.

Enabling the alarm activates the following behaviors once it is triggered:

The counter will reset to 0, if auto-reload is set
An interrupt will be triggered, if configured

source

pub fn alarm(&self) -> Result<u64, EspError>

Returns the configured alarm value

source

pub fn set_alarm(&mut self, value: u64) -> Result<(), EspError>

Set the alarm value of the timer.

NOTE: The alarm must be activated with enable_alarm for this value to take effect

Once the counter exceeds this value:

The counter will reset to 0, if auto-reload is set
An interrupt will be triggered, if configured

source

pub fn enable_interrupt(&mut self) -> Result<(), EspError>

source

pub fn disable_interrupt(&mut self) -> Result<(), EspError>

source

pub async fn delay(&mut self, counter: u64) -> Result<(), EspError>

Delays for counter ticks

NOTE: This function resets the counter

source

pub fn reset_wait(&mut self)

Resets the internal wait notification

source

pub async fn wait(&mut self) -> Result<(), EspError>

Wait for an alarm interrupt to occur

NOTE: This requires interrupts to be enabled to work

Subscribes the provided callback for ISR notifications. As a side effect, interrupts will be disabled, so to receive a notification, one has to also call TimerDriver::enable_interrupt after calling this method.

§Safety

Care should be taken not to call STD, libc or FreeRTOS APIs (except for a few allowed ones) in the callback passed to this function, as it is executed in an ISR context.

source

pub unsafe fn subscribe_nonstatic<F>( &mut self, callback: F, ) -> Result<(), EspError>
where F: FnMut() + Send + 'd,

Subscribes the provided callback for ISR notifications. As a side effect, interrupts will be disabled, so to receive a notification, one has to also call TimerDriver::enable_interrupt after calling this method.

§Safety

Care should be taken not to call STD, libc or FreeRTOS APIs (except for a few allowed ones) in the callback passed to this function, as it is executed in an ISR context.

Additionally, this method - in contrast to method subscribe - allows the passed-in callback/closure to be non-'static. This enables users to borrow

in the closure - variables that live on the stack - or more generally - in the same scope where the driver is created.

HOWEVER: care should be taken NOT to call core::mem::forget() on the driver, as that would immediately lead to an UB (crash). Also note that forgetting the driver might happen with Rc and Arc when circular references are introduced: https://github.com/rust-lang/rust/issues/24456

The reason is that the closure is actually sent and owned by an ISR routine, which means that if the driver is forgotten, Rust is free to e.g. unwind the stack and the ISR routine will end up with references to variables that no longer exist.

The destructor of the driver takes care - prior to the driver being dropped and e.g. the stack being unwind - to unsubscribe the ISR routine. Unfortunately, when the driver is forgotten, the un-subscription does not happen and invalid references are left dangling.

This “local borrowing” will only be possible to express in a safe way once/if !Leak types are introduced to Rust (i.e. the impossibility to “forget” a type and thus not call its destructor).

source