A new approach for erasing WiFi Settings (#8828)

* A new approach for erasing WiFi Settings

Add support for hardware reset function call - simulates EXT_RST via HWDT.

Add reset selection to `ESP.eraseConfig()` for calling hardware reset
after erasing the WiFi Settings.

Update ArduinoOTA to use `ESP.eraseConfig(true)`

Externalized `ArduinoOTA.eraseConfigAndReset()`

Add OTA examples to illustrate using erase config changes.

* style
fixed confused example

* improve wording

* Add new state to retry eraseConfigAndReset

* Removed unreachable error test from examples.

Removed continuous retry of "eraseConfig" and allow the script to
assign an error handling option for "eraseConfig" failure.

Update example to use error handling option.

* In eboot for function ets_wdt_enable() added missing arguments

* Update comments and example

* Wording

* Rebuilt eboot.elf with current tools from ./get.py

* Requested changes.

* cleanup comments

* Update hardware_reset

Avoid using "[[noreturn]]" - not accepted for a .c file function
Updated to use __attribute__((noreturn)) to handle both .cpp and .c
file functions.

bootloaders/eboot/eboot.c

@@ -17,8 +17,39 @@
 
 #define SWRST do { (*((volatile uint32_t*) 0x60000700)) |= 0x80000000; } while(0);
 
-extern void ets_wdt_enable(void);
-extern void ets_wdt_disable(void);
+/*
+  After Power Enable Pin, EXT_RST, or HWDT event, at "main()" in eboot, WDT is
+  disabled. Key WDT hardware registers are zero.
+
+  After "ESP.restart()" and other soft restarts, at "main()" in eboot, WDT is enabled.
+
+  References for the under-documented ets_wdt_* API
+    https://mongoose-os.com/blog/esp8266-watchdog-timer/
+    http://cholla.mmto.org/esp8266/bootrom/boot.txt
+
+  After looking at esp8266-watchdog-timer some more, `ets_wdt_enable(4, 12, 12)`
+  is good for eboot's needs. From a ".map" the NON-OS SDK does not use the
+  ets_wdt_* APIs, so our choices are not too critical.
+  The SDK will set up the WDT as it wants it.
+
+  A rationale for keeping the "ets_wdt_enable()" line, if the system is not
+  stable during a "soft restart," the HWDT would provide a recovery reboot.
+*/
+extern void ets_wdt_enable(uint32_t mode, uint32_t arg1, uint32_t arg2);
+/*
+  "ets_wdt_disable"
+
+  Diables WDT, then feeds the dog.
+  For current modes other than 1 or 2, returns the current mode.
+  For current mode 1, calls ets_timer_disarm, then return the current mode.
+  For current mode 2, calls ets_isr_mask, then return the current mode.
+
+  I always see a return value of 0xFFFFFFFF.
+
+  The return value would normally be used with ets_wdt_restore; however, that is
+  not an option since a valid prior call to ets_wdt_enable() may not have been done.
+*/
+extern uint32_t ets_wdt_disable(void);
 
 int print_version(const uint32_t flash_addr)
 {
@@ -241,12 +272,12 @@ int main()
 
         ets_wdt_disable();
         res = copy_raw(cmd.args[0], cmd.args[1], cmd.args[2], false);
-        ets_wdt_enable();
+        ets_wdt_enable(4, 12, 12);  // WDT about 13 secs.
 
         ets_printf("%d\n", res);
 #if 0
-	//devyte: this verify step below (cmp:) only works when the end of copy operation above does not overwrite the 
-	//beginning of the image in the empty area, see #7458. Disabling for now. 
+	//devyte: this verify step below (cmp:) only works when the end of copy operation above does not overwrite the
+	//beginning of the image in the empty area, see #7458. Disabling for now.
         //TODO: replace the below verify with hash type, crc, or similar.
         // Verify the copy
         ets_printf("cmp:");
@@ -257,7 +288,7 @@ int main()
             }
 
         ets_printf("%d\n", res);
-#endif	    
+#endif
         if (res == 0) {
             cmd.action = ACTION_LOAD_APP;
             cmd.args[0] = cmd.args[1];

cores/esp8266/Esp.cpp

@@ -31,6 +31,7 @@
 #include "umm_malloc/umm_malloc.h"
 #include <pgmspace.h>
 #include "reboot_uart_dwnld.h"
+#include "hardware_reset.h"
 
 extern "C" {
 #include "user_interface.h"
@@ -519,7 +520,7 @@ struct rst_info * EspClass::getResetInfoPtr(void) {
 }
 
 bool EspClass::eraseConfig(void) {
-    const size_t cfgSize = 0x4000;
+    const size_t cfgSize = 0x4000;  // Sectors: RF_CAL + SYSTEMPARAM[3]
     size_t cfgAddr = ESP.getFlashChipSize() - cfgSize;
 
     for (size_t offset = 0; offset < cfgSize; offset += SPI_FLASH_SEC_SIZE) {
@@ -531,6 +532,17 @@ bool EspClass::eraseConfig(void) {
     return true;
 }
 
+bool EspClass::eraseConfigAndReset(void) {
+    // Before calling, ensure the WiFi state is equivalent to
+    // "WiFi.mode(WIFI_OFF)." This will reduce the likelihood of the SDK
+    // performing WiFi data writes to Flash between erasing and resetting.
+    bool reset = eraseConfig();
+    if (reset) {
+        hardware_reset();
+    }
+    return reset;
+}
+
 uint8_t *EspClass::random(uint8_t *resultArray, const size_t outputSizeBytes)
 {
   /**

cores/esp8266/Esp.h

@@ -212,6 +212,22 @@ class EspClass {
 
         static bool eraseConfig();
 
+        /**
+         * @brief Erases 4 sectors at the end of flash, 1 - RF_CAL and 3 - SYSTEMPARM.
+         * These are the same additional sectors that are erase when you select
+         * Erase Flash: "Sketch + WiFi Settings" from the Arduino IDE Tools menu.
+         *
+         * This operation erases the running SDK's flash configuration space.
+         * As a precaution before calling, first call "WiFi.mode(WIFI_OFF)."
+         *
+         * If you need to erase "WiFi Settings" and reboot consider using
+         * "ArduinoOTA.eraseConfigAndReset()" it handles shutting down WiFi
+         * before the erase.
+         * @return bool result of operation. Always False on return.
+         * Function does not return on success.
+         */
+        static bool eraseConfigAndReset();
+
         static uint8_t *random(uint8_t *resultArray, const size_t outputSizeBytes);
         static uint32_t random();
 

cores/esp8266/hardware_reset.cpp

@@ -0,0 +1,119 @@
+/*
+  Make the reset look like an EXT_RST reset by:
+    * Set INTLEVEL to 15 blocking NMI Software WDT interference
+    * set "restart reason" to REASON_EXT_SYS_RST
+    * Config Hardware WDT for 1.6ms
+    * Disable Hardware WDT Level-1 interrupt option
+    * wait, ...
+
+  Inspired by RTOS SDK hardware_restart in panic.c
+*/
+
+#include "Arduino.h"
+#include <user_interface.h>
+#include <ets_sys.h>
+#include "hardware_reset.h"
+
+
+// Extracted from RTOS_SDK eagle_soc.h
+/*
+ * ESPRSSIF MIT License
+ *
+ * Copyright (c) 2015 <ESPRESSIF SYSTEMS (SHANGHAI) PTE LTD>
+ *
+ * Permission is hereby granted for use on ESPRESSIF SYSTEMS ESP8266 only, in which case,
+ * it is free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished
+ * to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ */
+#define REG_WRITE(_r, _v)       (*(volatile uint32_t *)(_r)) = (_v)
+#define REG_READ(_r)            (*(volatile uint32_t *)(_r))
+
+//Watchdog reg {{
+#define PERIPHS_WDT_BASEADDR        0x60000900
+
+#define WDT_CTL_ADDRESS             0
+#define WDT_OP_ADDRESS              0x4
+#define WDT_OP_ND_ADDRESS           0x8
+#define WDT_RST_ADDRESS             0x14
+
+#define WDT_CTL_RSTLEN_MASK         0x38
+#define WDT_CTL_RSPMOD_MASK         0x6
+#define WDT_CTL_EN_MASK             0x1
+
+#define WDT_CTL_RSTLEN_LSB          0x3
+#define WDT_CTL_RSPMOD_LSB          0x1
+#define WDT_CTL_EN_LSB              0
+
+#define WDT_FEED_VALUE              0x73
+
+#define WDT_REG_READ(_reg)                  REG_READ(PERIPHS_WDT_BASEADDR + _reg)
+#define WDT_REG_WRITE(_reg, _val)           REG_WRITE(PERIPHS_WDT_BASEADDR + _reg, _val)
+#define CLEAR_WDT_REG_MASK(_reg, _mask)     WDT_REG_WRITE(_reg, WDT_REG_READ(_reg) & (~_mask))
+#define SET_WDT_REG_MASK(_reg, _mask, _val) SET_PERI_REG_BITS((PERIPHS_WDT_BASEADDR + _reg), _mask, _val, 0)
+#undef WDT_FEED
+#define WDT_FEED()                          WDT_REG_WRITE(WDT_RST_ADDRESS, WDT_FEED_VALUE)
+//}}
+
+// Inspired by RTOS SDK task_wdt.c and hardware_restart in panic.c
+
+// Copyright 2018-2019 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+extern "C" {
+  void hardware_reset(void) {
+    volatile uint32_t* const rtc_mem = (volatile uint32_t *)0x60001100u;
+
+    // Block NMI or Software WDT from disturbing out restart reason
+    xt_rsil(15);
+
+    // An HWDT reason would imply a fault or bug, but this reset was requested.
+    // Set hint reason to EXT_RST. From empirical evidence, an HWDT looks a lot
+    // like an EXT_RST. The WDT registers are reset to zero like an EXT_RST;
+    // however, the PLL initialization is still set. We can still read the Boot
+    // ROM serial output messages.
+    // SDK restart reason/hint location
+    rtc_mem[0] = REASON_EXT_SYS_RST;
+
+    // Disable WDT
+    CLEAR_WDT_REG_MASK(WDT_CTL_ADDRESS, WDT_CTL_EN_MASK);
+
+    // Set Reset pulse to maximum
+    // Select Reset only - no level-1 interrupt
+    SET_WDT_REG_MASK(WDT_CTL_ADDRESS,
+                     WDT_CTL_RSTLEN_MASK       | WDT_CTL_RSPMOD_MASK,
+                     (7 << WDT_CTL_RSTLEN_LSB) | (2 << WDT_CTL_RSPMOD_LSB));
+
+    // Set WDT Reset timer to 1.6 ms.
+    WDT_REG_WRITE(WDT_OP_ADDRESS, 1);  // 2^n * 0.8ms, mask 0xf, n = 1 -> (2^1 = 2) * 0.8 * 0.001 = 0.0016
+
+    // Enable WDT
+    SET_WDT_REG_MASK(WDT_CTL_ADDRESS, WDT_CTL_EN_MASK, 1 << WDT_CTL_EN_LSB);
+
+    while (true);
+  }
+};

cores/esp8266/hardware_reset.h

@@ -0,0 +1,14 @@
+#ifndef HARDWARE_RESET_H
+#define HARDWARE_RESET_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void hardware_reset(void) __attribute__((noreturn));
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif