Software APIs
Data Structures | Typedefs | Functions
dif_rv_timer.h File Reference

(5b9f3a9)

RV Timer Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_rv_timer_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_rv_timer_tick_params
 Represents timekeeping parameters for a particular timer. More...
 

Typedefs

typedef struct dif_rv_timer_tick_params dif_rv_timer_tick_params_t
 Represents timekeeping parameters for a particular timer.
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_approximate_tick_params (uint64_t clock_freq, uint64_t counter_freq, dif_rv_timer_tick_params_t *out)
 Generates an aproximate dif_rv_timer_tick_params_t given the device clock frequency and desired counter frequency (both given in Hertz). More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_reset (const dif_rv_timer_t *timer)
 Completely resets a timer device, disabling all IRQs, counters, and comparators. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_set_tick_params (const dif_rv_timer_t *timer, uint32_t hart_id, dif_rv_timer_tick_params_t params)
 Configures the tick params for a particular hart's counter. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_set_enabled (const dif_rv_timer_t *timer, uint32_t hart_id, dif_toggle_t state)
 Starts or stops a particular hart's counter. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_read (const dif_rv_timer_t *timer, uint32_t hart_id, uint64_t *out)
 Reads the current value on a particular hart's timer. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_write (const dif_rv_timer_t *timer, uint32_t hart_id, uint64_t count)
 Writes the given value to a particular hart's timer. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_arm (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t comp_id, uint64_t threshold)
 Arms the timer to go off once the counter value is greater than or equal to threshold, by setting up the given comparator. More...
 

Detailed Description

RV Timer Device Interface Functions

Definition in file dif_rv_timer.h.


Data Structure Documentation

◆ dif_rv_timer_tick_params

struct dif_rv_timer_tick_params

Represents timekeeping parameters for a particular timer.

Definition at line 27 of file dif_rv_timer.h.

Data Fields
uint16_t prescale The prescaler value is the period of the timer tick in clock cycles, minus one.

That is,

prescale = clock_freq * tick_period - 1

with |clock_freq| and |tick_period| given in units of hertz and seconds, respectively.

For example, if the clock frequency is 50 MHz, and the desired tick period is 1 microsecond, i.e, a tick frequency of 1 MHz, then the prescaler should be:

(50 * 10^6) * (1 * 10^-6) - 1 = 49

However, since |tick_period| is very small, it is much more convenient to work with |tick_freq|, its inverse, which will be an integer number of hertz. In particular,

prescale = (clock_freq / tick_freq) - 1

This value is declared as a uint16_t, but only the lowest 12 bits are actually used.

uint8_t tick_step The amount to increment the timer counter at each tick.

Function Documentation

◆ dif_rv_timer_approximate_tick_params()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_approximate_tick_params ( uint64_t  clock_freq,
uint64_t  counter_freq,
dif_rv_timer_tick_params_t out 
)

Generates an aproximate dif_rv_timer_tick_params_t given the device clock frequency and desired counter frequency (both given in Hertz).

For the purposes of this function, "counter frequency" is the frequency at which software would observe a timer counter to increase. If the clock has insufficient resolution, high counter frequencies may set a larger value for tick_step. For example, if the clock ticks at 50kHz, but we want a counter that seems to tick every microsecond (1MHz), we can achieve this with a prescale of 0 (so that there is a tick per clock cycle) and a tick step of 20 (since 20 * 50kHz = 1MHz).

The return value of this function is only an approximation, and the actual counter frequency ultimately depends on the accuracy of the clock. The function will return an error if it cannot produce an acceptably accurate counter frequency using the given clock resolution.

Parameters
clock_freqThe device clock frequency, in Hertz.
counter_freqThe desired counter frequency, in Hertz.
[out]outTick parameters that will approximately produce the desired counter frequency.
Returns
The result of the operation.

Definition at line 54 of file dif_rv_timer.c.

◆ dif_rv_timer_arm()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_arm ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  comp_id,
uint64_t  threshold 
)

Arms the timer to go off once the counter value is greater than or equal to threshold, by setting up the given comparator.

Beware that the following naive implementation of setting an alarm contains a bug: uint64_t time; dif_rv_timer_counter_read(my_timer, kMyHart, &time); time += kSomeDuration; // (*) dif_rv_timer_arm(my_timer, kMyHart, kMyComp, time);

If time wraps around when performing the addition, an interrupt will be fired immediately upon calling dif_rv_timer_arm. Care should be taken to perform saturating addition at (*), so that the interrupt is fired when the timer value wraps around; this way, the interrupt handler can re-arm the timer for the rest of the duration.

This function makes no effort to protect the caller from setting alarms in the past that would immediately fire an interrupt. It is the caller's responsibility to read the current counter value and pick a reasonable alarm threshold.

Parameters
timerA timer device.
hart_idThe hart counter to arm against.
comp_idThe comparator to set up.
thresholdThe value to go off at.
Returns
The result of the operation.

Definition at line 182 of file dif_rv_timer.c.

◆ dif_rv_timer_counter_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_read ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint64_t *  out 
)

Reads the current value on a particular hart's timer.

Parameters
timerA timer device.
hart_idThe hart counter to read.
[out]outThe counter value.
Returns
The result of the operation.

Definition at line 124 of file dif_rv_timer.c.

◆ dif_rv_timer_counter_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_set_enabled ( const dif_rv_timer_t timer,
uint32_t  hart_id,
dif_toggle_t  state 
)

Starts or stops a particular hart's counter.

While a counter is enabled, the counter value will increase each tick, but its timekeeping values cannot be reconfigured.

Parameters
timerA timer device.
hart_idThe hart counter to enable/disable.
stateThe new enablement state.
Returns
The result of the operation.

Definition at line 101 of file dif_rv_timer.c.

◆ dif_rv_timer_counter_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_counter_write ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint64_t  count 
)

Writes the given value to a particular hart's timer.

Parameters
timerA timer device.
hart_idThe hart counter to write.
countThe counter value to write.
Returns
The result of the operation.

Definition at line 153 of file dif_rv_timer.c.

◆ dif_rv_timer_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_reset ( const dif_rv_timer_t timer)

Completely resets a timer device, disabling all IRQs, counters, and comparators.

Parameters
timerA timer device.
Returns
The result of the operation.

Definition at line 212 of file dif_rv_timer.c.

◆ dif_rv_timer_set_tick_params()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_timer_set_tick_params ( const dif_rv_timer_t timer,
uint32_t  hart_id,
dif_rv_timer_tick_params_t  params 
)

Configures the tick params for a particular hart's counter.

This function should not be called when hart_id's counter is enabled; it is the caller's responsibility to assert this precondition. The function dif_rv_timer_approximate_tick_params() can be used to generate tick parameter values.

Parameters
timerA timer device.
hart_idThe hart to configure.
paramsThe timing parameters.
Returns
The result of the operation.

Definition at line 82 of file dif_rv_timer.c.