Add a CRC32 over progmem and ESP.checkFlashCRC

bootloaders/eboot/eboot.ld

@@ -154,6 +154,12 @@ SECTIONS
     *(.gnu.linkonce.b.*)
     . = ALIGN (8);
     _bss_end = ABSOLUTE(.);
+    /* CRC stored in last 8 bytes */
+    ASSERT((. < 4096 - 8), "Error: No space for CRC in bootloader sector.");
+    . = _stext + 4096 - 8;
+    _crc_size = .;
+    . = . + 4;
+    _crc_val = .;
   } >iram1_0_seg :iram1_0_phdr
 
   .lit4 : ALIGN(4)

cores/esp8266/Esp.cpp

@@ -26,6 +26,7 @@
 #include "MD5Builder.h"
 #include "umm_malloc/umm_malloc.h"
 #include "cont.h"
+#include "coredecls.h"
 
 extern "C" {
 #include "user_interface.h"
@@ -447,6 +448,25 @@ bool EspClass::checkFlashConfig(bool needsEquals) {
     return false;
 }
 
+bool EspClass::checkFlashCRC() {
+    // The CRC and total length are placed in extra space at the end of the 4K chunk
+    // of flash occupied by the bootloader.  If the bootloader grows to >4K-8 bytes,
+    // we'll need to adjust this.
+    uint32_t flashsize = *((uint32_t*)(0x40200000 + 4088)); // Start of PROGMEM plus 4K-8
+    uint32_t flashcrc = *((uint32_t*)(0x40200000 + 4092)); // Start of PROGMEM plus 4K-4
+    uint32_t z[2];
+    z[0] = z[1] = 0;
+
+    // Start the checksum
+    uint32_t crc = crc32_P((const void*)0x40200000, 4096-8, 0xffffffff);
+    // Pretend the 2 words of crc/len are zero to be idempotent
+    crc = crc32_P(z, 8, crc);
+    // Finish the CRC calculation over the rest of flash
+    crc = crc32_P((const void*)0x40201000, flashsize-4096, crc);
+    return crc == flashcrc;
+}
+
+
 String EspClass::getResetReason(void) {
     char buff[32];
     if (resetInfo.reason == REASON_DEFAULT_RST) { // normal startup by power on

cores/esp8266/Esp.h

@@ -176,6 +176,8 @@ class EspClass {
 
         bool checkFlashConfig(bool needsEquals = false);
 
+        bool checkFlashCRC();
+
         bool flashEraseSector(uint32_t sector);
         bool flashWrite(uint32_t offset, uint32_t *data, size_t size);
         bool flashRead(uint32_t offset, uint32_t *data, size_t size);

cores/esp8266/coredecls.h

@@ -22,6 +22,7 @@ void disable_extra4k_at_link_time (void) __attribute__((noinline));
 
 uint32_t sqrt32 (uint32_t n);
 uint32_t crc32 (const void* data, size_t length, uint32_t crc = 0xffffffff);
+uint32_t crc32_P (const void* data, size_t length, uint32_t crc = 0xffffffff);
 
 #ifdef __cplusplus
 }

cores/esp8266/crc32.cpp

@@ -20,6 +20,7 @@
  */
 
 #include "coredecls.h"
+#include "pgmspace.h"
 
 // moved from core_esp8266_eboot_command.cpp
 uint32_t crc32 (const void* data, size_t length, uint32_t crc /*= 0xffffffff*/)
@@ -40,3 +41,23 @@ uint32_t crc32 (const void* data, size_t length, uint32_t crc /*= 0xffffffff*/)
     }
     return crc;
 }
+
+
+uint32_t crc32_P (const void* data, size_t length, uint32_t crc /*= 0xffffffff*/)
+{
+    const uint8_t* ldata = (const uint8_t*)data;
+    while (length--)
+    {
+        uint8_t c = pgm_read_byte(ldata++);
+        for (uint32_t i = 0x80; i > 0; i >>= 1)
+        {
+            bool bit = crc & 0x80000000;
+            if (c & i)
+                bit = !bit;
+            crc <<= 1;
+            if (bit)
+                crc ^= 0x04c11db7;
+        }
+    }
+    return crc;
+}

doc/libraries.rst

@@ -113,6 +113,8 @@ Some ESP-specific APIs related to deep sleep, RTC and flash memories are availab
 
 ``ESP.getCycleCount()`` returns the cpu instruction cycle count since start as an unsigned 32-bit. This is useful for accurate timing of very short actions like bit banging.
 
+``ESP.checkFlashCRC()`` calculates the CRC of the program memory (not including any filesystems) and compares it to the one embedded in the image.  If this call returns ``false`` then the flash has been corrupted.  At that point, you may want to consider trying to send a MQTT message, to start a re-download of the application, blink a LED in an `SOS` pattern, etc.  However, since the flash is known corrupted at this point there is no guarantee the app will be able to perform any of these operations, so in safety critical deployments an immediate shutdown to a fail-safe mode may be indicated.
+
 ``ESP.getVcc()`` may be used to measure supply voltage. ESP needs to reconfigure the ADC at startup in order for this feature to be available. Add the following line to the top of your sketch to use ``getVcc``:
 
 .. code:: cpp

libraries/esp8266/examples/CheckFlashCRC/CheckFlashCRC.ino

@@ -0,0 +1,45 @@
+/*
+   Demonstrate CRC check passing and failing by simulating a bit flip in flash.
+   WARNING!!!  You would never want to actually do this in a real application!
+
+   Released to the Public Domain by Earle F. Philhower, III <[email protected]>
+*/
+
+extern "C" {
+#include "spi_flash.h"
+}
+// Artificially create a space in PROGMEM that fills multipe sectors so
+// we can corrupt one without crashing the system
+const int corruptme[SPI_FLASH_SEC_SIZE * 4] PROGMEM = { 0 };
+
+void setup() {
+  Serial.begin(115200);
+  Serial.printf("Starting\n");
+  Serial.printf("CRC check: %s\n", ESP.checkFlashCRC() ? "OK" : "ERROR");
+  Serial.printf("...Corrupting a portion of flash in the array...\n");
+
+  uint32_t ptr = (uint32_t)corruptme;
+  // Find a page aligned spot inside the array
+  ptr += 2 * SPI_FLASH_SEC_SIZE;
+  ptr &= ~(SPI_FLASH_SEC_SIZE - 1); // Sectoralign
+  uint32_t sector = ((((uint32_t)ptr - 0x40200000) / SPI_FLASH_SEC_SIZE));
+
+  // Create a sector with 1 bit set (i.e. fake corruption)
+  uint32_t *space = (uint32_t*)calloc(SPI_FLASH_SEC_SIZE, 1);
+  space[42] = 64;
+
+  // Write it into flash at the spot in question
+  spi_flash_erase_sector(sector);
+  spi_flash_write(sector * SPI_FLASH_SEC_SIZE, (uint32_t*)space, SPI_FLASH_SEC_SIZE);
+  Serial.printf("CRC check: %s\n", ESP.checkFlashCRC() ? "OK" : "ERROR");
+
+  Serial.printf("...Correcting the flash...\n");
+  memset(space, 0, SPI_FLASH_SEC_SIZE);
+  spi_flash_erase_sector(sector);
+  spi_flash_write(sector * SPI_FLASH_SEC_SIZE, (uint32_t*)space, SPI_FLASH_SEC_SIZE);
+  Serial.printf("CRC check: %s\n", ESP.checkFlashCRC() ? "OK" : "ERROR");
+}
+
+
+void loop() {
+}

platform.txt

@@ -18,6 +18,7 @@ runtime.tools.elf2bin={runtime.platform.path}/tools/elf2bin.py
 runtime.tools.sizes={runtime.platform.path}/tools/sizes.py
 runtime.tools.makecorever={runtime.platform.path}/tools/makecorever.py
 runtime.tools.eboot={runtime.platform.path}/bootloaders/eboot/eboot.elf
+runtime.tools.crc={runtime.platform.path}/tools/crc32bin.py
 
 compiler.warning_flags=-w
 compiler.warning_flags.none=-w
@@ -117,8 +118,9 @@ recipe.objcopy.eep.pattern=
 
 ## Create hex
 recipe.objcopy.hex.1.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.elf2bin}" --eboot "{runtime.tools.eboot}" --app "{build.path}/{build.project_name}.elf" --flash_mode {build.flash_mode} --flash_freq {build.flash_freq} --flash_size {build.flash_size} --path "{runtime.tools.xtensa-lx106-elf-gcc.path}/bin" --out "{build.path}/{build.project_name}.bin"
-recipe.objcopy.hex.2.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.signing}" --mode sign --privatekey "{build.source.path}/private.key" --bin "{build.path}/{build.project_name}.bin" --out "{build.path}/{build.project_name}.bin.signed" --legacy "{build.path}/{build.project_name}.bin.legacy_sig"
-recipe.objcopy.hex.3.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.sizes}" --elf "{build.path}/{build.project_name}.elf" --path "{runtime.tools.xtensa-lx106-elf-gcc.path}/bin"
+recipe.objcopy.hex.2.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.crc}" --bin "{build.path}/{build.project_name}.bin" --size 4088 --crc 4092
+recipe.objcopy.hex.3.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.signing}" --mode sign --privatekey "{build.source.path}/private.key" --bin "{build.path}/{build.project_name}.bin" --out "{build.path}/{build.project_name}.bin.signed" --legacy "{build.path}/{build.project_name}.bin.legacy_sig"
+recipe.objcopy.hex.4.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.sizes}" --elf "{build.path}/{build.project_name}.elf" --path "{runtime.tools.xtensa-lx106-elf-gcc.path}/bin"
 
 ## Save hex
 recipe.output.tmp_file={build.project_name}.bin

tools/crc32bin.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+
+"""
+# Place a CRC32 checksum and length in a generated BIN file
+#
+# Copyright (C) 2019 - Earle F. Philhower, III
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from __future__ import print_function
+import argparse
+import sys
+
+def crc8266(ldata):
+    "Return the CRC of ldata using same algorithm as eboot"
+    crc = 0xffffffff
+    idx = 0
+    while idx < len(ldata):
+        byte = int(ldata[idx])
+        idx = idx + 1
+        for i in [0x80, 0x40, 0x20, 0x10, 0x08, 0x04, 0x02, 0x01]:
+            bit = crc & 0x80000000
+            if (byte & i) != 0:
+                if bit == 0:
+                    bit = 1
+                else:
+                    bit = 0
+            crc = int(crc << 1) & 0xffffffff
+            if bit != 0:
+                crc = int(crc ^ 0x04c11db7)
+    return crc
+
+def store_word(raw, offset, val):
+    "Place a 4-byte word in 8266-dependent order in the raw image"
+    raw[offset] = val & 255
+    raw[offset + 1] = (val >> 8) & 255
+    raw[offset + 2] = (val >> 16) & 255
+    raw[offset + 3] = (val >> 24) & 255
+    return raw
+
+def main():
+    "Main CLI interface"
+    parser = argparse.ArgumentParser(description='Embed CRC32 and length in a generated BIN image')
+    parser.add_argument('-b', '--bin', action='store', required=True,
+                        help='Path to the Arduino sketch.bin')
+    parser.add_argument('-s', '--size', action='store', required=True,
+                        help='Byte offset in bin to store the size')
+    parser.add_argument('-c', '--crc', action='store', required=True,
+                        help='Byte offset in bin to store the crc32')
+    args = parser.parse_args()
+
+    with open(args.bin, "rb") as binfile:
+        raw = bytearray(binfile.read())
+
+    # Zero out the spots we're going to overwrite to be idempotent
+    raw = store_word(raw, int(args.size), 0)
+    raw = store_word(raw, int(args.crc), 0)
+    crc = crc8266(raw)
+    raw = store_word(raw, int(args.size), len(raw))
+    raw = store_word(raw, int(args.crc), int(crc))
+
+    with open(args.bin, "wb") as binfile:
+        binfile.write(raw)
+
+    print("Inserted length of " + hex(len(raw)) + " and CRC of " + hex(crc)+ " into " + args.bin)
+
+if __name__ == '__main__':
+    sys.exit(main())