cpu/esp32: allow external 32 kHz crystal for the RTC hardware timer

[gschorcht]

Contribution description

This PR changes the RTC low-level driver to allow the use of the RTC hardware timer with an external 32.768 kHz crystal.

The RTC hardware timer of ESP32 can be clocked with either an external 32.768 kHz crystal or an internal adjustable 150 kHz RC oscillator. If the the external 32.768 kHz crystal is not available (as on most boards), the internal 150 kHz RC oscillator is used automatically. However, since this internal 150 kHz RC oscillator is not very accurate, the RTC low-level driver uses by default the PLL-controlled 64-bit microsecond system timer to emulate the RTC timer.

To allow the use of the RTC hardware timer for boards with an external 32 kHz crystal, the pseudomodules esp_rtc_timer and esp_rtc_timer_32k have been defined to control which timer is used for RTC as following:

• default
  Use the emulated RTC timer. The RTC hardware timer with the internal RC 150 kHz oscillator is only used in deep sleep mode and during a reset.

• esp_rtc_timer
  Use always the RTC hardware timer with the internal 150 kHz RC oscillator.

• esp_rtc_timer_32k
  Use the RTC hardware timer with the external 32.768 kHz crystal. If the external 32.768 kHz crystal is not available, the RTC hardware timer is used with the internal 150 kHz RC oscillator.

Furthermore, module esp_rtc_timer_32k is enabled by default for board esp32-wrover-kit by this PR.

This PR requires the bootloader images and the automatic XTAL clock detection from PR #13059.

Testing procedure

1. Use a board with and a board without external 32.768 kHz crystal. Flash and test both boards with

   LOG_LEVEL=4 make BOARD=esp32-wroom-32 -C test/periph_rtc flash test
   

   and

   LOG_LEVEL=4 USEMODULE=esp_rtc_timer_32 make BOARD=esp32-wroom-32 -C test/periph_rtc flash test
   

   All tests should work as expected. Module esp_rtc_timer_32 depends on module esp_rtc_timer so that all cases are covered.

2. Use a terminal program, reset the boards and check for following output during startup. SLOW is the clock used for RTC timer:

   • with enabled esp_rtc_timer_32k and the board with 32.768 kHz crystal:

     Used clocks in Hz: CPU=80000000 APB=80000000 XTAL=40000000 FAST=8000000 SLOW=32768
     

   • with enabled esp_rtc_timer_32k and the board w/o 32.768 kHz crystal:

     RTC: Not found External 32 kHz XTAL. Switching to Internal 150 kHz RC chain
     Used clocks in Hz: CPU=80000000 APB=80000000 XTAL=40000000 FAST=8000000 SLOW=150000
     

   • w/o module esp_rtc_timer_32k and any board:

     Used clocks in Hz: CPU=80000000 APB=80000000 XTAL=40000000 FAST=8000000 SLOW=150000
     

Issues/PRs references

Depends on PR #13059

[benpicco]

Do we always want to build the RTC?
I'd rather put

ifneq (,$(filter periph_rtc,$(USEMODULE)))
  USEMODULE += esp_rtc_timer_32k
endif

in the board's Makefile.dep. Or maybe add a new FEATURES_PROVIDED.

[gschorcht]

esp_rtc_timer_32 is just a pseudomodule to control the compilation in cpu/esp32/periph/rtc.c and doesn't depend on periph_rtc. RTC is only compiled if module periph_rtc is used.

[benpicco]

Ah I see - but then it would probably be better semantics to set

FEATURES_PROVIDED += esp_rtc_timer_32k

in Makefile.features

[gschorcht]

However, if I am right, we would need an additional FEATURES_OPTIONAL in MCU's Makefile.include to use the esp32_rtc_timer_32k module when the feature is provided.

[benpicco]

Yes and then check FEATURES_USED to select the the proper implementation.
Maybe a bit more convoluted, but certainly the 'cleaner' solution.

[benpicco]

On esp32-wroom-32 I get

RTC: Not found External 32 kHz XTAL. Switching to Internal 150 kHz RC chain

RTC still works as before.

Since this automatically falls back to the internal oscillator, is there any reason to not always use esp_rtc_timer_32k?

I also get a slightly smaller binary with this compared to the default behavior.

[gschorcht]

Since this automatically falls back to the internal oscillator, is there any reason to not always use esp_rtc_timer_32k?

Yes. esp_rtc_timer and esp_rtc_timer_32k are used to control what timer/clock is used for RTC module:

• default:
  The PLL-controlled system clock is used to emulate a RTC. The hardware RTC is then only used in deepsleep mode and during reboot.

• esp_rtc_timer:
  The RTC hardware timer with the internal 150 kHz RC oscillator is always used.

• esp_rtc_timer_32k:
  The RTC hardware timer with the external 32.768 kHz crystal is always used. If the
  external 32.768 kHz crystal is not available, the RTC hardware timer is used with the internal 150 kHz RC oscillator.

The problem is that the accuracy of the RTC hardware timer with the internal 150 kHz RC oscillator is much worse than the accuracy of the emulated RTC timer. So if you don't have an external 32.768 kHz crystal connected, it is better to use the default configuration with the emulated RTC. Otherwise the system time would drift quite fast (up to 3 seconds per minute).

Therefore, the user has to enable the esp_rtc_timer module explicitly. If the board has a 32.768 kHz crystal connected, module esp_rtc_timer can be used to enable the hardware RTC as the default cofiguration.

[gschorcht]

I committed a small change that avoids that module periph_rtc is enabled by default. This avoids the compilation of cpu/esp32/periph/rtc.c.

[benpicco]

I'm a bit surprised this works, since FEATURES_USED only gets set by Makefile.features, but I guess that's just the magic of makes dynamic variables.
I compile-tested esp32-wrover-kit and there the esp_rtc_timer_32k path gets build, as opposed to esp32-wroom-32 - nice!

[benpicco]

Works as intended - please squash.

[gschorcht]

@benpicco Thanks for reviewing, testing and merging.