Docs: Esp32 Performance & Power

Initial docs for changing performance/power params on Esp32.

Signed-off-by: Peter M <[email protected]>

doc/src/programmers-guide.md

@@ -1375,6 +1375,58 @@ Calling [`esp:rtc_slow_get_binary/0`](./apidocs/erlang/eavmlib/esp.md#rtc_slow_g
 
 By default, RTC slow memory in AtomVM is limited to 4098 (4k) bytes.  This value can be modified at build time using an IDF SDK `KConfig` setting.  For  instructions about how to build AtomVM, see the AtomVM [Build Instructions](./build-instructions.md#building-for-esp32).
 
+### Performance and Power
+
+AtomVM comes with conservative defaults for broad compatibility with different ESP32 boards.
+You may want to change these settings to optimize for performance or power usage.
+
+#### CPU frequency
+
+Use `idf.py menuconfig` in `src/platforms/esp32`
+```Component config ---> ESP System Settings  ---> CPU frequency (160 MHz)  --->```
+
+You can increase or decrease the CPU frequency, this is a tradeoff against power usage.
+Eg. 160 MHz is the conservative default for the ESP32, but you can increase it to 240 MHz or decrease it to 80 MHz. The higher the frequency, the more power is consumed. The lower the frequency, the less power is consumed.
+
+#### Flash mode and speed
+
+Use `idf.py menuconfig` in `src/platforms/esp32`
+```Serial flasher config  ---> Flash SPI mode (DIO)  --->```
+You can change the mode of the SPI flash. QIO is the fastest mode, but not all flash chips support it.
+
+```Serial flasher config  ---> Flash SPI speed (40 MHz)  --->```
+You can change the speed of the SPI flash. The higher the speed, the faster the flash will be, but not all flash chips support higher speeds.
+
+#### PSRAM speed
+
+Use `idf.py menuconfig` in `src/platforms/esp32`
+```Component config ---> ESP PSRAM  ---> SPI RAM config  --->```
+
+If your board has PSRAM and it's enabled, you can configure the SPI RAM settings here.
+```Set RAM clock speed (40MHz clock speed)  --->```
+You can increase or decrease the clock speed of the PSRAM.
+
+```{warning}
+You may have to increase "Flash SPI speed" (see above) before you can increase PSRAM speed.
+```
+
+The higher the speed, the faster the PSRAM will be, but not all PSRAM chips support higher speeds.
+
+#### Sleep mode - Deep sleep
+
+For low power applications, you should use the [deep sleep functionality](./programmers-guide.md#restart-and-deep-sleep) of the ESP32.
+
+This will put the ESP32 into a very low power state, and it will consume very little power.
+You can wake the ESP32 from deep sleep using a timer, or an interrupt etc.
+
+Make sure your board is suitable for deep sleep, some boards have voltage regulators and/or LEDs constantly draining power, also make sure sensors are powered down or in low power mode when the ESP32 is in deep sleep.
+
+For persisting small amounts of data during deep sleep, you can use the [RTC memory](./programmers-guide.md#rtc-memory) of the ESP32, which is preserved during deep sleep.
+
+#### Sleep mode - Light sleep
+
+Usage of light sleep is untested, and no support for controlling light sleep is currently implemented. Reach out if you do any experiments and measurements.
+
 ### Miscellaneous ESP32 APIs
 
 * [`esp:freq_hz/0`](./apidocs/erlang/eavmlib/esp.md#freq_hz0)