rp2/modmachine: Set the peripheral frequency with machine.freq().

By default, the peripheral clock for UART and SPI is set to 48 MHz and will
not be affected by the MCU clock change.  This can be changed by a second
argument to `machine.freq(freq, peripheral_freq)`.  The second argument
must be either 48 MHz or identical with the first argument.

Note that UART and SPI baud rates may have to be re-configured after
changing the MCU clock.

Signed-off-by: robert-hh <robert@hammelrath.com>

docs/rp2/quickref.rst

@@ -31,12 +31,25 @@ The MicroPython REPL is accessed via the USB serial port. Tab-completion is usef
 find out what methods an object has. Paste mode (ctrl-E) is useful to paste a
 large slab of Python code into the REPL.
 
-The :mod:`machine` module::
+The :mod:`machine` module:
+
+machine.freq() allows to change the MCU frequency and control the peripheral
+frequency for UART and SPI. Usage::
+
+    machine.freq(MCU_frequency[, peripheral_frequency=48_000_000])
+
+The MCU frequency can be set in a range from less than 48 MHz to about 250MHz.
+The default at boot time is 125 MHz. The peripheral frequency must be either
+48 MHz or identical to the MCU frequency, with 48 MHz as the default.
+If the peripheral frequency is changed, any already existing instance of
+UART and SPI will change it's baud rate and may have to be re-configured::
 
     import machine
 
     machine.freq()          # get the current frequency of the CPU
-    machine.freq(240000000) # set the CPU frequency to 240 MHz
+    machine.freq(240000000) # set the CPU frequency to 240 MHz and keep
+                            # the UART frequency at 48MHz
+    machine.freq(125000000, 125000000) # set the CPU and UART frequency to 125 MHz
 
 The :mod:`rp2` module::
 

ports/rp2/modmachine.c

@@ -96,6 +96,20 @@ static void mp_machine_set_freq(size_t n_args, const mp_obj_t *args) {
     if (!set_sys_clock_khz(freq / 1000, false)) {
         mp_raise_ValueError(MP_ERROR_TEXT("cannot change frequency"));
     }
+    if (n_args > 1) {
+        mp_int_t freq_peri = mp_obj_get_int(args[1]);
+        if (freq_peri != (USB_CLK_KHZ * KHZ)) {
+            if (freq_peri == freq) {
+                clock_configure(clk_peri,
+                    0,
+                    CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS,
+                    freq,
+                    freq);
+            } else {
+                mp_raise_ValueError(MP_ERROR_TEXT("peripheral freq must be 48_000_000 or the same as the MCU freq"));
+            }
+        }
+    }
     #if MICROPY_HW_ENABLE_UART_REPL
     setup_default_uart();
     mp_uart_init();

ports/rp2/mpconfigport.h

@@ -148,6 +148,7 @@
 #define MICROPY_PY_MACHINE_UART_SENDBREAK       (1)
 #define MICROPY_PY_MACHINE_WDT                  (1)
 #define MICROPY_PY_MACHINE_WDT_INCLUDEFILE      "ports/rp2/machine_wdt.c"
+#define MICROPY_PY_MACHINE_FREQ_NUM_ARGS_MAX    (2)
 #define MICROPY_PY_ONEWIRE                      (1)
 #define MICROPY_VFS                             (1)
 #define MICROPY_VFS_LFS2                        (1)