tx_systick_retune.c File Reference

Implementation of the ThreadX SysTick kernel-tick retune. More...

#include <stdint.h>
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_systick.h"
#include "ra8_threadx.h"

Include dependency graph for tx_systick_retune.c:

Go to the source code of this file.

Functions
ra8_err_t	ra8_threadx_systick_reload_for (uint32_t cpuclk_hz, uint32_t tick_hz, uint32_t *out_reload)
	Compute the SysTick reload for a given core clock + tick rate.
ra8_err_t	ra8_threadx_systick_retune (void)
	Reprogram SysTick.LOAD from the live CPUCLK0 rate.

Variables
static const char *	s_tag = "TX_SYST"

Detailed Description

Implementation of the ThreadX SysTick kernel-tick retune.

See port/threadx/inc/ra8_threadx.h for the public contract. ra8_threadx_systick_reload_for derives the SYST_RVR reload from the live core clock and the kernel tick rate; ra8_threadx_systick_retune then programs it through the shared ra8_core SysTick timebase primitive (ra8_systick_set_reload), which owns the SYST_RVR / SYST_CVR access. That primitive replaced this file's private address-cast accessors, so the SysTick registers are now programmed from exactly one place in the tree. The SysTick registers are architectural (Arm), not Renesas peripherals, so they carry an Arm v8-M reference rather than a HUM citation. On the host unit-test build the primitive writes to the fake MMIO map, so the retune runs end-to-end and the clock query + reload arithmetic remain testable.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file tx_systick_retune.c.

Function Documentation

ra8_threadx_systick_reload_for()

ra8_err_t ra8_threadx_systick_reload_for ( uint32_t cpuclk_hz, uint32_t tick_hz, uint32_t * out_reload )

nodiscard

Compute the SysTick reload for a given core clock + tick rate.

Derives the SYST_RVR reload value as cpuclk_hz / tick_hz - 1, the count that makes SysTick underflow once per tick period. Validates that the inputs are non-zero, that the clock is fast enough for at least one tick period (cpuclk_hz >= tick_hz), and that the resulting reload fits the 24-bit SYST_RVR field. Pure arithmetic – touches no hardware – so it is exercised directly by the host MC/DC unit tests.

Parameters

[in]	cpuclk_hz	Live core (CPUCLK0) frequency in Hz. Must be > 0.
[in]	tick_hz	Kernel tick rate in Hz (see k_ra8_threadx_tick_hz). Must be > 0.
[out]	out_reload	On success, the SYST_RVR reload value to program.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Reload computed and written to out_reload.
k_ra8_err_null_ptr	out_reload is NULL.
k_ra8_err_invalid_arg	cpuclk_hz or tick_hz is 0, or the clock is slower than one tick period.
k_ra8_err_out_of_range	Reload would exceed the 24-bit SYST_RVR range (cpuclk_hz far too high for tick_hz).

Precondition

out_reload is a valid, writable uint32_t.

Caller supplies the live clock, not a compile-time assumption.

Postcondition

On k_ra8_ok, *out_reload <= k_ra8_systick_reload_max.

On any error, out_reload is left unmodified.

Note

Thread safety: pure function, trivially thread-safe.

Example:

uint32_t reload = 0U;
// 1 GHz core, 1 kHz tick -> 999999.
(void)ra8_threadx_systick_reload_for(1000000000U, 1000U, &reload);

See also

ra8_threadx_systick_retune

Since

0.1.0

Definition at line 34 of file tx_systick_retune.c.

References k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_ok, k_ra8_systick_reload_max, RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag.

Referenced by ra8_threadx_systick_retune(), and tx_application_define().

ra8_threadx_systick_retune()

ra8_err_t ra8_threadx_systick_retune ( void )

nodiscard

Reprogram SysTick.LOAD from the live CPUCLK0 rate.

Queries the live CPUCLK0 frequency via ra8_cgc_get_clock_hz, derives the reload with ra8_threadx_systick_reload_for for the ThreadX tick rate (k_ra8_threadx_tick_hz), then writes SYST_RVR and clears SYST_CVR so the new period takes effect on the next reload. The SysTick enable / clock-source / interrupt bits programmed by _tx_initialize_low_level.S are left untouched.

Call this from tx_application_define (which ThreadX invokes after _tx_initialize_low_level but before the first scheduling decision) so that whatever clock the app raised via ra8_cgc_init() – or did not – the kernel tick is accurate. Calling it earlier (from main before tx_kernel_enter) has no effect: _tx_initialize_low_level reprograms SYST_RVR afterwards and would overwrite it.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	SysTick reprogrammed for the live clock.
k_ra8_err_invalid_arg	CPUCLK0 query returned a nonsensical rate (0, or too slow for one tick period).
k_ra8_err_out_of_range	Live clock too high for a 24-bit reload.

Precondition

_tx_initialize_low_level has already armed SysTick (i.e. this runs from tx_application_define or later).

The CGC published-clock table reflects the live clock (i.e. ra8_cgc_init() has run if the app raises the clock).

Postcondition

On k_ra8_ok, SYST_RVR == CPUCLK0 / k_ra8_threadx_tick_hz - 1.

On k_ra8_ok, SYST_CVR == 0 (counter restarts at the new reload).

Note

Thread safety: not thread-safe; single-threaded init context only.

On the host unit-test build (RA8_OFF_TARGET) the SYST_RVR / SYST_CVR writes are skipped – the System Control Space is not mapped – but the clock query + reload validation still run.

Example:

void tx_application_define(void* unused) {
  (void)unused;
  if (ra8_threadx_systick_retune() != k_ra8_ok) { for (;;) { } }
  // ... tx_thread_create(...) ...
}

See also

ra8_threadx_systick_reload_for

ra8_cgc_get_clock_hz

Since

0.1.0

Definition at line 64 of file tx_systick_retune.c.

References k_ra8_clock_id_cpuclk0, k_ra8_ok, k_ra8_threadx_tick_hz, ra8_cgc_get_clock_hz(), ra8_log_info_val, RA8_RETURN_ON_ERROR, ra8_systick_set_reload(), ra8_threadx_systick_reload_for(), and s_tag.

Referenced by tx_application_define().

Variable Documentation

s_tag

const char* s_tag = "TX_SYST"

static

Definition at line 32 of file tx_systick_retune.c.