RV Timer Device Interface Functions More...
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... | |
RV Timer Device Interface Functions
Definition in file dif_rv_timer.h.
struct dif_rv_timer_tick_params |
Represents timekeeping parameters for a particular timer.
Definition at line 32 of file dif_rv_timer.h.
struct dif_rv_timer_config |
Configuration for initializing the RISC-V timer device.
Definition at line 117 of file dif_rv_timer.h.
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 enum dif_rv_timer_result dif_rv_timer_result_t |
Represents the result of an RV timer operation.
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.
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.
enum dif_rv_timer_result |
Represents the result of an RV timer operation.
Definition at line 68 of file dif_rv_timer.h.
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.
clock_freq | The device clock frequency, in Hertz. | |
counter_freq | The desired counter frequency, in Hertz. | |
[out] | out | Tick parameters that will approximately produce the desired counter frequency. |
Definition at line 62 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart counter to arm against. |
comp_id | The comparator to set up. |
threshold | The value to go off at. |
Definition at line 161 of file dif_rv_timer.c.
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.
timer | A timer device. | |
hart_id | The hart counter to read. | |
[out] | out | The counter value. |
Definition at line 131 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart counter to enable/disable. |
state | The new enablement state. |
Definition at line 108 of file dif_rv_timer.c.
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.
base_addr | MMIO region for the device hardware registers. | |
config | Configuration for initializing a particular timer. | |
[out] | timer_out | The timer device. |
Definition at line 32 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart counter associated with the timer. |
comp_id | The comparator associated with the timer. |
Definition at line 267 of file dif_rv_timer.c.
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()
.
timer | a timer device. | |
[out] | state | IRQ state information for use with dif_rv_timer_irq_restore . |
Definition at line 283 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart counter associated with the timer. |
comp_id | The comparator associated with the timer. |
state | The desired status. |
Definition at line 224 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart counter associated with the timer. |
comp_id | The comparator associated with the timer. |
Definition at line 317 of file dif_rv_timer.c.
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.
timer | A timer device. | |
hart_id | The hart counter associated with the timer. | |
comp_id | The comparator associated with the timer. | |
[out] | flag_out | The interrupt status. |
Definition at line 250 of file dif_rv_timer.c.
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.
timer | a timer device. |
state | IRQ state information to restore. |
Definition at line 302 of file dif_rv_timer.c.
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.
timer | A timer device. |
Definition at line 333 of file dif_rv_timer.c.
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.
timer | A timer device. |
hart_id | The hart to configure. |
params | The timing parameters. |
Definition at line 89 of file dif_rv_timer.c.