Modeling CPU frequency (Setting, calculating, sources)

[soypat]

This discussion centers on modeling CPU frequency at the TinyGo API level.

Things to take into consideration:

• MCUs sometimes have varying sources of frequency. Pico has a PLL for startup and then switches to crystal
• MCUs sometimes can switch sources of frequency mid program
• Low power mode: How do we design low power modes so that it is cohesive with the CPU Frequency modelling
  • Low power mode can interact with CPU frequency.
• Sometimes you need to do lots of calculation to get the values needed to set a CPU frequency, see current Pico implementation, it does a lot of calculation on the interp level of tinygo compiler and does not affect build size

Catalyst conversation: #5106 (comment)

[eliasnaur]

Can say a bit what you're trying to achieve? I guess the ability for user code to configure the CPU frequency at runtime, but why? Saving power? Is there really so much power to save compared to, say, running whatever task needs done at highest frequency and then going to sleep?

[burgrp]

In theory yes, but how it would look like in real? Can you write an example please?

[eliasnaur]

tinygo build -target pico2 -cpufrequency 200MHz ...

[burgrp]

Does it mean (please tell me no :) ), that you would add it here:
https://github.com/burgrp/tinygo/blob/py32/compileopts/options.go#L10-L18
then here:
https://github.com/burgrp/tinygo/blob/py32/compileopts/options.go#L23
then here:
https://github.com/burgrp/tinygo/blob/py32/main.go#L1726
then here:
https://github.com/burgrp/tinygo/blob/py32/compileopts/config.go#L105
and few more places.

And for other details, like oscillator, PLL etc... we would do the the same for other options?
And finally it will just enable a particular block of code, which will be compiled-in.
I'm afraid it's not flexible, there is no abstraction, can't cover all uses cases.
Sorry to say, but that's very poor design in my opinion...

[aykevl]

As to why changing frequency at runtime is needed: I have a project that needs to be very low power (powered from a CR1225 coin cell). It also needs to run constantly (to bitbang LEDs), that is, it can't use the trick of running fast and going to sleep. The solution is to run at a low frequency.
However, sometimes it does need to run at a higher frequency simply because it needs more processing power. In that case it is useful to be able to change the clock frequency on the fly. At the moment this happens entirely by direct register accesses, which works well enough but is certainly not beginner friendly.

In any case, being able to set the clock frequency at compile time seems like the best solution since that probably covers most cases without having to impact binary size.

[burgrp]

As I explained above, setting the CPU frequency at compile time can never cover all possible configurations. Clock configuration on ARM processors is relatively complex, so only a specific use case would ever be covered, not all possibilities. I’m not opposed to doing this at compile time, but definitely not as part of this PR - it should be an iterative process. At the same time, it must be possible to configure the clock by direct register access, so that it remains sufficiently flexible.

[Gustavomurta]

My experiments with configuring CPU Clock of Rasp Pico and Rasp Pico 2:

Rasp Pico CPU clock config:
https://github.com/Gustavomurta/tinyGo_my_experiments/tree/main/Raspberry_Pico/System_Clock_adjust

Rasp Pico2 CPU clock config:
https://github.com/Gustavomurta/tinyGo_my_experiments/tree/main/Raspberry_Pico2/CPU_clock
The clock frequency and voltage configuration registers have been modified.

[rdon-key]

It seems that two separate issues are being discussed together here.

The first is how to represent the actual hardware configuration. Boards with the same name may still use different MCUs, oscillator sources, crystal frequencies, or maximum operating frequencies. These are not arbitrary settings that users should freely combine; they are properties of the manufactured hardware.

For that reason, rather than adding separate common CLI options such as -cpufrequency, -oscillator, or -pll-*, I think board definitions should support hardware variants. Users would select the MCU and crystal configuration they actually have, rather than configuring individual clock components.

The second issue is how to switch between performance and power-consumption levels at runtime on the same hardware. Rather than exposing a raw CPU-frequency setter, this could be represented by a small set of validated operating modes:

type PowerMode uint8

const (
    PowerHigh PowerMode = iota
    PowerNormal
    PowerLow
    PowerVeryLow
)

func SetPowerMode(mode PowerMode) error

The selected hardware variant would define the actual frequency, PLL configuration, bus dividers, flash wait states, and other details for each mode.

SetPowerMode would update the TinyGo runtime timers internally. Peripherals such as UART, I2C, and SPI could follow an explicit contract: the caller must stop active transfers before changing modes and reconfigure affected peripherals afterward when necessary.

This does not need to be implemented for every target at once. Targets that do not support runtime switching can return an unsupported error, and support can be added incrementally.

Why validated modes instead of a raw frequency setter?

RP2040-E16 requires clk_sys to run at least 10% faster than clk_usb while the USB peripheral is active. Otherwise, USB status signals crossing between the two clock domains may be lost at PVT extremes. With clk_usb at 48MHz, this requires clk_sys to remain above 52.8MHz.

This is not simply another point on a performance-versus-power scale, and it is not something users can reasonably be expected to know when choosing a frequency. It is exactly the kind of silicon-specific constraint that a hardware variant should encode and that validated operating modes should preserve.

With a raw frequency setter, a user trying to save power could silently violate this erratum by lowering the system clock. The failure might then appear only at process, voltage, or temperature extremes rather than during normal development.

I am not suggesting that direct register access should be removed. It should remain available for configurations that TinyGo does not cover. However, the modes that TinyGo does provide should be known-good configurations.

Summary

Rather than modeling clock configuration itself as one common abstraction, I suggest separating the problem into two layers:

• At compile time, select the actual hardware configuration.
• At runtime, select one of the validated PowerMode values supported by that configuration.

The number and exact meaning of the modes are open to discussion. The four modes above are only a starting point.