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

(dcee03a)

RV Timer Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.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...
 
struct  dif_rv_timer_config
 Configuration for initializing the RISC-V timer device. More...
 
struct  dif_rv_timer
 State for a RISC-V timer, associated with a particular hardware thread. More...
 

Typedefs

typedef enum dif_rv_timer_enabled dif_rv_timer_enabled_t
 Represents an "enabled" state for a timer.
 
typedef struct dif_rv_timer_tick_params dif_rv_timer_tick_params_t
 Represents timekeeping parameters for a particular timer.
 
typedef enum dif_rv_timer_result dif_rv_timer_result_t
 Represents the result of an RV timer operation. More...
 
typedef enum dif_rv_timer_approximate_tick_params_result dif_rv_timer_approximate_tick_params_result_t
 Errors returned by dif_rv_timer_approximate_tick_params().
 
typedef struct dif_rv_timer_config dif_rv_timer_config_t
 Configuration for initializing the RISC-V timer device.
 
typedef struct dif_rv_timer dif_rv_timer_t
 State for a RISC-V timer, associated with a particular hardware thread. More...
 

Enumerations

enum  dif_rv_timer_enabled {
  kDifRvTimerDisabled = 0,
  kDifRvTimerEnabled
}
 Represents an "enabled" state for a timer.
 
enum  dif_rv_timer_result {
  kDifRvTimerOk = 0,
  kDifRvTimerBadArg = 1,
  kDifRvTimerError = 2
}
 Represents the result of an RV timer operation. More...
 
enum  dif_rv_timer_approximate_tick_params_result {
  kDifRvTimerApproximateTickParamsOk = kDifRvTimerOk,
  kDifRvTimerApproximateTickParamsBadArg = kDifRvTimerBadArg,
  kDifRvTimerApproximateTickParamsError = kDifRvTimerError,
  kDifRvTimerApproximateTickParamsUnrepresentable
}
 Errors returned by dif_rv_timer_approximate_tick_params(). More...
 

Functions

dif_rv_timer_approximate_tick_params_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...
 
dif_rv_timer_result_t dif_rv_timer_init (mmio_region_t base_addr, dif_rv_timer_config_t config, dif_rv_timer_t *timer_out)
 Initialize a RISC-V timer device with the given configuration. More...
 
dif_rv_timer_result_t dif_rv_timer_reset (const dif_rv_timer_t *timer)
 Completely resets a timer device, disabling all IRQs, counters, and comparators. More...
 
dif_rv_timer_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...
 
dif_rv_timer_result_t dif_rv_timer_counter_set_enabled (const dif_rv_timer_t *timer, uint32_t hart_id, dif_rv_timer_enabled_t state)
 Starts or stops a particular hart's counter. More...
 
dif_rv_timer_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 particlar hart's timer. More...
 
dif_rv_timer_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...
 
dif_rv_timer_result_t dif_rv_timer_irq_enable (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t comp_id, dif_rv_timer_enabled_t state)
 Enables or disables a particular timer's IRQ. More...
 
dif_rv_timer_result_t dif_rv_timer_irq_get (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t comp_id, bool *flag_out)
 Returns whether the IRQ for a particular timer is currently being serviced. More...
 
dif_rv_timer_result_t dif_rv_timer_irq_clear (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t comp_id)
 Clears the IRQ for a particular timer. More...
 
dif_rv_timer_result_t dif_rv_timer_irq_force (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t comp_id)
 Forces the IRQ for a particular timer to fire. More...
 
dif_rv_timer_result_t dif_rv_timer_irq_disable (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t *state)
 Disables all IRQs for a particular hart. More...
 
dif_rv_timer_result_t dif_rv_timer_irq_restore (const dif_rv_timer_t *timer, uint32_t hart_id, uint32_t state)
 Restores IRQ state for a particular hart. 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 32 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 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.

◆ dif_rv_timer_config

struct dif_rv_timer_config

Configuration for initializing the RISC-V timer device.

Definition at line 117 of file dif_rv_timer.h.

Data Fields
uint32_t comparator_count The number of comparators (i.e, timers that can be set) associated with each hart.

Must be at least one.

This value is determined entirely by the hardware configuration.

uint32_t hart_count The number of harts that this device supports time counters for.

Must be at least one.

This value is determined entirely by the hardware configuration.

◆ dif_rv_timer

struct dif_rv_timer

State for a RISC-V timer, associated with a particular hardware thread.

Its member variables should be considered private, and are only provided so that callers can allocate it.

Definition at line 141 of file dif_rv_timer.h.

Data Fields
mmio_region_t base_addr
dif_rv_timer_config_t config

Typedef Documentation

◆ dif_rv_timer_result_t

Represents the result of an RV timer operation.

◆ dif_rv_timer_t

typedef struct dif_rv_timer dif_rv_timer_t

State for a RISC-V timer, associated with a particular hardware thread.

Its member variables should be considered private, and are only provided so that callers can allocate it.

Enumeration Type Documentation

◆ dif_rv_timer_approximate_tick_params_result

Errors returned by dif_rv_timer_approximate_tick_params().

Enumerator
kDifRvTimerApproximateTickParamsUnrepresentable 

Indicates that the requested counter frequency cannot be represented without loss in precission.

Definition at line 77 of file dif_rv_timer.h.

◆ dif_rv_timer_result

Represents the result of an RV timer operation.

Definition at line 68 of file dif_rv_timer.h.

Function Documentation

◆ dif_rv_timer_approximate_tick_params()

dif_rv_timer_approximate_tick_params_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 62 of file dif_rv_timer.c.

◆ dif_rv_timer_arm()

dif_rv_timer_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 161 of file dif_rv_timer.c.

◆ dif_rv_timer_counter_read()

dif_rv_timer_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 particlar 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 131 of file dif_rv_timer.c.

◆ dif_rv_timer_counter_set_enabled()

dif_rv_timer_result_t dif_rv_timer_counter_set_enabled ( const dif_rv_timer_t timer,
uint32_t  hart_id,
dif_rv_timer_enabled_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 108 of file dif_rv_timer.c.

◆ dif_rv_timer_init()

dif_rv_timer_result_t dif_rv_timer_init ( mmio_region_t  base_addr,
dif_rv_timer_config_t  config,
dif_rv_timer_t timer_out 
)

Initialize a RISC-V timer device with the given configuration.

This function will deactivate all counters and reset all timers, which should each be configured and turned on manually after this function returns.

Parameters
base_addrMMIO region for the device hardware registers.
configConfiguration for initializing a particular timer.
[out]timer_outThe timer device.
Returns
The result of the operation.

Definition at line 32 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_clear()

dif_rv_timer_result_t dif_rv_timer_irq_clear ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  comp_id 
)

Clears the IRQ for a particular timer.

Parameters
timerA timer device.
hart_idThe hart counter associated with the timer.
comp_idThe comparator associated with the timer.
Returns
the result of the operation.

Definition at line 267 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_disable()

dif_rv_timer_result_t dif_rv_timer_irq_disable ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t *  state 
)

Disables all IRQs for a particular hart.

Optionally returns a state value containing the previous itnerrupt state. state may be NULL. See dif_rv_timer_irq_restore().

Parameters
timera timer device.
[out]stateIRQ state information for use with dif_rv_timer_irq_restore.
Returns
the result of the operation.

Definition at line 283 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_enable()

dif_rv_timer_result_t dif_rv_timer_irq_enable ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  comp_id,
dif_rv_timer_enabled_t  state 
)

Enables or disables a particular timer's IRQ.

That is, this function controls whether or not an IRQ is fired when the timer reaches its configured threshold.

Parameters
timerA timer device.
hart_idThe hart counter associated with the timer.
comp_idThe comparator associated with the timer.
stateThe desired status.
Returns
the result of the operation.

Definition at line 224 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_force()

dif_rv_timer_result_t dif_rv_timer_irq_force ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  comp_id 
)

Forces the IRQ for a particular timer to fire.

Parameters
timerA timer device.
hart_idThe hart counter associated with the timer.
comp_idThe comparator associated with the timer.
Returns
the result of the operation.

Definition at line 317 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_get()

dif_rv_timer_result_t dif_rv_timer_irq_get ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  comp_id,
bool *  flag_out 
)

Returns whether the IRQ for a particular timer is currently being serviced.

Parameters
timerA timer device.
hart_idThe hart counter associated with the timer.
comp_idThe comparator associated with the timer.
[out]flag_outThe interrupt status.
Returns
the result of the operation.

Definition at line 250 of file dif_rv_timer.c.

◆ dif_rv_timer_irq_restore()

dif_rv_timer_result_t dif_rv_timer_irq_restore ( const dif_rv_timer_t timer,
uint32_t  hart_id,
uint32_t  state 
)

Restores IRQ state for a particular hart.

Parameters
timera timer device.
stateIRQ state information to restore.
Returns
the result of the operation.

Definition at line 302 of file dif_rv_timer.c.

◆ dif_rv_timer_reset()

dif_rv_timer_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 333 of file dif_rv_timer.c.

◆ dif_rv_timer_set_tick_params()

dif_rv_timer_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 89 of file dif_rv_timer.c.