soc/rtc: warn if detected XTAL frequency does not match configured one

Since 9a8c0392, XTAL frequency is set to 40MHz by default, and users
of 26MHz boards need to select 26MHz manually. Most users are not aware
of this change, and existing getting started guides do not mention that
XTAL frequency needs to be set for some boards. So users are left with
garbage output from UART without any clue what to check.

This change adds a warning in case specific XTAL frequency was set, and
it does not match automatically detected one. This should help users
fix the issue.

diff --git a/components/bootloader/subproject/main/bootloader_start.c b/components/bootloader/subproject/main/bootloader_start.c
index 65e55fac9e5b0fde97ed15e99223a34dd6820cd0..012348ddf2e5b6f7df8b312f47390e08c3fdb4e8 100644 (file)
--- a/components/bootloader/subproject/main/bootloader_start.c
+++ b/components/bootloader/subproject/main/bootloader_start.c
@@ -753,7 +753,6 @@ static void clock_configure(void)
         cpu_freq = RTC_CPU_FREQ_240M;
     }
 
-    uart_tx_wait_idle(0);
     rtc_clk_config_t clk_cfg = RTC_CLK_CONFIG_DEFAULT();
     clk_cfg.xtal_freq = CONFIG_ESP32_XTAL_FREQ;
     clk_cfg.cpu_freq = cpu_freq;

diff --git a/components/soc/esp32/rtc_clk.c b/components/soc/esp32/rtc_clk.c
index aee0a39ff1ec605882d7b4e1281adf9ab0615b75..39ea41f40d5f09467f66457c44231b1e51386806 100644 (file)
--- a/components/soc/esp32/rtc_clk.c
+++ b/components/soc/esp32/rtc_clk.c
@@ -541,7 +541,8 @@ void rtc_clk_init(rtc_clk_config_t cfg)
     SET_PERI_REG_BITS(ANA_CONFIG_REG, ANA_CONFIG_M, ANA_CONFIG_M, ANA_CONFIG_S);
     CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, I2C_APLL_M | I2C_BBPLL_M);
 
-    /* Estimate XTAL frequency if requested */
+    /* Estimate XTAL frequency */
+    rtc_xtal_freq_t est_xtal_freq = rtc_clk_xtal_freq_estimate();
     rtc_xtal_freq_t xtal_freq = cfg.xtal_freq;
     if (xtal_freq == RTC_XTAL_FREQ_AUTO) {
         if (clk_val_is_valid(READ_PERI_REG(RTC_XTAL_FREQ_REG))) {
@@ -549,13 +550,21 @@ void rtc_clk_init(rtc_clk_config_t cfg)
             xtal_freq = rtc_clk_xtal_freq_get();
         } else {
             /* Not set yet, estimate XTAL frequency based on RTC_FAST_CLK */
-            xtal_freq = rtc_clk_xtal_freq_estimate();
+            xtal_freq = est_xtal_freq;
             if (xtal_freq == RTC_XTAL_FREQ_AUTO) {
                 SOC_LOGW(TAG, "Can't estimate XTAL frequency, assuming 26MHz");
                 xtal_freq = RTC_XTAL_FREQ_26M;
             }
         }
+    } else if (!clk_val_is_valid(READ_PERI_REG(RTC_XTAL_FREQ_REG))) {
+        /* Exact frequency was set in sdkconfig, but still warn if autodetected
+         * frequency is different. If autodetection failed, worst case we get a
+         * bit of garbage output.
+         */
+        SOC_LOGW(TAG, "Possibly invalid CONFIG_ESP32_XTAL_FREQ setting (%dMHz). Detected %d MHz.",
+                xtal_freq, est_xtal_freq);
     }
+    uart_tx_wait_idle(0);
     rtc_clk_xtal_freq_update(xtal_freq);
     rtc_clk_apb_freq_update(xtal_freq * MHZ);
     /* Set CPU frequency */

diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst
index 3a65d6cd7a77a40bfb52997ddac7f3c23a0634cc..16c8598dfee3c4b5118cf984e43068d78650ca1a 100644 (file)
--- a/docs/get-started/index.rst
+++ b/docs/get-started/index.rst
@@ -205,6 +205,9 @@ Here are couple of tips on navigation and use of ``menuconfig``:
 \r
     If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.\r
 \r
+.. note::\r
+\r
+    Most ESP32 development boards have a 40MHz crystal installed. However, some boards use a 26MHz crystal. If your board uses a 26MHz crystal, or you get garbage output from serial port after code upload, adjust the :ref:`CONFIG_ESP32_XTAL_FREQ` option in menuconfig.\r
 \r
 .. _get-started-build-flash:\r
 \r