High-resolution performance counter-based timer API. More...

Functions
void	perf_cntr_timer_enable (void)
	Enable the nanosecond timer.

void	perf_cntr_timer_disable (void)
	Disable the nanosecond timer.

bool	perf_cntr_timer_enabled (void)
	Check whether the nanosecond timer is enabled.

uint64_t	perf_cntr_timer_ns (void)
	Gets elapsed CPU time (in nanoseconds)

Detailed Description

High-resolution performance counter-based timer API.

This API allows for using the performance counters as high-resolution general-purpose interval timer with 5ns ticks. It does this by configuring PRFC0 in PMCR_ELAPSED_TIME_MODE.

Note: This is enabled by default. To use PRFC0 for something else, either use perf_cntr_timer_disable() or perf_cntr_start() to reconfigure it for something else. When disabled, the timer will simply fall through to use timer_ns_gettime64() from the timer driver, decreasing the resolution of each tick to 80ns.

Warning: The performance counter timer is only counting active CPU cycles. This means that when KOS's thread scheduler uses the "sleep" instruction, putting the CPU to sleep, these counters cease to record elapsed time. Because of this, they should only be used to measure small deltas that are not across frames, when you want real wall time rather than active CPU time.

See also: Timer Unit

Function Documentation

◆ perf_cntr_timer_disable()

void perf_cntr_timer_disable ( void )

Disable the nanosecond timer.

This function disables the performance counter used for the perf_cntr_timer_ns() function.

Note: Generally, you will not want to do this, unless you have some need to use the counter PRFC0 for something else.

◆ perf_cntr_timer_enable()

void perf_cntr_timer_enable ( void )

Enable the nanosecond timer.

This function enables the performance counter used for the perf_cntr_timer_ns() function.

Note: This is on by default. The function uses PRFC0 to do the work.

Warning: The performance counters are only counting active CPU cycles while in this mode. This is analogous to providing you with the CPU time of your application, not the actual wall-time or monotonic clock, as it ceases to count when the kernel puts the CPU to sleep.

◆ perf_cntr_timer_enabled()

bool perf_cntr_timer_enabled ( void )

Check whether the nanosecond timer is enabled.

Queries the configuration of PRFC0 to check whether it's currently acting as the nanosecond timer.

Note: Even when it's not, perf_cntr_timer_ns() will still gracefully fall-through to using the timer_ns_gettime64(), which decreases the resolution of each tick to 80ns.

Return values

true	The nanosecond timer is configured and running
false	The nanosecond timer is not configured and/or isn't running

◆ perf_cntr_timer_ns()

uint64_t perf_cntr_timer_ns ( void )

Gets elapsed CPU time (in nanoseconds)

This function retrieves the total amount of active CPU time since perf_cntr_timer_enabled() was called.

Note: It's called by default when KOS initializes, so unless you reinitialize it later on, this should be the total CPU time since KOS booted up.