GPTIMER — General-purpose timer unit¶

GRLIB GPTIMER (GR712RC §11 / GRLIB IP core): a single prescaler driving up to four sub-timers, each with an independent control register and an optional underflow interrupt. In Tero this is the RTEMS system tick source and the backing for the rtems_timecounter_simple time-of-day counter.

Using it¶

Driver-visible model¶

The RTEMS LEON3 BSP uses the GPTIMER as a 1 MHz down-counter. The boot path:

1. Programs the prescaler reload so the prescaler underflows at 1 MHz (one prescaler underflow = one 1 µs sub-timer tick). Tero's initialize() pre-programs this from cpu_clock_hz so direct-ELF guests never rebuild (see Bootloader prescaler init).
2. Programs a sub-timer's reload register (in µs) and writes its control register with EN|RS|IE (enable, restart-on-underflow, interrupt-enable).
3. On each underflow the timer reloads (RS=1), latches the IP status bit, and pulses the IRQ line to the IRQMP if IE is set.
4. The interrupt handler clears IP by writing 1 to control bit 4 (write-1-to-clear).

Register map¶

All registers are 32-bit, word-aligned, word-only (sub-word access returns ErrorCode::AlignmentError).

The timer block starts at 0x10 (TimerBlockBase) with a 0x10 stride (TimerStride); within each block the counter/reload/control are at +0x00, +0x04, +0x08. The classic GPTIMER also defines a per-timer latch at +0x0C; Tero does not model a separate latch register (the RTEMS LEON3 BSP does not use it), so that sub-offset reads back 0.

CONFIG register¶

CONFIG (0x08) reports the fixed implementation parameters (gptimer.cpp:38): SI = 1 (bit 8 — separate interrupt per timer), IRQ = 8 (bits 5:3 — base IRQ line), TIMERS = 4 (bits 2:0). Bit 9 (DF, "disable timer freeze") is the only writable field and is stored verbatim.

Control register bit map¶

The writable mask is CtrlWritableMask = EN|RS|IE|CH = 0x2B (gptimer.hpp:61). LD is a write-only trigger (not stored); IP is computed separately; DH is read-only.

const auto new_ip = (value & (1U << CtrlIpBit))
                      ? 0U                              // write-1 clears
                      : (ctrl & (1U << CtrlIpBit));     // write-0 preserves

Reset state¶

reset() (gptimer.cpp:12):

Internals / how it's modelled¶

Prescaler + sub-timer tick¶

tick(now) (gptimer.cpp:204) converts elapsed simulated nanoseconds into system-clock cycles and advances the prescaler:

delta_ns = now - last_tick_time
cycles   = delta_ns / ns_per_cycle          # ns_per_cycle injected at attach()
advance_by_cycles(cycles)

advance_by_cycles (gptimer.cpp:164) decrements the prescaler by cycles, firing process_timer_tick() once per prescaler underflow (it handles partial periods and multiple full periods in one call, so the result is simulated-time accurate at the cycle level regardless of how coarse the tick cadence is). The prescaler period is scaler_reload + 1 (or 0x10000 when the reload is 0).

process_timer_tick() (gptimer.cpp:135) is the per-underflow step for each enabled timer:

for each timer with EN == 1:
    counter -= 1
    if counter == 0:
        IP = 1                       # latch sticky status
        if RS == 1: counter = reload # restart
        else:       EN = 0           # one-shot: stop
        if IE == 1: ctx.irq->raise() # pulse the IRQ line (every underflow)

There is a second IRQ-raise site in mmio_write (gptimer.cpp:122): if a control write transitions IP from clear to set and IE is set, the line is raised. In practice software never sets IP (it is write-1-clear), so this branch is dormant; it exists to mirror the hardware "IP becomes set with IE enabled" edge.

ns_per_cycle and clock frequency¶

The prescaler is clocked by the system clock, so its tick period is the SoC's per-cycle time. The runtime injects this via PeripheralContext::ns_per_cycle (derived from EmulatorConfig::cpu_clock_hz) at attach() (gptimer.hpp:83); the GPTIMER no longer hardcodes 20 ns. A 0 (unset) value falls back to the historical 20 ns ≈ 50 MHz default. Changing cpu_clock_hz therefore scales the prescaler correctly. See the clock-frequency configuration.

Bootloader prescaler init¶

During Emulator::initialize() (emulator.cpp:394) the runtime simulates the GR712RC/GR740 ROM bootloader's prescaler setup: it writes a scaler reload (and the current scaler value) so the prescaler underflows at exactly 1 MHz — the rate the RTEMS LEON3 BSP assumes when it programs only the per-timer reload in µs. The divisor is derived straight from the clock in MHz:

scaler_reload = (cpu_clock_hz + 500'000) / 1'000'000 - 1;  // round-to-nearest MHz

Without this, the prescaler would start at 0xFFFF and take ~65 ms before the first underflow, delaying the first RTEMS clock interrupt enough to break test timing. Computing the divisor from MHz (rather than from ns_per_cycle) keeps the 1 MHz tick exact at any cpu_clock_hz (e.g. 80 MHz → exact divisor 80, not the 76 you'd get from a rounded 13 ns period), so direct-ELF guests never need rebuilding when the clock changes.

RTEMS timecounter usage¶

RTEMS uses the GPTIMER both as the periodic clock-tick source and (via rtems_timecounter_simple) as the time-of-day counter. The simple-timecounter reads the counter and the IP pending bit to derive a monotonic uptime; the write-1-clear IP semantics above are exactly what make that arithmetic monotonic. The GR740's IRQAMP exposes no usable high-resolution timestamp counter (its TIMESTAMP block reads zero), so the GPTIMER remains the timecounter on GR740 as well — consistent with the round-granular system clock.

Reading current state¶

control(idx) and counter(idx) (gptimer.cpp:233) expose a timer's current control/counter to host code (tests, the publisher) without an MMIO round-trip. publish() registers scaler_value, scaler_reload, and per-timer counter/reload/control fields.

Tests¶

• tests/unit/test_gptimer.cpp — writable mask, LD trigger, IP write-1-clear, prescaler underflow, RS=0 stopping / RS=1 reloading, IE=1 IRQ raise, CH chaining between adjacent timers, and the timer-4 reset state.
• The RTEMS sptests exercise the GPTIMER end-to-end as the system clock source.

See also¶

• IRQMP — where the underflow IRQ pulse lands.
• Clock frequency configuration.
• Multicore & timing.