docs(secure_download_mode): Explain available commands and serial protocol restrictions in SDM

Author: radimkarnis

docs/en/advanced-topics/serial-protocol.rst

@@ -302,6 +302,26 @@ ROM loaders will not recognize these commands.
 | ``0xd3``   | RUN_USER_CODE     | Exits loader and runs user code   |                                                                                                                         |          |
 +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+
 
+.. only:: not esp8266 and not esp32
+
+    .. _supported-in-sdm:
+
+    Supported in Secure Download Mode
+    """""""""""""""""""""""""""""""""
+
+    Secure Download Mode is a restricted version of the ROM Loader available on Espressif chips. It only allows a limited set of commands:
+
+    * synchronisation (``SYNC``)
+    * attaching SPI flash (``SPI_ATTACH``)
+    * updating SPI config (``SPI_SET_PARAMS``)
+    * changing baud rate (``CHANGE_BAUDRATE``)
+    * basic flash write (``FLASH_BEGIN``, ``FLASH_DATA``, ``FLASH_END``)
+    * reading a summary of currently enabled security features (``GET_SECURITY_INFO``)
+
+    Any other command (e.g., reading or writing memory, arbitrary code execution through loading to RAM, ...) will result in an error.
+
+    You can read more about Secure Download Mode in the `ESP-IDF Security Overview <https://docs.espressif.com/projects/esp-idf/en/stable/{IDF_TARGET_PATH_NAME}/security/security.html#uart-download-mode>`__.
+
 Checksum
 ^^^^^^^^
 
@@ -442,7 +462,7 @@ SPI Configuration Commands
 SPI Attach Command
 """"""""""""""""""
 
-The SPI _ATTACH command enables the SPI flash interface. It takes a 32-bit data payload which is used to determine which SPI peripheral and pins should be used to connect to SPI flash.
+The SPI_ATTACH command enables the SPI flash interface. It takes a 32-bit data payload which is used to determine which SPI peripheral and pins should be used to connect to SPI flash.
 
 .. only:: esp8266
 

docs/en/esptool/advanced-commands.rst

@@ -136,6 +136,8 @@ This will read 4 bytes from SFDP address 16.
 
 .. only:: not esp8266 and not esp32
 
+    .. _get-security-info:
+
     Read Security Info: ``get_security_info``
     ------------------------------------------
 

docs/en/esptool/basic-commands.rst

@@ -335,6 +335,21 @@ Gaps between the files will be filled with `0x00` bytes.
     esptool --chip {IDF_TARGET_NAME} merge-bin --format uf2 -o merged-flash.uf2 --flash-mode dio --flash-size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin
 
 
+.. only:: not esp8266 and not esp32
+
+    Commands Supported in Secure Download Mode
+    ------------------------------------------
+
+    When running a command against an SoC with active Secure Download Mode, only the following commands are supported:
+
+    *  :ref:`write-flash`
+    *  :ref:`erase-flash` (only ``erase-region``)
+    *  :ref:`get-security-info`
+
+    Running any other operation will result in an error. This is caused by the set of available serial protocol commands being restricted in Secure Download Mode, see :ref:`supported-in-sdm` for details.
+
+    Binary image manipulation commands (``elf2image``, ``image-info``, ``merge-bin``) are not affected, because they do not require a serial connection with an SoC.
+
 Advanced Commands
 -----------------
 
@@ -351,3 +366,4 @@ The following commands are less commonly used, or only of interest to advanced u
     *  :ref:`read-flash-sfdp`
     :esp8266: *  :ref:`chip-id`
     :esp8266: *  :ref:`run`
+    :not esp8266 and not esp32: *  :ref:`get-security-info`