diff --git a/docs/rp2/quickref.rst b/docs/rp2/quickref.rst
index ecf3f3186..9b82ea5dc 100644
--- a/docs/rp2/quickref.rst
+++ b/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::
 
diff --git a/ports/rp2/modmachine.c b/ports/rp2/modmachine.c
index 229000cc1..372c17bcf 100644
--- a/ports/rp2/modmachine.c
+++ b/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();
diff --git a/ports/rp2/mpconfigport.h b/ports/rp2/mpconfigport.h
index 3399212aa..abe25d700 100644
--- a/ports/rp2/mpconfigport.h
+++ b/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)