Merge branch 'docs/flash_encryption_disable' into 'master'

Docs: Document flash encryption disable steps, clean up flash encryption & secure boot docs

Generate clean up of flash encryption & secure boot docs

Including steps for disabling flash encryption (for people who accidentally enable it).

See merge request !500

README.md

@@ -24,6 +24,16 @@ Once you've found the project you want to work with, change to its directory and
 
 `make menuconfig`
 
+* Opens a text-based configuration menu for the project.
+* Use up & down arrow keys to navigate the menu.
+* Use Enter key to go into a submenu, Escape key to go out or to exit.
+* Type `?` to see a help screen. Enter key exits the help screen.
+* Use Space key, or `Y` and `N` keys to enable (Yes) and disable (No) configuration items with checkboxes "`[*]`"
+* Pressing `?` while highlighting a configuration item displays help about that item.
+* Type `/` to search the configuration items.
+
+Once done configuring, press Escape multiple times to exit and say "Yes" to save the new configuration when prompted.
+
 ## Compiling the Project
 
 `make all`
@@ -59,7 +69,7 @@ After the initial flash, you may just want to build and flash just your app, not
 
 `make app-flash` will automatically rebuild the app if it needs it.
 
-(There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
+(In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
 
 ## Parallel Builds
 

components/bootloader/Kconfig.projbuild

@@ -35,16 +35,16 @@ endmenu
 menu "Security features"
 
 config SECURE_BOOT_ENABLED
-    bool "Enable secure boot in bootloader"
+    bool "Enable secure boot in bootloader (READ DOCS FIRST)"
     default N
     help
         Build a bootloader which enables secure boot on first boot.
 
-        Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature.
+        Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.
 
         When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.
 
-        See docs/security/secure-boot.rst for details.
+        Refer to http://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
 
 choice SECURE_BOOTLOADER_MODE
     bool "Secure bootloader mode"
@@ -108,7 +108,7 @@ config SECURE_BOOT_VERIFICATION_KEY
        PEM formatted private key using the espsecure.py
        extract_public_key command.
 
-       See docs/security/secure-boot.rst for details.
+       Refer to http://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
 
 config SECURE_BOOT_INSECURE
     bool "Allow potentially insecure options"
@@ -119,16 +119,18 @@ config SECURE_BOOT_INSECURE
 
        Only enable these options if you are very sure.
 
-       Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.
+       Refer to http://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
 
 config FLASH_ENCRYPTION_ENABLED
-    bool "Enable flash encryption on boot"
+    bool "Enable flash encryption on boot (READ DOCS FIRST)"
     default N
     help
        If this option is set, flash contents will be encrypted by the bootloader on first boot.
 
-       Note: After first boot, the system will be permanently encrypted.
-       See docs/securityflash-encryption.rst for details.
+       Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted
+       system is complicated and not always possible.
+
+       Read http://esp-idf.readthedocs.io/en/latest/security/flash-encryption.html before enabling.
 
 config FLASH_ENCRYPTION_INSECURE
     bool "Allow potentially insecure options"

components/bootloader_support/include/esp_flash_encrypt.h

@@ -20,10 +20,12 @@
 #include "esp_spi_flash.h"
 #include "soc/efuse_reg.h"
 
-/* Support functions for flash encryption features.
-
-   Can be compiled as part of app or bootloader code.
-*/
+/**
+ * @file esp_partition.h
+ * @brief Support functions for flash encryption features
+ *
+ * Can be compiled as part of app or bootloader code.
+ */
 
 /** @brief Is flash encryption currently enabled in hardware?
  *

docs/Doxyfile

@@ -37,7 +37,8 @@ INPUT = ../components/esp32/include/esp_wifi.h \
 	../components/fatfs/src/esp_vfs_fat.h \
 	../components/fatfs/src/diskio.h \
 	../components/esp32/include/esp_core_dump.h \
-	../components/mdns/include/mdns.h
+	../components/mdns/include/mdns.h \
+	../components/bootloader_support/include/esp_flash_encrypt.h
 
 ## Get warnings for functions that have no documentation for their parameters or return value 
 ##

docs/api/storage/spi_flash.rst

@@ -8,7 +8,7 @@ Header Files
 
   * :component_file:`spi_flash/include/esp_spi_flash.h`
   * :component_file:`spi_flash/include/esp_partition.h`
-  * :component_file:`esp32/include/esp_flash_encrypt.h`
+  * :component_file:`bootloader_support/include/esp_flash_encrypt.h`
 
 Macros
 ^^^^^^

docs/index.rst

@@ -53,10 +53,10 @@ Contents:
 .. toctree::
    :caption: Hardware Reference
 
-   Technical Reference Manual <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
-   Pin List and Functions <http://espressif.com/sites/default/files/documentation/esp32_chip_pin_list_en.pdf>
-   Chip Pinout <http://espressif.com/sites/default/files/documentation/esp32_pinout_v1_0.pdf>
-   Silicon Errata <http://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
+   Technical Reference Manual (PDF) <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+   Pin List and Functions (PDF) <http://espressif.com/sites/default/files/documentation/esp32_chip_pin_list_en.pdf>
+   Chip Pinout (PDF) <http://espressif.com/sites/default/files/documentation/esp32_pinout_v1_0.pdf>
+   Silicon Errata (PDF) <http://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
 
 .. toctree::
    :caption: Contribute
@@ -78,4 +78,4 @@ Contents:
 Indices
 =======
 
-* :ref:`genindex`
+* :ref:`genindex`