(dcee03a)

RV Timer Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"

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

typedef enum dif_rv_timer_result 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

enum 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

enum 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_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.

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

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.

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

	timer	A timer device.
	hart_id	The hart counter to read.
[out]	out	The 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

timer	A timer device.
hart_id	The hart counter to enable/disable.
state	The 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_addr	MMIO region for the device hardware registers.
	config	Configuration for initializing a particular timer.
[out]	timer_out	The 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

timer	A timer device.
hart_id	The hart counter associated with the timer.
comp_id	The 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

	timer	a timer device.
[out]	state	IRQ 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

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.

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

timer	A timer device.
hart_id	The hart counter associated with the timer.
comp_id	The 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

	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.

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

timer	a timer device.
state	IRQ 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

timer A 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

timer	A timer device.
hart_id	The hart to configure.
params	The timing parameters.

Returns: The result of the operation.

Definition at line 89 of file dif_rv_timer.c.

(dcee03a)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_rv_timer_tick_params

◆ dif_rv_timer_config

◆ dif_rv_timer

Typedef Documentation

◆ dif_rv_timer_result_t

◆ dif_rv_timer_t

Enumeration Type Documentation

◆ dif_rv_timer_approximate_tick_params_result

◆ dif_rv_timer_result

Function Documentation

◆ dif_rv_timer_approximate_tick_params()

◆ dif_rv_timer_arm()

◆ dif_rv_timer_counter_read()

◆ dif_rv_timer_counter_set_enabled()

◆ dif_rv_timer_init()

◆ dif_rv_timer_irq_clear()

◆ dif_rv_timer_irq_disable()

◆ dif_rv_timer_irq_enable()

◆ dif_rv_timer_irq_force()

◆ dif_rv_timer_irq_get()

◆ dif_rv_timer_irq_restore()

◆ dif_rv_timer_reset()

◆ dif_rv_timer_set_tick_params()