Trait r3_portkit::tickless::TicklessStateTrait

source · 
pub trait TicklessStateTrait: Init + Copy + Debug {
    // Required methods
    fn reset(&mut self, cfg: &TicklessCfg, hw_tick_count: u32);
    fn mark_reference(&mut self, cfg: &TicklessCfg, hw_tick_count: u32) -> u32;
    fn tick_count_to_hw_tick_count(
        &self,
        cfg: &TicklessCfg,
        tick_count: u32
    ) -> u32;
    fn tick_count(&self, cfg: &TicklessCfg, hw_tick_count: u32) -> u32;

    // Provided method
    fn mark_reference_and_measure(
        &mut self,
        cfg: &TicklessCfg,
        hw_tick_count: u32,
        ticks: u32
    ) -> Measurement { ... }
}
Expand description

Operations implemented by all valid instantiations of TicklessState.

Required Methods§

source

fn reset(&mut self, cfg: &TicklessCfg, hw_tick_count: u32)

Mark the given hardware tick count as the origin (where OS tick count is exactly zero).

To use this method, TicklessOptions::resettable must be set to true when constructing TicklessCfg.

self must be in the initial state (Init::INIT) when this method is called.

source

fn mark_reference(&mut self, cfg: &TicklessCfg, hw_tick_count: u32) -> u32

Mark a reference point. Returns the reference point’s OS tick count (in range 0..=cfg.max_tick_count()).

hw_tick_count should be in range 0..=cfg.hw_max_tick_count() and satisfy the requirements of TicklessStateTrait::tick_count.

All reference points are exactly aligned to OS ticks (microseconds).

The client should call this method periodically for a correct behavior. The client should use the Self::tick_count_to_hw_tick_count method to determine the next hardware tick count to mark the next reference point on.

cfg must be the instance of TicklessCfg that was passed to TicklessState to derive Self.

source

fn tick_count_to_hw_tick_count(&self, cfg: &TicklessCfg, tick_count: u32) -> u32

Calculate the earliest hardware tick count representing a point of time that coincides or follows the one represented by the specified OS tick count.

Returns a value in range 0..=cfg.hw_max_tick_count().

tick_count must satisfy the following condition: Given a last reference point ref_tick_count (a value returned by mark_reference), there must exist i such that i ∈ 1..=cfg.max_timeout() and tick_count == (ref_tick_count + i) % (cfg.max_tick_count() + 1).

In particular, tick_count must not be identical to ref_tick_count. If this was allowed, the result could refer to the past. Consider the following diagram. In this case, mark_reference is called at the 6th hardware tick, creating a reference point at time 2μs. Now if you call tick_count_to_hw_tick_count with tick_count = 2, the returned value will refer to the 5th hardware tick, which is in the past. Because of wrap-around arithmetics, it’s impossible to tell if the returned value refers to the past or not.

cfg must be the instance of TicklessCfg that was passed to TicklessState to derive Self.

source

fn tick_count(&self, cfg: &TicklessCfg, hw_tick_count: u32) -> u32

Get the OS tick count (in range 0..=cfg.max_tick_count()).

cfg must be the instance of TicklessCfg that was passed to TicklessState to derive Self.

hw_tick_count should be in range 0..=cfg.hw_max_tick_count(). In addition, hw_tick_count must satisfy the following condition:

  • Let ref_hw_tick_count and ref_tick_count be the last reference point (the last values passed to and returned by mark_reference, respectively).
  • Let period = cfg.max_tick_count() + 1.
  • Let hw_period = cfg.hw_max_tick_count() + 1.
  • Let hw_max_timeout = (tick_count_to_hw_tick_count((ref_tick_count + cfg.max_timeout) % period) + hw_period - ref_hw_tick_count) % hw_period.
  • There must exist hw_timeout and latency such that hw_timeout ∈ 0..=hw_max_timeout, latency ∈ 0..=hw_headroom_ticks, and hw_tick_count == (ref_hw_tick_count + hw_timeout + latency) % hw_period.

Note: ref_hw_tick_count should not be confused with the identically-named private field of TicklessStateCore.

In the above diagram, hw_tick_count should fall within the filled zone.

Provided Methods§

source

fn mark_reference_and_measure( &mut self, cfg: &TicklessCfg, hw_tick_count: u32, ticks: u32 ) -> Measurement

Mark a reference point and start measuring the specified time interval ticks (measured in OS ticks = microseconds).

The caller can use the information contained in the returned Measurement to configure timer hardware and receive an interrupt at the end of measurement.

hw_tick_count should be in range 0..=cfg.hw_max_tick_count() and satisfy the requirements of TicklessStateTrait::tick_count.

ticks should be in range 1..=cfg.max_timeout().

Implementors§