From fd4042a2fd1e1f70a798cb642036cea3fbd520aa Mon Sep 17 00:00:00 2001 From: Jason2866 <24528715+Jason2866@users.noreply.github.com> Date: Sat, 4 Nov 2023 23:33:55 +0100 Subject: [PATCH] Delete docs directory --- docs/README.md | 17 - docs/_static/esptool_versions.js | 16 - docs/conf_common.py | 60 --- docs/en/about.rst | 6 - .../advanced-topics/boot-mode-selection.rst | 356 ------------- .../advanced-topics/firmware-image-format.rst | 172 ------ docs/en/advanced-topics/index.rst | 12 - docs/en/advanced-topics/serial-protocol.rst | 488 ------------------ docs/en/advanced-topics/spi-flash-modes.rst | 114 ---- docs/en/conf.py | 29 -- docs/en/contributing.rst | 3 - docs/en/espefuse/adc-info-cmd.rst | 60 --- docs/en/espefuse/burn-bit-cmd.rst | 74 --- docs/en/espefuse/burn-block-data-cmd.rst | 59 --- docs/en/espefuse/burn-custom-mac-cmd.rst | 120 ----- docs/en/espefuse/burn-efuse-cmd.rst | 101 ---- docs/en/espefuse/burn-key-cmd.rst | 345 ------------- docs/en/espefuse/burn-key-digest-cmd.rst | 174 ------- docs/en/espefuse/check-error-cmd.rst | 107 ---- docs/en/espefuse/dump-cmd.rst | 114 ---- docs/en/espefuse/execute-scripts-cmd.rst | 119 ----- docs/en/espefuse/get-custom-mac-cmd.rst | 30 -- docs/en/espefuse/inc/summary_ESP32-C2.rst | 67 --- docs/en/espefuse/inc/summary_ESP32-C3.rst | 154 ------ docs/en/espefuse/inc/summary_ESP32-C6.rst | 155 ------ docs/en/espefuse/inc/summary_ESP32-H2.rst | 155 ------ docs/en/espefuse/inc/summary_ESP32-P4.rst | 176 ------- docs/en/espefuse/inc/summary_ESP32-S2.rst | 172 ------ docs/en/espefuse/inc/summary_ESP32-S3.rst | 163 ------ docs/en/espefuse/inc/summary_ESP32.rst | 90 ---- docs/en/espefuse/index.rst | 124 ----- .../espefuse/read-write-protections-cmd.rst | 81 --- docs/en/espefuse/set-flash-voltage-cmd.rst | 161 ------ docs/en/espefuse/summary-cmd.rst | 114 ---- docs/en/espsecure/index.rst | 80 --- docs/en/esptool/advanced-commands.rst | 160 ------ docs/en/esptool/advanced-options.rst | 111 ---- docs/en/esptool/basic-commands.rst | 333 ------------ docs/en/esptool/basic-options.rst | 56 -- docs/en/esptool/configuration-file.rst | 148 ------ docs/en/esptool/entering-bootloader.rst | 25 - docs/en/esptool/flash-modes.rst | 120 ----- docs/en/esptool/flasher-stub.rst | 24 - docs/en/esptool/flashing-firmware.rst | 103 ---- docs/en/esptool/index.rst | 31 -- docs/en/esptool/remote-serial-ports.rst | 62 --- docs/en/esptool/scripting.rst | 14 - docs/en/esptool/serial-connection.rst | 47 -- docs/en/index.rst | 55 -- docs/en/installation.rst | 23 - docs/en/resources.rst | 40 -- docs/en/troubleshooting.rst | 214 -------- docs/en/versions.rst | 48 -- docs/requirements.txt | 1 - docs/utils.sh | 18 - 55 files changed, 5901 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/_static/esptool_versions.js delete mode 100644 docs/conf_common.py delete mode 100644 docs/en/about.rst delete mode 100644 docs/en/advanced-topics/boot-mode-selection.rst delete mode 100644 docs/en/advanced-topics/firmware-image-format.rst delete mode 100644 docs/en/advanced-topics/index.rst delete mode 100644 docs/en/advanced-topics/serial-protocol.rst delete mode 100644 docs/en/advanced-topics/spi-flash-modes.rst delete mode 100644 docs/en/conf.py delete mode 100644 docs/en/contributing.rst delete mode 100644 docs/en/espefuse/adc-info-cmd.rst delete mode 100644 docs/en/espefuse/burn-bit-cmd.rst delete mode 100644 docs/en/espefuse/burn-block-data-cmd.rst delete mode 100644 docs/en/espefuse/burn-custom-mac-cmd.rst delete mode 100644 docs/en/espefuse/burn-efuse-cmd.rst delete mode 100644 docs/en/espefuse/burn-key-cmd.rst delete mode 100644 docs/en/espefuse/burn-key-digest-cmd.rst delete mode 100644 docs/en/espefuse/check-error-cmd.rst delete mode 100644 docs/en/espefuse/dump-cmd.rst delete mode 100644 docs/en/espefuse/execute-scripts-cmd.rst delete mode 100644 docs/en/espefuse/get-custom-mac-cmd.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-C2.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-C3.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-C6.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-H2.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-P4.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-S2.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32-S3.rst delete mode 100644 docs/en/espefuse/inc/summary_ESP32.rst delete mode 100644 docs/en/espefuse/index.rst delete mode 100644 docs/en/espefuse/read-write-protections-cmd.rst delete mode 100644 docs/en/espefuse/set-flash-voltage-cmd.rst delete mode 100644 docs/en/espefuse/summary-cmd.rst delete mode 100644 docs/en/espsecure/index.rst delete mode 100644 docs/en/esptool/advanced-commands.rst delete mode 100644 docs/en/esptool/advanced-options.rst delete mode 100644 docs/en/esptool/basic-commands.rst delete mode 100644 docs/en/esptool/basic-options.rst delete mode 100644 docs/en/esptool/configuration-file.rst delete mode 100644 docs/en/esptool/entering-bootloader.rst delete mode 100644 docs/en/esptool/flash-modes.rst delete mode 100644 docs/en/esptool/flasher-stub.rst delete mode 100644 docs/en/esptool/flashing-firmware.rst delete mode 100644 docs/en/esptool/index.rst delete mode 100644 docs/en/esptool/remote-serial-ports.rst delete mode 100644 docs/en/esptool/scripting.rst delete mode 100644 docs/en/esptool/serial-connection.rst delete mode 100644 docs/en/index.rst delete mode 100644 docs/en/installation.rst delete mode 100644 docs/en/resources.rst delete mode 100644 docs/en/troubleshooting.rst delete mode 100644 docs/en/versions.rst delete mode 100644 docs/requirements.txt delete mode 100644 docs/utils.sh diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index e9f747d07..000000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Documentation Source Folder - -This folder contains source files of **esptool documentation**. - -The sources do not render well in GitHub and some information is not visible at all. - -Use actual documentation generated within about 20 minutes on each commit: - -# Hosted Documentation - -* English: https://docs.espressif.com/projects/esptool/ - -The above URL is for the master branch latest version. Click the drop-down in the bottom left to choose a particular version. - -# Building Documentation - -The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md diff --git a/docs/_static/esptool_versions.js b/docs/_static/esptool_versions.js deleted file mode 100644 index b5e0fab54..000000000 --- a/docs/_static/esptool_versions.js +++ /dev/null @@ -1,16 +0,0 @@ -var DOCUMENTATION_VERSIONS = { - DEFAULTS: { has_targets: false, - supported_targets: [ "esp32" ] - }, - VERSIONS: [ ], - IDF_TARGETS: [ - { text: "ESP8266", value: "esp8266" }, - { text: "ESP32", value: "esp32" }, - { text: "ESP32-S2", value: "esp32s2" }, - { text: "ESP32-S3", value: "esp32s3" }, - { text: "ESP32-C3", value: "esp32c3" }, - { text: "ESP32-C2", value: "esp32c2" }, - { text: "ESP32-C6", value: "esp32c6" }, - { text: "ESP32-H2", value: "esp32h2" }, - ] -}; diff --git a/docs/conf_common.py b/docs/conf_common.py deleted file mode 100644 index 3d82118d5..000000000 --- a/docs/conf_common.py +++ /dev/null @@ -1,60 +0,0 @@ -from esp_docs.conf_docs import * # noqa: F403,F401 - -languages = ["en"] -idf_targets = [ - "esp8266", - "esp32", - "esp32s2", - "esp32s3", - "esp32c3", - "esp32c2", - "esp32c6", - "esp32h2", -] - -# link roles config -github_repo = "espressif/esptool" - -# context used by sphinx_idf_theme -html_context["github_user"] = "espressif" -html_context["github_repo"] = "esptool" - -html_static_path = ["../_static"] - -# Conditional content -extensions += ["esp_docs.esp_extensions.dummy_build_system"] - -ESP8266_DOCS = [] - -ESP32_DOCS = [ - "espefuse/*", - "espsecure/*", -] - -ESP32S2_DOCS = ESP32_DOCS - -ESP32C3_DOCS = ESP32S2_DOCS - -ESP32S3_DOCS = ESP32S2_DOCS - -ESP32C2_DOCS = ESP32S3_DOCS - -ESP32C6_DOCS = ESP32C2_DOCS - -ESP32H2_DOCS = ESP32C6_DOCS - -conditional_include_dict = { - "esp8266": ESP8266_DOCS, - "esp32": ESP32_DOCS, - "esp32s2": ESP32S2_DOCS, - "esp32c3": ESP32C3_DOCS, - "esp32s3": ESP32S3_DOCS, - "esp32c2": ESP32C2_DOCS, - "esp32c6": ESP32C6_DOCS, - "esp32h2": ESP32H2_DOCS, -} - -# Extra options required by sphinx_idf_theme -project_slug = "esptool" - -versions_url = "./_static/esptool_versions.js" diff --git a/docs/en/about.rst b/docs/en/about.rst deleted file mode 100644 index d26acadd8..000000000 --- a/docs/en/about.rst +++ /dev/null @@ -1,6 +0,0 @@ -About -===== - -Esptool was started by Fredrik Ahlberg (`themadinventor `_) as an unofficial community project. Later, it was maintained by Angus Gratton (`projectgus `_). It is now supported by `Espressif Systems `_. - -Esptool source code and this documentation are released as Free Software under GNU General Public License Version 2 or later. See `the LICENSE `_ for a copy. diff --git a/docs/en/advanced-topics/boot-mode-selection.rst b/docs/en/advanced-topics/boot-mode-selection.rst deleted file mode 100644 index 62e187b5a..000000000 --- a/docs/en/advanced-topics/boot-mode-selection.rst +++ /dev/null @@ -1,356 +0,0 @@ -{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0"} - -{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46"} - -{IDF_TARGET_BOOTLOADER_OFFSET:default="0",esp32="1000", esp32s2="1000"} - -.. _boot-mode: - -Boot Mode Selection -=================== - -This guide explains how to select the boot mode correctly and describes the boot log messages of {IDF_TARGET_NAME}. - -.. only:: esp8266 - - On many development boards with built-in USB/Serial, this is done for you and ``esptool`` can automatically reset the board into bootloader mode. For other configurations, you will need to follow these steps: - - Required Pins - ------------- - - The following ESP8266 pins must be in a known state for either normal (flash boot) or serial bootloader operation. Most development boards or modules make necessary connections already, internally: - - +--------+--------------------------------------------------------------------------------------------------------------------+ - | GPIO | State | - +========+====================================================================================================================+ - | 15 | Pulled Low/GND (directly connected to GND, or external pull-down resistor) | - +--------+--------------------------------------------------------------------------------------------------------------------+ - | 2 | Pull-up resistor High/VCC, or No Connection (pin has internal weak pullup, external pullup resistor is optional) | - +--------+--------------------------------------------------------------------------------------------------------------------+ - - If these pins are set differently to shown, nothing on the ESP8266 will work as expected. See `ESP8266 Pin List document `__ to see what boot modes are enabled for different pin combinations. - - When the ESP8266 goes into serial bootloader mode, the Boot ROM switches GPIO2 to an output and the UART TX signal is also output to this pin. For this reason GPIO2 should not be directly connected to VCC. Similarly, make sure GPIO2 is not connected to another peripheral where this may cause an issue when in download mode. - - Select Bootloader Mode - ---------------------- - - The ESP8266 will enter the serial bootloader when GPIO0 is held low on reset. Otherwise it will run the program in flash. - - +---------------+----------------------------------------+ - | GPIO0 Input | Mode | - +===============+========================================+ - | Low/GND | ROM serial bootloader for esptool | - +---------------+----------------------------------------+ - | High/VCC | Normal execution mode | - +---------------+----------------------------------------+ - - Many configurations use a "Flash" button that pulls GPIO0 low when pressed. - -.. only:: not esp8266 - - .. warning:: - - The {IDF_TARGET_NAME} has a 45k ohm internal pull-up/pull-down resistor at {IDF_TARGET_STRAP_BOOT_GPIO} (and other pins). If you want to connect a switch button to enter the boot mode, this has to be a strong pull-down. For example a 10k resistor to GND. - - Information about {IDF_TARGET_NAME} strapping pins can also be found in the `{IDF_TARGET_NAME} Datasheet `__, section "Strapping Pins". - - On many development boards with built-in USB/Serial, ``esptool.py`` can automatically reset the board into bootloader mode. For other configurations or custom hardware, you will need to check the orientation of some "strapping pins" to get the correct boot mode: - - Select Bootloader Mode - ---------------------- - - {IDF_TARGET_STRAP_BOOT_GPIO} - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - The {IDF_TARGET_NAME} will enter the serial bootloader when {IDF_TARGET_STRAP_BOOT_GPIO} is held low on reset. Otherwise it will run the program in flash. - - +---------------+----------------------------------------+ - | {IDF_TARGET_STRAP_BOOT_GPIO} Input | Mode | - +===============+========================================+ - | Low/GND | ROM serial bootloader for esptool | - +---------------+----------------------------------------+ - | High/VCC | Normal execution mode | - +---------------+----------------------------------------+ - - {IDF_TARGET_STRAP_BOOT_GPIO} has an internal pullup resistor, so if it is left unconnected then it will pull high. - - Many boards use a button marked "Flash" (or "BOOT" on some Espressif development boards) that pulls {IDF_TARGET_STRAP_BOOT_GPIO} low when pressed. - - {IDF_TARGET_STRAP_BOOT_2_GPIO} - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. only:: esp32 or esp32s2 or esp32s3 - - {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be either left unconnected/floating, or driven Low, in order to enter the serial bootloader. - - .. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6 - - {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of {IDF_TARGET_STRAP_BOOT_2_GPIO} = 0 and {IDF_TARGET_STRAP_BOOT_GPIO} = 0 is invalid and will trigger unexpected behavior. - - In normal boot mode ({IDF_TARGET_STRAP_BOOT_GPIO} high), {IDF_TARGET_STRAP_BOOT_2_GPIO} is ignored. - - - Other Pins - ^^^^^^^^^^ - - .. only:: not esp32 - - As well as the above mentioned pins, other ones influence the serial bootloader, please consult the `{IDF_TARGET_NAME} Datasheet `__, section "Strapping Pins". - - .. only:: esp32 - - As well as {IDF_TARGET_STRAP_BOOT_GPIO} and {IDF_TARGET_STRAP_BOOT_2_GPIO}, the following pins influence the serial bootloader mode: - - +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | GPIO | Meaning | - +=============+============================================================================================================================================================================================================================================================================================+ - | 12 (MTDI) | If driven High, flash voltage (VDD_SDIO) is 1.8V not default 3.3V. Has internal pull-down, so unconnected = Low = 3.3V. May prevent flashing and/or booting if 3.3V flash is used and this pin is pulled high, causing the flash to brownout. See the datasheet for more details. | - +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | 15 (MTDO) | If driven Low, silences boot messages printed by the ROM bootloader. Has an internal pull-up, so unconnected = High = normal output. | - +-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - For more information, consult the `{IDF_TARGET_NAME} Datasheet `__, section "Strapping Pins". - -.. _automatic-bootloader: - -Automatic Bootloader --------------------- - -``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting ``DTR`` and ``RTS`` control lines of the USB to serial converter chip, i.e., FTDI, CP210x, or CH340x. The ``DTR`` and ``RTS`` control lines are in turn connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of ``DTR`` and ``RTS`` will boot the {IDF_TARGET_NAME} into Firmware Download mode. - -.. note:: - - When developing ``esptool.py``, keep in mind ``DTR`` and ``RTS`` are active low signals, i.e., ``True`` = pin @ 0V, ``False`` = pin @ VCC. - -As an example of auto-reset curcuitry implementation, check the `schematic `_ of the ESP32 DevKitC development board: - -- The **Micro USB 5V & USB-UART** section shows the ``DTR`` and ``RTS`` control lines of the USB to serial converter chip connected to ``GPIO0`` and ``EN`` pins of the ESP module. -- Some OS and/or drivers may activate ``RTS`` and or ``DTR`` automatically when opening the serial port (true only for some serial terminal programs, not ``esptool.py``), pulling them low together and holding the ESP in reset. If ``RTS`` is wired directly to ``EN`` then RTS/CTS "hardware flow control" needs to be disabled in the serial program to avoid this. - An additional circuitry is implemented in order to avoid this problem - if both ``RTS`` and ``DTR`` are asserted together, this doesn't reset the chip. The schematic shows this specific circuit with two transistors and its truth table. -- If this circuitry is implemented (all Espressif boards have it), adding a capacitor between the ``EN`` pin and ``GND`` (in the 1uF-10uF range) is necessary for the reset circuitry to work reliably. This is shown in the **ESP32 Module** section of the schematic. -- The **Switch Button** section shows buttons needed for :ref:`manually switching to bootloader `. - -Make the following connections for ``esptool`` to automatically enter the bootloader of an {IDF_TARGET_NAME} chip: - -+-------------+--------------+ -| ESP Pin | Serial Pin | -+=============+==============+ -| EN | RTS | -+-------------+--------------+ -| {IDF_TARGET_STRAP_BOOT_GPIO} | DTR | -+-------------+--------------+ - -In Linux serial ports by default will assert RTS when nothing is attached to them. This can hold the {IDF_TARGET_NAME} in a reset loop which may cause some serial adapters to subsequently reset loop. This functionality can be disabled by disabling ``HUPCL`` (ie ``sudo stty -F /dev/ttyUSB0 -hupcl``). - -(Some third party {IDF_TARGET_NAME} development boards use an automatic reset circuit for ``EN`` & ``{IDF_TARGET_STRAP_BOOT_GPIO}`` pins, but don't add a capacitor on the ``EN`` pin. This results in unreliable automatic reset, especially on Windows. Adding a 1uF (or higher) value capacitor between ``EN`` pin and ``GND`` may make automatic reset more reliable.) - -In general, you should have no problems with the official Espressif development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases: - -- Your hardware does not have the ``DTR`` and ``RTS`` lines connected to ``{IDF_TARGET_STRAP_BOOT_GPIO}`` and ``EN`` (``CHIP_PU``) -- The ``DTR`` and ``RTS`` lines are configured differently -- There are no such serial control lines at all - -.. _manual-bootloader: - -Manual Bootloader ------------------ - -Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset). - -- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset a development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_BOOT_GPIO}``) and press the **EN** button (``EN`` (``CHIP_PU``)). -- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_BOOT_GPIO}`` down. - -.. only:: esp8266 - - .. _boot-log-esp8266: - - Boot Log - -------- - - The ESP8266 boot rom writes a log to the UART when booting. The timing is a little bit unusual: ``74880 baud`` (see :ref:`serial-port-settings`). - - :: - - ets Jan 8 2014,rst cause 1, boot mode:(3,7) - - load 0x40100000, len 24236, room 16 - tail 12 - chksum 0xb7 - ho 0 tail 12 room 4 - load 0x3ffe8000, len 3008, room 12 - tail 4 - chksum 0x2c - load 0x3ffe8bc0, len 4816, room 4 - tail 12 - chksum 0x46 - csum 0x46 - - - Explanation - ^^^^^^^^^^^ - - **rst_cause:** - - +---------------+----------------------------------------+ - | Value | Meaning | - +===============+========================================+ - | 1 | power-on | - +---------------+----------------------------------------+ - | 2 | external-reset | - +---------------+----------------------------------------+ - | 4 | hardware watchdog-reset | - +---------------+----------------------------------------+ - - - **The first parameter of boot_mode:** - - +-------------------------+----------------------------------------------+ - | Value | Meaning | - +=========================+==============================================+ - | 1 (eg. boot mode:(1,x)) | UART download mode (download FW into Flash) | - +-------------------------+----------------------------------------------+ - | 2 (eg. boot mode:(3,x)) | Boot from flash mode | - +-------------------------+----------------------------------------------+ - - **chksum:** - - If value of “chksum” == value of “csum”, it means flash has been read correctly during booting. - - The rest of boot messages are used internally by Espressif. - -.. only:: not esp8266 - - Boot Log - -------- - - Boot Mode Message - ^^^^^^^^^^^^^^^^^ - - After reset, the second line printed by the {IDF_TARGET_NAME} ROM (at 115200bps) is a reset & boot mode message: - - :: - - ets Jun 8 2016 00:22:57 - rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)) - - - ``rst:0xNN (REASON)`` is an enumerated value (and description) of the reason for the reset. A mapping between the hex value and each reason can be found in the `ESP-IDF source under RESET_REASON enum `__. - The value can be read in {IDF_TARGET_NAME} code via the `get_reset_reason() ROM function `__. - - ``boot:0xNN (DESCRIPTION)`` is the hex value of the strapping pins, as represented in the `GPIO_STRAP register `__. - - The individual bit values are as follows: - - .. only:: esp32 - - - ``0x01`` - GPIO5 - - ``0x02`` - MTDO (GPIO15) - - ``0x04`` - GPIO4 - - ``0x08`` - GPIO2 - - ``0x10`` - GPIO0 - - ``0x20`` - MTDI (GPIO12) - - .. only:: not esp32 - - - ``0x04`` - {IDF_TARGET_STRAP_BOOT_2_GPIO} - - ``0x08`` - {IDF_TARGET_STRAP_BOOT_GPIO} - - If the pin was high on reset, the bit value will be set. If it was low on reset, the bit will be cleared. - - A number of boot mode strings can be shown depending on which bits are set: - - - ``DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)`` or ``DOWNLOAD(USB/UART0)`` - {IDF_TARGET_NAME} is in download flashing mode (suitable for esptool) - - ``SPI_FAST_FLASH_BOOT`` - This is the normal SPI flash boot mode. - - Other modes (including ``SPI_FLASH_BOOT``, ``SDIO_REI_FEO_V1_BOOT``, ``ATE_BOOT``) may be shown here. This indicates an unsupported boot mode has been selected. - Consult the strapping pins shown above (in most cases, one of these modes is selected if {IDF_TARGET_STRAP_BOOT_2_GPIO} has been pulled high when {IDF_TARGET_STRAP_BOOT_GPIO} is low). - - .. only:: esp32 - - .. note:: - - ``GPIO_STRAP`` register includes GPIO 4 but this pin is not used by any supported boot mode and be set either high or low for all supported boot modes. - - - Later Boot Messages - ^^^^^^^^^^^^^^^^^^^ - - Later output from the ROM bootloader depends on the strapping pins and - the boot mode. Some common output includes: - - Early Flash Read Error - """""""""""""""""""""" - - :: - - flash read err, {IDF_TARGET_BOOTLOADER_OFFSET} - - This fatal error indicates that the bootloader tried to read the software bootloader header at address 0x{IDF_TARGET_BOOTLOADER_OFFSET} but failed to read valid data. Possible reasons for this include: - - .. list:: - - - There isn't actually a bootloader at offset 0x{IDF_TARGET_BOOTLOADER_OFFSET} (maybe the bootloader was flashed to the wrong offset by mistake, or the flash has been erased and no bootloader has been flashed yet.) - - Physical problem with the connection to the flash chip, or flash chip power. - - Flash encryption is enabled but the bootloader is plaintext. Alternatively, flash encryption is disabled but the bootloader is encrypted ciphertext. - - :esp32: - Boot mode accidentally set to ``HSPI_FLASH_BOOT``, which uses different SPI flash pins. Check {IDF_TARGET_STRAP_BOOT_2_GPIO} (see above). - :esp32: - VDDSDIO has been enabled at 1.8V (due to MTDI/GPIO12, see above), but this flash chip requires 3.3V so it's browning out. - - - Software Bootloader Header Info - """"""""""""""""""""""""""""""" - - .. only:: esp32 - - :: - - configsip: 0, SPIWP:0x00 - clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 - mode:DIO, clock div:1 - - - .. only:: not esp32 - - :: - - SPIWP:0xee - mode:DIO, clock div:1 - - - This is normal boot output based on a combination of eFuse values and information read from the bootloader header at flash offset 0x{IDF_TARGET_BOOTLOADER_OFFSET}: - - .. list:: - - :esp32: - ``configsip: N`` indicates SPI flash config: - - :esp32: - 0 for default SPI flash - :esp32: - 1 if booting from the HSPI bus (due to eFuse configuration) - :esp32: - Any other value indicates that SPI flash pins have been remapped via eFuse (the value is the value read from eFuse, consult :ref:`espefuse docs ` to get an easier to read representation of these pin mappings). - - - ``SPIWP:0xNN`` indicates a custom ``WP`` pin value, which is stored in the bootloader header. This pin value is only used if SPI flash pins have been remapped via eFuse (as shown in the ``configsip`` value). - All custom pin values but WP are encoded in the configsip byte loaded from eFuse, and WP is supplied in the bootloader header. - :esp32: - ``clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00`` Custom GPIO drive strength values for SPI flash pins. These are read from the bootloader header in flash. Not currently supported. - - ``mode: AAA, clock div: N``. SPI flash access mode. Read from the bootloader header, correspond to the ``--flash_mode`` and ``--flash_freq`` arguments supplied to ``esptool.py write_flash`` or ``esptool.py elf2image``. - - ``mode`` can be DIO, DOUT, QIO, or QOUT. *QIO and QOUT are not supported here*, to boot in a Quad I/O mode the ROM bootloader should load the software bootloader in a Dual I/O mode and then the ESP-IDF software bootloader enables Quad I/O based on the detected flash chip mode. - - ``clock div: N`` is the SPI flash clock frequency divider. This is an integer clock divider value from an 80MHz APB clock, based on the supplied ``--flash_freq`` argument (ie 80MHz=1, 40MHz=2, etc). - The ROM bootloader actually loads the software bootloader at a lower frequency than the flash_freq value. The initial APB clock frequency is equal to the crystal frequency, so with a 40MHz crystal the SPI clock used to load the software bootloader will be half the configured value (40MHz/2=20MHz). - When the software bootloader starts it sets the APB clock to 80MHz causing the SPI clock frequency to match the value set when flashing. - - Software Bootloader Load Segments - """"""""""""""""""""""""""""""""" - - :: - - load:0x3fff0008,len:8 - load:0x3fff0010,len:3680 - load:0x40078000,len:8364 - load:0x40080000,len:252 - entry 0x40080034 - - These entries are printed as the ROM bootloader loads each segment in the software bootloader image. The load address and length of each segment is printed. - - You can compare these values to the software bootloader image by running ``esptool.py --chip {IDF_TARGET_PATH_NAME} image_info /path/to/bootloader.bin`` to dump image info including a summary of each segment. Corresponding details will also be found in the bootloader ELF file headers. - - If there is a problem with the SPI flash chip addressing mode, the values printed by the bootloader here may be corrupted. - - The final line shows the entry point address of the software bootloader, where the ROM bootloader will call as it hands over control. diff --git a/docs/en/advanced-topics/firmware-image-format.rst b/docs/en/advanced-topics/firmware-image-format.rst deleted file mode 100644 index 48cb90669..000000000 --- a/docs/en/advanced-topics/firmware-image-format.rst +++ /dev/null @@ -1,172 +0,0 @@ -{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"} - -{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"} - -{IDF_TARGET_FLASH_FREQ_1:default="26", esp32c2="20", esp32h2="16"} - -{IDF_TARGET_FLASH_FREQ_2:default="20", esp32c2="15", esp32h2="12"} - - -.. _image-format: - -Firmware Image Format -===================== - -This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by ``esptool.py elf2image``. - -.. only:: esp8266 - - The firmware file consists of a header, a variable number of data segments and a footer. Multi-byte fields are little-endian. - -.. only:: not esp8266 - - The firmware file consists of a header, an extended header, a variable number of data segments and a footer. Multi-byte fields are little-endian. - -File Header ------------ - -The image header is 8 bytes long: - -.. only:: esp8266 - - +--------+--------------------------------------------------------------------------------------------------+ - | Byte | Description | - +========+==================================================================================================+ - | 0 | Magic number (always ``0xE9``) | - +--------+--------------------------------------------------------------------------------------------------+ - | 1 | Number of segments | - +--------+--------------------------------------------------------------------------------------------------+ - | 2 | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT) | - +--------+--------------------------------------------------------------------------------------------------+ - | 3 | High four bits - Flash size (``0`` = 512KB, ``1`` = 256KB, ``2`` = 1MB, ``3`` = 2MB, ``4`` = 4MB,| - | | ``5`` = 2MB-c1, ``6`` = 4MB-c1, ``8`` = 8MB, ``9`` = 16MB) | - | | | - | | Low four bits - Flash frequency (``0`` = 40MHz, ``1`` = 26MHz, ``2`` = 20MHz, ``0xf`` = 80MHz) | - +--------+--------------------------------------------------------------------------------------------------+ - | 4-7 | Entry point address | - +--------+--------------------------------------------------------------------------------------------------+ - - -.. only:: esp32s2 or esp32s3 - - +--------+------------------------------------------------------------------------------------------------+ - | Byte | Description | - +========+================================================================================================+ - | 0 | Magic number (always ``0xE9``) | - +--------+------------------------------------------------------------------------------------------------+ - | 1 | Number of segments | - +--------+------------------------------------------------------------------------------------------------+ - | 2 | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT) | - +--------+------------------------------------------------------------------------------------------------+ - | 3 | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB, | - | | ``5`` = 32MB, ``6`` = 64MB, ``7`` = 128MB") | - | | | - | | Low four bits - Flash frequency (``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``1`` = {IDF_TARGET_FLASH_FREQ_1}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz, ``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz) | - +--------+------------------------------------------------------------------------------------------------+ - | 4-7 | Entry point address | - +--------+------------------------------------------------------------------------------------------------+ - - -.. only:: esp32c6 - - +--------+------------------------------------------------------------------------------------------------+ - | Byte | Description | - +========+================================================================================================+ - | 0 | Magic number (always ``0xE9``) | - +--------+------------------------------------------------------------------------------------------------+ - | 1 | Number of segments | - +--------+------------------------------------------------------------------------------------------------+ - | 2 | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT) | - +--------+------------------------------------------------------------------------------------------------+ - | 3 | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB) | - | | | - | | Low four bits - Flash frequency (``0`` = 80MHz, ``0`` = 40MHz, ``2`` = 20MHz) | - +--------+------------------------------------------------------------------------------------------------+ - | 4-7 | Entry point address | - +--------+------------------------------------------------------------------------------------------------+ - - .. note:: - Flash frequency with value ``0`` can mean either 80MHz or 40MHz based on MSPI clock source mode. - - -.. only:: not (esp8266 or esp32c6 or esp32s3 or esp32s2) - - +--------+------------------------------------------------------------------------------------------------+ - | Byte | Description | - +========+================================================================================================+ - | 0 | Magic number (always ``0xE9``) | - +--------+------------------------------------------------------------------------------------------------+ - | 1 | Number of segments | - +--------+------------------------------------------------------------------------------------------------+ - | 2 | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT) | - +--------+------------------------------------------------------------------------------------------------+ - | 3 | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB) | - | | | - | | Low four bits - Flash frequency (``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``1`` = {IDF_TARGET_FLASH_FREQ_1}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz, ``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz) | - +--------+------------------------------------------------------------------------------------------------+ - | 4-7 | Entry point address | - +--------+------------------------------------------------------------------------------------------------+ - - -``esptool.py`` overrides the 2nd and 3rd (start from 0) bytes according to the SPI flash info provided through command line option, but only if there is no SHA256 digest appended after the image. Therefore, if you would like to change SPI flash info during flashing, i.e. with the ``esptool.py write_flash`` command, then generate images without SHA256 digests. This can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument. - -.. only:: esp8266 - - Individual segments come right after this header. - -.. only:: not esp8266 - - Extended File Header - -------------------- - - The 16-byte long extended header comes right after the image header, individual segments come right after it: - - +--------+---------------------------------------------------------------------------------------------------------+ - | Byte | Description | - +========+=========================================================================================================+ - | 0 | WP pin when SPI pins set via efuse (read by ROM bootloader) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 1-3 | Drive settings for the SPI flash pins (read by ROM bootloader) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 4-5 | Chip ID (which ESP device is this image for) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 6 | Minimal chip revision supported by the image (deprecated, use the following field) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 7-8 | Minimal chip revision supported by the image (in format: major * 100 + minor) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 9-10 | Maximal chip revision supported by the image (in format: major * 100 + minor) | - +--------+---------------------------------------------------------------------------------------------------------+ - | 11-14 | Reserved bytes in additional header space, currently unused | - +--------+---------------------------------------------------------------------------------------------------------+ - | 15 | Hash appended (If 1, SHA256 digest is appended after the checksum) | - +--------+---------------------------------------------------------------------------------------------------------+ - -Segment -------- - -+---------+-----------------+ -| Byte | Description | -+=========+=================+ -| 0-3 | Memory offset | -+---------+-----------------+ -| 4-7 | Segment size | -+---------+-----------------+ -| 8...n | Data | -+---------+-----------------+ - -Footer ------- - -The file is padded with zeros until its size is one byte less than a multiple of 16 bytes. A last byte (thus making the file size a multiple of 16) is the checksum of the data of all segments. The checksum is defined as the xor-sum of all bytes and the byte ``0xEF``. - -.. only:: not esp8266 - - If ``hash appended`` in the extended file header is ``0x01``, a SHA256 digest “simple hash” (of the entire image) is appended after the checksum. This digest is separate to secure boot and only used for detecting corruption. The SPI flash info cannot be changed during flashing if hash is appended after the image. - - If secure boot is enabled, a signature is also appended (and the simple hash is included in the signed data). This image signature is `Secure Boot V1 `_ and `Secure Boot V2 `_ specific. - - -Analyzing a Binary Image ------------------------- - -To analyze a binary image and get a complete summary of its headers and segments, use the :ref:`image_info ` command with the ``--version 2`` option. diff --git a/docs/en/advanced-topics/index.rst b/docs/en/advanced-topics/index.rst deleted file mode 100644 index 7f1d79e21..000000000 --- a/docs/en/advanced-topics/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Advanced Topics -=============== - -This sections contains advanced topics and technical documentation useful if you're developing ``esptool`` or hacking system internals: - -.. toctree:: - :maxdepth: 1 - - Firmware Image Format - Serial Protocol - SPI Flash Modes - Boot Mode Selection diff --git a/docs/en/advanced-topics/serial-protocol.rst b/docs/en/advanced-topics/serial-protocol.rst deleted file mode 100644 index 83a7e3a6b..000000000 --- a/docs/en/advanced-topics/serial-protocol.rst +++ /dev/null @@ -1,488 +0,0 @@ -{IDF_TARGET_SECURITY_INFO:default="32 bits ``flags``, 1 byte ``flash_crypt_cnt``, 7x1 byte ``key_purposes``, 32-bit word ``chip_id``, 32-bit word ``eco_version``", esp32s2="32 bits ``flags``, 1 byte ``flash_crypt_cnt``, 7x1 byte ``key_purposes`` "} - -Serial Protocol -=============== - -This is technical documentation for the serial protocol used by the UART bootloader in the {IDF_TARGET_NAME} ROM and the esptool :ref:`stub loader ` program. - -The UART bootloader runs on chip reset if certain strapping pins are set. See :ref:`entering-the-bootloader` for details of this process. - -.. only:: not esp8266 - - The {IDF_TARGET_NAME} ROM loader serial protocol is similar to ESP8266, although {IDF_TARGET_NAME} adds some additional commands and some slightly different behaviour. - -By default, esptool uploads a stub "software loader" to the IRAM of the chip. The stub loader then replaces the ROM loader for all future interactions. This standardizes much of the behaviour. Pass ``--no-stub`` to esptool in order to disable the stub loader. See :ref:`stub` for more information. - -.. note:: - - There are differences in the serial protocol between ESP chips! To switch to documentation for a different chip, choose the desired target from the dropdown menu in the upper left corner. - -Packet Description ------------------- - -The host computer sends a SLIP encoded command request to the ESP chip. The ESP chip responds to the request with a SLIP encoded response packet, including status information and any data as a payload. - -.. _low-level-protocol: - -Low Level Protocol -^^^^^^^^^^^^^^^^^^ - -The bootloader protocol uses `SLIP `_ packet framing for data transmissions in both directions. - -Each SLIP packet begins and ends with ``0xC0``. Within the packet, all occurrences of ``0xC0`` and ``0xDB`` are replaced with ``0xDB 0xDC`` and ``0xDB 0xDD``, respectively. The replacing is to be done **after** the checksum and lengths are calculated, so the packet length may be longer than the ``size`` field below. - -Command Packet -^^^^^^^^^^^^^^ - -Each command is a SLIP packet initiated by the host and results in a response packet. Inside the packet, the packet consists of a header and a variable-length body. All multi-byte fields are little-endian. - -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ -| Byte | Name | Comment | -+========+=============+====================================================================================================================+ -| 0 | Direction | Always ``0x00`` for requests | -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ -| 1 | Command | Command identifier (see `Commands`_). | -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ -| 2-3 | Size | Length of Data field, in bytes. | -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ -| 4-7 | Checksum | Simple checksum of part of the data field (only used for some commands, see `Checksum`_). | -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ -| 8..n | Data | Variable length data payload (0-65535 bytes, as indicated by Size parameter). Usage depends on specific command. | -+--------+-------------+--------------------------------------------------------------------------------------------------------------------+ - -Response Packet -^^^^^^^^^^^^^^^ - -Each received command will result in a response SLIP packet sent from the ESP chip to the host. Contents of the response packet is: - -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ -| Byte | Name | Comment | -+========+=============+==============================================================================================================+ -| 0 | Direction | Always ``0x01`` for responses | -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ -| 1 | Command | Same value as Command identifier in the request packet that triggered the response | -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ -| 2-3 | Size | Size of data field. At least the length of the `Status Bytes`_ (2 or 4 bytes, see below). | -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ -| 4-7 | Value | Response value used by READ_REG command (see below). Zero otherwise. | -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ -| 8..n | Data | Variable length data payload. Length indicated by "Size" field. | -+--------+-------------+--------------------------------------------------------------------------------------------------------------+ - -Status bytes -"""""""""""" - -The final bytes of the Data payload indicate command status: - -.. only:: esp8266 - - For stub loader and ESP8266 ROM loader the final two bytes indicate status (most commands return at least a two byte Data payload): - -.. only:: not esp8266 - - For stub loader the final two bytes indicate status (most commands return at least a two byte Data payload): - -+----------+----------+-----------------------------------------------------+ -| Byte | Name | Comment | -+==========+==========+=====================================================+ -| Size-2 | Status | Status flag, success (``0``) or failure (``1``) | -+----------+----------+-----------------------------------------------------+ -| Size-1 | Error | If Status is 1, this indicates the type of error. | -+----------+----------+-----------------------------------------------------+ - -.. only:: not esp8266 - - For {IDF_TARGET_NAME} ROM (only, not the stub loader) the final four bytes are used, but only the first two bytes contain status information: - - +----------+------------+---------------------------------------------------+ - | Byte | Name | Comment | - +==========+============+===================================================+ - | Size-4 | Status | Status flag, success (``0``) or failure (``1``) | - +----------+------------+---------------------------------------------------+ - | Size-3 | Error | If Status 1, this indicates the type of error. | - +----------+------------+---------------------------------------------------+ - | Size-2 | Reserved | | - +----------+------------+---------------------------------------------------+ - | Size-1 | Reserved | | - +----------+------------+---------------------------------------------------+ - -ROM Loader Errors -""""""""""""""""" - -The ROM loader sends the following error values - -+----------+---------------------------------------------------------------------------+ -| Value | Meaning | -+==========+===========================================================================+ -| ``0x05`` | "Received message is invalid" (parameters or length field is invalid) | -+----------+---------------------------------------------------------------------------+ -| ``0x06`` | "Failed to act on received message" | -+----------+---------------------------------------------------------------------------+ -| ``0x07`` | "Invalid CRC in message" | -+----------+---------------------------------------------------------------------------+ -| ``0x08`` | "Flash write error" - after writing a block of data to flash, | -| | the ROM loader reads the value back and the 8-bit CRC is compared | -| | to the data read from flash. If they don't match, this error is returned. | -+----------+---------------------------------------------------------------------------+ -| ``0x09`` | "Flash read error" - SPI read failed | -+----------+---------------------------------------------------------------------------+ -| ``0x0a`` | "Flash read length error" - SPI read request length is too long | -+----------+---------------------------------------------------------------------------+ -| ``0x0b`` | "Deflate error" (compressed uploads only) | -+----------+---------------------------------------------------------------------------+ - -Stub Loader Status & Error -"""""""""""""""""""""""""" - -If the stub loader is used: - -- The status response is always 2 bytes regardless of chip type. -- Stub loader error codes are entirely different to the ROM loader codes. They all take the form ``0xC*``, or ``0xFF`` for "unimplemented command". (`Full list here `_). - -After sending a command, the host should continue to read response packets until one is received where the Command field matches the request's Command field, or a timeout is exceeded. - -Commands -^^^^^^^^ - -Supported by stub loader and ROM loader -""""""""""""""""""""""""""""""""""""""" - -.. only:: esp8266 - - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | Byte | Name | Description | Input Data | Output Data | - +============+================+=======================================================+====================================================================================================================================+================================================+ - | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | - +------------+----------------+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------+ - -.. only:: esp32 - - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | Byte | Name | Description | Input Data | Output Data | - +============+======================+================================================================+================================================================================================================================================================================================================================================+===================================================================================================================================+ - | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0b`` | SPI_SET_PARAMS | `Configure SPI flash <#spi-set-parameters>`__ | Six 32-bit words: id, total size in bytes, block size, sector size, page size, status mask. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0d`` | SPI_ATTACH | `Attach SPI flash <#spi-attach-command>`__ | 32-bit word: Zero for normal SPI flash. A second 32-bit word (should be ``0``) is passed to ROM loader only. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0f`` | CHANGE_BAUDRATE | `Change Baud rate <#initial-synchronisation>`__ | Two 32-bit words: new baud rate, ``0`` if we are talking to the ROM loader or the current/old baud rate if we are talking to the stub loader. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x10`` | FLASH_DEFL_BEGIN | `Begin compressed flash download <#writing-data>`__ | Four 32-bit words: uncompressed size, number of data packets, data packet size, flash offset. With stub loader the uncompressed size is exact byte count to be written, whereas on ROM bootloader it is rounded up to flash erase block size. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x11`` | FLASH_DEFL_DATA | `Compressed flash download data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | Error code ``0xC1`` on checksum error. | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x12`` | FLASH_DEFL_END | `End compressed flash download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x13`` | SPI_FLASH_MD5 | `Calculate MD5 of flash region <#verifying-uploaded-data>`__ | Four 32-bit words: address, size, ``0``, ``0`` | Body contains 16 raw bytes of MD5 followed by 2 status bytes (stub loader) or 32 hex-coded ASCII (ROM loader) of calculated MD5 | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - -.. only:: not esp8266 and not esp32 - - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | Byte | Name | Description | Input Data | Output Data | - +============+======================+================================================================+================================================================================================================================================================================================================================================+===================================================================================================================================+ - | ``0x02`` | FLASH_BEGIN | `Begin Flash Download <#writing-data>`__ | Four 32-bit words: size to erase, number of data packets, data size in one packet, flash offset. A fifth 32-bit word passed to ROM loader only: ``1`` to begin encrypted flash, ``0`` to not. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x03`` | FLASH_DATA | `Flash Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x04`` | FLASH_END | `Finish Flash Download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x05`` | MEM_BEGIN | `Begin RAM Download Start <#writing-data>`__ | Total size, number of data packets, data size in one packet, memory offset | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x06`` | MEM_END | `Finish RAM Download <#writing-data>`__ | Two 32-bit words: execute flag, entry point address | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x07`` | MEM_DATA | `RAM Download Data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x08`` | SYNC | `Sync Frame <#initial-synchronisation>`__ | 36 bytes: ``0x07 0x07 0x12 0x20``, followed by 32 x ``0x55`` | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x09`` | WRITE_REG | `Write 32-bit memory address <#32-bit-readwrite>`__ | Four 32-bit words: address, value, mask and delay (in microseconds) | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0a`` | READ_REG | `Read 32-bit memory address <#32-bit-readwrite>`__ | Address as 32-bit word | Read data as 32-bit word in ``value`` field. | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0b`` | SPI_SET_PARAMS | `Configure SPI flash <#spi-set-parameters>`__ | Six 32-bit words: id, total size in bytes, block size, sector size, page size, status mask. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0d`` | SPI_ATTACH | `Attach SPI flash <#spi-attach-command>`__ | 32-bit word: Zero for normal SPI flash. A second 32-bit word (should be ``0``) is passed to ROM loader only. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x0f`` | CHANGE_BAUDRATE | `Change Baud rate <#initial-synchronisation>`__ | Two 32-bit words: new baud rate, ``0`` if we are talking to the ROM loader or the current/old baud rate if we are talking to the stub loader. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x10`` | FLASH_DEFL_BEGIN | `Begin compressed flash download <#writing-data>`__ | Four 32-bit words: uncompressed size, number of data packets, data packet size, flash offset. With stub loader the uncompressed size is exact byte count to be written, whereas on ROM bootloader it is rounded up to flash erase block size. | | - | | | | A fifth 32-bit word passed to ROM loader only: ``1`` to begin encrypted flash, ``0`` to not. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x11`` | FLASH_DEFL_DATA | `Compressed flash download data <#writing-data>`__ | Four 32-bit words: data size, sequence number, ``0``, ``0``, then data. Uses `Checksum`_. | Error code ``0xC1`` on checksum error. | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x12`` | FLASH_DEFL_END | `End compressed flash download <#writing-data>`__ | One 32-bit word: ``0`` to reboot, ``1`` to run user code. Not necessary to send this command if you wish to stay in the loader. | | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x13`` | SPI_FLASH_MD5 | `Calculate MD5 of flash region <#verifying-uploaded-data>`__ | Four 32-bit words: address, size, ``0``, ``0`` | Body contains 16 raw bytes of MD5 followed by 2 status bytes (stub loader) or 32 hex-coded ASCII (ROM loader) of calculated MD5 | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | ``0x14`` | GET_SECURITY_INFO | Read chip security info | | {IDF_TARGET_SECURITY_INFO} | - +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - -Supported by stub loader only -""""""""""""""""""""""""""""" - -ROM loaders will not recognise these commands. - -+------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ -| Byte | Name | Descripton | Input | Output | -+============+===================+===================================+=========================================================================================================================+==========+ -| ``0xd0`` | ERASE_FLASH | Erase entire flash chip | | | -+------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ -| ``0xd1`` | ERASE_REGION | Erase flash region | Two 32-bit words: flash offset to erase, erase size in bytes. Both must be multiples of flash sector size. | | -+------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ -| ``0xd2`` | READ_FLASH | `Read flash <#reading-flash>`__ | Four 32-bit words: flash offset, read length, flash sector size, read packet size, maximum number of un-acked packets | | -+------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ -| ``0xd3`` | RUN_USER_CODE | Exits loader and runs user code | | | -+------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ - -Checksum -^^^^^^^^ - -The checksum field is ignored (can be zero) for all comands except for MEM_DATA, FLASH_DATA, and FLASH_DEFL_DATA. - -Each of the ``_DATA`` command packets (like ``FLASH_DEFL_DATA``, ``MEM_DATA``) has the same "data payload" format: - -+---------+--------------------------+----------------------------------------------------------------+ -| Bytes | Name | Format | -+=========+==========================+================================================================+ -| 0-3 | "Data to write" length | Little endian 32-bit word. | -+---------+--------------------------+----------------------------------------------------------------+ -| 4-7 | Sequence number | Little endian 32-bit word. The sequence numbers are 0 based. | -+---------+--------------------------+----------------------------------------------------------------+ -| 8-15 | 0 | Two words of all zeroes, unused. | -+---------+--------------------------+----------------------------------------------------------------+ -| 16- | "Data to write" | Length given at beginning of payload. | -+---------+--------------------------+----------------------------------------------------------------+ - -The checksum is only applied to this final "data to write" section, not the first 16 bytes of data. - -To calculate checksum, start with seed value 0xEF and XOR each individual byte in the "data to write". The 8-bit result is stored in the checksum field of the packet header (as a little endian 32-bit value). - -.. note:: - - Because this checksum is not adequate to ensure valid data, the SPI_FLASH_MD5 command was added to validate flash contents after flashing. It is recommended that this command is always used. See `Verifying Uploaded Data`_, below. - -Functional Description ----------------------- - -Initial Synchronisation -^^^^^^^^^^^^^^^^^^^^^^^ -.. list:: - - :esp8266: * The ESP chip is reset into UART bootloader mode. The host starts by sending SYNC commands. These commands have a large data payload which is also used by the ESP chip to detect the configured baud rate. The ESP8266 will initialise at 74800bps with a 26MHz crystal and 115200bps with a 40MHz crystal. However the sync packets can be sent at any baud rate, and the UART peripheral will detect this. - :not esp8266: * The ESP chip is reset into UART bootloader mode. The host starts by sending SYNC commands. These commands have a large data payload which is also used by the ESP chip to detect the configured baud rate. {IDF_TARGET_NAME} always initialises at 115200bps. However the sync packets can be sent at any baud rate, and the UART peripheral will detect this. - * The host should wait until it sees a valid response to a SYNC command, indicating the ESP chip is correctly communicating. - * Esptool then (by default) uses the "RAM Download" sequence to upload :ref:`stub loader ` code to IRAM of the chip. The MEM_END command contains the entry-point address to run the stub loader. - The stub loader then sends a custom SLIP packet of the sequence OHAI (``0xC0 0x4F 0x48 0x41 0x49 0xC0``), indicating that it is now running. This is the only unsolicited packet ever sent by the ESP. - If the ``--no-stub`` argument is supplied to esptool, this entire step is skipped. - * esptool then uses READ_REG commands to read various addresses on the chip, to identify chip subtype, revision, etc. - :not esp8266: * For commands which need to use the flash, the {IDF_TARGET_NAME} ROM an stub loader requires the SPI_ATTACH and SPI_SET_PARAMS commands. See `SPI Configuration Commands`_. - :esp8266: * For stub loader, the host can send a CHANGE_BAUD command to set the baud rate to an explicit value. Compared to auto-detecting during the SYNC pulse, this can be more reliable for setting very high baud rate. Esptool tries to sync at (maximum) 115200bps and then sends this command to go to a higher baud rate, if requested. - :not esp8266: * For stub loader and/or {IDF_TARGET_NAME} ROM loader, the host can send a CHANGE_BAUD command to set the baud rate to an explicit value. Compared to auto-detecting during the SYNC pulse, this can be more reliable for setting very high baud rate. Esptool tries to sync at (maximum) 115200bps and then sends this command to go to a higher baud rate, if requested. - -Writing Data -^^^^^^^^^^^^ - -(Includes RAM Download, Flash Download, Compressed Flash Download.) - -.. list:: - - * RAM Download (MEM_BEGIN, MEM_DATA, MEM_END) loads data into the ESP chip memory space and (optionally) executes it. - * Flash Download (FLASH_BEGIN, FLASH_DATA) flashes data into the ESP SPI flash. - :esp8266: * Compressed Flash Download is the same, only the data is compressed using the gzip Deflate algorithm to reduce serial overhead. Not supported on ESP8266 ROM loader. - :not esp8266: * Compressed Flash Download is the same, only the data is compressed using the gzip Deflate algorithm to reduce serial overhead. - -All three of these sequences follow a similar pattern: - -* A _BEGIN command (FLASH_BEGIN, etc) is sent which contains basic parameters for the flash erase size, start address to write to, etc. The uploader also needs to specify how many "blocks" of data (ie individual data packets) will be sent, and how big each packet is. -* One or more _DATA commands (FLASH_DATA, etc) is sent where the data payload contains the actual data to write to flash/RAM. In the case of Compressed Flash Downloads, the data is compressed using the gzip deflate algorithm. The number of _DATA commands is specified in the _BEGIN command, as is the size of each _DATA payload. - The last data block should be padded to the block size with 0xFF bytes. -* An _END command (FLASH_END, etc) is sent to exit the bootloader and optionally reset the chip (or jump to an address in RAM, in the case of MEM_END). Not necessary to send after flashing if you wish to continue sending other or different commands. - -It's not necessary to send flash erase commands before sending commands to write to flash, etc. The ROM loaders erase the to-be-written region in response to the FLASH_BEGIN command. -The stub loader does just-in-time erasing as it writes data, to maximise overall flashing performance (each block of data is read into RAM via serial while the previous block is simultaneously being written to flash, and 4KB and 64KB erases are done as needed before writing to flash). - -The block size chosen should be small enough to fit into RAM of the device. Esptool uses 16KB which gives good performance when used with the stub loader. - -.. only:: esp8266 - - Erase Size Bug - """""""""""""" - - On ESP8266 ROM loader only (not stub loader), there is a bug in the interpretation of the FLASH_BEGIN "erase size" parameter. Consult the ``ESP8266ROM.get_erase_size()`` function in esptool for the algorithm which works around this bug and provides the correct erase size parameter to send to the ESP8266. - - This workaround is not needed if the ESP8266 is running the stub loader. - -Verifying Uploaded Data -""""""""""""""""""""""" - -.. only:: esp8266 - - The 8-bit checksum used in the upload protocol is not sufficient to ensure valid flash contents after upload. The uploader should send the SPI_FLASH_MD5 command (not supported on ESP8266 ROM loader) or use another method to verify flash contents. - -.. only:: not esp8266 - - The 8-bit checksum used in the upload protocol is not sufficient to ensure valid flash contents after upload. The uploader should send the SPI_FLASH_MD5 command or use another method to verify flash contents. - -The SPI_FLASH_MD5 command passes the start address in flash and the size of data to calculate. The MD5 value is returned in the response payload, before the status bytes. - -.. only:: not esp8266 - - Note that the {IDF_TARGET_NAME} ROM loader returns the md5sum as 32 hex encoded ASCII bytes, whereas the stub loader returns the md5sum as 16 raw data bytes of MD5 followed by 2 status bytes. - -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. - -.. only:: esp8266 - - On the ESP8266 stub loader sending this command before interacting with SPI flash is optional. On ESP8266 ROM loader this command is not supported (SPI flash is enabled when the FLASH_BEGIN command is sent). - - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - | Value | Meaning | - +==================+==================================================================================================================================+ - | 0 | Default SPI flash interface | - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - | 1 | HSPI interface | - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - -.. only:: not esp8266 - - On the {IDF_TARGET_NAME} stub loader, it is required to send this command before interacting with SPI flash. - - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - | Value | Meaning | - +==================+==================================================================================================================================+ - | 0 | Default SPI flash interface | - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - | 1 | HSPI interface | - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - | (other values) | Pin numbers as 6-bit values, packed into a 30-bit value. Order (from MSB): HD pin, Q pin, D pin, CS pin, CLK pin. | - +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - - The "Default SPI flash interface" uses pins configured via the ``SPI_PAD_CONFIG_xxx`` efuses (if unset, these efuses are all zero and the default SPI flash pins given in the datasheet are used.) - - When writing the values of each pin as 6-bit numbers packed into the data word, each 6-bit value uses the following representation: - - * Pin numbers 0 through 30 are represented as themselves. - * Pin numbers 32 & 33 are represented as values 30 & 31. - * It is not possible to represent pins 30 & 31 or pins higher than 33. This is the same 6-bit representation used by the ``SPI_PAD_CONFIG_xxx`` efuses. - - On {IDF_TARGET_NAME} ROM loader only, there is an additional 4 bytes in the data payload of this command. These bytes should all be set to zero. - -SPI Set Parameters -"""""""""""""""""" - -The SPI_SET_PARAMS command sets some parameters of the attached SPI flash chip (sizes, etc). - -.. only:: esp8266 - - This command is not supported by the ESP8266 ROM loader. - -All the values which are passed except total size are hardcoded, and most are not used when writing to flash. See `flash_set_parameters function `__ in esptool for the values which it sends. - -32-bit Read/Write -^^^^^^^^^^^^^^^^^ - -The 32-bit read/write commands (READ_REG, WRITE_REG) allow word-oriented reading and writing of memory and register data. - -These commands can be used to manipulate peripherals in arbitrary ways. For example, the esptool "flash id" functionality is implemented by manipulating the SPI peripheral registers to send a JEDEC flash ID command to the flash chip and read the response. - -Reading Flash -^^^^^^^^^^^^^ - -The stub loader implements a READ_FLASH command. This command behaves differently to other commands, including the ROM loader's READ_FLASH command: - -* The host sends the READ_FLASH command and the data payload contains the offset, read size, size of each individual packet of data, and the maximum number of "un-acknowledged" data packets which can be in flight at one time. -* The stub loader will send a standard response packet, with no additional data payload. -* Now the stub loader will start sending SLIP packets with raw data (of the size requested in the command). There is no metadata included with these SLIP packets. -* After each SLIP packet is received, the host should send back a 4 byte raw SLIP acknowledgement packet with the total number of bytes which have been received. There is no header or other metadata included with these SLIP packets. -* The stub loader may send up to a maximum number (specified by the host in the READ_FLASH commands) of data packets before waiting for the first acknowledgement packet. No more than this "max in flight" limit can be un-acknowledged at any one time. -* After all data packets are acknowledged received, the stub loader sends a 16 byte MD5 digest of all the data which was read from flash. This is also sent as a raw SLIP packet, with no metadata. - -After the read flash process is complete, the stub loader goes back to normal command/response operation. - -The ROM loader read flash command is more normal but also much slower to read data. - -.. _tracing-communications: - -Tracing Esptool Serial Communications -------------------------------------- - -esptool has a ``--trace`` option which can be supplied in the first group of arguments (before the command). This will dump all traffic sent and received via the serial port to the console. - -Here is a sample extract, showing a READ_REG command and response: - -:: - - TRACE +0.000 command op=0x0a data len=4 wait_response=1 timeout=3.000 data=1400f43f - TRACE +0.000 Write 14 bytes: c0000a0400000000001400f43fc0 - TRACE +0.005 Read 1 bytes: c0 - TRACE +0.000 Read 11 bytes: 010a0200620100000000c0 - TRACE +0.000 Received full packet: 010a0200620100000000 - -The +X.XXX value is the time delta (in seconds) since the last trace line. - -Values are printed in hexadecimal. If more than 16 bytes is printed at one time, a split display is used with hexadecimal bytes on the left and ASCII on the right. Non-printable characters are represented as ``.`` in ASCII: - -Note that multiple protocol layers are represented in the logs. The "Write X bytes" lines show exactly which bytes are being sent "over the wire", including SLIP framing. Similarly the "Read X bytes" lines show what bytes are being read over the wire, including any SLIP framing. -Once a full SLIP packet is read, the same bytes - as a SLIP payload with any escaping removed - appear in the "Received full packet" log lines. - -Here is a second example showing part of the initial synchronization sequence (lots of 0x55 bytes which are ``U`` in ASCII): - -:: - - TRACE +0.000 Write 46 bytes: - c000082400000000 0007071220555555 | ...$........ UUU - 5555555555555555 5555555555555555 | UUUUUUUUUUUUUUUU - 5555555555555555 5555555555c0 | UUUUUUUUUUUUU. - TRACE +0.011 Read 1 bytes: c0 - TRACE +0.000 Read 63 bytes: - 0108040007122055 00000000c0c00108 | ...... U........ - 0400071220550000 0000c0c001080400 | .... U.......... - 0712205500000000 c0c0010804000712 | .. U............ - 205500000000c0c0 01080400071220 | U............ - TRACE +0.000 Received full packet: 010804000712205500000000 - TRACE +0.000 Received full packet: 010804000712205500000000 - -.. important:: - - If you don't plan to use the esptool stub loader, pass ``--no-stub --trace`` to see interactions with the chip's built-in ROM loader only. Otherwise, the trace will show the full binary upload of the loader. - -In addition to this trace feature, most operating systems have "system call trace" or "port trace" features which can be used to dump serial interactions. diff --git a/docs/en/advanced-topics/spi-flash-modes.rst b/docs/en/advanced-topics/spi-flash-modes.rst deleted file mode 100644 index 22b54766d..000000000 --- a/docs/en/advanced-topics/spi-flash-modes.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _spi-flash-modes: - -SPI Flash Modes -=============== - -The ESP chips support four different SPI flash access modes: DIO, DOUT, QIO & QOUT. These can be set via the ``--flash_mode`` option of ``esptool.py write_flash``. - -These options control how many I/O pins are used for communication with the attached SPI flash chip, and which SPI commands are used. - -ESP chips use these commands when reading or executing code and data from the SPI flash chip. Data is read and then cached internally to the chip. - -Summary -------- - -In order of performance: - -+------------+---------------+----------------------------------+-----------------------------------+ -| Option | Mode Name | Pins Used | Speed (ESP device) | -+============+===============+==================================+===================================+ -| ``qio`` | Quad I/O | 4 pins used for address & data | Fastest. | -+------------+---------------+----------------------------------+-----------------------------------+ -| ``qout`` | Quad Output | 4 pins used for data. | Approx 15% slower than ``qio``. | -+------------+---------------+----------------------------------+-----------------------------------+ -| ``dio`` | Dual I/O | 2 pins used for address & data | Approx 45% slower than ``qio``. | -+------------+---------------+----------------------------------+-----------------------------------+ -| ``dout`` | Dual Output | 2 pins used for data. | Approx 50% slower than ``qio``. | -+------------+---------------+----------------------------------+-----------------------------------+ - -In general, choose the fastest option for flash_mode that works with your device. Not all devices support all modes. See FAQ below for details. - -Mode Descriptions ------------------ - -Normal SPI -^^^^^^^^^^ - -A traditional "single" SPI (Serial Peripheral Interface) bus uses 4 pins for communication: - -* Clock (CLK) -* Master Out Slave In (MOSI) -* Master In Slave Out (MISO) -* Chip Select (CS) - -`Wikipedia has a fairly complete description `__. - -All of these signals are unidirectional. In single SPI mode, data is sent from the device to the host using the MISO pin and from the host to the device using the MOSI pin. - -The maximum data rate for normal SPI is the clock rate in bits - so a 40MHz clock = 40Mbits/sec = 5Mbytes/sec. - -Dual SPI -^^^^^^^^ - -To improve performance, SPI flash manufacturers introduced "Dual SPI". In Dual SPI modes, the MOSI & MISO pins are both used to read or write data simultaneously with two bits per clock cycle. This doubles the data rate for some commands, compared to single SPI. - -In ``dout`` mode, the host uses the "Dual Output Fast Read" (3BH) command to read data. Each read command and the read address is sent from the host to the flash chip via normal SPI, but then the host reads the data via both the MOSI & MISO pins simultaneously with two bits per clock. -This doubles the data transfer rate compared to single SPI which only uses MISO to read data. - -In ``dio`` mode, the host uses the "Dual I/O Fast Read" (BBH) command to read data. Each read command is sent from the host to the flash chip via normal SPI, but then the address is sent to the flash chip via both the MOSI & MISO pins with two bits per clock. -After this, the host reads the data bits with two bits per clock in the same way as "Dual Output Fast Read". - -For ESP chips, 32 bytes is read per command and ``dio`` mode is approximately 5% faster than ``dout``. - -Consult the datasheet for your particular SPI flash chip to determine if it supports either or both of these commands. - -Quad SPI -^^^^^^^^ - -To further improve the performance of SPI flash data transfers, SPI flash manufacturers introduced "Quad SPI" mode. This mode added two additional pins (otherwise used for flash chip ``WP`` and ``HOLD`` signals) for data transfers. This allows double the data rate of dual SPI. - -Not all flash chips support Quad SPI modes, and not all ESP chips have these pins wired up to the SPI flash chip. Some flash chips require special commands to enable quad modes (see below). - -In ``qout`` mode, the host uses the "Quad Output Fast Read" (6BH) command to read data. This command is the same as "Dual Output Fast Read", only data is read on 4 pins instead of 2 with 4 bits per clock cycle. This makes the data transfer exactly twice as fast as "Dual Output Fast Read". - -In ``qio`` mode, the host uses the "Quad I/O Fast Read" (EBH) command to read data. This command is the same as "Dual I/O Fast Read", only both address & data are transferred on 4 pins instead of 2 with 4 bits per clock cycle. -This makes both the address & data transfer exactly twice as fast as "Dual I/O Fast Read". - -Frequently Asked Questions --------------------------- - -Why don't qio & qout modes work with my Espressif chip/module? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is usually one of the following reasons: - -* The WP and HOLD pins of the SPI flash chip are not wired to the correct GPIOs of the Espressif chip. These pins must be connected correctly for quad modes to work, and not all boards/modules connect them at all. -* The SPI flash chip does not support quad modes. Look up the flash chip datasheet to see which modes it supports. You can identify the flash chip visually, or by using the :ref:`esptool.py flash_id ` command. -* Quad mode is not enabled correctly for this chip model. SPI flash is not a standard, so every manufacturer implements their chip differently. Most flash chips require certain commands to be sent in order to enable Quad SPI modes, and these commands vary. - For Espressif chips, this often means that the chip first boots in a Dual SPI mode and then software detects the chip type and tries to enable Quad SPI mode. - If the particular chip model is not supported by the software then it won't be able to enter quad mode. - -Why does qout/dout mode work but qio/dio mode doesn't work? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Some SPI flash chip models only support the "Dual Output Fast Read" and/or "Quad Output Fast Read" commands, not their Dual I/O & Quad I/O equivalents. - -Will my code run half as fast in Dual SPI mode compared to Quad SPI? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -No. Espressif chips execute code directly from flash, however because reading from flash is slow the data is cached transparently in RAM. Flash read commands are only sent went a cache miss occurs. -However, refilling the cache with a Dual SPI read is approximately half as fast as its Quad SPI equivalent. - -If you can't use the Quad SPI modes, make sure you are configuring the fastest SPI Flash clock rate that works reliably on your board/module. An 80MHz SPI clock in Dual I/O mode is faster than a 40MHz SPI clock in Quad I/O mode. - -How is flash mode communicated to the Espressif chip? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The bootloader .bin file, flashed to the SPI flash, contains a header which has flash speed, flash mode, and some other metadata. The initial host mode is determined by ROM code when it reads this header after reset. -Passing the ``--flash_mode`` argument to esptool will update this header when the file is being written to flash. - -This only determines the mode which is used for the initial boot from reset. Software may then configure the flash mode differently as part of the boot process. - -For example, on ESP32 if ESP-IDF is configured for qio/qout mode then the IDF software bootloader is actually flashed with a dio/dout mode. -When ROM code boots this bootloader from flash, the bootloader software checks the flash chip model and enables the correct Quad SPI mode for the rest of the boot process. -This is because of the multiple different ways to enable Quad SPI on different chip models. diff --git a/docs/en/conf.py b/docs/en/conf.py deleted file mode 100644 index 0362dfc3e..000000000 --- a/docs/en/conf.py +++ /dev/null @@ -1,29 +0,0 @@ -# -*- coding: utf-8 -*- -# -# English Language RTD & Sphinx config file -# -# Uses ../conf_common.py for most non-language-specific settings. - -# Importing conf_common adds all the non-language-specific -# parts to this conf module - -import datetime - -try: - from conf_common import * # noqa: F403,F401 -except ImportError: - import os - import sys - - sys.path.insert(0, os.path.abspath("../")) - from conf_common import * # noqa: F403,F401 - -# General information about the project. -project = "esptool.py" -copyright = "2016 - {}, Espressif Systems (Shanghai) Co., Ltd".format( - datetime.datetime.now().year -) - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -language = "en" diff --git a/docs/en/contributing.rst b/docs/en/contributing.rst deleted file mode 100644 index c7fcb94cf..000000000 --- a/docs/en/contributing.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _contribute: - -.. include:: ../../CONTRIBUTING.rst diff --git a/docs/en/espefuse/adc-info-cmd.rst b/docs/en/espefuse/adc-info-cmd.rst deleted file mode 100644 index e7c11f22c..000000000 --- a/docs/en/espefuse/adc-info-cmd.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _adc-info-cmd: - -Adc Info -======== - -The ``espefuse.py adc_info`` command displays information about ADC calibration data stored in eFuse. - -.. only:: esp32 - - .. code-block:: none - - > espefuse.py adc_info - - === Run "adc_info" command === - ADC VRef calibration: 1121mV - -.. only:: esp32c3 or esp32s2 or esp32s3 - - .. code-block:: none - - > espefuse.py adc_info - - === Run "adc_info" command === - Temperature Sensor Calibration = -2.1C - - ADC1 readings stored in efuse BLOCK2: - MODE0 D1 reading (250mV): 76 - MODE0 D2 reading (600mV): 340 - MODE1 D1 reading (250mV): -100 - MODE1 D2 reading (800mV): 356 - MODE2 D1 reading (250mV): 116 - MODE2 D2 reading (1000mV): -136 - MODE3 D1 reading (250mV): 8 - MODE3 D2 reading (2000mV): 304 - - ADC2 readings stored in efuse BLOCK2: - MODE0 D1 reading (250mV): 0 - MODE0 D2 reading (600mV): 168 - MODE1 D1 reading (250mV): 0 - MODE1 D2 reading (800mV): 300 - MODE2 D1 reading (250mV): 0 - MODE2 D2 reading (1000mV): -404 - MODE3 D1 reading (250mV): 0 - MODE3 D2 reading (2000mV): -32 - -.. only:: esp32c2 - - .. code-block:: none - - > espefuse.py adc_info - - === Run "adc_info" command === - RF_REF_I_BIAS_CONFIG: 0 - LDO_VOL_BIAS_CONFIG_LOW: 0 - LDO_VOL_BIAS_CONFIG_HIGH: 0 - PVT_LOW: 0 - PVT_HIGH: 0 - ADC_CALIBRATION_0: 0 - ADC_CALIBRATION_1: 0 - ADC_CALIBRATION_2: 0 diff --git a/docs/en/espefuse/burn-bit-cmd.rst b/docs/en/espefuse/burn-bit-cmd.rst deleted file mode 100644 index 13f22ede6..000000000 --- a/docs/en/espefuse/burn-bit-cmd.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _burn-bit-cmd: - -Burn Bit -======== - -The ``espefuse.py burn_bit`` command burns bits in efuse blocks by bit number. This is useful when the fields are not represented in the eFuse table. - -Positional arguments: - -- ``block`` - Efuse block. -- ``bit number`` - Bit number in the efuse block [0..BLK_LEN-1] (list of numbers, like 10 15 18 17 5 etc.). - -Optional arguments: - -- ``--force-write-always``. Burn it even if it looks like it is already been written, or is write protected. Note that this option can not disable write protection, or clear any bit which has already been set. - -Usage ------ - -Burning bits to BLOCK2: - -.. code-block:: none - - > espefuse.py burn_bit BLOCK2 15 16 17 18 19 20 - - === Run "burn_bit" command === - bit_number: [255]........................................................[0] - BLOCK2 : 0x00000000000000000000000000000000000000000000000000000000001f8000 - BLOCK2 (secure_boot_v1 s) [2 ] regs_to_write: 001f8000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [02] BLOCK2 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK2 - OK (write block == read block) - Reading updated efuses... - Successful - -Burning In Multiple Blocks -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - > espefuse.py --virt burn_bit BLOCK2 15 16 17 18 19 20 \ - burn_bit BLOCK3 15 16 17 18 19 20 - - === Run "burn_bit" command === - bit_number: [255]........................................................[0] - BLOCK2 : 0x00000000000000000000000000000000000000000000000000000000001f8000 - BLOCK2 (secure_boot_v1 s) [2 ] regs_to_write: 001f8000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - Batch mode is enabled, the burn will be done at the end of the command. - - === Run "burn_bit" command === - bit_number: [255]........................................................[0] - BLOCK3 : 0x00000000000000000000000000000000000000000000000000000000001f8000 - BLOCK3 ( ) [3 ] regs_to_write: 001f8000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - Batch mode is enabled, the burn will be done at the end of the command. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [02] BLOCK2 is empty, will burn the new value - [03] BLOCK3 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - BURN BLOCK2 - OK (write block == read block) - Reading updated efuses... diff --git a/docs/en/espefuse/burn-block-data-cmd.rst b/docs/en/espefuse/burn-block-data-cmd.rst deleted file mode 100644 index 333c5db84..000000000 --- a/docs/en/espefuse/burn-block-data-cmd.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _burn-block-data-cmd: - -Burn Block Data -=============== - -The ``espefuse.py burn_block_data`` command allows writing arbitrary data (non-key data) from a file into an eFuse block, for software use. - -This command is available in ``espefuse.py`` v2.6 and newer. - -Positional arguments: - -* ``Name of key block`` -* ``Datafile``. File containing data to burn into the efuse block. The file size can be smaller than the eFuse block size. - -It can be list of blocks and datafiles (like BLOCK1 datafile1.bin BLOCK2 datafile2.bin etc.). - -Optional arguments: - -* ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set. -* ``--offset``. Byte offset in the eFuse block. - -**Example:** Write to eFuse BLOCK3 from binary file ``device_id.bin``, starting at eFuse byte offset 6: - -.. code-block:: none - - > espefuse.py -p PORT burn_block_data --offset 6 BLOCK3 device_id.bin - - === Run "burn_block_data" command === - [03] BLOCK3 size=32 bytes, offset=06 - > [00 00 00 00 00 00 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 00 00 00 00 00 00 00 00 00 00]. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [03] BLOCK3 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - Reading updated efuses... - Successful - -Peculiarities -------------- - -1. Data is written to the eFuse block in normal byte order (treating the eFuse block as if it was an array of bytes). It can be read back in firmware using eFuse API or from the eFuse read registers (but these reads must be always be complete register words, 4-byte aligned). - -.. code-block:: none - - > espefuse.py dump - ... - BLOCK3 ( ) [3 ] read_regs: 00000000 01000000 05040302 09080706 0d0c0b0a 00000f0e 00000000 00000000 - - > espefuse.py summary - .... - BLOCK3 (BLOCK3): Variable Block 3 - = 00 00 00 00 00 00 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 00 00 00 00 00 00 00 00 00 00 R/W - -2. Part of the eFuse block can be written at a time. The ``--offset`` argument allows writing to a byte offset inside the eFuse block itself. -3. This command is not suitable for writing key data which will be used by flash encryption or secure boot hardware, use ``burn_key`` for this. diff --git a/docs/en/espefuse/burn-custom-mac-cmd.rst b/docs/en/espefuse/burn-custom-mac-cmd.rst deleted file mode 100644 index 3ccebfae6..000000000 --- a/docs/en/espefuse/burn-custom-mac-cmd.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. _burn-custom-mac-cmd: - -Burn Custom Mac -=============== - -The ``espefuse.py burn_custom_mac`` command burns a 48-bit Custom MAC Address. - -Positional arguments: - -* ``MAC``. Custom MAC Address (``CUSTOM_MAC``) to burn given in hexadecimal format with bytes separated by colons (e.g. AA:CD:EF:01:02:03) - -Optional arguments: - -* ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set. - -If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already has data then it is not possible to write new data without breaking the encoding. The correct way is to contact Espressif to order chips with ``CUSTOM_MAC`` pre-burned from the factory. Another way is, it is not recommended, to use the ``--force-write-always`` flag to ignore the encoding violation. - -.. only:: esp32 - - This command burns a few eFuse fields: - - 1. ``CUSTOM_MAC`` - 2. ``MAC_VERSION`` = 1 - 3. ``CUSTOM_MAC_CRC`` = crc8(``CUSTOM_MAC``) - - .. code-block:: none - - > espefuse.py burn_custom_mac 48:63:92:15:72:16 - - === Run "burn_custom_mac" command === - - 'MAC_VERSION' (Version of the MAC field) 0x00 -> 0x1 - - 'CUSTOM_MAC' (Custom MAC) 0x000000000000 -> 0x167215926348 - - 'CUSTOM_MAC_CRC' (CRC of custom MAC) 0x00 -> 0x75 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [03] BLOCK3 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - Reading updated efuses... - Custom MAC Address version 1: 48:63:92:15:72:16 (CRC 0x75 OK) - Successful - - > espefuse.py summary - ... - MAC_VERSION (BLOCK3): Version of the MAC field = Custom MAC in BLOCK3 R/W (0x01) - CUSTOM_MAC (BLOCK3): Custom MAC - = 48:63:92:15:72:16 (CRC 0x75 OK) R/W - CUSTOM_MAC_CRC (BLOCK3): CRC of custom MAC = 117 R/W (0x75) - ... - BLOCK3 (BLOCK3): Variable Block 3 - = 75 48 63 92 15 72 16 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 R/W - -.. only:: esp32c2 - - This command burns a few eFuse fields: - - 1. ``CUSTOM_MAC`` - 2. ``CUSTOM_MAC_USED`` = 1 - - .. code-block:: none - - > espefuse.py burn_custom_mac 48:63:92:15:72:16 - - === Run "burn_custom_mac" command === - - 'CUSTOM_MAC' (Custom MAC addr) 0x000000000000 -> 0x167215926348 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is not empty - (written ): 0x0000000000000080 - (to write): 0x0400000000000000 - (coding scheme = NONE) - [01] BLOCK1 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK1 - OK (write block == read block) - BURN BLOCK0 - OK (all write block bits are set) - Reading updated efuses... - Custom MAC Address: 48:63:92:15:72:16 (OK) - Successful - - > espefuse.py summary - ... - CUSTOM_MAC_USED (BLOCK0) Enable CUSTOM_MAC programming = True R/W (0b1) - CUSTOM_MAC (BLOCK1) Custom MAC addr - = 48:63:92:15:72:16 (OK) R/W - -.. only:: esp32c3 or esp32s2 or esp32s3 - - This command burns a given MAC to ``CUSTOM_MAC`` field. - - .. code-block:: none - - > espefuse.py burn_custom_mac 48:63:92:15:72:16 - - === Run "burn_custom_mac" command === - - 'CUSTOM_MAC' (Custom MAC Address) 0x000000000000 -> 0x167215926348 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [03] BLOCK_USR_DATA is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - Reading updated efuses... - Custom MAC Address: 48:63:92:15:72:16 (OK) - Successful - - > espefuse.py summary - ... - CUSTOM_MAC (BLOCK3) Custom MAC Address - = 48:63:92:15:72:16 (OK) R/W \ No newline at end of file diff --git a/docs/en/espefuse/burn-efuse-cmd.rst b/docs/en/espefuse/burn-efuse-cmd.rst deleted file mode 100644 index b5d974316..000000000 --- a/docs/en/espefuse/burn-efuse-cmd.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _burn-efuse-cmd: - -Burn Efuse -========== - -The ``espefuse.py burn_efuse`` command burns eFuses. The arguments to ``burn_efuse`` are eFuse names (as shown in summary output) and new values. - -Positional arguments: - -- ``eFuse name`` -- ``value`` - -It can be list of eFuse names and values (like EFUSE_NAME1 1 EFUSE_NAME2 7 EFUSE_NAME3 10 etc.). - -New values can be a numeric value in decimal or hex (with "0x" prefix). eFuse bits can only be burned from 0 to 1, attempting to set any back to 0 will have no effect. Most eFuses have a limited bit width (many are only 1-bit flags). Longer eFuses (MAC addresses, keys) can be set with this command, but it's better to use a specific command (``burn_custom_mac``, ``burn_key``) for a specific field. - -This command supports simultaneous burning of multiple eFuses, it doesn't matter if they are from different eFuse blocks or not. The format is the same as for burning just one eFuse, just list the eFuse name and value pairs, see the example below. - -.. code-block:: none - - > espefuse.py --port /dev/ttyUSB0 burn_efuse DIS_USB_JTAG 1 VDD_SPI_AS_GPIO 1 - - === Run "burn_efuse" command === - The efuses to burn: - from BLOCK0 - - DIS_USB_JTAG - - VDD_SPI_AS_GPIO - - Burning efuses: - - - 'DIS_USB_JTAG' (Disables USB JTAG. JTAG access via pads is controlled separately) 0b0 -> 0b1 - - 'VDD_SPI_AS_GPIO' (Set this bit to vdd spi pin function as gpio) 0b0 -> 0b1 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - -By default, ``espefuse.py`` will ask you to type ``BURN`` before it permanently sets eFuses. The ``--do-not-confirm`` option allows you to bypass this. - -.. code-block:: none - - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Checking efuses... - Successful - -.. _espefuse-spi-flash-pins: - -SPI Flash Pins --------------- - -The following efuses configure the SPI flash pins which are used to boot: - -.. only:: esp32 - - .. code-block:: none - - SPI_PAD_CONFIG_CLK Override SD_CLK pad (GPIO6/SPICLK) = 0 R/W (0x0) - SPI_PAD_CONFIG_Q Override SD_DATA_0 pad (GPIO7/SPIQ) = 0 R/W (0x0) - SPI_PAD_CONFIG_D Override SD_DATA_1 pad (GPIO8/SPID) = 0 R/W (0x0) - SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0) - SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0) - -.. only:: not esp32 - - .. code-block:: none - - Spi_Pad_Config fuses: - SPI_PAD_CONFIG_CLK (BLOCK1) SPI CLK pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_Q (BLOCK1) SPI Q (D1) pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_D (BLOCK1) SPI D (D0) pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_CS (BLOCK1) SPI CS pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_HD (BLOCK1) SPI HD (D3) pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_WP (BLOCK1) SPI WP (D2) pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_DQS (BLOCK1) SPI DQS pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_D4 (BLOCK1) SPI D4 pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_D5 (BLOCK1) SPI D5 pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_D6 (BLOCK1) SPI D6 pad = 0 R/W (0b000000) - SPI_PAD_CONFIG_D7 (BLOCK1) SPI D7 pad = 0 R/W (0b000000) - -On {IDF_TARGET_NAME} chips without integrated SPI flash, these eFuses are left zero at the factory. This causes the default GPIO pins (shown in the summary output above) to be used for the SPI flash. - -On {IDF_TARGET_NAME} chips with integrated internal SPI flash, these eFuses are burned in the factory to the GPIO numbers where the flash is connected. These values override the defaults on boot. - -In order to change the SPI flash pin configuration, these eFuses can be burned to the GPIO numbers where the flash is connected. If at least one of these eFuses is burned, all of of them must be set to the correct values. - -If these eFuses are burned, GPIO1 (U0TXD pin) is no longer consulted to set the boot mode from SPI to HSPI flash on reset. - -These pins can be set to any GPIO number in the range 0-29, 32 or 33. Values 30 and 31 cannot be set. The "raw" hex value for pins 32, 33 is 30, 31 (this is visible in the summary output if these pins are configured for any SPI I/Os.) - -For example: - -.. code-block:: none - - SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 32 R/W (0x1e) - -If using the ``burn_efuse`` command to configure these pins, always specify the actual GPIO number you wish to set. diff --git a/docs/en/espefuse/burn-key-cmd.rst b/docs/en/espefuse/burn-key-cmd.rst deleted file mode 100644 index ebaa8ebd6..000000000 --- a/docs/en/espefuse/burn-key-cmd.rst +++ /dev/null @@ -1,345 +0,0 @@ -.. _burn-key-cmd: - -Burn Key -======== - -The ``espefuse.py burn_key`` command burns keys to eFuse blocks: - -.. list:: - - :esp32: - `Secure Boot V1 `_ - - `Secure Boot V2 `_ - - `Flash Encryption `_ - - etc. - -Positional arguments: - -.. list:: - - - ``block`` - Name of key block. - :esp32: - ``Keyfile``. It is a raw binary file. It must contain 256 bits of binary key if the coding scheme is ``None`` and 128 bits if ``3/4``. - :not esp32 and not esp32h2: - ``Keyfile``. It is a raw binary file. The length of binary key depends on the key purpose option. - :esp32h2: - ``Keyfile``. It is a raw binary file. The length of binary key depends on the key purpose option. For the ``ECDSA_KEY`` purpose use ``PEM`` file. - :not esp32: - ``Key purpose``. The purpose of this key. - -.. only:: esp32 - - It can be list of key blocks and keyfiles (like BLOCK1 file1.bin BLOCK2 file2.bin etc.). - -.. only:: not esp32 - - It can be list of key blocks and keyfiles and key purposes (like BLOCK_KEY1 file1.bin USER BLOCK_KEY2 file2.bin USER etc.). - -Optional arguments: - -.. list:: - - :esp32: - ``--no-protect-key``. Disable default read and write protecting of the key. If this option is not set, once the key is flashed it can not be read back. - :not esp32: - ``--no-write-protect``. Disable write-protecting of the key. The key remains writable. The keys use the RS coding scheme that does not support post-write data changes. Forced write can damage RS encoding bits. The write-protecting of keypurposes does not depend on the option, it will be set anyway. - :not esp32: - ``--no-read-protect``. Disable read-protecting of the key. The key remains readable software. The key with keypurpose [USER, RESERVED and .._DIGEST] will remain readable anyway, but for the rest keypurposes the read-protection will be defined by this option (Read-protect by default). - - ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set. - - ``--show-sensitive-info``. Show data to be burned (may expose sensitive data). Enabled if --debug is used. Use this option to see the byte order of the data being written. - -.. only:: esp32 - - {IDF_TARGET_NAME} supportes keys: - - * Secure boot key. Use ``secure_boot_v1`` or ``secure_boot_v2`` as block name. The key is placed in BLOCK2. - * Flash encryption key. Use ``flash_encryption`` as block name. The key is placed in BLOCK1. - - Keys for ``flash_encryption`` and ``secure_boot_v1`` will be burned as read and write protected. The hardware will still have access to them. These keys are burned in reversed byte order. - - Key for ``secure_boot_v2`` will be burned only as write protected. The key must be readable because the software need acces to it. - - .. warning:: - - Do not use the names ``BLOCK1`` and ``BLOCK2`` to burn flash encryption and secure boot v2 keys because byte order will be incorrect and read protection will not meet security requirements. - -.. only:: not esp32 and not esp32c2 - - {IDF_TARGET_NAME} supportes eFuse key purposes. This means that each eFuse block has a special eFuse field that indicates which key is in the eFuse block. During the burn operation this eFuse key purpose is burned as well with write protection (the ``--no-write-protect`` flag has no effect on this field). The {IDF_TARGET_NAME} chip supports the following key purposes: - - .. list:: - - - USER. - - RESERVED. - :esp32s2 or esp32s3: - XTS_AES_256_KEY_1. The first 256 bits of 512bit flash encryption key. - :esp32s2 or esp32s3: - XTS_AES_256_KEY_2. The second 256 bits of 512bit flash encryption key. - :esp32h2: - ECDSA_KEY. It can be ECDSA private keys based on NIST192p or NIST256p curve. The private key is extracted from the given file and written into a eFuse block with write and read protection enabled. This private key shall be used by ECDSA accelerator for the signing purpose. - - XTS_AES_128_KEY. 256 bit flash encryption key. - - HMAC_DOWN_ALL. - - HMAC_DOWN_JTAG. - - HMAC_DOWN_DIGITAL_SIGNATURE. - - HMAC_UP. - - SECURE_BOOT_DIGEST0. 1 secure boot key. - - SECURE_BOOT_DIGEST1. 2 secure boot key. - - SECURE_BOOT_DIGEST2. 3 secure boot key. - :esp32s2 or esp32s3: - XTS_AES_256_KEY. This is a virtual key purpose for flash encryption key. This allows you to write a whole 512-bit key into two blocks with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` purposes without splitting the key file. - -.. only:: esp32h2 - - {IDF_TARGET_NAME} has the ECDSA accelerator for signature purposes and supports private keys based on the NIST192p or NIST256p curve. These two commands below can be used to generate such keys (``PEM`` file). The ``burn_key`` command with the ``ECDSA_KEY`` purpose takes the ``PEM`` file and writes the private key into a eFuse block. The key is written to the block in reverse byte order. - - For NIST192p, the private key is 192 bits long, so 8 padding bytes ("0x00") are added. - - .. code-block:: none - - > espsecure.py generate_signing_key -v 2 -s ecdsa192 ecdsa192.pem - ECDSA NIST192p private key in PEM format written to ecdsa192.pem - - .. code-block:: none - - > espsecure.py generate_signing_key -v 2 -s ecdsa256 ecdsa256.pem - ECDSA NIST256p private key in PEM format written to ecdsa256.pem - -.. only:: esp32c2 - - {IDF_TARGET_NAME} has only one eFuse key block (256 bits long). It is block #3 - ``BLOCK_KEY0``. This block can have user, flash encryption, secure boot keys. This chip does not have any eFuse key purpose fields, but we use the key purpose option to distinguish between such keys. The key purpose option determines protection and byte order for key. - - .. list:: - - - USER - - XTS_AES_128_KEY. 256 bits flash encryption key. The secure boot key can not be used with this option. In addition, eFuse ``XTS_KEY_LENGTH_256`` is set to 1, which means that the flash encryption key is 256 bits long. - - XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS. 128 bits flash encryption key. The 128 bits of this key will be burned to the low part of the eFuse block. These bits will be read protected. - - SECURE_BOOT_DIGEST. Secure boot key. The first 128 bits of key will be burned to the high part of the eFuse block. - - {IDF_TARGET_NAME} can have in eFuse block the following combination of keys: - - 1. Both, Flash encryption (low 128 bits of eFuse block) and Secure boot key (high 128 bits of eFuse block). - 2. only Flash encryption (low 128 bits of eFuse block), rest part of eFuse block is not possible to use in future. - 3. only Flash encryption key (256 bits long), whole eFuse key block. - 4. only Secure boot key (high 128 bits of eFuse block). - 5. no keys, used for user purposes. Chip does not have security features. - -.. only:: not esp32 - - All keys will be burned with write protection if ``--no-write-protect`` is not used. - - Only flash encryption key is read protected if ``--no-read-protect`` is not used. - - All keys, except flash encryption, will be burned in direct byte order. The encryption key is written in reverse byte order for compatibility with encryption hardware. - -.. only:: esp32 - - Key Coding Scheme - ^^^^^^^^^^^^^^^^^ - - When the ``None`` coding scheme is in use, keys are 256-bits (32 bytes) long. When 3/4 Coding Scheme is in use (``CODING_SCHEME`` eFuse has value 1 not 0), keys are 192-bits (24 bytes) long and an additional 64 bits of error correction data are also written. - espefuse v2.6 or newer supports the 3/4 Coding Scheme. The key file must be the appropriate length for the coding scheme currently in use. - -Unprotected Keys -^^^^^^^^^^^^^^^^ - -By default, when an encryption key block is burned it is also read and write protected. - -.. only:: esp32 - - The ``--no-protect-key`` option will disable this behaviour (you can separately read or write protect the key later). - -.. only:: not esp32 - - The ``--no-read-protect`` and ``--no-write-protect`` options will disable this behaviour (you can separately read or write protect the key later). - -.. note:: - - Leaving a key unprotected may compromise its use as a security feature. - -.. code-block:: none - - espefuse.py burn_key secure_boot_v1 secure_boot_key_v1.bin - -.. only:: esp32 - - Note that the hardware flash encryption and secure boot v1 features require the key to be written to the eFuse block in reversed byte order, compared to the order used by the AES algorithm on the host. Using corresponding block name, the tool automatically reverses the bytes when writing. For this reason, an unprotected key will read back in the reverse order. - -Force Writing a Key -^^^^^^^^^^^^^^^^^^^ - -Normally, a key will only be burned if the efuse block has not been previously written to. The ``--force-write-always`` option can be used to ignore this and try to burn the key anyhow. - -Note that this option is still limited by the eFuse hardware - hardware does not allow any eFuse bits to be cleared 1->0, and can not write anything to write protected eFuse blocks. - -Usage ------ - -.. only:: esp32 - - .. code-block:: none - - > espefuse.py burn_key flash_encryption 256bit_fe_key.bin - - === Run "burn_key" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK1 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Reversing the byte order - Disabling read to key block - Disabling write to key block - - Burn keys in efuse blocks. - The key block will be read and write protected - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [01] BLOCK1 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK1 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - .. code-block:: none - - > espefuse.py summary - ... - BLOCK1 (BLOCK1): Flash encryption key - = ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/- - - Byte order for flash encryption key is reversed. Content of flash encryption key file ("256bit_fe_key.bin"): - - .. code-block:: none - - 0001 0203 0405 0607 0809 0a0b 0c0d 0e0f 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f - - When the ``no protection`` option is used then you can see the burned key: - - .. code-block:: none - - > espefuse.py burn_key flash_encryption 256bit_fe_key.bin --no-protect-key - - === Run "burn_key" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK1 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Reversing the byte order - - Key is left unprotected as per --no-protect-key argument. - Burn keys in efuse blocks. - The key block will left readable and writeable (due to --no-protect-key) - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [01] BLOCK1 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK1 - OK (write block == read block) - Reading updated efuses... - Successful - - .. code-block:: none - - > espefuse.py summary - ... - BLOCK1 (BLOCK1): Flash encryption key - = 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 R/W - -.. only:: esp32s2 or esp32s3 - - Burning XTS_AES_256_KEY: - - The first 256 bit of the key goes to given BLOCK (here it is ``BLOCK_KEY0``) with key purpose = ``XTS_AES_256_KEY_1``. The last 256 bit of the key will be burned to the first free key block after BLOCK (here it is ``BLOCK_KEY1``) and set key purpose to ``XTS_AES_256_KEY_2`` for this block. - - This example uses ``--no-read-protect`` to expose the byte order written into eFuse blocks. - - Content of flash encryption key file (``512bits_0.bin``): - - .. code-block:: none - - 0001 0203 0405 0607 0809 0a0b 0c0d 0e0f 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f - 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f 3031 3233 3435 3637 3839 3a3b 3c3d 3e3f - - .. code-block:: none - - > espefuse.py burn_key BLOCK_KEY0 ~/esp/tests/efuse/512bits_0.bin XTS_AES_256_KEY --no-read-protect - - === Run "burn_key" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK_KEY0 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Reversing byte order for AES-XTS hardware peripheral - 'KEY_PURPOSE_0': 'USER' -> 'XTS_AES_256_KEY_1'. - Disabling write to 'KEY_PURPOSE_0'. - Disabling write to key block - - - BLOCK_KEY1 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Reversing byte order for AES-XTS hardware peripheral - 'KEY_PURPOSE_1': 'USER' -> 'XTS_AES_256_KEY_2'. - Disabling write to 'KEY_PURPOSE_1'. - Disabling write to key block - - Keys will remain readable (due to --no-read-protect) - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [04] BLOCK_KEY0 is empty, will burn the new value - [05] BLOCK_KEY1 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK5 - OK (write block == read block) - BURN BLOCK4 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - > espefuse.py summary - ... - KEY_PURPOSE_0 (BLOCK0) KEY0 purpose = XTS_AES_256_KEY_1 R/- (0x2) - KEY_PURPOSE_1 (BLOCK0) KEY1 purpose = XTS_AES_256_KEY_2 R/- (0x3) - ... - BLOCK_KEY0 (BLOCK4) - Purpose: XTS_AES_256_KEY_1 - Encryption key0 or user data - = 1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10 0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00 R/- - BLOCK_KEY1 (BLOCK5) - Purpose: XTS_AES_256_KEY_2 - Encryption key1 or user data - = 3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30 2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20 R/- - -.. only:: esp32c2 - - .. code-block:: none - - > espefuse.py -c esp32c2 \ - burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \ - burn_key BLOCK_KEY0 images/efuse/128bit_key.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS - - === Run "burn_key_digest" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK_KEY0_HI_128 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Disabling write to key block - - - Batch mode is enabled, the burn will be done at the end of the command. - - === Run "burn_key" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK_KEY0_LOW_128 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Reversing byte order for AES-XTS hardware peripheral - Disabling read to key block - Disabling write to key block - The same value for WR_DIS is already burned. Do not change the efuse. - - Batch mode is enabled, the burn will be done at the end of the command. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [03] BLOCK_KEY0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... diff --git a/docs/en/espefuse/burn-key-digest-cmd.rst b/docs/en/espefuse/burn-key-digest-cmd.rst deleted file mode 100644 index 1a6e50971..000000000 --- a/docs/en/espefuse/burn-key-digest-cmd.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _burn-key-digest-cmd: - -Burn key Digest -=============== - -The ``espefuse.py burn_key_digest`` command parses a RSA public key and burns the digest to eFuse block for use with `Secure Boot V2 `_. - -Positional arguments: - -.. list:: - - :not esp32 and not esp32c2: - ``block`` - Name of key block. - - ``Keyfile``. Key file to digest (PEM format). - :not esp32 and not esp32c2: - ``Key purpose``. The purpose of this key [``SECURE_BOOT_DIGEST0``, ``SECURE_BOOT_DIGEST1``, ``SECURE_BOOT_DIGEST2``]. - -.. only:: not esp32 and not esp32c2 - - It can be list of blocks and keyfiles and key purposes (like BLOCK_KEY0 keyfile0.pem SECURE_BOOT_DIGEST0 BLOCK_KEY1 keyfile1.pem SECURE_BOOT_DIGEST1 etc.). - -Optional arguments: - -.. list:: - - :esp32: - ``--no-protect-key``. Disable default read and write protecting of the key. - :not esp32: - ``--no-write-protect``. Disable write-protecting of the key. The key remains writable. The keys use the RS coding scheme that does not support post-write data changes. Forced write can damage RS encoding bits. The write-protecting of keypurposes does not depend on the option, it will be set anyway. - :not esp32: - ``--no-read-protect``. Disable read-protecting of the key. This option does not change anything, because Secure Boot keys are readable anyway. - - ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set. - - ``--show-sensitive-info``. Show data to be burned (may expose sensitive data). Enabled if --debug is used. Use this option to see the byte order of the data being written. - -.. only:: esp32 - - {IDF_TARGET_NAME} must have chip version > 3 (v300) and coding scheme = ``None`` otherwise an error will be shown. The key will be burned to BLOCK2. - -.. only:: esp32c2 - - The key will be burned to BLOCK3. - -The secure boot v2 key(s) will be readable and write protected. - -Usage ------ - -.. only:: esp32 - - .. code-block:: none - - > espefuse.py burn_key_digest secure_boot_key_v2_0.pem - - === Run "burn_key_digest" command === - Sensitive data will be hidden (see --show-sensitive-info) - - BLOCK2 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Disabling write to efuse BLOCK2... - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [02] BLOCK2 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK2 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - > espefuse.py summary - ... - BLOCK2 (BLOCK2): Secure boot key - = a2 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- - -.. only:: esp32c2 - - See :ref:`perform-multiple-operations` for how to burn flash encryption and secure boot keys to the same eFuse key block at the same time. - - .. code-block:: none - - > espefuse.py burn_key_digest secure_boot_v2_ecdsa192.pem - - === Run "burn_key_digest" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK_KEY0_HI_128 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - Disabling write to key block - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [03] BLOCK_KEY0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK3 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - > espefuse.py summary - ... - XTS_KEY_LENGTH_256 (BLOCK0) Flash encryption key length = 128 bits key R/W (0b0) - ... - BLOCK_KEY0 (BLOCK3) BLOCK_KEY0 - 256-bits. 256-bit key of Flash Encryp - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f R/- - tion - BLOCK_KEY0_LOW_128 (BLOCK3) BLOCK_KEY0 - lower 128-bits. 128-bit key of Flash - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/- - Encryption - BLOCK_KEY0_HI_128 (BLOCK3) BLOCK_KEY0 - higher 128-bits. 128-bits key of Secu - = 02 c2 bd 9c 1a b4 b7 44 22 59 c6 d3 12 0b 79 1f R/- - re Boot. - -.. only:: esp32c3 or esp32s2 or esp32s3 - - .. code-block:: none - - > espefuse.py burn_key_digest \ - BLOCK_KEY0 ~/esp/tests/efuse/secure_boot_key_v2_0.pem SECURE_BOOT_DIGEST0 \ - BLOCK_KEY1 ~/esp/tests/efuse/secure_boot_key_v2_1.pem SECURE_BOOT_DIGEST1 \ - BLOCK_KEY2 ~/esp/tests/efuse/secure_boot_key_v2_2.pem SECURE_BOOT_DIGEST2 - - === Run "burn_key_digest" command === - Sensitive data will be hidden (see --show-sensitive-info) - Burn keys to blocks: - - BLOCK_KEY0 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - 'KEY_PURPOSE_0': 'USER' -> 'SECURE_BOOT_DIGEST0'. - Disabling write to 'KEY_PURPOSE_0'. - Disabling write to key block - - - BLOCK_KEY1 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - 'KEY_PURPOSE_1': 'USER' -> 'SECURE_BOOT_DIGEST1'. - Disabling write to 'KEY_PURPOSE_1'. - Disabling write to key block - - - BLOCK_KEY2 -> [?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??] - 'KEY_PURPOSE_2': 'USER' -> 'SECURE_BOOT_DIGEST2'. - Disabling write to 'KEY_PURPOSE_2'. - Disabling write to key block - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - [04] BLOCK_KEY0 is empty, will burn the new value - [05] BLOCK_KEY1 is empty, will burn the new value - [06] BLOCK_KEY2 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK6 - OK (write block == read block) - BURN BLOCK5 - OK (write block == read block) - BURN BLOCK4 - OK (write block == read block) - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - > espefuse.py summary - - KEY_PURPOSE_0 (BLOCK0) KEY0 purpose = SECURE_BOOT_DIGEST0 R/- (0x9) - KEY_PURPOSE_1 (BLOCK0) KEY1 purpose = SECURE_BOOT_DIGEST1 R/- (0xa) - KEY_PURPOSE_2 (BLOCK0) KEY2 purpose = SECURE_BOOT_DIGEST2 R/- (0xb) - ... - BLOCK_KEY0 (BLOCK4) - Purpose: SECURE_BOOT_DIGEST0 - Encryption key0 or user data - = a2 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- - BLOCK_KEY1 (BLOCK5) - Purpose: SECURE_BOOT_DIGEST1 - Encryption key1 or user data - = a3 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- - BLOCK_KEY2 (BLOCK6) - Purpose: SECURE_BOOT_DIGEST2 - Encryption key2 or user data - = a4 cd 39 85 df 00 d7 95 07 0f f6 7c 8b ab e1 7d 39 11 95 c4 5b 37 6e 7b f0 ec 04 5e 36 30 02 5d R/- diff --git a/docs/en/espefuse/check-error-cmd.rst b/docs/en/espefuse/check-error-cmd.rst deleted file mode 100644 index 8d3a56003..000000000 --- a/docs/en/espefuse/check-error-cmd.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _check-error-cmd: - -Check Error -=========== - -The ``espefuse.py check_error`` command checks eFuse errors. It triggers several reads to force the eFuse controller to reload eFuses and update status registers. This command can be run after burn operations to make sure that there is not errors. - -Optional argument: - -* ``--recovery``. It repairs encoding errors in eFuse blocks, if possible. - -The summary log below shows an error in BLOCK0. - -.. code-block:: none - - > espefuse.py summary - ... - WDT_DELAY_SEL (BLOCK0)[FAIL:1] Selects RTC WDT timeout threshold at startup = False R/W (0b0) - ... - Error(s) in BLOCK0 [ERRORS:1 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000400 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00000000 - EFUSE_RD_RS_ERR1_REG 0x00000000 - WARNING: Coding scheme has encoding bit error warnings - -Usage ------ - -Checks the status registers of eFuse blocks and throws an error if there is an error. - -.. code-block:: none - - > espefuse.py check_error - - Error(s) in BLOCK1 [ERRORS:0 FAIL:1] - Error(s) in BLOCK2 [ERRORS:1 FAIL:1] - Error(s) in BLOCK3 [ERRORS:1 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00008990 - EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "check_error" command === - Error(s) in BLOCK1 [ERRORS:0 FAIL:1] - Error(s) in BLOCK2 [ERRORS:1 FAIL:1] - Error(s) in BLOCK3 [ERRORS:1 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00008990 - EFUSE_RD_RS_ERR1_REG 0x00000000 - - A fatal error occurred: Error(s) were detected in eFuses - -Repairs encoding errors in eFuse blocks, if possible. - -.. code-block:: none - - > espefuse.py check_error --recovery - - Error(s) in BLOCK1 [ERRORS:0 FAIL:1] - Error(s) in BLOCK2 [ERRORS:1 FAIL:1] - Error(s) in BLOCK3 [ERRORS:1 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00008990 - EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "check_error" command === - Error(s) in BLOCK1 [ERRORS:0 FAIL:1] - Error(s) in BLOCK2 [ERRORS:1 FAIL:1] - Error(s) in BLOCK3 [ERRORS:1 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00008990 - EFUSE_RD_RS_ERR1_REG 0x00000000 - Recovery of block coding errors. - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - Error in BLOCK3, re-burn it again (#0), to fix it. fail_bit=1, num_errors=0 - Error in BLOCK3, re-burn it again (#1), to fix it. fail_bit=1, num_errors=0 - Error in BLOCK3, re-burn it again (#2), to fix it. fail_bit=1, num_errors=0 - BURN BLOCK3 - OK (write block == read block) - Error in BLOCK2, re-burn it again (#0), to fix it. fail_bit=1, num_errors=1 - Error in BLOCK2, re-burn it again (#1), to fix it. fail_bit=1, num_errors=1 - Error in BLOCK2, re-burn it again (#2), to fix it. fail_bit=1, num_errors=1 - BURN BLOCK2 - OK (write block == read block) - Error in BLOCK1, re-burn it again (#0), to fix it. fail_bit=1, num_errors=0 - Error in BLOCK1, re-burn it again (#1), to fix it. fail_bit=1, num_errors=0 - Error in BLOCK1, re-burn it again (#2), to fix it. fail_bit=1, num_errors=0 - BURN BLOCK1 - OK (write block == read block) - Error(s) in BLOCK1 [ERRORS:0 FAIL:1] - Error(s) in BLOCK2 [ERRORS:1 FAIL:1] - Error(s) in BLOCK3 [ERRORS:0 FAIL:1] - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00008890 - EFUSE_RD_RS_ERR1_REG 0x00000000 - - A fatal error occurred: Error(s) were detected in eFuses - -If all errors are fixed, then this message is displayed: - -.. code-block:: none - - No errors detected diff --git a/docs/en/espefuse/dump-cmd.rst b/docs/en/espefuse/dump-cmd.rst deleted file mode 100644 index a1a09a277..000000000 --- a/docs/en/espefuse/dump-cmd.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _dump-cmd: - -Dump -==== - -The ``espefuse.py dump`` command allows: - -- display raw values of eFuse registers, grouped by block. Output corresponds directly to eFuse register values in the `register space `__. -- save dump into files. - -Optional arguments: - -- ``--file_name`` - Saves dump for each block into separate file. Provide the common path name like /path/blk.bin, it will create: blk0.bin, blk1.bin ... blkN.bin. Then using ``burn_block_data`` command these dump files can be written to another chip. - -Raw Values Of Efuse Registers ------------------------------ - -The number of blocks depends on the chips and can vary from 4 to 11. A block can have different names, which can be used with ``burn_key`` or ``burn_block_data``. - -The order of registers in the dump: - -.. code-block:: none - - REG_0 REG_1 REG_2 REG_3 REG_4 REG_5 - BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 - -.. only:: esp32 - - .. code-block:: none - - > espefuse.py dump - - Detecting chip type... Unsupported detection protocol, switching and trying again... - Connecting.... - Detecting chip type... ESP32 - BLOCK0 ( ) [0 ] read_regs: 00000000 7e5a6e58 00e294b9 0000a200 00000333 00100000 00000004 - BLOCK1 (flash_encryption) [1 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK2 (secure_boot_v1 s) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK3 ( ) [3 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - EFUSE_REG_DEC_STATUS 0x00000000 - -.. only:: esp32c2 - - .. code-block:: none - - > espefuse.py dump - - Connecting......... - Detecting chip type... ESP32-C2 - BLOCK0 (BLOCK0 ) [0 ] read_regs: 00000000 00000000 - BLOCK1 (BLOCK1 ) [1 ] read_regs: 11efcdab 00000000 00000000 - BLOCK2 (BLOCK2 ) [2 ] read_regs: 558000a4 000094b5 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY0 (BLOCK3 ) [3 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - BLOCK0 (BLOCK0 ) [0 ] err__regs: 00000000 00000000 - EFUSE_RD_RS_ERR_REG 0x00000000 - -.. only:: not esp32 and not esp32c2 - - .. code-block:: none - - > espefuse.py dump - - Connecting.... - Detecting chip type... ESP32-C3 - BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 - MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_USR_DATA (BLOCK3 ) [3 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY0 (BLOCK4 ) [4 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY1 (BLOCK5 ) [5 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY2 (BLOCK6 ) [6 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY3 (BLOCK7 ) [7 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY4 (BLOCK8 ) [8 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_KEY5 (BLOCK9 ) [9 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - BLOCK_SYS_DATA2 (BLOCK10 ) [10] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 - - BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 - EFUSE_RD_RS_ERR0_REG 0x00000000 - EFUSE_RD_RS_ERR1_REG 0x00000000 - -In the last lines, which are separated from the main dump, you can see the encoding scheme status for each block. If there are all zeros, then there are no coding scheme errors. - -Save Dump To Files ------------------- - -This command saves dump for each block into a separate file. You need to provide the common path name ``/chip1/blk.bin``, it will create files in the given directory (the directory must exist): /chip1/blk0.bin, /chip1/blk1.bin - /chip1/blkN.bin. Use ``burn_block_data`` command to write them back to another chip. Note that some blocks may be read-protected, in which case the data in the block will be zero. - -.. code-block:: none - - > espefuse.py dump --file_name backup/chip1/blk.bin - - === Run "dump" command === - backup/chip1/blk0.bin - backup/chip1/blk1.bin - backup/chip1/blk2.bin - backup/chip1/blk3.bin - backup/chip1/blk4.bin - backup/chip1/blk5.bin - backup/chip1/blk6.bin - backup/chip1/blk7.bin - backup/chip1/blk8.bin - backup/chip1/blk9.bin - backup/chip1/blk10.bin - -These dump files can be written to another chip: - -.. code-block:: none - - > espefuse.py burn_block_data BLOCK0 backup/chip1/blk0.bin \ - BLOCK1 backup/chip1/blk1.bin \ - BLOCK2 backup/chip1/blk2.bin - \ No newline at end of file diff --git a/docs/en/espefuse/execute-scripts-cmd.rst b/docs/en/espefuse/execute-scripts-cmd.rst deleted file mode 100644 index 81319a354..000000000 --- a/docs/en/espefuse/execute-scripts-cmd.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. _execute-scripts-cmd: - -Execute Scripts -=============== - -The ``espefuse.py execute_scripts`` command executes scripts to burn at one time. - -Positional arguments: - -- ``scripts`` - it is special format of python scripts (receives list of files, like script1.py script2.py etc.). - -Optional arguments: - -- ``--index`` - integer index. It allows to retrieve unique data per chip from configfiles and then burn them (ex. CUSTOM_MAC, UNIQUE_ID). -- ``--configfiles`` - List of configfiles with data (receives list of configfiles, like configfile1.py configfile2.py etc.). - -.. code-block:: none - - > espefuse.py execute_scripts efuse_script1.py efuse_script2.py ... - -This command allows burning all needed efuses at one time based on your own python script and control issues during the burn process if so it will abort the burn process. This command has a few arguments: - -* ``scripts`` is a list of scripts. The special format of python scripts can be executed inside ``espefuse.py``. -* ``--index`` integer index (it means the number of chip in the batch in the range 1 - the max number of chips in the batch). It allows to retrieve unique data per chip from configfiles and then burn them (ex. CUSTOM_MAC, UNIQUE_ID). -* ``--configfiles`` List of configfiles with data. - -Below you can see some examples of the script. This script file is run from ``espefuse.py`` as ``exec(open(file.name).read())`` it means that some functions and imported libs are available for using like ``os``. Please use only provided functions. -If you want to use other libs in the script you can add them manually. - -Inside this script, you can call all commands which are available in CLI, see ``espefuse.py --help``. To run a efuse command you need to call ``espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_DECRYPT 1')``. This command will not burn eFuses immediately, the burn occurs at the end of all scripts. -If necessary, you can call ``efuses.burn_all()`` which prompts ``Type 'BURN' (all capitals) to continue.``. To skip this check and go without confirmation just add the ``--do-not-confirm`` flag to the ``execute_scripts`` command. - -This command supports nesting. This means that one script can be called from another script (see the test case ``test_execute_scripts_nesting`` in ``esptool/test/test_espefuse.py``). - -.. code-block:: none - - > espefuse.py execute_scripts efuse_script1.py --do-not-confirm - -Additionally, you can implement some checks based on the value of efuses. To get value of an efuse use ``efuses['FLASH_CRYPT_CNT'].get()``. Some eFuses have a dictionary to convert from a value to a human-readable as it looks in the table is printed by the ``summary`` command. -See how it is done (for ESP32) for ``CODING_SCHEME`` when ``get_meaning()`` is called: - -* 0: ``NONE (BLK1-3 len=256 bits)`` -* 1: ``3/4 (BLK1-3 len=192 bits)`` -* 2: ``REPEAT (BLK1-3 len=128 bits) not supported`` -* 3: ``NONE (BLK1-3 len=256 bits)`` - -.. code:: python - - print("connected chip: %s, coding scheme %s" % (esp.get_chip_description(), efuses["CODING_SCHEME"].get_meaning())) - if os.path.exists("flash_encryption_key.bin"): - espefuse(esp, efuses, args, "burn_key flash_encryption flash_encryption_key.bin") - else: - raise esptool.FatalError("The 'flash_encryption_key.bin' file is missing in the project directory") - - espefuse(esp, efuses, args, 'burn_efuse FLASH_CRYPT_CNT 0x7') - - current_flash_crypt_cnt = efuses['FLASH_CRYPT_CNT'].get() - if current_flash_crypt_cnt in [0, 3]: - espefuse(esp, efuses, args, 'burn_efuse FLASH_CRYPT_CNT') - - espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_ENCRYPT 1') - - espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_DECRYPT 1') - - espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_CACHE 1') - - espefuse(esp, efuses, args, 'burn_efuse JTAG_DISABLE 1') - ... - -After ``efuses.burn_all()``, all needed efuses will be burnt to chip in order ``BLK_MAX`` to ``BLK_0``. This order prevents cases when protection is set before the value goes to a block. Please note this while developing your scripts. -Upon completion, the new eFuses will be read back, and will be done some checks of written eFuses by ``espefuse.py``. In production, you might need to check that all written efuses are set properly, see the example below. - -The script `execute_efuse_script.py `__ burns some efuses and checks them after reading back. To check read and write protection, ``is_readable()`` and ``is_writeable()`` are called. - -Burn Unique Data Per Chip -^^^^^^^^^^^^^^^^^^^^^^^^^ - -In case you are running the ``execute_scripts`` command from your production script, you may need to pass ``index`` to get the unique data for each chip from the ``configfiles`` (* .txt, * .json, etc.). The espefuse command will be like this, where ``{index}`` means the number of chip in the batch, you increment it by your own script in the range 1 - the max number of chips in the batch: - -.. code-block:: none - - espefuse.py execute_scripts efuse_script2.py --do-not-confirm --index {index} --configfiles mac_addresses.json unique_id.json - -The example of a script to burn custom_mac address and unique_id getting them from configfiles. - -.. code:: python - - # efuse_script2.py - - mac_addresses = json.load(args.configfiles[0]) - unique_id = json.load(args.configfiles[1]) - - mac_val = mac_addresses[str(args.index)] - cmd = 'burn_custom_mac {}'.format(mac_val) - print(cmd) - espefuse(esp, efuses, args, cmd) - - unique_id_val = unique_id[str(args.index)] - cmd = 'burn_efuse UNIQUE_ID {}'.format(unique_id_val) - print(cmd) - espefuse(esp, efuses, args, cmd) - -The example of a script to burn custom_mac address that generated right in the script. - -.. code:: python - - # efuse_script2.py - - step = 4 - base_mac = '0xAABBCCDD0000' - mac = '' - for index in range(100): - mac = "{:012X}".format(int(base_mac, 16) + (args.index - 1) * step) - mac = ':'.join(mac[k] + mac [k + 1] for k in range(0, len(mac), 2)) - break - - cmd = 'burn_custom_mac mac' - print(cmd) - espefuse(esp, efuses, args, cmd) diff --git a/docs/en/espefuse/get-custom-mac-cmd.rst b/docs/en/espefuse/get-custom-mac-cmd.rst deleted file mode 100644 index 3077e991e..000000000 --- a/docs/en/espefuse/get-custom-mac-cmd.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _get-custom-mac-cmd: - -Get Custom Mac -============== - -The ``espefuse.py burn_custom_mac`` command prints the Custom MAC Address (``CUSTOM_MAC``). - -The chips also have a factory MAC address (eFuse name ``MAC``), which is written at the factory. It can not be changed with this tool. - -.. only:: esp32 - - .. code-block:: none - - > espefuse.py get_custom_mac - - === Run "get_custom_mac" command === - Custom MAC Address version 1: 48:63:92:15:72:16 (CRC 0x75 OK) - - If the custom MAC address is not burned, then you will see the message "Custom MAC Address is not set in the device". And in the summary, those eFuses associated with custom MAC addresses will not show up. - -.. only:: not esp32 - - .. code-block:: none - - > espefuse.py get_custom_mac - - === Run "get_custom_mac" command === - Custom MAC Address: 48:63:92:15:72:16 (OK) - - If the custom MAC address is not burned, then you will see the message "Custom MAC Address: 00:00:00:00:00:00 (OK)". diff --git a/docs/en/espefuse/inc/summary_ESP32-C2.rst b/docs/en/espefuse/inc/summary_ESP32-C2.rst deleted file mode 100644 index 0c29a2556..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-C2.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting................... - Detecting chip type... ESP32-C2 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00) - RD_DIS (BLOCK0) Disable reading from BlOCK3 = 0 R/W (0b00) - UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) - DIS_DIRECT_BOOT (BLOCK0) This bit set means disable direct_boot mode = False R/W (0b0) - - Flash fuses: - FORCE_SEND_RESUME (BLOCK0) Set this bit to force ROM code to send a resume co = False R/W (0b0) - mmand during SPI boot - FLASH_TPUW (BLOCK0) Configures flash waiting time after power-up; in u = 0 R/W (0x0) - nit of ms. If the value is less than 15; the waiti - ng time is the configurable value. Otherwise; the - waiting time is twice the configurable value - - Identity fuses: - DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) - DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) - WAFER_VERSION_MINOR (BLOCK2) WAFER_VERSION_MINOR = 0 R/W (0x0) - WAFER_VERSION_MAJOR (BLOCK2) WAFER_VERSION_MAJOR = 1 R/W (0b01) - PKG_VERSION (BLOCK2) EFUSE_PKG_VERSION = 1 R/W (0b001) - BLK_VERSION_MINOR (BLOCK2) Minor version of BLOCK2 = No calib R/W (0b000) - BLK_VERSION_MAJOR (BLOCK2) Major version of BLOCK2 = 0 R/W (0b00) - - Jtag fuses: - DIS_PAD_JTAG (BLOCK0) Set this bit to disable pad jtag = False R/W (0b0) - - Mac fuses: - CUSTOM_MAC_USED (BLOCK0) True if MAC_CUSTOM is burned = False R/W (0b0) - CUSTOM_MAC (BLOCK1) Custom MAC address - = 00:00:00:00:00:00 (OK) R/W - MAC (BLOCK2) MAC address - = 10:97:bd:f0:e5:28 (OK) R/W - - Security fuses: - DIS_DOWNLOAD_ICACHE (BLOCK0) The bit be set to disable icache in download mode = False R/W (0b0) - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) The bit be set to disable manual encryption = False R/W (0b0) - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disables otherwise - XTS_KEY_LENGTH_256 (BLOCK0) Flash encryption key length = 128 bits key R/W (0b0) - DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download mode (boot_mode[3 = False R/W (0b0) - :0] = 0; 1; 2; 4; 5; 6; 7) - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode = False R/W (0b0) - SECURE_BOOT_EN (BLOCK0) The bit be set to enable secure boot = False R/W (0b0) - SECURE_VERSION (BLOCK0) Secure version for anti-rollback = 0 R/W (0x0) - BLOCK_KEY0 (BLOCK3) BLOCK_KEY0 - 256-bits. 256-bit key of Flash Encryp - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - tion - BLOCK_KEY0_LOW_128 (BLOCK3) BLOCK_KEY0 - lower 128-bits. 128-bit key of Flash - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - Encryption - BLOCK_KEY0_HI_128 (BLOCK3) BLOCK_KEY0 - higher 128-bits. 128-bits key of Secu - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - re Boot - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) - ock cycle diff --git a/docs/en/espefuse/inc/summary_ESP32-C3.rst b/docs/en/espefuse/inc/summary_ESP32-C3.rst deleted file mode 100644 index b1a19ea79..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-C3.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-C3 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Calibration fuses: - K_RTC_LDO (BLOCK1) BLOCK1 K_RTC_LDO = -36 R/W (0b1001001) - K_DIG_LDO (BLOCK1) BLOCK1 K_DIG_LDO = -64 R/W (0b1010000) - V_RTC_DBIAS20 (BLOCK1) BLOCK1 voltage of rtc dbias20 = -40 R/W (0x8a) - V_DIG_DBIAS20 (BLOCK1) BLOCK1 voltage of digital dbias20 = -76 R/W (0x93) - DIG_DBIAS_HVT (BLOCK1) BLOCK1 digital dbias when hvt = -28 R/W (0b10111) - THRES_HVT (BLOCK1) BLOCK1 pvt threshold when hvt = 2000 R/W (0b0111110100) - TEMP_CALIB (BLOCK2) Temperature calibration data = -7.2 R/W (0b101001000) - OCODE (BLOCK2) ADC OCode = 78 R/W (0x4e) - ADC1_INIT_CODE_ATTEN0 (BLOCK2) ADC1 init code at atten0 = 1560 R/W (0b0110000110) - ADC1_INIT_CODE_ATTEN1 (BLOCK2) ADC1 init code at atten1 = -108 R/W (0b1000011011) - ADC1_INIT_CODE_ATTEN2 (BLOCK2) ADC1 init code at atten2 = -232 R/W (0b1000111010) - ADC1_INIT_CODE_ATTEN3 (BLOCK2) ADC1 init code at atten3 = -696 R/W (0b1010101110) - ADC1_CAL_VOL_ATTEN0 (BLOCK2) ADC1 calibration voltage at atten0 = -212 R/W (0b1000110101) - ADC1_CAL_VOL_ATTEN1 (BLOCK2) ADC1 calibration voltage at atten1 = 52 R/W (0b0000001101) - ADC1_CAL_VOL_ATTEN2 (BLOCK2) ADC1 calibration voltage at atten2 = -152 R/W (0b1000100110) - ADC1_CAL_VOL_ATTEN3 (BLOCK2) ADC1 calibration voltage at atten3 = -284 R/W (0b1001000111) - - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - DIS_ICACHE (BLOCK0) Set this bit to disable Icache = False R/W (0b0) - DIS_TWAI (BLOCK0) Set this bit to disable CAN function = False R/W (0b0) - DIS_DIRECT_BOOT (BLOCK0) Disable direct boot mode = False R/W (0b0) - UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) - ERR_RST_ENABLE (BLOCK0) Use BLOCK0 to check error record registers = with check R/W (0b1) - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TPUW (BLOCK0) Configures flash waiting time after power-up; in u = 0 R/W (0x0) - nit of ms. If the value is less than 15; the waiti - ng time is the configurable value; Otherwise; the - waiting time is twice the configurable value - FORCE_SEND_RESUME (BLOCK0) Set this bit to force ROM code to send a resume co = False R/W (0b0) - mmand during SPI boot - - Identity fuses: - DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) - DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) - WAFER_VERSION_MINOR_LO (BLOCK1) WAFER_VERSION_MINOR least significant bits = 3 R/W (0b011) - PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) - BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR = 2 R/W (0b010) - WAFER_VERSION_MINOR_HI (BLOCK1) WAFER_VERSION_MINOR most significant bit = False R/W (0b0) - WAFER_VERSION_MAJOR (BLOCK1) WAFER_VERSION_MAJOR = 0 R/W (0b00) - OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID - = 25 60 04 96 c3 fd 41 6f be ed 2c 51 1d e3 7e 21 R/W - BLK_VERSION_MAJOR (BLOCK2) BLK_VERSION_MAJOR of BLOCK2 = With calibration R/W (0b01) - WAFER_VERSION_MINOR (BLOCK0) calc WAFER VERSION MINOR = WAFER_VERSION_MINOR_HI = 3 R/W (0x3) - << 3 + WAFER_VERSION_MINOR_LO (read only) - - Jtag fuses: - SOFT_DIS_JTAG (BLOCK0) Set these bits to disable JTAG in the soft way (od = 0 R/W (0b000) - d number 1 means disable ). JTAG can be enabled in - HMAC module - DIS_PAD_JTAG (BLOCK0) Set this bit to disable JTAG in the hard way. JTAG = False R/W (0b0) - is disabled permanently - - Mac fuses: - MAC (BLOCK1) MAC address - = 58:cf:79:0f:96:8c (OK) R/W - CUSTOM_MAC (BLOCK3) Custom MAC address - = 00:00:00:00:00:00 (OK) R/W - - Security fuses: - DIS_DOWNLOAD_ICACHE (BLOCK0) Set this bit to disable Icache in download mode (b = False R/W (0b0) - oot_mode[3:0] is 0; 1; 2; 3; 6; 7) - DIS_FORCE_DOWNLOAD (BLOCK0) Set this bit to disable the function that forces c = False R/W (0b0) - hip into download mode - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Set this bit to disable flash encryption when in d = False R/W (0b0) - ownload boot modes - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disables otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Purpose of Key0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Purpose of Key1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Purpose of Key2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Purpose of Key3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Purpose of Key4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Purpose of Key5 = USER R/W (0x0) - SECURE_BOOT_EN (BLOCK0) Set this bit to enable secure boot = False R/W (0b0) - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Set this bit to enable revoking aggressive secure = False R/W (0b0) - boot - DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download mode (boot_mode[3 = False R/W (0b0) - :0] = 0; 1; 2; 3; 6; 7) - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode = False R/W (0b0) - SECURE_VERSION (BLOCK0) Secure version (used by ESP-IDF anti-rollback feat = 0 R/W (0x0000) - ure) - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Spi Pad fuses: - SPI_PAD_CONFIG_CLK (BLOCK1) SPI PAD CLK = 0 R/W (0b000000) - SPI_PAD_CONFIG_Q (BLOCK1) SPI PAD Q(D1) = 0 R/W (0b000000) - SPI_PAD_CONFIG_D (BLOCK1) SPI PAD D(D0) = 0 R/W (0b000000) - SPI_PAD_CONFIG_CS (BLOCK1) SPI PAD CS = 0 R/W (0b000000) - SPI_PAD_CONFIG_HD (BLOCK1) SPI PAD HD(D3) = 0 R/W (0b000000) - SPI_PAD_CONFIG_WP (BLOCK1) SPI PAD WP(D2) = 0 R/W (0b000000) - SPI_PAD_CONFIG_DQS (BLOCK1) SPI PAD DQS = 0 R/W (0b000000) - SPI_PAD_CONFIG_D4 (BLOCK1) SPI PAD D4 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D5 (BLOCK1) SPI PAD D5 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D6 (BLOCK1) SPI PAD D6 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D7 (BLOCK1) SPI PAD D7 = 0 R/W (0b000000) - - Usb fuses: - DIS_USB_JTAG (BLOCK0) Set this bit to disable function of usb switch to = False R/W (0b0) - jtag in module of usb device - DIS_USB_SERIAL_JTAG (BLOCK0) USB-Serial-JTAG = Enable R/W (0b0) - USB_EXCHG_PINS (BLOCK0) Set this bit to exchange USB D+ and D- pins = False R/W (0b0) - DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) USB printing = Enable R/W (0b0) - DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Disable UART download mode through USB-Serial-JTAG = False R/W (0b0) - - Vdd fuses: - VDD_SPI_AS_GPIO (BLOCK0) Set this bit to vdd spi pin function as gpio = False R/W (0b0) - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) - ock cycle diff --git a/docs/en/espefuse/inc/summary_ESP32-C6.rst b/docs/en/espefuse/inc/summary_ESP32-C6.rst deleted file mode 100644 index 39411b778..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-C6.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-C6 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - SWAP_UART_SDIO_EN (BLOCK0) Represents whether pad of uart and sdio is swapped = False R/W (0b0) - or not. 1: swapped. 0: not swapped - DIS_ICACHE (BLOCK0) Represents whether icache is disabled or enabled. = False R/W (0b0) - 1: disabled. 0: enabled - DIS_TWAI (BLOCK0) Represents whether TWAI function is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - DIS_DIRECT_BOOT (BLOCK0) Represents whether direct boot mode is disabled or = False R/W (0b0) - enabled. 1: disabled. 0: enabled - UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TPUW (BLOCK0) Represents the flash waiting time after power-up; = 0 R/W (0x0) - in unit of ms. When the value less than 15; the wa - iting time is the programmed value. Otherwise; the - waiting time is 2 times the programmed value - FORCE_SEND_RESUME (BLOCK0) Represents whether ROM code is forced to send a re = False R/W (0b0) - sume command during SPI boot. 1: forced. 0:not for - ced - FLASH_CAP (BLOCK1) = 0 R/W (0b000) - FLASH_TEMP (BLOCK1) = 0 R/W (0b00) - FLASH_VENDOR (BLOCK1) = 0 R/W (0b000) - - Identity fuses: - DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) - DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) - WAFER_VERSION_MINOR (BLOCK1) = 0 R/W (0x0) - WAFER_VERSION_MAJOR (BLOCK1) = 0 R/W (0b00) - BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR of BLOCK2 = 0 R/W (0b000) - BLK_VERSION_MAJOR (BLOCK1) BLK_VERSION_MAJOR of BLOCK2 = 0 R/W (0b00) - PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) - OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Jtag fuses: - JTAG_SEL_ENABLE (BLOCK0) Represents whether the selection between usb_to_jt = False R/W (0b0) - ag and pad_to_jtag through strapping gpio15 when b - oth EFUSE_DIS_PAD_JTAG and EFUSE_DIS_USB_JTAG are - equal to 0 is enabled or disabled. 1: enabled. 0: - disabled - SOFT_DIS_JTAG (BLOCK0) Represents whether JTAG is disabled in soft way. O = 0 R/W (0b000) - dd number: disabled. Even number: enabled - DIS_PAD_JTAG (BLOCK0) Represents whether JTAG is disabled in the hard wa = False R/W (0b0) - y(permanently). 1: disabled. 0: enabled - - Mac fuses: - MAC (BLOCK1) MAC address - = 60:55:f9:f6:03:24 (OK) R/W - MAC_EXT (BLOCK1) Stores the extended bits of MAC address = 00:00 (OK) R/W - CUSTOM_MAC (BLOCK3) Custom MAC - = 00:00:00:00:00:00 (OK) R/W - - Security fuses: - DIS_DOWNLOAD_ICACHE (BLOCK0) Represents whether icache is disabled or enabled i = False R/W (0b0) - n Download mode. 1: disabled. 0: enabled - DIS_FORCE_DOWNLOAD (BLOCK0) Represents whether the function that forces chip i = False R/W (0b0) - nto download mode is disabled or enabled. 1: disab - led. 0: enabled - SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Represents whether SPI0 controller during boot_mod = False R/W (0b0) - e_download is disabled or enabled. 1: disabled. 0: - enabled - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0) - led or enabled(except in SPI boot mode). 1: disabl - ed. 0: enabled - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disables otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Represents the purpose of Key0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Represents the purpose of Key1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Represents the purpose of Key2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Represents the purpose of Key3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Represents the purpose of Key4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Represents the purpose of Key5 = USER R/W (0x0) - SEC_DPA_LEVEL (BLOCK0) Represents the spa secure level by configuring the = 0 R/W (0b00) - clock random divide mode - CRYPT_DPA_ENABLE (BLOCK0) Represents whether anti-dpa attack is enabled. 1:e = False R/W (0b0) - nabled. 0: disabled - SECURE_BOOT_EN (BLOCK0) Represents whether secure boot is enabled or disab = False R/W (0b0) - led. 1: enabled. 0: disabled - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Represents whether revoking aggressive secure boot = False R/W (0b0) - is enabled or disabled. 1: enabled. 0: disabled - DIS_DOWNLOAD_MODE (BLOCK0) Represents whether Download mode is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Represents whether security download is enabled or = False R/W (0b0) - disabled. 1: enabled. 0: disabled - SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000) - ck feature - SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0) - or enabled when Secure Boot is enabled. 1: disabl - ed. 0: enabled - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Usb fuses: - DIS_USB_JTAG (BLOCK0) Represents whether the function of usb switch to j = False R/W (0b0) - tag is disabled or enabled. 1: disabled. 0: enable - d - DIS_USB_SERIAL_JTAG (BLOCK0) Represents whether USB-Serial-JTAG is disabled or = False R/W (0b0) - enabled. 1: disabled. 0: enabled - USB_EXCHG_PINS (BLOCK0) Represents whether the D+ and D- pins is exchanged = False R/W (0b0) - . 1: exchanged. 0: not exchanged - DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) Represents whether print from USB-Serial-JTAG is d = False R/W (0b0) - isabled or enabled. 1: disabled. 0: enabled - DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Represents whether the USB-Serial-JTAG download fu = False R/W (0b0) - nction is disabled or enabled. 1: disabled. 0: ena - bled - - Vdd fuses: - VDD_SPI_AS_GPIO (BLOCK0) Represents whether vdd spi pin is functioned as gp = False R/W (0b0) - io. 1: functioned. 0: not functioned - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) Represents whether RTC watchdog timeout threshold = 0 R/W (0b00) - is selected at startup. 1: selected. 0: not select - ed diff --git a/docs/en/espefuse/inc/summary_ESP32-H2.rst b/docs/en/espefuse/inc/summary_ESP32-H2.rst deleted file mode 100644 index 0032586bd..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-H2.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-H2 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - DIS_ICACHE (BLOCK0) Represents whether icache is disabled or enabled. = False R/W (0b0) - 1: disabled. 0: enabled - POWERGLITCH_EN (BLOCK0) Represents whether power glitch function is enable = False R/W (0b0) - d. 1: enabled. 0: disabled - DIS_TWAI (BLOCK0) Represents whether TWAI function is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - DIS_DIRECT_BOOT (BLOCK0) Represents whether direct boot mode is disabled or = False R/W (0b0) - enabled. 1: disabled. 0: enabled - UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00) - HYS_EN_PAD0 (BLOCK0) Set bits to enable hysteresis function of PAD0~5 = 0 R/W (0b000000) - HYS_EN_PAD1 (BLOCK0) Set bits to enable hysteresis function of PAD6~27 = 0 R/W (0b0000000000000000000000) - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TPUW (BLOCK0) Represents the flash waiting time after power-up; = 0 R/W (0x0) - in unit of ms. When the value less than 15; the wa - iting time is the programmed value. Otherwise; the - waiting time is 2 times the programmed value - FORCE_SEND_RESUME (BLOCK0) Represents whether ROM code is forced to send a re = False R/W (0b0) - sume command during SPI boot. 1: forced. 0:not for - ced - FLASH_CAP (BLOCK1) = 0 R/W (0b000) - FLASH_TEMP (BLOCK1) = 0 R/W (0b00) - FLASH_VENDOR (BLOCK1) = 0 R/W (0b000) - - Identity fuses: - WAFER_VERSION_MINOR (BLOCK1) = 0 R/W (0b000) - WAFER_VERSION_MAJOR (BLOCK1) = 0 R/W (0b00) - DISABLE_WAFER_VERSION_MAJOR (BLOCK1) Disables check of wafer version major = False R/W (0b0) - PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) - OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLK_VERSION_MINOR (BLOCK2) BLK_VERSION_MINOR of BLOCK2 = 0 R/W (0b000) - BLK_VERSION_MAJOR (BLOCK2) BLK_VERSION_MAJOR of BLOCK2 = 0 R/W (0b00) - DISABLE_BLK_VERSION_MAJOR (BLOCK2) Disables check of blk version major = False R/W (0b0) - - Jtag fuses: - JTAG_SEL_ENABLE (BLOCK0) Set this bit to enable selection between usb_to_jt = False R/W (0b0) - ag and pad_to_jtag through strapping gpio25 when b - oth EFUSE_DIS_PAD_JTAG and EFUSE_DIS_USB_JTAG are - equal to 0 - SOFT_DIS_JTAG (BLOCK0) Represents whether JTAG is disabled in soft way. O = 0 R/W (0b000) - dd number: disabled. Even number: enabled - DIS_PAD_JTAG (BLOCK0) Represents whether JTAG is disabled in the hard wa = False R/W (0b0) - y(permanently). 1: disabled. 0: enabled - - Mac fuses: - MAC (BLOCK1) MAC address - = 60:55:f9:f7:2c:05 (OK) R/W - MAC_EXT (BLOCK1) Stores the extended bits of MAC address = ff:fe (OK) R/W - CUSTOM_MAC (BLOCK3) Custom MAC - = 00:00:00:00:00:00 (OK) R/W - - Security fuses: - DIS_FORCE_DOWNLOAD (BLOCK0) Represents whether the function that forces chip i = False R/W (0b0) - nto download mode is disabled or enabled. 1: disab - led. 0: enabled - SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Represents whether SPI0 controller during boot_mod = False R/W (0b0) - e_download is disabled or enabled. 1: disabled. 0: - enabled - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0) - led or enabled(except in SPI boot mode). 1: disabl - ed. 0: enabled - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disables otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Represents the purpose of Key0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Represents the purpose of Key1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Represents the purpose of Key2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Represents the purpose of Key3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Represents the purpose of Key4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Represents the purpose of Key5 = USER R/W (0x0) - SEC_DPA_LEVEL (BLOCK0) Represents the spa secure level by configuring the = 0 R/W (0b00) - clock random divide mode - ECDSA_FORCE_USE_HARDWARE_K (BLOCK0) Represents whether hardware random number k is for = False R/W (0b0) - ced used in ESDCA. 1: force used. 0: not force use - d - CRYPT_DPA_ENABLE (BLOCK0) Represents whether anti-dpa attack is enabled. 1:e = False R/W (0b0) - nabled. 0: disabled - SECURE_BOOT_EN (BLOCK0) Represents whether secure boot is enabled or disab = False R/W (0b0) - led. 1: enabled. 0: disabled - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Represents whether revoking aggressive secure boot = False R/W (0b0) - is enabled or disabled. 1: enabled. 0: disabled - DIS_DOWNLOAD_MODE (BLOCK0) Represents whether Download mode is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Represents whether security download is enabled or = False R/W (0b0) - disabled. 1: enabled. 0: disabled - SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000) - ck feature - SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0) - or enabled when Secure Boot is enabled. 1: disabl - ed. 0: enabled - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Usb fuses: - DIS_USB_JTAG (BLOCK0) Represents whether the function of usb switch to j = False R/W (0b0) - tag is disabled or enabled. 1: disabled. 0: enable - d - USB_EXCHG_PINS (BLOCK0) Represents whether the D+ and D- pins is exchanged = False R/W (0b0) - . 1: exchanged. 0: not exchanged - DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) Set this bit to disable USB-Serial-JTAG print duri = False R/W (0b0) - ng rom boot - DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Represents whether the USB-Serial-JTAG download fu = False R/W (0b0) - nction is disabled or enabled. 1: disabled. 0: ena - bled - - Vdd fuses: - VDD_SPI_AS_GPIO (BLOCK0) Represents whether vdd spi pin is functioned as gp = False R/W (0b0) - io. 1: functioned. 0: not functioned - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) Represents whether RTC watchdog timeout threshold = 0 R/W (0b00) - is selected at startup. 1: selected. 0: not select - ed diff --git a/docs/en/espefuse/inc/summary_ESP32-P4.rst b/docs/en/espefuse/inc/summary_ESP32-P4.rst deleted file mode 100644 index 74421869c..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-P4.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-P4 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - POWERGLITCH_EN (BLOCK0) Represents whether power glitch function is enable = False R/W (0b0) - d. 1: enabled. 0: disabled - DIS_TWAI (BLOCK0) Represents whether TWAI function is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - KM_HUK_GEN_STATE_LOW (BLOCK0) Set this bit to control validation of HUK generate = 0 R/W (0b000000) - mode. Odd of 1 is invalid; even of 1 is valid - KM_HUK_GEN_STATE_HIGH (BLOCK0) Set this bit to control validation of HUK generate = 0 R/W (0b000) - mode. Odd of 1 is invalid; even of 1 is valid - KM_RND_SWITCH_CYCLE (BLOCK0) Set bits to control key manager random number swit = 0 R/W (0b00) - ch cycle. 0: control by register. 1: 8 km clk cycl - es. 2: 16 km cycles. 3: 32 km cycles - KM_DEPLOY_ONLY_ONCE (BLOCK0) Set each bit to control whether corresponding key = 0 R/W (0x0) - can only be deployed once. 1 is true; 0 is false. - Bit0: ecdsa. Bit1: xts. Bit2: hmac. Bit3: ds - DIS_DIRECT_BOOT (BLOCK0) Represents whether direct boot mode is disabled or = False R/W (0b0) - enabled. 1: disabled. 0: enabled - UART_PRINT_CONTROL (BLOCK0) Represents the type of UART printing. 00: force en = 0 R/W (0b00) - able printing. 01: enable printing when GPIO8 is r - eset at low level. 10: enable printing when GPIO8 - is reset at high level. 11: force disable printing - HYS_EN_PAD (BLOCK0) Represents whether the hysteresis function of corr = False R/W (0b0) - esponding PAD is enabled. 1: enabled. 0:disabled - DCDC_VSET (BLOCK0) Set the dcdc voltage default = 0 R/W (0b00000) - PXA0_TIEH_SEL_0 (BLOCK0) TBD = 0 R/W (0b00) - PXA0_TIEH_SEL_1 (BLOCK0) TBD = 0 R/W (0b00) - PXA0_TIEH_SEL_2 (BLOCK0) TBD = 0 R/W (0b00) - PXA0_TIEH_SEL_3 (BLOCK0) TBD = 0 R/W (0b00) - KM_DISABLE_DEPLOY_MODE (BLOCK0) TBD = 0 R/W (0x0) - HP_PWR_SRC_SEL (BLOCK0) HP system power source select. 0:LDO. 1: DCDC = False R/W (0b0) - DCDC_VSET_EN (BLOCK0) Select dcdc vset use efuse_dcdc_vset = False R/W (0b0) - DIS_SWD (BLOCK0) Set this bit to disable super-watchdog = False R/W (0b0) - BLOCK_SYS_DATA1 (BLOCK2) System data part 1 - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TYPE (BLOCK0) The type of interfaced flash. 0: four data lines; = False R/W (0b0) - 1: eight data lines - FLASH_PAGE_SIZE (BLOCK0) Set flash page size = 0 R/W (0b00) - FLASH_ECC_EN (BLOCK0) Set this bit to enable ecc for flash boot = False R/W (0b0) - FLASH_TPUW (BLOCK0) Represents the flash waiting time after power-up; = 0 R/W (0x0) - in unit of ms. When the value less than 15; the wa - iting time is the programmed value. Otherwise; the - waiting time is 2 times the programmed value - FORCE_SEND_RESUME (BLOCK0) Represents whether ROM code is forced to send a re = False R/W (0b0) - sume command during SPI boot. 1: forced. 0:not for - ced - - Jtag fuses: - JTAG_SEL_ENABLE (BLOCK0) Represents whether the selection between usb_to_jt = False R/W (0b0) - ag and pad_to_jtag through strapping gpio15 when b - oth EFUSE_DIS_PAD_JTAG and EFUSE_DIS_USB_JTAG are - equal to 0 is enabled or disabled. 1: enabled. 0: - disabled - SOFT_DIS_JTAG (BLOCK0) Represents whether JTAG is disabled in soft way. O = 0 R/W (0b000) - dd number: disabled. Even number: enabled - DIS_PAD_JTAG (BLOCK0) Represents whether JTAG is disabled in the hard wa = False R/W (0b0) - y(permanently). 1: disabled. 0: enabled - - Mac fuses: - MAC (BLOCK1) MAC address - = 00:00:00:00:00:00 (OK) R/W - MAC_EXT (BLOCK1) Stores the extended bits of MAC address = 00:00 (OK) R/W - MAC_EUI64 (BLOCK1) calc MAC_EUI64 = MAC[0]:MAC[1]:MAC[2]:MAC_EXT[0]:M - = 00:00:00:00:00:00:00:00 (OK) R/W - AC_EXT[1]:MAC[3]:MAC[4]:MAC[5] - - Security fuses: - DIS_FORCE_DOWNLOAD (BLOCK0) Represents whether the function that forces chip i = False R/W (0b0) - nto download mode is disabled or enabled. 1: disab - led. 0: enabled - SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Set this bit to disable accessing MSPI flash/MSPI = False R/W (0b0) - ram by SYS AXI matrix during boot_mode_download - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0) - led or enabled(except in SPI boot mode). 1: disabl - ed. 0: enabled - FORCE_USE_KEY_MANAGER_KEY (BLOCK0) Set each bit to control whether corresponding key = 0 R/W (0x0) - must come from key manager.. 1 is true; 0 is false - . Bit0: ecdsa. Bit1: xts. Bit2: hmac. Bit3: ds - FORCE_DISABLE_SW_INIT_KEY (BLOCK0) Set this bit to disable software written init key; = False R/W (0b0) - and force use efuse_init_key - XTS_KEY_LENGTH_256 (BLOCK0) Set this bit to configure flash encryption use xts = False R/W (0b0) - -128 key; else use xts-256 key - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disables otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Represents the purpose of Key0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Represents the purpose of Key1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Represents the purpose of Key2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Represents the purpose of Key3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Represents the purpose of Key4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Represents the purpose of Key5 = USER R/W (0x0) - SEC_DPA_LEVEL (BLOCK0) Represents the spa secure level by configuring the = 0 R/W (0b00) - clock random divide mode - ECDSA_ENABLE_SOFT_K (BLOCK0) Represents whether hardware random number k is for = False R/W (0b0) - ced used in ESDCA. 1: force used. 0: not force use - d - CRYPT_DPA_ENABLE (BLOCK0) Represents whether anti-dpa attack is enabled. 1:e = False R/W (0b0) - nabled. 0: disabled - SECURE_BOOT_EN (BLOCK0) Represents whether secure boot is enabled or disab = False R/W (0b0) - led. 1: enabled. 0: disabled - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Represents whether revoking aggressive secure boot = False R/W (0b0) - is enabled or disabled. 1: enabled. 0: disabled - DIS_DOWNLOAD_MODE (BLOCK0) Represents whether Download mode is disabled or en = False R/W (0b0) - abled. 1: disabled. 0: enabled - LOCK_KM_KEY (BLOCK0) TBD = False R/W (0b0) - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Represents whether security download is enabled or = False R/W (0b0) - disabled. 1: enabled. 0: disabled - SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000) - ck feature - SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST VERIFY ON WAKE is disabled = False R/W (0b0) - or enabled when Secure Boot is enabled. 1: disabl - ed. 0: enabled - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Usb fuses: - USB_DEVICE_EXCHG_PINS (BLOCK0) Enable usb device exchange pins of D+ and D- = False R/W (0b0) - USB_OTG11_EXCHG_PINS (BLOCK0) Enable usb otg11 exchange pins of D+ and D- = False R/W (0b0) - DIS_USB_JTAG (BLOCK0) Represents whether the function of usb switch to j = False R/W (0b0) - tag is disabled or enabled. 1: disabled. 0: enable - d - USB_PHY_SEL (BLOCK0) TBD = False R/W (0b0) - DIS_USB_OTG_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download via USB-OTG = False R/W (0b0) - DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) Represents whether print from USB-Serial-JTAG is d = False R/W (0b0) - isabled or enabled. 1: disabled. 0: enabled - DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Represents whether the USB-Serial-JTAG download fu = False R/W (0b0) - nction is disabled or enabled. 1: disabled. 0: ena - bled - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) Represents whether RTC watchdog timeout threshold = 0 R/W (0b00) - is selected at startup. 1: selected. 0: not select - ed - DIS_WDT (BLOCK0) Set this bit to disable watch dog = False R/W (0b0) - \ No newline at end of file diff --git a/docs/en/espefuse/inc/summary_ESP32-S2.rst b/docs/en/espefuse/inc/summary_ESP32-S2.rst deleted file mode 100644 index 85617bfa4..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-S2.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-S2 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Calibration fuses: - ADC_CALIB (BLOCK2) 4 bit of ADC calibration = 0 R/W (0x0) - TEMP_CALIB (BLOCK2) Temperature calibration data = 3.2 R/W (0b000100000) - RTCCALIB_V1IDX_A10H (BLOCK2) = 55 R/W (0x37) - RTCCALIB_V1IDX_A11H (BLOCK2) = 51 R/W (0x33) - RTCCALIB_V1IDX_A12H (BLOCK2) = 52 R/W (0x34) - RTCCALIB_V1IDX_A13H (BLOCK2) = 53 R/W (0x35) - RTCCALIB_V1IDX_A20H (BLOCK2) = 56 R/W (0x38) - RTCCALIB_V1IDX_A21H (BLOCK2) = 55 R/W (0x37) - RTCCALIB_V1IDX_A22H (BLOCK2) = 55 R/W (0x37) - RTCCALIB_V1IDX_A23H (BLOCK2) = 59 R/W (0x3b) - RTCCALIB_V1IDX_A10L (BLOCK2) = 25 R/W (0b011001) - RTCCALIB_V1IDX_A11L (BLOCK2) = 17 R/W (0b010001) - RTCCALIB_V1IDX_A12L (BLOCK2) = 14 R/W (0b001110) - RTCCALIB_V1IDX_A13L (BLOCK2) = 7 R/W (0b000111) - RTCCALIB_V1IDX_A20L (BLOCK2) = 19 R/W (0b010011) - RTCCALIB_V1IDX_A21L (BLOCK2) = 14 R/W (0b001110) - RTCCALIB_V1IDX_A22L (BLOCK2) = 10 R/W (0b001010) - RTCCALIB_V1IDX_A23L (BLOCK2) = 6 R/W (0b000110) - - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - DIS_ICACHE (BLOCK0) Set this bit to disable Icache = False R/W (0b0) - DIS_DCACHE (BLOCK0) Set this bit to disable Dcache = False R/W (0b0) - DIS_TWAI (BLOCK0) Set this bit to disable the TWAI Controller functi = False R/W (0b0) - on - DIS_BOOT_REMAP (BLOCK0) Disables capability to Remap RAM to ROM address sp = False R/W (0b0) - ace - DIS_LEGACY_SPI_BOOT (BLOCK0) Set this bit to disable Legacy SPI boot mode = False R/W (0b0) - UART_PRINT_CHANNEL (BLOCK0) Selects the default UART for printing boot message = UART0 R/W (0b0) - s - UART_PRINT_CONTROL (BLOCK0) Set the default UART boot message output mode = Enable R/W (0b00) - PIN_POWER_SELECTION (BLOCK0) Set default power supply for GPIO33-GPIO37; set wh = VDD3P3_CPU R/W (0b0) - en SPI flash is initialized - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TPUW (BLOCK0) Configures flash startup delay after SoC power-up; = 0 R/W (0x0) - in unit of (ms/2). When the value is 15; delay is - 7.5 ms - FLASH_TYPE (BLOCK0) SPI flash type = 4 data lines R/W (0b0) - FORCE_SEND_RESUME (BLOCK0) If set; forces ROM code to send an SPI flash resum = False R/W (0b0) - e command during SPI boot - FLASH_VERSION (BLOCK1) Flash version = 1 R/W (0x1) - - Identity fuses: - BLOCK0_VERSION (BLOCK0) BLOCK0 efuse version = 0 R/W (0b00) - DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) - DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) - WAFER_VERSION_MAJOR (BLOCK1) WAFER_VERSION_MAJOR = 0 R/W (0b00) - WAFER_VERSION_MINOR_HI (BLOCK1) WAFER_VERSION_MINOR most significant bit = False R/W (0b0) - BLK_VERSION_MAJOR (BLOCK1) BLK_VERSION_MAJOR = 0 R/W (0b00) - PSRAM_VERSION (BLOCK1) PSRAM version = 0 R/W (0x0) - PKG_VERSION (BLOCK1) Package version = 0 R/W (0x0) - WAFER_VERSION_MINOR_LO (BLOCK1) WAFER_VERSION_MINOR least significant bits = 0 R/W (0b000) - OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID - = d9 8f 05 d0 86 77 53 db 80 6c ee 40 df 5d ef b0 R/W - BLK_VERSION_MINOR (BLOCK2) BLK_VERSION_MINOR of BLOCK2 = ADC calib V1 R/W (0b001) - WAFER_VERSION_MINOR (BLOCK0) calc WAFER VERSION MINOR = WAFER_VERSION_MINOR_HI = 0 R/W (0x0) - << 3 + WAFER_VERSION_MINOR_LO (read only) - - Jtag fuses: - SOFT_DIS_JTAG (BLOCK0) Software disables JTAG. When software disabled; JT = False R/W (0b0) - AG can be activated temporarily by HMAC peripheral - HARD_DIS_JTAG (BLOCK0) Hardware disables JTAG permanently = False R/W (0b0) - - Mac fuses: - MAC (BLOCK1) MAC address - = 7c:df:a1:00:48:34 (OK) R/W - CUSTOM_MAC (BLOCK3) Custom MAC - = 00:00:00:00:00:00 (OK) R/W - - Security fuses: - DIS_DOWNLOAD_ICACHE (BLOCK0) Disables Icache when SoC is in Download mode = False R/W (0b0) - DIS_DOWNLOAD_DCACHE (BLOCK0) Disables Dcache when SoC is in Download mode = False R/W (0b0) - DIS_FORCE_DOWNLOAD (BLOCK0) Set this bit to disable the function that forces c = False R/W (0b0) - hip into download mode - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Disables flash encryption when in download boot mo = False R/W (0b0) - des - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disabled otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Purpose of KEY0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Purpose of KEY1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Purpose of KEY2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Purpose of KEY3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Purpose of KEY4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Purpose of KEY5 = USER R/W (0x0) - SECURE_BOOT_EN (BLOCK0) Set this bit to enable secure boot = False R/W (0b0) - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Set this bit to enable aggressive secure boot key = False R/W (0b0) - revocation mode - DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable all download boot modes = False R/W (0b0) - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode ( = False R/W (0b0) - read/write flash only) - SECURE_VERSION (BLOCK0) Secure version (used by ESP-IDF anti-rollback feat = 0 R/W (0x0000) - ure) - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Spi Pad fuses: - SPI_PAD_CONFIG_CLK (BLOCK1) SPI_PAD_configure CLK = 0 R/W (0b000000) - SPI_PAD_CONFIG_Q (BLOCK1) SPI_PAD_configure Q(D1) = 0 R/W (0b000000) - SPI_PAD_CONFIG_D (BLOCK1) SPI_PAD_configure D(D0) = 0 R/W (0b000000) - SPI_PAD_CONFIG_CS (BLOCK1) SPI_PAD_configure CS = 0 R/W (0b000000) - SPI_PAD_CONFIG_HD (BLOCK1) SPI_PAD_configure HD(D3) = 0 R/W (0b000000) - SPI_PAD_CONFIG_WP (BLOCK1) SPI_PAD_configure WP(D2) = 0 R/W (0b000000) - SPI_PAD_CONFIG_DQS (BLOCK1) SPI_PAD_configure DQS = 0 R/W (0b000000) - SPI_PAD_CONFIG_D4 (BLOCK1) SPI_PAD_configure D4 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D5 (BLOCK1) SPI_PAD_configure D5 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D6 (BLOCK1) SPI_PAD_configure D6 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D7 (BLOCK1) SPI_PAD_configure D7 = 0 R/W (0b000000) - - Usb fuses: - DIS_USB (BLOCK0) Set this bit to disable USB OTG function = False R/W (0b0) - USB_EXCHG_PINS (BLOCK0) Set this bit to exchange USB D+ and D- pins = False R/W (0b0) - USB_EXT_PHY_ENABLE (BLOCK0) Set this bit to enable external USB PHY = False R/W (0b0) - USB_FORCE_NOPERSIST (BLOCK0) If set; forces USB BVALID to 1 = False R/W (0b0) - DIS_USB_DOWNLOAD_MODE (BLOCK0) Set this bit to disable use of USB OTG in UART dow = False R/W (0b0) - nload boot mode - - Vdd fuses: - VDD_SPI_XPD (BLOCK0) If VDD_SPI_FORCE is 1; this value determines if th = False R/W (0b0) - e VDD_SPI regulator is powered on - VDD_SPI_TIEH (BLOCK0) If VDD_SPI_FORCE is 1; determines VDD_SPI voltage - = VDD_SPI connects to 1.8 V LDO R/W (0b0) - VDD_SPI_FORCE (BLOCK0) Set this bit to use XPD_VDD_PSI_REG and VDD_SPI_TI = False R/W (0b0) - EH to configure VDD_SPI LDO - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) - ock cycle - - Flash voltage (VDD_SPI) determined by GPIO45 on reset (GPIO45=High: VDD_SPI pin is powered from internal 1.8V LDO - GPIO45=Low or NC: VDD_SPI pin is powered directly from VDD3P3_RTC_IO via resistor Rspi. Typically this voltage is 3.3 V). diff --git a/docs/en/espefuse/inc/summary_ESP32-S3.rst b/docs/en/espefuse/inc/summary_ESP32-S3.rst deleted file mode 100644 index 25c64ac27..000000000 --- a/docs/en/espefuse/inc/summary_ESP32-S3.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting.... - Detecting chip type... ESP32-S3 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Config fuses: - WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000) - RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000) - DIS_ICACHE (BLOCK0) Set this bit to disable Icache = False R/W (0b0) - DIS_DCACHE (BLOCK0) Set this bit to disable Dcache = False R/W (0b0) - DIS_TWAI (BLOCK0) Set this bit to disable CAN function = False R/W (0b0) - DIS_APP_CPU (BLOCK0) Disable app cpu = False R/W (0b0) - DIS_DIRECT_BOOT (BLOCK0) Disable direct boot mode = False R/W (0b0) - UART_PRINT_CONTROL (BLOCK0) Set the default UART boot message output mode = Enable R/W (0b00) - PIN_POWER_SELECTION (BLOCK0) Set default power supply for GPIO33-GPIO37; set wh = VDD3P3_CPU R/W (0b0) - en SPI flash is initialized - BLOCK_USR_DATA (BLOCK3) User data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved) - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Flash fuses: - FLASH_TPUW (BLOCK0) Configures flash waiting time after power-up; in u = 0 R/W (0x0) - nit of ms. If the value is less than 15; the waiti - ng time is the configurable value. Otherwise; the - waiting time is twice the configurable value - FLASH_ECC_MODE (BLOCK0) Flash ECC mode in ROM = 16to18 byte R/W (0b0) - FLASH_TYPE (BLOCK0) SPI flash type = 4 data lines R/W (0b0) - FLASH_PAGE_SIZE (BLOCK0) Set Flash page size = 0 R/W (0b00) - FLASH_ECC_EN (BLOCK0) Set 1 to enable ECC for flash boot = False R/W (0b0) - FORCE_SEND_RESUME (BLOCK0) Set this bit to force ROM code to send a resume co = False R/W (0b0) - mmand during SPI boot - - Identity fuses: - DISABLE_WAFER_VERSION_MAJOR (BLOCK0) Disables check of wafer version major = False R/W (0b0) - DISABLE_BLK_VERSION_MAJOR (BLOCK0) Disables check of blk version major = False R/W (0b0) - WAFER_VERSION_MINOR_LO (BLOCK1) WAFER_VERSION_MINOR least significant bits = 0 R/W (0b000) - PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000) - BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR = 0 R/W (0b000) - WAFER_VERSION_MINOR_HI (BLOCK1) WAFER_VERSION_MINOR most significant bit = False R/W (0b0) - WAFER_VERSION_MAJOR (BLOCK1) WAFER_VERSION_MAJOR = 0 R/W (0b00) - OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLK_VERSION_MAJOR (BLOCK2) BLK_VERSION_MAJOR of BLOCK2 = No calib R/W (0b00) - WAFER_VERSION_MINOR (BLOCK0) calc WAFER VERSION MINOR = WAFER_VERSION_MINOR_HI = 0 R/W (0x0) - << 3 + WAFER_VERSION_MINOR_LO (read only) - - Jtag fuses: - SOFT_DIS_JTAG (BLOCK0) Set these bits to disable JTAG in the soft way (od = 0 R/W (0b000) - d number 1 means disable ). JTAG can be enabled in - HMAC module - DIS_PAD_JTAG (BLOCK0) Set this bit to disable JTAG in the hard way. JTAG = False R/W (0b0) - is disabled permanently - STRAP_JTAG_SEL (BLOCK0) Set this bit to enable selection between usb_to_jt = False R/W (0b0) - ag and pad_to_jtag through strapping gpio10 when b - oth reg_dis_usb_jtag and reg_dis_pad_jtag are equa - l to 0 - - Mac fuses: - MAC (BLOCK1) MAC address - = 7c:df:a1:e0:00:58 (OK) R/W - CUSTOM_MAC (BLOCK3) Custom MAC - = 00:00:00:00:00:00 (OK) R/W - - Security fuses: - DIS_DOWNLOAD_ICACHE (BLOCK0) Set this bit to disable Icache in download mode (b = False R/W (0b0) - oot_mode[3:0] is 0; 1; 2; 3; 6; 7) - DIS_DOWNLOAD_DCACHE (BLOCK0) Set this bit to disable Dcache in download mode ( = False R/W (0b0) - boot_mode[3:0] is 0; 1; 2; 3; 6; 7) - DIS_FORCE_DOWNLOAD (BLOCK0) Set this bit to disable the function that forces c = False R/W (0b0) - hip into download mode - DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Set this bit to disable flash encryption when in d = False R/W (0b0) - ownload boot modes - SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000) - and disabled otherwise - SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0) - SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0) - KEY_PURPOSE_0 (BLOCK0) Purpose of Key0 = USER R/W (0x0) - KEY_PURPOSE_1 (BLOCK0) Purpose of Key1 = USER R/W (0x0) - KEY_PURPOSE_2 (BLOCK0) Purpose of Key2 = USER R/W (0x0) - KEY_PURPOSE_3 (BLOCK0) Purpose of Key3 = USER R/W (0x0) - KEY_PURPOSE_4 (BLOCK0) Purpose of Key4 = USER R/W (0x0) - KEY_PURPOSE_5 (BLOCK0) Purpose of Key5 = USER R/W (0x0) - SECURE_BOOT_EN (BLOCK0) Set this bit to enable secure boot = False R/W (0b0) - SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Set this bit to enable revoking aggressive secure = False R/W (0b0) - boot - DIS_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download mode (boot_mode[3 = False R/W (0b0) - :0] = 0; 1; 2; 3; 6; 7) - ENABLE_SECURITY_DOWNLOAD (BLOCK0) Set this bit to enable secure UART download mode = False R/W (0b0) - SECURE_VERSION (BLOCK0) Secure version (used by ESP-IDF anti-rollback feat = 0 R/W (0x0000) - ure) - BLOCK_KEY0 (BLOCK4) - Purpose: USER - Key0 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY1 (BLOCK5) - Purpose: USER - Key1 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY2 (BLOCK6) - Purpose: USER - Key2 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY3 (BLOCK7) - Purpose: USER - Key3 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY4 (BLOCK8) - Purpose: USER - Key4 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK_KEY5 (BLOCK9) - Purpose: USER - Key5 or user data - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Spi Pad fuses: - SPI_PAD_CONFIG_CLK (BLOCK1) SPI_PAD_configure CLK = 0 R/W (0b000000) - SPI_PAD_CONFIG_Q (BLOCK1) SPI_PAD_configure Q(D1) = 0 R/W (0b000000) - SPI_PAD_CONFIG_D (BLOCK1) SPI_PAD_configure D(D0) = 0 R/W (0b000000) - SPI_PAD_CONFIG_CS (BLOCK1) SPI_PAD_configure CS = 0 R/W (0b000000) - SPI_PAD_CONFIG_HD (BLOCK1) SPI_PAD_configure HD(D3) = 0 R/W (0b000000) - SPI_PAD_CONFIG_WP (BLOCK1) SPI_PAD_configure WP(D2) = 0 R/W (0b000000) - SPI_PAD_CONFIG_DQS (BLOCK1) SPI_PAD_configure DQS = 0 R/W (0b000000) - SPI_PAD_CONFIG_D4 (BLOCK1) SPI_PAD_configure D4 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D5 (BLOCK1) SPI_PAD_configure D5 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D6 (BLOCK1) SPI_PAD_configure D6 = 0 R/W (0b000000) - SPI_PAD_CONFIG_D7 (BLOCK1) SPI_PAD_configure D7 = 0 R/W (0b000000) - - Usb fuses: - DIS_USB_OTG (BLOCK0) Set this bit to disable USB function = False R/W (0b0) - USB_EXCHG_PINS (BLOCK0) Set this bit to exchange USB D+ and D- pins = False R/W (0b0) - USB_EXT_PHY_ENABLE (BLOCK0) Set this bit to enable external PHY = False R/W (0b0) - DIS_USB_JTAG (BLOCK0) Set this bit to disable function of usb switch to = False R/W (0b0) - jtag in module of usb device - DIS_USB_SERIAL_JTAG (BLOCK0) Set this bit to disable usb device = False R/W (0b0) - USB_PHY_SEL (BLOCK0) This bit is used to switch internal PHY and extern - = internal PHY is assigned to USB Device while external PHY is assigned to USB OTG R/W (0b0) - al PHY for USB OTG and USB Device - DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) USB printing = Enable R/W (0b0) - DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Set this bit to disable UART download mode through = False R/W (0b0) - USB - DIS_USB_OTG_DOWNLOAD_MODE (BLOCK0) Set this bit to disable download through USB-OTG = False R/W (0b0) - - Vdd fuses: - VDD_SPI_XPD (BLOCK0) SPI regulator power up signal = False R/W (0b0) - VDD_SPI_TIEH (BLOCK0) If VDD_SPI_FORCE is 1; determines VDD_SPI voltage - = VDD_SPI connects to 1.8 V LDO R/W (0b0) - VDD_SPI_FORCE (BLOCK0) Set this bit and force to use the configuration of = False R/W (0b0) - eFuse to configure VDD_SPI - - Wdt fuses: - WDT_DELAY_SEL (BLOCK0) RTC watchdog timeout threshold; in unit of slow cl = 40000 R/W (0b00) - ock cycle - - Flash voltage (VDD_SPI) determined by GPIO45 on reset (GPIO45=High: VDD_SPI pin is powered from internal 1.8V LDO - GPIO45=Low or NC: VDD_SPI pin is powered directly from VDD3P3_RTC_IO via resistor Rspi. Typically this voltage is 3.3 V). diff --git a/docs/en/espefuse/inc/summary_ESP32.rst b/docs/en/espefuse/inc/summary_ESP32.rst deleted file mode 100644 index 59f303815..000000000 --- a/docs/en/espefuse/inc/summary_ESP32.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. code-block:: none - - > espefuse.py -p PORT summary - - Connecting........__ - Detecting chip type... ESP32 - - === Run "summary" command === - EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) - ---------------------------------------------------------------------------------------- - Calibration fuses: - ADC_VREF (BLOCK0): True ADC reference voltage = 1121 R/W (0b00011) - - Config fuses: - WR_DIS (BLOCK0): Efuse write disable mask = 0 R/W (0x0000) - RD_DIS (BLOCK0): Disable reading from BlOCK1-3 = 0 R/W (0x0) - DISABLE_APP_CPU (BLOCK0): Disables APP CPU = False R/W (0b0) - DISABLE_BT (BLOCK0): Disables Bluetooth = False R/W (0b0) - DIS_CACHE (BLOCK0): Disables cache = False R/W (0b0) - CHIP_CPU_FREQ_LOW (BLOCK0): If set alongside EFUSE_RD_CHIP_CPU_FREQ_RATED; the = False R/W (0b0) - ESP32's max CPU frequency is rated for 160MHz. 24 - 0MHz otherwise - CHIP_CPU_FREQ_RATED (BLOCK0): If set; the ESP32's maximum CPU frequency has been = True R/W (0b1) - rated - BLK3_PART_RESERVE (BLOCK0): BLOCK3 partially served for ADC calibration data = False R/W (0b0) - CLK8M_FREQ (BLOCK0): 8MHz clock freq override = 51 R/W (0x33) - VOL_LEVEL_HP_INV (BLOCK0): This field stores the voltage level for CPU to run = 0 R/W (0b00) - at 240 MHz; or for flash/PSRAM to run at 80 MHz.0 - x0: level 7; 0x1: level 6; 0x2: level 5; 0x3: leve - l 4. (RO) - CODING_SCHEME (BLOCK0): Efuse variable block length scheme - = NONE (BLK1-3 len=256 bits) R/W (0b00) - CONSOLE_DEBUG_DISABLE (BLOCK0): Disable ROM BASIC interpreter fallback = True R/W (0b1) - DISABLE_SDIO_HOST (BLOCK0): = False R/W (0b0) - DISABLE_DL_CACHE (BLOCK0): Disable flash cache in UART bootloader = False R/W (0b0) - - Flash fuses: - FLASH_CRYPT_CNT (BLOCK0): Flash encryption is enabled if this field has an o = 0 R/W (0b0000000) - dd number of bits set - FLASH_CRYPT_CONFIG (BLOCK0): Flash encryption config (key tweak bits) = 0 R/W (0x0) - - Identity fuses: - CHIP_PACKAGE_4BIT (BLOCK0): Chip package identifier #4bit = False R/W (0b0) - CHIP_PACKAGE (BLOCK0): Chip package identifier = 1 R/W (0b001) - CHIP_VER_REV1 (BLOCK0): bit is set to 1 for rev1 silicon = True R/W (0b1) - CHIP_VER_REV2 (BLOCK0): = True R/W (0b1) - WAFER_VERSION_MINOR (BLOCK0): = 0 R/W (0b00) - WAFER_VERSION_MAJOR (BLOCK0): calc WAFER VERSION MAJOR from CHIP_VER_REV1 and CH = 3 R/W (0b011) - IP_VER_REV2 and apb_ctl_date (read only) - PKG_VERSION (BLOCK0): calc Chip package = CHIP_PACKAGE_4BIT << 3 + CHIP_ = 1 R/W (0x1) - PACKAGE (read only) - - Jtag fuses: - JTAG_DISABLE (BLOCK0): Disable JTAG = False R/W (0b0) - - Mac fuses: - MAC (BLOCK0): MAC address - = 94:b9:7e:5a:6e:58 (CRC 0xe2 OK) R/W - MAC_CRC (BLOCK0): CRC8 for MAC address = 226 R/W (0xe2) - MAC_VERSION (BLOCK3): Version of the MAC field = 0 R/W (0x00) - - Security fuses: - UART_DOWNLOAD_DIS (BLOCK0): Disable UART download mode. Valid for ESP32 V3 and = False R/W (0b0) - newer; only - ABS_DONE_0 (BLOCK0): Secure boot V1 is enabled for bootloader image = False R/W (0b0) - ABS_DONE_1 (BLOCK0): Secure boot V2 is enabled for bootloader image = False R/W (0b0) - DISABLE_DL_ENCRYPT (BLOCK0): Disable flash encryption in UART bootloader = False R/W (0b0) - DISABLE_DL_DECRYPT (BLOCK0): Disable flash decryption in UART bootloader = False R/W (0b0) - KEY_STATUS (BLOCK0): Usage of efuse block 3 (reserved) = False R/W (0b0) - SECURE_VERSION (BLOCK3): Secure version for anti-rollback = 0 R/W (0x00000000) - BLOCK1 (BLOCK1): Flash encryption key - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK2 (BLOCK2): Security boot key - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - BLOCK3 (BLOCK3): Variable Block 3 - = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W - - Spi Pad fuses: - SPI_PAD_CONFIG_HD (BLOCK0): read for SPI_pad_config_hd = 0 R/W (0b00000) - SPI_PAD_CONFIG_CLK (BLOCK0): Override SD_CLK pad (GPIO6/SPICLK) = 0 R/W (0b00000) - SPI_PAD_CONFIG_Q (BLOCK0): Override SD_DATA_0 pad (GPIO7/SPIQ) = 0 R/W (0b00000) - SPI_PAD_CONFIG_D (BLOCK0): Override SD_DATA_1 pad (GPIO8/SPID) = 0 R/W (0b00000) - SPI_PAD_CONFIG_CS0 (BLOCK0): Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0b00000) - - Vdd fuses: - XPD_SDIO_REG (BLOCK0): read for XPD_SDIO_REG = False R/W (0b0) - XPD_SDIO_TIEH (BLOCK0): If XPD_SDIO_FORCE & XPD_SDIO_REG = 1.8V R/W (0b0) - XPD_SDIO_FORCE (BLOCK0): Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = False R/W (0b0) - - Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V) diff --git a/docs/en/espefuse/index.rst b/docs/en/espefuse/index.rst deleted file mode 100644 index 7c8c40c88..000000000 --- a/docs/en/espefuse/index.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. _espefuse: - -espefuse.py -=========== - -``espefuse.py`` is a tool for communicating with Espressif chips for the purpose of reading/writing ("burning") the one-time-programmable eFuses. Burning occurs only in one direction from 0 to 1 (never cleared 1->0). - -.. warning:: - - Because eFuse is one-time-programmable, it is possible to permanently damage or "brick" your {IDF_TARGET_NAME} using this tool. Use it with great care. - -For more details about Espressif chips eFuse features, see the `Technical Reference Manual `__. - -``espefuse.py`` is installed alongside ``esptool.py``, so if ``esptool.py`` (v2.0 or newer) is available on the PATH then ``espefuse.py`` should be as well. - -Initial State of Efuses ------------------------ - -On relatively new chip, most eFuses are unburned (value 0). Some eFuses are already burned at the factory stage: - -- MAC (Factory MAC Address). -- ADC calibration -- Chip package and revision. -- etc. - -Supported Commands ------------------- - -.. toctree:: - :maxdepth: 1 - - dump - summary - burn_efuse - burn_block_data - burn_bit - read_protect_efuse and write_protect_efuse - burn_key - burn_key_digest - burn_custom_mac - get_custom_mac - adc_info - set_flash_voltage - execute_scripts - check_error - -Optional General Arguments Of Commands --------------------------------------- - -- ``-h``, ``--help`` - Show help message and exit. Use ``-h`` to see a summary of all available commands and command line options. To see all options for a particular chip and command, add ``-c {IDF_TARGET_NAME}`` and ``-h`` to the command name, i.e. ``espefuse.py -c {IDF_TARGET_NAME} burn_key -h``. -- ``--chip``, ``-c`` - Target chip type. If this argument is omitted, the tool automatically detects the chip type when connected. But if the command has a help option, the chip is not connected, and the default chip is ``esp32``, please specify the specific type of chip to get the correct help. Example of usage: ``-c esp32``, ``-c esp32c3``, ``-c esp32s2`` and others. -- ``--baud``, ``-b`` - Serial port baud rate, the same as for esptool. -- ``--port``, ``-p`` - Serial port device, ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows). -- ``--before`` - What to do before connecting to the chip: ``default_reset``, ``no_reset``, ``esp32r1``, ``no_reset_no_sync``. -- ``--debug``, ``-d`` - Show debugging information. -- ``--virt`` - For host tests. The tool will work in the virtual mode (without connecting to a chip). -- ``--path-efuse-file`` - For host tests. Use it together with ``--virt`` option. The tool will work in the virtual mode (without connecting to a chip) and save eFuse memory to a given file. If the file does not exists the tool creates it. To reset written eFuses just delete the file. Usage: ``--path-efuse-file efuse_memory.bin``. -- ``--do-not-confirm`` - Do not pause for confirmation before permanently writing eFuses. Use with caution. If this option is not used, a manual confirmation step is required, you need to enter the word ``BURN`` to continue burning. - -Virtual mode -^^^^^^^^^^^^ - -This mode is enabled with the ``--virt`` flag (need to specify chip with ``--chip``). This helps to test commands without physical access to the chip. Burned data is not saved between commands. Using ``--path-efuse-file``, you can save the written data to a file. Delete the file to clear eFuses. - -Confirmation -^^^^^^^^^^^^ - -Each burn operation requires manual confirmation, you need to type the word ``BURN`` to continue burning. Using the ``--do-not-confirm`` option allows to skip it. - -Coding Scheme -------------- - -The coding scheme helps the eFuse controller to detect an error of the eFuse blocks. There are special registers that indicate that there is an error in the block. - -{IDF_TARGET_NAME} supports the following coding schemes: - -.. only:: esp32 - - * ``None`` no need any special encoding data. BLOCK0. - * ``3/4``, requires encoding data. The BLOCK length is reduced from 256 bits to 192 bits. - * ``Repeat`` not supported by this tool and IDF. The BLOCK length is reduced from 256 bits to 128 bits. - - BLOCK1-3 can have any of this coding scheme. It depends on the ``CODING_SCHEME`` eFuse. - -.. only:: not esp32 - - * ``None`` no need any special encoding data, but internally it copies data four times. BLOCK0. - * ``RS`` (Reed-Solomon), it uses 6 bytes of automatic error correction. - - Rest eFuse blocks from BLOCK1 to BLOCK(max) have ``RS`` coding scheme. - -This tool automatically adds encoding data to the burning data if it requires. Encoded data is calculated individually for each block. - -All coding schemes (except ``None``) require additional encoding data to be provided at write time. Due to the encoding data, such blocks cannot be overwritten again without breaking the block's coding scheme. Use the :ref:`perform-multiple-operations` feature or list multiple eFuses/keys. - -Burning Efuse -------------- - -Burning occurs in order from BLOCK(max) to BLOCK0. This prevents read/write protection from being set before the data is set. After burning, the tool reads the written data back and compares the original data, and additionally checks the status of the coding scheme, if there are any errors, it re-burns the data again to correct it. - -.. _perform-multiple-operations: - -Perform Multiple Operations In A Single Espefuse Run ----------------------------------------------------- - -Some eFuse blocks have an encoding scheme (Reed-Solomon or 3/4) that requires encoded data, making these blocks only writable once. If you need to write multiple keys/eFuses to one block using different commands, you can use this feature - multiple commands. This feature burns given data once at the end of all commands. All commands supported by version v3.2 or later are supported to be chained together. - -The example below shows how to use the two commands ``burn_key_digest`` and ``burn_key`` to write the Secure Boot key and Flash Encryption key into one BLOCK3 for the ``ESP32-C2`` chip. Using these commands individually will result in only one key being written correctly. - -.. code-block:: none - - > espefuse.py -c esp32c2 \ - burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \ - burn_key BLOCK_KEY0 images/efuse/128bit_key.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS - -Recommendations ---------------- - -1. The `Technical Reference Manual `__ has a recommendation for reducing the number of burn operations as much as possible. The tool supports several ways to do this: - - - Combine multiple commands into one with this :ref:`perform-multiple-operations` feature. - - Most commands support getting a list of arguments (eFuse names, keys). - -3. Make sure the power supply is stable because this may cause burning problems. diff --git a/docs/en/espefuse/read-write-protections-cmd.rst b/docs/en/espefuse/read-write-protections-cmd.rst deleted file mode 100644 index c6c6364cb..000000000 --- a/docs/en/espefuse/read-write-protections-cmd.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _read-write-protections-cmd: - -Read Write Protection -===================== - -There are two commands (to get the correct list of eFuse fields that can be protected, specify the chip with ``--chip``): - -- ``espefuse.py read_protect_efuse``. It sets read protection for given eFuse names. -- ``espefuse.py write_protect_efuse``. It sets write protection for given eFuse names. - -Positional arguments: - -- eFuse name. It can recieve a list of eFuse names (like EFUSE_NAME1 EFUSE_NAME2 etc.). - -Read protection prevents software from reading eFuse fields, only hardware can access such eFuses. Such eFuses are read as zero and the data is marked as ``??`` in this tool. - -Write protection prevents further changes of eFuse fields. - -Not all eFuses have read and write protections. See the help for these commands for the eFuse names that can be protected. - -eFuses are often read/write protected as a group, so protecting one of eFuse will result in some related eFuses becoming protected. The tool will show the full list of eFuses that will be protected. - -Read and Write Protection Status -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``R/W`` output indicates a protection status of a specific eFuse field/block: - -- ``-/W`` indicates that read protection is set. Value of such eFuse field will always show all-zeroes, even though hardware may use the correct value. In espefuse v2.6 and newer, read-protected eFuse values are displayed as question marks (``??``). On earlier versions, they are displayed as zeroes. - - .. code-block:: none - - BLOCK1 (BLOCK1): - = ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/W - -- ``R/-`` indicates that write protection is set. No further bits can be set. -- ``-/-`` means both read and write protection are set. - -Usage ------ - -.. code-block:: none - - > espefuse.py read_protect_efuse BLOCK2 BLOCK3 MAC_VERSION - - === Run "read_protect_efuse" command === - If Secure Boot V2 is used, BLOCK2 must be readable, please stop this operation! - Permanently read-disabling efuse BLOCK2 - Permanently read-disabling efuses MAC_VERSION, BLOCK3 - Permanently read-disabling efuses MAC_VERSION, BLOCK3 - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Checking efuses... - Successful - -.. code-block:: none - - > espefuse.py write_protect_efuse WR_DIS FLASH_CRYPT_CNT - - === Run "write_protect_efuse" command === - Permanently write-disabling efuse WR_DIS - Permanently write-disabling efuses FLASH_CRYPT_CNT, UART_DOWNLOAD_DIS - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Checking efuses... - Successful diff --git a/docs/en/espefuse/set-flash-voltage-cmd.rst b/docs/en/espefuse/set-flash-voltage-cmd.rst deleted file mode 100644 index 719a76c6c..000000000 --- a/docs/en/espefuse/set-flash-voltage-cmd.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _set-flash-voltage-cmd: - -Set Flash Voltage -================= - -{IDF_TARGET_VDD_SPI:default="VDD_SPI",esp32="VDD_SDIO"} -{IDF_TARGET_VDD_FORCE:default="VDD_SPI_FORCE",esp32="XPD_SDIO_FORCE"} -{IDF_TARGET_VDD_TIEH:default="VDD_SPI_TIEH",esp32="XPD_SDIO_TIEH"} -{IDF_TARGET_VDD_REG:default="VDD_SPI_XPD",esp32="XPD_SDIO_REG"} -{IDF_TARGET_VDD_GPIO:default="GPIO45",esp32="GPIO12"} - -The ``espefuse.py set_flash_voltage`` command permanently sets the internal flash voltage regulator to either 1.8V, 3.3V or OFF. This means a GPIO can be high or low at reset without changing the flash voltage. - -Positional arguments: - -- ``voltage`` - Voltage selection ['1.8V', '3.3V', 'OFF']. - -.. only:: esp32c2 or esp32c3 - - .. note:: - - This command is not supported. The tool prints the error ``set_flash_voltage not supported!``. - -Setting Flash Voltage ({IDF_TARGET_VDD_SPI}) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After reset, the default {IDF_TARGET_NAME} behaviour is to enable and configure the flash voltage regulator ({IDF_TARGET_VDD_SPI}) based on the level of the MTDI pin ({IDF_TARGET_VDD_GPIO}). - -The default behaviour on reset is: - -+--------------------+--------------------+ -| MTDI | Internal Regulator | -+====================+====================+ -| Low or unconnected | Enabled at 3.3V | -+--------------------+--------------------+ -| High | Enabled at 1.8V | -+--------------------+--------------------+ - -.. only:: esp32 - - Consult ESP32 Technical Reference Manual chapter 4.8.1 "{IDF_TARGET_VDD_SPI} Power Domain" for details. - -.. only:: not esp32 - - Consult {IDF_TARGET_NAME} Technical Reference Manual for details. - -A combination of 3 efuses (``{IDF_TARGET_VDD_FORCE}``, ``{IDF_TARGET_VDD_REG}``, ``{IDF_TARGET_VDD_TIEH}``) can be burned in order to override this behaviour and disable {IDF_TARGET_VDD_SPI} regulator, or set it to a fixed voltage. These efuses can be burned with individual ``burn_efuse`` commands, but the ``set_flash_voltage`` command makes it easier: - -Disable {IDF_TARGET_VDD_SPI} Regulator -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - espefuse.py set_flash_voltage OFF - -Once set: - -* {IDF_TARGET_VDD_SPI} regulator always disabled. -* MTDI pin ({IDF_TARGET_VDD_GPIO}) is ignored. -* Flash must be powered externally and voltage supplied to {IDF_TARGET_VDD_SPI} pin of {IDF_TARGET_NAME}. -* Efuse ``{IDF_TARGET_VDD_FORCE}`` is burned. - -Fixed 1.8V {IDF_TARGET_VDD_SPI} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - espefuse.py set_flash_voltage 1.8V - -Once set: - -* {IDF_TARGET_VDD_SPI} regulator always enables at 1.8V. -* MTDI pin ({IDF_TARGET_VDD_GPIO}) is ignored. -* External voltage should not be supplied to {IDF_TARGET_VDD_SPI}. -* Efuses ``{IDF_TARGET_VDD_FORCE}`` and ``{IDF_TARGET_VDD_REG}`` are burned. - -Fixed 3.3V {IDF_TARGET_VDD_SPI} -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - espefuse.py set_flash_voltage 3.3V - -Once set: - -* {IDF_TARGET_VDD_SPI} regulator always enables at 3.3V. -* MTDI pin ({IDF_TARGET_VDD_GPIO}) is ignored. -* External voltage should not be supplied to {IDF_TARGET_VDD_SPI}. -* Efuses ``{IDF_TARGET_VDD_FORCE}``, ``{IDF_TARGET_VDD_REG}``, ``{IDF_TARGET_VDD_TIEH}`` are burned. - -Subsequent Changes -^^^^^^^^^^^^^^^^^^ - -Once an efuse is burned it cannot be un-burned. However, changes can be made by burning additional efuses: - -* ``set_flash_voltage OFF`` can be changed to ``1.8V`` or ``3.3V`` -* ``set_flash_voltage 1.8V`` can be changed to ``3.3V`` - - -.. only:: esp32s2 or esp32s3 - - .. code-block:: none - - > espefuse.py set_flash_voltage 1.8V - - === Run "set_flash_voltage" command === - Set internal flash voltage regulator (VDD_SPI) to 1.8V. - - VDD_SPI setting complete. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - - .. code-block:: none - - > espefuse.py set_flash_voltage 3.3V - - === Run "set_flash_voltage" command === - Enable internal flash voltage regulator (VDD_SPI) to 3.3V. - - VDD_SPI setting complete. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful - - - .. code-block:: none - - > espefuse.py set_flash_voltage OFF - - === Run "set_flash_voltage" command === - Disable internal flash voltage regulator (VDD_SPI). SPI flash will - VDD_SPI setting complete. - - Check all blocks for burn... - idx, BLOCK_NAME, Conclusion - [00] BLOCK0 is empty, will burn the new value - . - This is an irreversible operation! - Type 'BURN' (all capitals) to continue. - BURN - BURN BLOCK0 - OK (write block == read block) - Reading updated efuses... - Successful diff --git a/docs/en/espefuse/summary-cmd.rst b/docs/en/espefuse/summary-cmd.rst deleted file mode 100644 index 5e5d46962..000000000 --- a/docs/en/espefuse/summary-cmd.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _summary-cmd: - -Summary -======= - -The ``espefuse.py summary`` command reads all eFuses from the chip and outputs them in text or json format. It is also possible to save it to a file. - -Optional arguments: - -- ``--format`` - Select the summary format: ``summary`` - text format (default option), ``json`` - json format. Usage ``--format json``. -- ``--file`` - File to save the efuse summary. Usage ``--file efuses.json``. - -Text Format Summary -------------------- - -The text format of summary consists of 3 main columns: - -1. This column consists of the eFuse name and additional information: the block name associated with this eFuse field and encoding errors (if any). -2. Description of eFuse field. -3. This column has human readable value, read/write protection status, raw value (hexadecimal or binary). - -Read and Write Protection Status -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``R/W`` output indicates a protection status of a specific eFuse field/block: - -- ``-/W`` indicates that read protection is set. Value of such eFuse field will always show all-zeroes, even though hardware may use the correct value. In espefuse v2.6 and newer, read-protected eFuse values are displayed as question marks (``??``). On earlier versions, they are displayed as zeroes. - - .. code-block:: none - - BLOCK1 (BLOCK1): - = ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/W - -- ``R/-`` indicates that write protection is set. No further bits can be set. -- ``-/-`` means both read and write protection are set. - -Some eFuses have no protection at all, and some eFuses have only one read or write protection. There is no mark in the summary to expose it. - -Display Efuse Summary -^^^^^^^^^^^^^^^^^^^^^ - -The eFuse summary may vary from version to version of this tool and differ for different chips. Below is the summary for the {IDF_TARGET_NAME} chip. - -For details on the meaning of each eFuse value, refer to the `Technical Reference Manual `__. - -.. include:: inc/summary_{IDF_TARGET_NAME}.rst - -Json Format Summary -------------------- - -The json representation of eFuses for the ESP32 chip is shown below. - -.. code-block:: none - - > espefuse.py summary --format json - - { - "ABS_DONE_0": { - "bit_len": 1, - "block": 0, - "category": "security", - "description": "Secure boot V1 is enabled for bootloader image", - "efuse_type": "bool", - "name": "ABS_DONE_0", - "pos": 4, - "readable": true, - "value": false, - "word": 6, - "writeable": true - }, - "BLOCK1": { - "bit_len": 256, - "block": 1, - "category": "security", - "description": "Flash encryption key", - "efuse_type": "bytes:32", - "name": "BLOCK1", - "pos": 0, - "readable": true, - "value": "00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00", - "word": 0, - "writeable": true - }, - ... - "CODING_SCHEME": { - "bit_len": 2, - "block": 0, - "category": "efuse", - "description": "Efuse variable block length scheme", - "efuse_type": "uint:2", - "name": "CODING_SCHEME", - "pos": 0, - "readable": true, - "value": "NONE (BLK1-3 len=256 bits)", - "word": 6, - "writeable": true - }, - .... - } - -Save Json Format Summary To File --------------------------------- - -.. code-block:: none - - > espefuse.py summary --format json --file efuses.json - - Connecting.......... - Detecting chip type... Unsupported detection protocol, switching and trying again... - Connecting.... - Detecting chip type... ESP32 - - === Run "summary" command === - Saving efuse values to efuses.json diff --git a/docs/en/espsecure/index.rst b/docs/en/espsecure/index.rst deleted file mode 100644 index c03b3478e..000000000 --- a/docs/en/espsecure/index.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _espsecure: - -espsecure.py -============ - -``espsecure.py`` is a tool for manipulating data that relates to the secure boot and flash encryption features of ESP32 and later Espressif chips. - -For more details, see the ESP-IDF documentation which explains this tool and how to use it to enable the relevant features: - -* `Secure Boot `_ -* `Flash Encryption `_ - -.. _hsm_signing: - -Remote Signing using an external HSM ------------------------------------- - -An external Hardware Security Module (HSM) can be used for remote signing of images in secure boot v2 scheme. - -You must install ``esptool.py`` package with the ``hsm`` extra using the command ``pip install 'esptool[hsm]'`` to use this feature. ``esp_hsm_sign`` provides a PKCS #11 interface to communicate with the external HSM and is integrated in ``espsecure.py``. - -The following command should be used to get an image signed using an external HSM. :: - - python espsecure.py sign_data --version 2 --hsm --hsm-config --output - -The above command first extracts the public key from the HSM, generates a signature for an image using the HSM, and then creates a signature block and appends it to the image to generate a signed image. - -If the public key is not stored in the external HSM, you can specify the ``--pub-key`` argument to supply the public key. :: - - python espsecure.py sign_data --version 2 --hsm --hsm-config --pub-key --output - -.. note:: - In case you are using ESP-IDF, then an unsigned application can be generated by disabling ``CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES`` configuration option in the project settings. - -Verifying the Signed Image -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once the signed image is generated, we can verify it using the following command: :: - - python espsecure.py verify_signature --version 2 --hsm --hsm-config - -If the public key is not stored in the external HSM, you can specify the ``--keyfile`` argument to supply the public key. :: - - python espsecure.py verify_signature --version 2 --keyfile - - -HSM config file -~~~~~~~~~~~~~~~ - -An HSM config file is required with the fields (``pkcs11_lib``, ``credentials``, ``slot``, ``label``, ``label_pubkey``) -populated corresponding to the HSM used. - -To access an HSM token of a selected slot, you will also need to pass in the token User PIN and thus you will be prompted to type in the User PIN. -Alternatively, you could also add a ``credentials`` field in the HSM config file to store the (plaintext) User PIN to automate the signing workflow. - -Below is a sample HSM config file (``hsm_config.ini``) for using `SoftHSMv2 `_ as an external HSM: :: - - # hsm_config.ini - - # Config file for the external Hardware Security Module - # to be used to generate signature. - - [hsm_config] - - # PKCS11 shared object/library module of the HSM vendor - pkcs11_lib = /usr/local/lib/softhsm/libsofthsm2.so - - # HSM login credentials - credentials = 1234 - - # Slot number to be used - slot = 1108821954 - - # Label of the object used to store the private key - label = Private Key for Digital Signature - - # Label of the object used to store corresponding public key - # label_pubkey is the same as label if the label for public key - # is not explicitly specified while key-pair generation. - label_pubkey = Public Key for Digital Signature diff --git a/docs/en/esptool/advanced-commands.rst b/docs/en/esptool/advanced-commands.rst deleted file mode 100644 index bfc9d2c0c..000000000 --- a/docs/en/esptool/advanced-commands.rst +++ /dev/null @@ -1,160 +0,0 @@ -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - -.. _advanced-commands: - -Advanced Commands -================= - -The ``write_flash``, ``read_flash``, ``erase_flash``, ``erase_region``, ``read_mac``, ``flash_id``, ``elf2image``, ``image_info`` and ``merge_bin`` commands are all documented in the :ref:`commands` section. - -The following less common commands are for more advanced users. - -.. _verify-flash: - -Verify Flash Data: verify_flash -------------------------------- - -The ``verify_flash`` command allows you to verify that data in flash matches a local file. - -The ``write_flash`` command always verifies the MD5 hash of data which is written to flash, so additional verification is not usually needed. However, if you wish to perform a byte-by-byte verification of the flash contents (and optionally print the differences to the console) then you can do so with this command: - -:: - - esptool.py verify_flash --diff yes 0x40000 my_app.elf-0x40000.bin - - -The ``--diff yes`` option specifies that if the files are different, the details should be printed to the console. - -.. note:: - - .. list:: - - * If verifying a default boot image (offset {IDF_TARGET_BOOTLOADER_OFFSET} for {IDF_TARGET_NAME}) then any ``--flash_mode``, ``--flash_size`` and ``--flash_freq`` arguments which were passed to `write_flash` must also be passed to ``verify_flash``. Otherwise, ``verify_flash`` will detect mismatches in the header of the image file. - * Another way to compare flash contents is to use the ``read_flash`` command, and then use binary diffing tools on the host. - -.. _dump-mem: - -Dump a Memory Region to File: dump_mem --------------------------------------- - -The ``dump_mem`` command will dump a region from the chip's memory space to a file. For example, to dump the ROM (64 kB) from an ESP8266: - -:: - - esptool.py dump_mem 0x40000000 65536 iram0.bin - -.. _load-ram: - -Load a Binary to RAM: load_ram ------------------------------- - -The ``load_ram`` command allows the loading of an executable binary image (created with the ``elf2image`` or ``make_image`` commands) directly into RAM, and then immediately executes the program contained within it. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files. - -:: - - esptool.py --no-stub load_ram ./test/images/helloworld-esp8266.bin - -.. note:: - - * The binary image must only contain IRAM- and DRAM-resident segments. Any SPI flash mapped segments will not load correctly and the image will probably crash. The ``image_info`` command can be used to check the binary image contents. - * Because the software loader is resident in IRAM and DRAM, this limits the region where a new program may be loaded. An error will be printed if the new program overlaps with the software loader in RAM. Older esptool versions may hang. Pass ``esptool.py --no-stub`` to avoid this problem. - * Due to a limitation in the ROM loader, when using ``--no-stub`` any very early serial output from a program may be lost if the program resets or reconfigures the UART. To avoid this problem, a program can be compiled with ``ets_delay_us(1)`` as the very first statement after the entry point. - -.. _read-mem-write-mem: - -Read or Write RAM: read_mem / write_mem ---------------------------------------- - -The ``read_mem`` & ``write_mem`` commands allow reading and writing single words (4 bytes) of RAM. This can be used to "peek" and "poke" at registers. - -:: - - esptool.py write_mem 0x400C0000 0xabad1dea - -:: - - esptool.py read_mem 0x400C0000 - -.. _read-flash-status: - -Read Flash Chip Registers: read_flash_status --------------------------------------------- - -This command is intended for use when debugging hardware flash chip-related problems. It allows sending a ``RDSR``, ``RDSR2`` and/or ``RDSR3`` commands to the flash chip to read the status register contents. This can be used to check write protection status, for example: - -:: - - esptool.py read_flash_status --bytes 2 - -The ``--bytes`` argument determines how many status register bytes are read. - -* ``--bytes 1`` sends the most common ``RDSR`` command (05h) and returns a single byte of status. -* ``--bytes 2`` sends both ``RDSR`` (05h) and ``RDSR2`` (35h), reads one byte of status from each, and returns a two byte status. -* ``--bytes 3`` sends ``RDSR`` (05h), ``RDSR2`` (35h), and ``RDSR3`` (15h), reads one byte of status from each, and returns a 3 byte status. - -.. note:: - - Not all flash chips support all of these comands. Consult the specific flash chip datasheet for details. - -.. _write-flash-status: - -Write Flash Chip Registers: write_flash_status ------------------------------------------------ - -This command is intended for use when debugging hardware flash chip-related problems. It allows sending ``WRSR``, ``WRSR2`` and/or ``WRSR3`` commands to the flash chip to write the status register contents. This can be used to clear write protection bits, for example: - -:: - - esptool.py write_flash_status --bytes 2 --non-volatile 0 - -The ``--bytes`` option is similar to the corresponding option for ``read_flash_status`` and causes a mix of ``WRSR`` (01h), ``WRSR2`` (31h), and ``WRSR3`` (11h) commands to be sent to the chip. If ``--bytes 2`` is used then ``WRSR`` is sent first with a 16-bit argument and then with an 8-bit argument, as different flash chips use this command differently. -Otherwise, each command is accompanied by 8-bits of the new status register value. - -A second option ``--non-volatile`` can be used in order to send a ``WREN`` (06h) command before writing the status. This may allow non-volatile status register bits to be set or cleared. If the ``--non-volatile`` option is not supplied, a ``WEVSR`` (50h) command is sent instead of ``WREN``. - -.. note:: - - Consult the specific flash chip datasheet for details about which commands are recognised by a particular chip. - -.. warning:: - - Setting status bits (particularly non-volatile ones) can have permanent side effects for some flash chips, so check carefully before using this command to set any bits! - -.. only:: esp8266 - - .. _chip-id: - - Read the Chip ID: chip_id - ------------------------- - - The ``chip_id`` command allows you to read a 4 byte ID which forms part of the MAC address. It is usually better to use ``read_mac`` to identify a chip. - - On {IDF_TARGET_NAME}, output is the same as the ``system_get_chip_id()`` SDK function. The chip ID is four bytes long, the lower three bytes are the final bytes of the MAC address. The upper byte is zero. - - :: - - esptool.py chip_id - - .. _make-image: - - Assemble a Firmware Image: make_image - ------------------------------------- - - ``make_image`` allows you to manually assemble a firmware image from binary segments (such as those extracted from objcopy). For example: - - :: - - esptool.py --chip esp8266 make_image -f app.text.bin -a 0x40100000 -f app.data.bin -a 0x3ffe8000 -f app.rodata.bin -a 0x3ffe8c00 app.flash.bin - - This command does not require a serial connection. - - .. note:: - - In general, it is better to create an ELF image (including any binary data as part of the ELF, by using objcopy or other tools) and then use ``elf2image`` to generate the ``.bin`` file. - - .. _run: - - Boot Application Code: run - -------------------------- - - The ``run`` command immediately exits the bootloader and attempts to boot the normal application code. diff --git a/docs/en/esptool/advanced-options.rst b/docs/en/esptool/advanced-options.rst deleted file mode 100644 index d47ab515a..000000000 --- a/docs/en/esptool/advanced-options.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. _advanced-options: - -Advanced Options -================ - -The following advanced configuration options can be used for all esptool commands (they are placed before the command name on the command line). - -For basic/fundamental configuration options, see the :ref:`options` page. - -Reset Modes ------------ - -By default, esptool tries to hard reset the chip into bootloader mode before it starts and hard resets the chip to run the normal program once it is complete. The ``--before`` and ``--after`` options allow this behavior to be changed: - -Reset Before Operation -^^^^^^^^^^^^^^^^^^^^^^ - -The ``--before`` argument allows you to specify whether the chip needs resetting into bootloader mode before esptool talks to it. - -.. list:: - - * ``--before default_reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode. - * ``--before no_reset`` will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled. - * ``--before no_reset_no_sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader ` and you want to avoid resetting the chip and uploading the stub again. - :esp32c3 or esp32s3 or esp32c6 or esp32h2: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial. - -Reset After Operation -^^^^^^^^^^^^^^^^^^^^^ - -The ``--after`` argument allows you to specify whether the chip should be reset after the esptool operation completes: - -.. list:: - - * ``--after hard_reset`` is the default. The DTR serial control line is used to reset the chip into a normal boot sequence. - :esp8266:* ``--after soft_reset`` This runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool v1.x. - * ``--after no_reset`` leaves the chip in the serial bootloader, no reset is performed. - * ``--after no_reset_stub`` leaves the chip in the stub bootloader, no reset is performed. - -.. _disable_stub: - -Disabling the Stub Loader -------------------------- - -The ``--no-stub`` option disables uploading of a software "stub loader" that manages flash operations, and only talks directly to the loader in ROM. - -Passing ``--no-stub`` will disable certain options, as not all options are implemented in every chip's ROM loader. - -.. only:: esp32 - - Overriding SPI Flash Connections - -------------------------------- - - The optional ``--spi-connection`` argument overrides the SPI flash connection configuration on ESP32. This means that the SPI flash can be connected to other pins, or esptool can be used to communicate with a different SPI flash chip to the default. - - Supply the ``--spi-connection`` argument after the ``esptool.py`` command, ie ``esptool.py flash_id --spi-connection HSPI``. - - Default Behavior - ^^^^^^^^^^^^^^^^ - - If the ``--spi-connection`` argument is not provided, the SPI flash is configured to use :ref:`pin numbers set in efuse `. These are the same SPI flash pins that are used during a normal boot. - - The only exception to this is if the ``--no-stub`` option is also provided. In this case, efuse values are ignored and ``--spi-connection`` will default to ``--spi-connection SPI`` unless set to a different value. - - SPI Mode - ^^^^^^^^ - - ``--spi-connection SPI`` uses the default SPI pins: - - * CLK = GPIO 6 - * Q = GPIO 7 - * D = GPIO 8 - * HD = GPIO 9 - * CS = GPIO 11 - - During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is not pulled low (default). - - This is the normal pin configuration for ESP32 chips that do not contain embedded flash. - - HSPI Mode - ^^^^^^^^^ - - ``--spi-connection HSPI`` uses the HSPI peripheral instead of the SPI peripheral for SPI flash communications, via the following HSPI pins: - - * CLK = GPIO 14 - * Q = GPIO 12 - * D = GPIO 13 - * HD = GPIO 4 - * CS = GPIO 15 - - During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is pulled low on reset. - - Custom SPI Pin Configuration - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - ``--spi-connection ,,,,`` allows a custom list of pins to be configured for the SPI flash connection. This can be used to emulate the flash configuration equivalent to a particular set of SPI pin efuses being burned. The values supplied are GPIO numbers. - - For example, ``--spi-connection 6,17,8,11,16`` sets an identical configuration to the factory efuse configuration for ESP32s with embedded flash. - - When setting a custom pin configuration, the SPI peripheral (not HSPI) will be used unless the ``CLK`` pin value is set to 14 (HSPI CLK), in which case the HSPI peripheral will be used. - -Specifying Arguments via File ------------------------------ -.. _specify_arguments_via_file: - -Anywhere on the esptool command line, you can specify a file name as ``@filename.txt`` to read one or more arguments from text file ``filename.txt``. Arguments can be separated by newlines or spaces, quotes can be used to enclose arguments that span multiple words. Arguments read from the text file are expanded exactly as if they had appeared in that order on the esptool command line. - -An example of this is available in the :ref:`merge_bin ` command description. - -.. note:: PowerShell users - - Because of `splatting `__ in PowerShell (method of passing a collection of parameter values to a command as a unit) there is a need to add quotes around @filename.txt ("@filename.txt") to be correctly resolved. diff --git a/docs/en/esptool/basic-commands.rst b/docs/en/esptool/basic-commands.rst deleted file mode 100644 index ead5ac208..000000000 --- a/docs/en/esptool/basic-commands.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. _commands: - -Basic Commands -============== - -Write Binary Data to Flash: write_flash ----------------------------------------- - -Binary data can be written to the ESP's flash chip via the serial ``write_flash`` command: - -:: - - esptool.py --port COM4 write_flash 0x1000 my_app-0x01000.bin - -Multiple flash addresses and file names can be given on the same command line: - -:: - - esptool.py --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin - -The ``--chip`` argument is optional when writing to flash, esptool will detect the type of chip when it connects to the serial port. - -The ``--port`` argument is documented under :ref:`serial-port`. - -.. only:: esp8266 - - The next arguments to ``write_flash`` are one or more pairs of offset (address) and file name. When generating ESP8266 "version 1" images, the file names created by ``elf2image`` include the flash offsets as part of the file name. - For other types of images, consult your SDK documentation to determine the files to flash at which offsets. - -.. only:: not esp8266 - - The next arguments to ``write_flash`` are one or more pairs of offset (address) and file name. Consult your SDK documentation to determine the files to flash at which offsets. - -Numeric values passed to write_flash (and other commands) can be specified either in hex (ie 0x1000), or in decimal (ie 4096). - -See the :ref:`troubleshooting` section if the ``write_flash`` command is failing, or the flashed module fails to boot. - -Setting Flash Mode and Size -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You may also need to specify arguments for :ref:`flash mode and flash size `, if you wish to override the defaults. For example: - -:: - - esptool.py --port /dev/ttyUSB0 write_flash --flash_mode qio --flash_size 32m 0x0 bootloader.bin 0x1000 my_app.bin - -Since esptool v2.0, these options are not often needed as the default is to keep the flash mode and size from the ``.bin`` image file. See the :ref:`flash-modes` section for more details. - -Compression -^^^^^^^^^^^ - -By default, the serial transfer data is compressed for better performance. The ``-u/--no-compress`` option disables this behaviour. - -Erasing Flash Before Write -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To successfully write data into flash, all 4096-byte memory sectors (the smallest erasable unit) affected by the operation have to be erased first. As a result, when the flashing offset address or the data are not 4096-byte aligned, more memory is erased than actually needed. -Esptool will display information about which flash memory sectors will be erased. - -Use the ``-e/--erase-all`` option to erase all flash sectors (not just the write areas) before programming. - -.. only:: not esp8266 - - Bootloader Protection - ^^^^^^^^^^^^^^^^^^^^^ - - Flashing into the bootloader region (``0x0`` -> ``0x8000``) is disabled by default if active `Secure Boot `_ is detected. - This is a safety measure to prevent accidentally overwriting the secure bootloader, which **can ultimately lead to bricking the device**. - - This behavior can be overridden with the ``--force`` option. **Use this only at your own risk and only if you know what you are doing!** - - - Encrypted Flash Protection - ^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. only:: esp32 - - Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if `Flash Encryption `_ is enabled and Encrypted Download being disabled (efuse bit ``EFUSE_DISABLE_DL_ENCRYPT`` is set). - - .. only:: not esp32 - - Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if: - - * `Flash Encryption `_ and Secure Download Mode are enabled or - * `Flash Encryption `_ is enabled but Encrypted Download is disabled (efuse bit ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` is set). - - This is a safety measure to prevent accidentally overwriting the encrypted firmware with a plaintext binary, which **can ultimately lead to bricking the device**. - - This behavior can be overridden with the ``--force`` option. **Use this option provided that the flash encryption key is generated external to the device and you could perform the encryption on the host machine.** - - Flashing an Incompatible Image - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - ``esptool.py`` checks every binary before flashing. If a valid firmware image is detected, the ``Chip ID`` and ``Minimum chip revision`` fields in its :ref:`header ` are compared against the actually connected chip. - If the image turns out to be incompatible with the chip in use or requires a newer chip revision, flashing is stopped. - - This behavior can be overridden with the ``--force`` option. - -Read Flash Contents: read_flash --------------------------------- - -The read_flash command allows reading back the contents of flash. The arguments to the command are an address, a size, and a filename to dump the output to. For example, to read a full 2MB of attached flash: - -:: - - esptool.py -p PORT -b 460800 read_flash 0 0x200000 flash_contents.bin - - -It is also possible to autodetect flash size by using ``ALL`` as size. The above example with autodetection would look like this: - -:: - - esptool.py -p PORT -b 460800 read_flash 0 ALL flash_contents.bin - - -.. note:: - - If ``write_flash`` updated the boot image's :ref:`flash mode and flash size ` during flashing then these bytes may be different when read back. - -.. _erase_flash: - -Erase Flash: erase_flash & erase_region ---------------------------------------- - -To erase the entire flash chip (all data replaced with 0xFF bytes): - -:: - - esptool.py erase_flash - -To erase a region of the flash, starting at address 0x20000 with length 0x4000 bytes (16KB): - -:: - - esptool.py erase_region 0x20000 0x4000 - -The address and length must both be multiples of the SPI flash erase sector size. This is 0x1000 (4096) bytes for supported flash chips. - -.. only:: not esp8266 - - Flash Protection - ^^^^^^^^^^^^^^^^ - - Erasing the flash chip is disabled by default if either active `Secure Boot `_ or - `Flash Encryption `_ is detected. - This is a safety measure to prevent accidentally deleting the secure bootloader or encrypted data, which **can ultimately lead to bricking the device**. - - This behavior can be overridden with the ``--force`` option. **Use this only at your own risk and only if you know what you are doing!** - -Read Built-in MAC Address: read_mac ------------------------------------- - -:: - - esptool.py read_mac - -.. _read-spi-flash-id: - -Read SPI Flash ID: flash_id ---------------------------- - -:: - - esptool.py flash_id - -Example output: - -:: - - Manufacturer: e0 - Device: 4016 - Detected flash size: 4MB - -Refer to `flashrom source code `__ for flash chip manufacturer name and part number. - -.. _elf-2-image: - -Convert ELF to Binary: elf2image --------------------------------- - -The ``elf2image`` command converts an ELF file (from compiler/linker output) into the binary executable images which can be flashed and then booted into: - -:: - - esptool.py --chip {IDF_TARGET_NAME} elf2image my_app.elf - -This command does not require a serial connection. - -``elf2image`` also accepts the `Flash Modes <#flash-modes>`__ arguments ``--flash_freq`` and ``--flash_mode``, which can be used to set the default values in the image header. This is important when generating any image which will be booted directly by the chip. -These values can also be overwritten via the ``write_flash`` command, see the `write_flash command <#write-binary-data-to-flash-write-flash>`__ for details. However, if you want to overwrite these values via the ``write_flash`` command then use the ``--dont-append-digest`` argument of the ``elf2image`` command in order to skip appending a SHA256 digest after the image. The SHA256 digest would be invalidated by rewriting the image header, therefore, it is not allowed. - -By default, ``elf2image`` uses the sections in the ELF file to generate each segment in the binary executable. To use segments (PHDRs) instead, pass the ``--use_segments`` option. - -.. only:: esp8266 - - The default command output for {IDF_TARGET_NAME} is two binary files: ``my_app.elf-0x00000.bin`` and ``my_app.elf-0x40000.bin``. You can alter the firmware file name prefix using the ``--output/-o`` option. - - ``elf2image`` can also produce a "version 2" image file suitable for use with a software bootloader stub such as `rboot `__ or the Espressif bootloader program. You can't flash a "version 2" image without also flashing a suitable bootloader. - - :: - - esptool.py --chip {IDF_TARGET_NAME} elf2image --version=2 -o my_app-ota.bin my_app.elf - -.. only:: not esp8266 - - For {IDF_TARGET_NAME}, elf2image produces a single output binary "image file". By default this has the same name as the .elf file, with a .bin extension. For example: - - :: - - esptool.py --chip {IDF_TARGET_NAME} elf2image my_esp_app.elf - - In the above example, the output image file would be called ``my_esp_app.bin``. - - The ``--ram-only-header`` configuration is mainly applicable for use within the Espressif's SIMPLE_BOOT option from 3rd party OSes such as ZephyrOS and NuttX OS. - This option makes only the RAM segments visible to the ROM bootloader placing them at the beginning of the file and altering the segment count from the image header with the quantity of these segments, and also writing only their checksum. This segment placement may result in a more fragmented binary because of flash alignment constraints. - It is strongly recommended to use this configuration with care, because the image built must then handle the basic hardware initialization and the flash mapping for code execution after ROM bootloader boot it. - -.. _image-info: - -Output .bin Image Details: image_info -------------------------------------- - -The ``image_info`` command outputs some information (load addresses, sizes, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files. - -To view more information about the image, such as set flash size, frequency and mode, or extended header information, use the ``--version 2`` option. This extended output will become the default in a future major release. - -This information corresponds to the headers described in :ref:`image-format`. - -:: - - esptool.py image_info --version 2 my_esp_app.bin - -.. only:: not esp8266 - - If the given binary file is an application and a valid `ESP-IDF application header `__ is detected in the image, specific fields describing the application are also displayed. - - If the given binary file is a bootloader and a valid `ESP-IDF bootloader header `__ is detected in the image, specific fields describing the bootloader are also displayed. - -.. _merge-bin: - -Merge Binaries for Flashing: merge_bin --------------------------------------- -The ``merge_bin`` command will merge multiple binary files (of any kind) into a single file that can be flashed to a device later. Any gaps between the input files are padded based on the selected output format. - -For example: - -:: - - esptool.py --chip {IDF_TARGET_NAME} merge_bin -o merged-flash.bin --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin - -Will create a file ``merged-flash.bin`` with the contents of the other 3 files. This file can be later written to flash with ``esptool.py write_flash 0x0 merged-flash.bin``. - - -**Common options:** - -* The ``merge_bin`` command supports the same ``--flash_mode``, ``--flash_size`` and ``--flash_freq`` options as the ``write_flash`` command to override the bootloader flash header (see above for details). - These options are applied to the output file contents in the same way as when writing to flash. Make sure to pass the ``--chip`` parameter if using these options, as the supported values and the bootloader offset both depend on the chip. -* The ``--format`` option will change the format of the output file. For more information about formats see formats description below. -* The input files can be in either ``bin`` or ``hex`` format and they will be automatically converted to type selected by ``--format`` argument. -* It is possible to append options from a text file with ``@filename`` (see the advanced options page :ref:`Specifying Arguments via File ` section for details). As an example, this can be conveniently used with the ESP-IDF build system, which produces a ``flash_args`` file in the build directory of a project: - -.. code:: sh - - cd build # The build directory of an ESP-IDF project - esptool.py --chip {IDF_TARGET_NAME} merge_bin -o merged-flash.bin @flash_args - - -HEX Output Format -^^^^^^^^^^^^^^^^^ - -The output of the command will be in `Intel Hex format `__. The gaps between the files won't be padded. - -Intel Hex format offers distinct advantages when compared to the binary format, primarily in the following areas: - -* **Transport**: Intel Hex files are represented in ASCII text format, significantly increasing the likelihood of flawless transfers across various mediums. -* **Size**: Data is carefully allocated to specific memory addresses eliminating the need for unnecessary padding. Binary images often lack detailed addressing information, leading to the inclusion of data for all memory locations from the file's initial address to its end. -* **Validity Checks**: Each line in an Intel Hex file has a checksum to help find errors and make sure data stays unchanged. - -.. code:: sh - - esptool.py --chip {IDF_TARGET_NAME} merge_bin --format hex -o merged-flash.hex --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin - - -RAW Output Format -^^^^^^^^^^^^^^^^^ - -The output of the command will be in ``raw`` format and gaps between individual files will be filled with `0xFF` bytes (same as unwritten flash contents). - -.. note:: - - Because gaps between the input files are padded with `0xFF` bytes, when the merged binary is written then any flash sectors between the individual files will be erased. To avoid this, write the files individually. - - -**RAW options:** - -* The ``--fill-flash-size SIZE`` option will pad the merged binary with `0xFF` bytes to the full flash specified size, for example ``--fill-flash-size 4MB`` will create a 4MB binary file. -* The ``--target-offset 0xNNN`` option will create a merged binary that should be flashed at the specified offset, instead of at offset 0x0. - - -UF2 Output Format -^^^^^^^^^^^^^^^^^ - -This command will generate a UF2 (`USB Flashing Format `_) binary. -This UF2 file can be copied to a USB mass storage device exposed by another ESP running the `ESP USB Bridge `_ project. The bridge MCU will use it to flash the target MCU. This is as simple copying (or "drag-and-dropping") the file to the exposed disk accessed by a file explorer in your machine. - -Gaps between the files will be filled with `0x00` bytes. - -**UF2 options:** - -* The ``--chunk-size`` option will set what portion of 512 byte block will be used for data. A common value is 256 bytes. By default, the largest possible value will be used. -* The ``--md5-disable`` option will disable MD5 checksums at the end of each block. This can be useful for integration with e.g. `tinyuf2 `__. - -.. code:: sh - - esptool.py --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 - - -Advanced Commands ------------------ - -The following commands are less commonly used, or only of interest to advanced users. They are documented in the :ref:`advanced-commands` section: - -.. list:: - - * :ref:`verify-flash` - * :ref:`dump-mem` - * :ref:`load-ram` - * :ref:`read-mem-write-mem` - * :ref:`read-flash-status` - * :ref:`write-flash-status` - :esp8266: * :ref:`chip-id` - :esp8266: * :ref:`make-image` - :esp8266: * :ref:`run` diff --git a/docs/en/esptool/basic-options.rst b/docs/en/esptool/basic-options.rst deleted file mode 100644 index 5d9bb4c46..000000000 --- a/docs/en/esptool/basic-options.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _options: - -Basic Options -============= - -These are the basic/fundamental esptool options needed to define the communication with an ESP target. For advanced configuration options, see the :ref:`advanced-options` page. - -.. _chip-type: - -Chip Type ---------- - -* The target chip type can be selected using the ``--chip``/ ``-c`` option, e.g. ``esptool.py --chip {IDF_TARGET_PATH_NAME} ``. -* A default chip type can be specified by setting the ``ESPTOOL_CHIP`` environment variable. -* If no ``-c`` option or ``ESPTOOL_CHIP`` value is specified, ``esptool.py`` automatically detects the chip type when connecting. -* Binary image generation commands, such as :ref:`elf2image ` or :ref:`merge_bin `, require the chip type to be specified. - -.. _serial-port: - -Serial Port ------------ - -* The serial port is selected using the ``-p`` option, like ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows). -* A default serial port can be specified by setting the ``ESPTOOL_PORT`` environment variable. -* If no ``-p`` option or ``ESPTOOL_PORT`` value is specified, ``esptool.py`` will enumerate all connected serial ports and try each one until it finds an Espressif device connected. - -.. note:: - - Windows and macOS may require drivers to be installed for a particular USB/serial adapter, before a serial port is available. Consult the documentation for your particular device. - On macOS, you can also consult `System Information `__'s list of USB devices to identify the manufacturer or device ID when the adapter is plugged in. - On Windows, you can use `Windows Update or Device Manager `__ to find a driver. - -If using Cygwin or WSL on Windows, you have to convert the Windows-style name into a Unix-style path (``COM1`` -> ``/dev/ttyS0``, and so on). (This is not necessary if using ESP-IDF with the supplied Windows MSYS2 environment, -this environment uses a native Windows Python which accepts COM ports as-is.) - -In Linux, the current user may not have access to serial ports and a "Permission Denied" or "Port doesn't exist" errors may appear. -On most Linux distributions, the solution is to add the user to the ``dialout`` group (check e.g. ``ls -l /dev/ttyUSB0`` to find the group) with a command like ``sudo usermod -a -G dialout $USER``. -You can call ``su - $USER`` to enable read and write permissions for the serial port without having to log out and back in again. -Check your Linux distribution's documentation for more information. - -Baud Rate ---------- - -The default esptool baud rate is 115200bps. Different rates may be set using ``-b 921600`` (or another baud rate of your choice). A default baud rate can also be specified using the ``ESPTOOL_BAUD`` environment variable. This can speed up ``write_flash`` and ``read_flash`` operations. - -The baud rate is limited to 115200 when esptool establishes the initial connection, higher speeds are only used for data transfers. - -Most hardware configurations will work with ``-b 230400``, some with ``-b 460800``, ``-b 921600`` and/or ``-b 1500000`` or higher. - -.. only:: esp8266 - - If you have connectivity problems then you can also set baud rates below 115200. You can also choose 74880, which is the :ref:`usual baud rate used by the ESP8266 ` to output :ref:`boot-log-esp8266` information. - -.. only:: not esp8266 - - If you have connectivity problems then you can also set baud rates below 115200. diff --git a/docs/en/esptool/configuration-file.rst b/docs/en/esptool/configuration-file.rst deleted file mode 100644 index c538c608a..000000000 --- a/docs/en/esptool/configuration-file.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. _config: - -Configuration File -================== - -``esptool.py`` relies on serial communication when connecting to, reading from, or writing to an ESP chip. -To ensure this two-way serial connection works properly, ``esptool.py`` is tuned with several pre-defined -variables describing the timings and other nuances when sending or receiving data. -These variables have been finely tuned to work in absolute majority of environments. -However, it is impossible to cover all of the existing combinations of hardware, OS, and drivers. -Sometimes little tweaking is necessary to cover even the most extreme edge cases. - -These options can be specified in a configuration file. This makes it easy to run -``esptool.py`` with custom settings, and also allows for specification of options -that are otherwise not available to a user without having to tamper with the source code. - -File Location -------------- - -The default name for a configuration file is ``esptool.cfg``. First, the same -directory ``esptool.py`` is being run in is inspected. - -If a configuration file is not found here, the current user's OS configuration directory is inspected next: - - - Linux: ``/home//.config/esptool/`` - - MacOS ``/Users//.config/esptool/`` - - Windows: ``c:\Users\\AppData\Local\esptool\`` - -If a configuration file is still not found, the last inspected location is the home directory: - - - Linux: ``/home//`` - - MacOS ``/Users//`` - - Windows: ``c:\Users\\`` - -On Windows, the home directory can be set with the ``HOME`` or ``USERPROFILE`` environment variables. -Therefore, the Windows configuration directory location also depends on these. - -A different location for the configuration file can be specified with the ``ESPTOOL_CFGFILE`` -environment variable, e.g. ``ESPTOOL_CFGFILE = ~/custom_config.cfg``. -This overrides the search priorities described above. - -``esptool.py`` will read settings from other usual configuration files if no other -configuration file is used. It will automatically read from ``setup.cfg`` or -``tox.ini`` if they exist. - -As a result, the order of priority of inspected configuration files is: - -#. a file specified with the ``ESPTOOL_CFGFILE`` environment variable -#. ``esptool.cfg`` -#. ``setup.cfg`` -#. ``tox.ini`` - -Syntax ------- - -An ``esptool.py`` configuration file is in .ini file format: it must be -introduced by an ``[esptool]`` header to be recognized as valid. -This section then contains ``name = value`` entries. -Lines beginning with ``#`` or ``;`` are ignored as comments. - -Delay and timeout options accept float values, -other numeric options are integers. Strings don't need quotes. - -Sample configuration file: - -.. code-block:: text - - # esptool.cfg file to configure internal settings of esptool - [esptool] - chip_erase_timeout = 140 - serial_write_timeout = 8.5 - connect_attempts = 7 - write_block_attempts = 2 - reset_delay = 0.75 - # Overriding the default reset sequence to work in an abnormal environment - custom_reset_sequence = D0|R1|W0.1|D1|R0|W0.5|D0 - -Options -------- - -Complete list configurable options: - -+------------------------------+-----------------------------------------------------------+----------+ -| Option | Description | Default | -+==============================+===========================================================+==========+ -| timeout | Timeout for most flash operations | 3 s | -+------------------------------+-----------------------------------------------------------+----------+ -| chip_erase_timeout | Timeout for a full chip erase | 120 s | -+------------------------------+-----------------------------------------------------------+----------+ -| max_timeout | The longest any command can run | 240 s | -+------------------------------+-----------------------------------------------------------+----------+ -| sync_timeout | Timeout for syncing with the bootloader | 0.1 s | -+------------------------------+-----------------------------------------------------------+----------+ -| md5_timeout_per_mb | Timeout (per megabyte) for calculating md5sum | 8 s | -+------------------------------+-----------------------------------------------------------+----------+ -| erase_region_timeout_per_mb | Timeout (per megabyte) for erasing a region | 30 s | -+------------------------------+-----------------------------------------------------------+----------+ -| erase_write_timeout_per_mb | Timeout (per megabyte) for erasing and writing data | 40 s | -+------------------------------+-----------------------------------------------------------+----------+ -| mem_end_rom_timeout | Short timeout for ESP_MEM_END | 0.2 s | -+------------------------------+-----------------------------------------------------------+----------+ -| serial_write_timeout | Timeout for serial port write | 10 s | -+------------------------------+-----------------------------------------------------------+----------+ -| connect_attempts | Default number of times to try connection | 7 | -+------------------------------+-----------------------------------------------------------+----------+ -| write_block_attempts | Number of times to try writing a data block | 3 | -+------------------------------+-----------------------------------------------------------+----------+ -| reset_delay | Time to wait before the boot pin is released after reset | 0.05 s | -+------------------------------+-----------------------------------------------------------+----------+ -| custom_reset_sequence | Custom reset sequence for resetting into the bootloader | | -+------------------------------+-----------------------------------------------------------+----------+ - -Custom Reset Sequence ---------------------- - -The ``custom_reset_sequence`` configuration option allows you to define a reset sequence which will get -used when an :ref:`automatic reset into the serial bootloader ` is performed. - -The sequence is defined with a string in the following format: - -- Consists of individual commands divided by ``|`` (e.g. ``R0|D1|W0.5``). -- Commands (e.g. ``R0``) are defined by a code (``R``) and an argument (``0``). - -+------+-----------------------------------------------------------+-----------------+ -| Code | Action | Argument | -+======+===========================================================+=================+ -| D | Set DTR control line | ``1``/``0`` | -+------+-----------------------------------------------------------+-----------------+ -| R | Set RTS control line | ``1``/``0`` | -+------+-----------------------------------------------------------+-----------------+ -| U | Set DTR and RTS control lines at the same time | ``0,0``/``0,1`` | -| | (Unix-like systems only) | ``1,0``/``1,1`` | -+------+-----------------------------------------------------------+-----------------+ -| W | Wait for ``N`` seconds (where ``N`` is a float) | ``N`` | -+------+-----------------------------------------------------------+-----------------+ - - -For example: ``D0|R1|W0.1|D1|R0|W0.5|D0`` represents the following classic reset sequence: - -.. code-block:: python - - _setDTR(False) # IO0=HIGH - _setRTS(True) # EN=LOW, chip in reset - time.sleep(0.1) - _setDTR(True) # IO0=LOW - _setRTS(False) # EN=HIGH, chip out of reset - time.sleep(0.05) - _setDTR(False) # IO0=HIGH, done diff --git a/docs/en/esptool/entering-bootloader.rst b/docs/en/esptool/entering-bootloader.rst deleted file mode 100644 index 4e5a95837..000000000 --- a/docs/en/esptool/entering-bootloader.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _entering-the-bootloader: - -Entering the Bootloader -======================= - -Espressif chips have to be reset in a certain way in order to launch the serial bootloader, only then can ``esptool.py`` communicate with the ESP chip. - -On some development boards (including NodeMCU, WeMOS, HUZZAH Feather, Core Board, ESP32-WROVER-KIT), esptool can :ref:`automatically trigger a reset into the serial bootloader ` - in which case you don't need to read this section. - -For everyone else, three things must happen to enter the serial bootloader (firmware download mode) - a reset, required pins set correctly, and a correct strapping pin pulled low. For more information, see the detailed :ref:`Boot Mode Selection` guide. - -Boot Mode ---------- - -Espressif chips choose the boot mode each time they reset. A reset event can happen in one of several ways: - -.. list:: - - * Power applied to chip. - :esp8266: * The nRESET pin was low and is pulled high. - * The CH_PD/EN pin ("enable") pin was low and is pulled high. - -.. only:: esp8266 - - On {IDF_TARGET_NAME}, both the nRESET and CH_PD pins must be pulled high for the chip to start operating. diff --git a/docs/en/esptool/flash-modes.rst b/docs/en/esptool/flash-modes.rst deleted file mode 100644 index 37d3033b7..000000000 --- a/docs/en/esptool/flash-modes.rst +++ /dev/null @@ -1,120 +0,0 @@ -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - -{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"} - -{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"} - -{IDF_TARGET_FLASH_FREQ:default="``40m``, ``26m``, ``20m``, ``80m``", esp32c2="``30m``, ``20m``, ``15m``, ``60m``", esp32h2="``24m``, ``16m``, ``12m``, ``48m``", esp32c6="``40m``, ``20m``, ``80m``"} - - -.. _flash-modes: - -Flash Modes -=========== - -``write_flash`` and some other commands accept command line arguments to set bootloader flash mode, flash size and flash clock frequency. The chip needs correct mode, frequency and size settings in order to run correctly - although there is some flexibility. -A header at the beginning of a bootable image contains these values. - -To override these values, the options ``--flash_mode``, ``--flash_size`` and/or ``--flash_freq`` must appear after ``write_flash`` on the command line, for example: - -:: - - esptool.py --port /dev/ttyUSB1 write_flash --flash_mode dio --flash_size 4MB 0x0 bootloader.bin - -These options are only consulted when flashing a bootable image to an {IDF_TARGET_NAME} at offset {IDF_TARGET_BOOTLOADER_OFFSET}. These are addresses used by the ROM bootloader to load from flash. When flashing at all other offsets, these arguments are not used. - -Flash Mode (--flash_mode, -fm) -------------------------------- - -These set Quad Flash I/O or Dual Flash I/O modes. Valid values are ``keep``, ``qio``, ``qout``, ``dio``, ``dout``. The default is ``keep``, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ``ESPTOOL_FM``. - -.. only:: esp8266 - - Most boards use ``qio`` mode. Some ESP8266 modules, including the ESP-12E modules on some (not all) NodeMCU boards, are dual I/O and the firmware will only boot when flashed with ``--flash_mode dio``. - -.. only:: not esp8266 - - Most {IDF_TARGET_NAME} modules use ``qio``, but are also dual I/O. - -In ``qio`` mode, two additional GPIOs (9 and 10) are used for SPI flash communications. If flash mode is set to ``dio`` then these pins are available for other purposes. - -For a full explanation of these modes, see the :ref:`SPI Flash Modes page `. - -Flash Frequency (--flash_freq, -ff) ------------------------------------- - -Clock frequency for SPI flash interactions. Valid values are ``keep``, {IDF_TARGET_FLASH_FREQ} (MHz). The default is ``keep``, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ``ESPTOOL_FF``. - -The flash chip connected to most chips works with {IDF_TARGET_FLASH_FREQ_0}MHz clock speeds, but you can try lower values if the device won't boot. The highest {IDF_TARGET_FLASH_FREQ_F}MHz flash clock speed will give the best performance, but may cause crashing if the flash or board design is not capable of this speed. - -Flash Size (--flash_size, -fs) -------------------------------- - -Size of the SPI flash, given in megabytes. - -.. only:: esp8266 - - Valid values are: ``keep``, ``detect``, ``256KB``, ``512KB``, ``1MB``, ``2MB``, ``4MB``, ``2MB-c1``, ``4MB-c1``, ``8MB``, ``16MB`` - -.. only:: esp32 or esp32c3 or esp32c6 or esp32c2 or esp32h2 - - Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB`` - -.. only:: esp32s2 or esp32s3 - - Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``, ``32MB``, ``64MB``, ``128MB`` - -.. note:: - - Esptool uses power of two units, so in IEC units the size arguments are Mebibytes, although Espressif's technical documentation doesn't use the Mebi- prefix. This is due to compatibility reasons and to keep consistent with flash manufacturers. - -.. only:: esp8266 - - For ESP8266, some :ref:`additional sizes & layouts for OTA "firmware slots" are available `. - -The default ``--flash_size`` parameter is ``keep``. This means that if no ``--flash_size`` argument is passed when flashing a bootloader, the value in the bootloader .bin file header is kept instead of detecting the actual flash size and updating the header. - -To enable automatic flash size detection based on SPI flash ID, add the argument ``esptool.py [...] write_flash [...] -fs detect``. If detection fails, a warning is printed and a default value of of ``4MB`` (4 megabytes) is used. - -If flash size is not successfully detected, you can find the flash size by using the ``flash_id`` command and then looking up the ID from the output (see :ref:`Read SPI flash id `). -Alternatively, read off the silkscreen labelling of the flash chip and search for its datasheet. - -The default ``flash_size`` parameter can also be overridden using the environment variable ``ESPTOOL_FS``. - -.. only:: esp8266 - - The ESP8266 SDK stores WiFi configuration at the "end" of flash, and it finds the end using this size. However there is no downside to specifying a smaller flash size than you really have, as long as you don't need to write an image larger than this size. - - ESP-12, ESP-12E and ESP-12F modules (and boards that use them such as NodeMCU, HUZZAH, etc.) usually have at least 4 megabyte / ``4MB`` (sometimes labelled 32 megabit) flash. - - .. _esp8266-and-flash-size: - - If using OTA, some additional sizes & layouts for OTA "firmware slots" are available. If not using OTA updates then you can ignore these extra sizes: - - +-------------------+-----------------------+-----------------+-----------------+ - | flash_size arg | Number of OTA slots | OTA Slot Size | Non-OTA Space | - +===================+=======================+=================+=================+ - | 256KB | 1 (no OTA) | 256KB | N/A | - +-------------------+-----------------------+-----------------+-----------------+ - | 512KB | 1 (no OTA) | 512KB | N/A | - +-------------------+-----------------------+-----------------+-----------------+ - | 1MB | 2 | 512KB | 0KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 2MB | 2 | 512KB | 1024KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 4MB | 2 | 512KB | 3072KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 2MB-c1 | 2 | 1024KB | 0KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 4MB-c1 | 2 | 1024KB | 2048KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 8MB [^] | 2 | 1024KB | 6144KB | - +-------------------+-----------------------+-----------------+-----------------+ - | 16MB [^] | 2 | 1024KB | 14336KB | - +-------------------+-----------------------+-----------------+-----------------+ - - - [^] Support for 8MB & 16MB flash size is not present in all ESP8266 SDKs. If your SDK doesn't support these flash sizes, use ``--flash_size 4MB``. - -.. only:: not esp8266 - - The ESP-IDF flashes a partition table to the flash at offset 0x8000. All of the partitions in this table must fit inside the configured flash size, otherwise the {IDF_TARGET_NAME} will not work correctly. diff --git a/docs/en/esptool/flasher-stub.rst b/docs/en/esptool/flasher-stub.rst deleted file mode 100644 index c2f179be7..000000000 --- a/docs/en/esptool/flasher-stub.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _stub: - -Flasher Stub -============ - -``esptool.py`` is a serial flasher utility. It communicates with the ROM bootloader in `Espressif SoCs `_ in order to load user applications or read chip data via serial port. - -The ROM bootloader is burned into the ESP chip during manufacturing and cannot be updated. A new version is issued only when a new chip revision is released. - -``esptool.py`` works around the limitations imposed by a fixed ROM bootloader by implementing a flasher stub (also known as "stub loader" or just "stub"). It is a small application used as a temporary substitute or extension for the ROM. - -When ``esptool.py`` connects to a chip, it first uploads the flasher stub, which basically replaces the original bootloader. All following operations are then handled by the stub. - -Benefits --------- - -The flasher stub behaves the same as the original bootloader, but uses more heavily optimized UART routines. - -The main benefit is improved performance of flashing and some other operations (like reading flash). Additionally, there are a few commands which are only available when using the stub loader (such as :ref:`erase_flash and erase_region `). It also allows to work around any bugs in ROM bootloaders. - -Disabling the Stub Loader -------------------------- - -There might be cases where it is necessary to disable the stub loader (e.g. debugging). To do that, run ``esptool.py`` with the ``--no-stub`` argument. All operations will then be handled by the original ROM bootloader. See the related :ref:`advanced options page `. diff --git a/docs/en/esptool/flashing-firmware.rst b/docs/en/esptool/flashing-firmware.rst deleted file mode 100644 index e99675840..000000000 --- a/docs/en/esptool/flashing-firmware.rst +++ /dev/null @@ -1,103 +0,0 @@ -Flashing Firmware -================= - -Esptool is used under the hood of many development frameworks for Espressif SoCs, such as `ESP-IDF `_, `Arduino `_, or `PlatformIO `_. -After the resulting firmware binary files are compiled, esptool is used to flash these into the device. - -Sometimes there might be a need to comfortably flash a bigger amount of decives with the same binaries or to share flashing instructions with a third party. -It is possible to compile the firmware just once and then repeatedly use esptool (manually or :ref:`in a custom script `) to flash the files. - -Sharing these instructions and below mentioned assets with a third party (for example a manufacturer) should suffice to allow reproducible and quick flashing of your application into an Espressif chip. - -.. note:: - - The following texts are just an example, please see the documentation of the development framework of your choice for precise instructions. - -Prerequisites -------------- - -* Installed esptool, see the :ref:`installation guide ` for instructions. -* All of the compiled binary files in a known location. -* Espressif chip connected to your computer. - -Binary Files Location ---------------------- - -The generated binary files are usually stored in the ``build`` folder of your project. - -For example, when building the `hello-world example project `_ in ESP-IDF, the resulting app binary can be found in ``.../esp-idf/examples/get-started/hello_world/build/hello_world.bin``. -The same applies to the bootloader and the partition table. - -The location of generated binaries depends on the used development framework. If you are unsure of the location, see the generated esptool `command <#command>`__ containing the full paths. - -Command -------- - -Compile and upload your firmware once with your preferred framework. The detailed esptool command will be displayed in the output right before the flashing happens. - -It is also possible to assemble the command manually, please see the :ref:`esptool usage documentation` for more information. - -ESP-IDF -^^^^^^^ - -ESP-IDF outputs the full esptool command used for flashing after the build is finished:: - - Project build complete. To flash, run this command: - python esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin - or run 'idf.py -p (PORT) flash' - -Arduino -^^^^^^^ - -The full esptool command is hidden from the user by default. To expose it, open the preferences window and check the ``Show verbose output during: upload`` option. A full command will be shown while uploading the sketch. - -PlatformIO -^^^^^^^^^^ - -To do a verbose upload and see the exact esptool invocation, run ``pio run -v -t upload`` in the terminal. In the generated output, there is the full esptool command, e.g.: - -:: - - “.../.platformio/penv/bin/python2.7” “.../.platformio/packages/tool-esptoolpy/esptool.py” --chip esp32 --port “/dev/cu.usbserial001” --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin - - -Flashing --------- - -If you split the output, you’ll find the ``write_flash`` command with a list of paths to binary files and their respective flashing offsets. If necessary, change the paths to the actual file locations. - -Change ``PORT`` to the name of :ref:`actually used serial port ` and run the command. A successful flash looks like this:: - - $ python esptool.py -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip esp32 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin - esptool.py v3.2-dev - Serial port /dev/tty.usbserial-0001 - Connecting......... - Chip is ESP32-D0WD (revision 1) - Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None - Crystal is 40MHz - MAC: de:ad:be:ef:1d:ea - Uploading stub... - Running stub... - Stub running... - Changing baud rate to 460800 - Changed. - Configuring flash size... - Auto-detected Flash size: 16MB - Flash will be erased from 0x00001000 to 0x00007fff... - Flash will be erased from 0x00008000 to 0x00008fff... - Flash will be erased from 0x00010000 to 0x00039fff... - Flash params set to 0x0240 - Compressed 25536 bytes to 15935... - Wrote 25536 bytes (15935 compressed) at 0x00001000 in 0.7 seconds (effective 275.5 kbit/s)... - Hash of data verified. - Compressed 3072 bytes to 103... - Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 334.1 kbit/s)... - Hash of data verified. - Compressed 169232 bytes to 89490... - Wrote 169232 bytes (89490 compressed) at 0x00010000 in 2.6 seconds (effective 513.0 kbit/s)... - Hash of data verified. - - Leaving... - Hard resetting via RTS pin... - -It is now possible to unplug the flashed device and repeat the process by connecting another one and running the command again. diff --git a/docs/en/esptool/index.rst b/docs/en/esptool/index.rst deleted file mode 100644 index 495896fb9..000000000 --- a/docs/en/esptool/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _esptool: - -esptool.py -========== - -Use ``esptool.py -h`` to see a summary of all available commands and command line options. - -To see all options for a particular command, append ``-h`` to the command name. ie ``esptool.py write_flash -h``. - -.. toctree:: - :maxdepth: 1 - - Basic Options - Basic Commands - Advanced Options - Advanced Commands - Flasher Stub - Flash Modes - Entering the Bootloader - Serial Connection - Configuration File - Remote Serial Ports - Flashing Firmware - Scripting - -.. only:: not esp8266 - - Instructions for other tools bundled with esptool: - - * :ref:`espefuse` - * :ref:`espsecure` diff --git a/docs/en/esptool/remote-serial-ports.rst b/docs/en/esptool/remote-serial-ports.rst deleted file mode 100644 index 5863516f0..000000000 --- a/docs/en/esptool/remote-serial-ports.rst +++ /dev/null @@ -1,62 +0,0 @@ -Remote Serial Ports -=================== - -It is possible to connect to any networked remote serial port that supports `RFC2217 `__ (Telnet) protocol. To do this, specify the serial port to esptool as ``rfc2217://:``. For example, to read information about your chip's SPI flash, run: - -:: - - esptool.py --port rfc2217://192.168.1.77:4000 flash_id - -Custom baud rates and DTR/RTS automatic resetting are supported over the RFC2217 protocol, the same as for a local serial port. - -Pyserial Example Servers ------------------------- - -PySerial (which is a dependency of esptool) includes two RFC2217 example programs - `a single-port example `__ and a `multi-port example `__. -These example servers can run on any OS that supports pyserial, and are the simplest way to connect to an Espressif SoC over the network. - -There is an issue with `automatic resetting due to network latency `__. In order to work around this issue, a modified version of the single-port server example called ``esp_rfc2217_server.py`` is provided with esptool. - -On server: - -:: - - esp_rfc2217_server.py -p 4000 /dev/ttyUSB1 - -On client: - -:: - - esptool.py --port rfc2217://ADDRESS_OF_SERVER:4000?ign_set_control flash_id - - -Raw Sockets ------------ - -For servers or hardware network/serial adapters which don't support the full RFC2217, it is also possible to specify ``--port socket://:`` syntax for a simple "raw TCP socket" protocol. - -These raw sockets don't support setting the baud rate or automatic resetting into the bootloader. If using this mode, don't pass the ``--baud`` option to esptool. You need to set the baud rate manually on the server, and manually reset the chip into the bootloader mode (or use some other signalling/control method to tell the server to do so). - -Here's a very basic example using the common Linux/OSX command line "netcat" and "stty" commands: - -On server: - -:: - - stty -F /dev/ttyUSB1 230400 # set baud rate - nc -p 4000 -lk < /dev/ttyUSB1 > /dev/ttyUSB1 - -On client: - -:: - - esptool.py -p socket://localhost:4000 flash_id - -.. note:: - - Using RFC2217 is strongly recommended where possible. - -More Details ------------- - -All of the remote serial port support comes via pyserial. Read more `here `__. (Please keep in mind that the link points to documentation for the most recent pyserial version. You may have an older version.) diff --git a/docs/en/esptool/scripting.rst b/docs/en/esptool/scripting.rst deleted file mode 100644 index e4e96608d..000000000 --- a/docs/en/esptool/scripting.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _scripting: - -Embedding into Custom Scripts -============================= - -``esptool.py``, ``espefuse.py``, and ``espsecure.py`` can easily be integrated into Python applications or called from other Python scripts. - -While it currently does have a poor Python API, something which `#208 `_ will address, it allows for passing CLI arguments to ``esptool.main()``. This workaround makes integration very straightforward as you can pass exactly the same arguments as you would on the CLI: - -.. code-block:: python - - command = ['--baud', '460800', 'read_flash', '0', '0x200000', 'flash_contents.bin'] - print('Using command %s' % ' '.join(command)) - esptool.main(command) diff --git a/docs/en/esptool/serial-connection.rst b/docs/en/esptool/serial-connection.rst deleted file mode 100644 index ed710edd4..000000000 --- a/docs/en/esptool/serial-connection.rst +++ /dev/null @@ -1,47 +0,0 @@ -{IDF_TARGET_BAUD_RATE:default="115200", esp8266="74880 "} - -Serial Connection -================= - -The ROM serial bootloader of Espressif chips uses a 3.3V UART serial connection. Many development boards make the serial connections for you onboard. - -However, if you are wiring the chip yourself to a USB/Serial adapter or similar then the following connections must be made: - -+---------------------+-------------------+ -| ESP Chip Pin | Serial Port Pin | -+=====================+===================+ -| TX | RX (receive) | -+---------------------+-------------------+ -| RX | TX (transmit) | -+---------------------+-------------------+ -| Ground | Ground | -+---------------------+-------------------+ - -Note that TX (transmit) on the ESP chip is connected to RX (receive) on the serial port connection, and vice versa. - -Do not connect the chip to 5V TTL serial adapters, and especially not to "standard" RS-232 adapters! 3.3V serial only!  - -.. _serial-port-settings: - -Serial Port Settings --------------------- - -When communicating with the {IDF_TARGET_NAME} ROM serial bootloader, the following serial port settings are recommended: - -+---------------------+-------------------+  -| Baud rate | {IDF_TARGET_BAUD_RATE} | -+---------------------+-------------------+ -| Data bits | 8 | -+---------------------+-------------------+ -| Stop bits | 1 | -+---------------------+-------------------+ -| Parity | None | -+---------------------+-------------------+ -| Flow control | None | -+---------------------+-------------------+ - -.. only:: esp8266 - - .. note:: - - Baud rate {IDF_TARGET_BAUD_RATE} is what the {IDF_TARGET_NAME} bootloader uses. The apps on top of the Espressif SDK (e.g. Arduino sketch) talk at 115200 if not specified otherwise. diff --git a/docs/en/index.rst b/docs/en/index.rst deleted file mode 100644 index 201b71bf1..000000000 --- a/docs/en/index.rst +++ /dev/null @@ -1,55 +0,0 @@ -Esptool.py Documentation -======================== - -This is the documentation for ``esptool.py`` - a Python-based, open source, platform independent utility to communicate with the ROM bootloader in `Espressif SoCs `_. - -``esptool.py``, ``espefuse.py`` and ``espsecure.py`` are a complete toolset for working with Espressif chips. They can do a number of things, for example: - -* Read, write, erase, and verify binary data stored in flash. -* Read chip features and other related data such as MAC address or flash chip ID. -* Read and write the one-time-programmable efuses. -* Prepare binary executable images ready for flashing. -* Analyze, assemble, and merge binary images. - -This document describes using ``esptool.py`` with the {IDF_TARGET_NAME} SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. - -Quick Start ------------ - -Getting started is easy: - -1) Install ``esptool.py``: - - :: - - $ pip install esptool - - For detailed instructions, see :ref:`installation`. - - -2) Connect an Espressif chip to your computer. - -3) Run ``esptool.py`` commands. For example, to read information about your chip's SPI flash, run: - - :: - - $ esptool.py -p PORT flash_id - - Replace ``PORT`` with the name of used serial port. If connection fails, see :ref:`troubleshooting`. - -More Information ----------------- - -.. toctree:: - :maxdepth: 1 - - Installation - Esptool - :not esp8266:Espefuse - :not esp8266:Espsecure - Advanced Topics - Troubleshooting - Contribute - Versions - Resources - About diff --git a/docs/en/installation.rst b/docs/en/installation.rst deleted file mode 100644 index 7fe9f876e..000000000 --- a/docs/en/installation.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _installation: - -Installation and Dependencies -============================= - -You will need `Python 3.7 or newer `_ installed on your system to use the latest version of ``esptool.py``. -If your use case requires Python 2.7, 3.4, 3.5, or 3.6, please use ``esptool.py`` v3.3.* instead. - -The latest stable esptool release can be installed from `PyPI `_ via pip: - -:: - - $ pip install esptool - -With some Python installations this may not work and you’ll receive an error, try ``python -m pip install esptool`` or ``pip3 install esptool``, or consult your `Python installation manual `_ for information about how to access pip. - -`Setuptools `_ is also a requirement which is not available on all systems by default. You can install it by a package manager of your operating system, or by ``pip install setuptools``. - -After installing, you will have ``esptool.py`` installed into the default Python executables directory and you should be able to run it with the command ``esptool.py`` or ``python -m esptool``. Please note that probably only ``python -m esptool`` will work for Pythons installed from Windows Store. - -.. note:: - - If you actually plan to do development work with esptool itself, see :ref:`development-setup` for more information. diff --git a/docs/en/resources.rst b/docs/en/resources.rst deleted file mode 100644 index 13add7041..000000000 --- a/docs/en/resources.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _resources: - -Resources -========= - - -Useful Links -------------- - -* The `esp32.com forum `_ is a place to ask questions and find community resources. - -* Check the `Issues `_ section on GitHub if you find a bug or have a feature request. Please check existing `issues `_ before opening a new one. - -* Several `books `_ have been written about the ESP8266 or ESP32 series of SoCs and they are listed on `Espressif `__ web site. - -* If you're interested in contributing to esptool.py, please check the :ref:`contribute` page. - -* For additional {IDF_TARGET_NAME} product related information, please refer to the `documentation `_ section of `Espressif `__ web site. - -Webinars and Trainings ----------------------- - -Mastering the Basics of Espressif Chips: An In-Depth Look at Chip Flashing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The content of this webinar is designed for developers, engineers and hobbyists interested in getting a better understanding of how to use esptool.py or other tools for the development with the ESP8266 or ESP32 series of SoCs. - -It offers an in-depth look at the inner mechanisms of esptool.py, including the :ref:`boot-mode` process. - -.. image:: https://img.youtube.com/vi/zh-Y_s4X6zs/maxresdefault.jpg - :alt: Mastering the Basics of Espressif Chips: An In-Depth Look at Chip Flashing - :target: https://www.youtube.com/watch?v=zh-Y_s4X6zs - -DevCon22: esptool.py: Espressif's Swiss Army Knife -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This talk aims to show how simple, yet powerful, esptool.py is, and how to use it to tame your ESP. - -.. image:: https://img.youtube.com/vi/GjWGKzu3XTk/maxresdefault.jpg - :alt: DevCon22: esptool.py: Espressif's Swiss Army Knife - :target: https://www.youtube.com/watch?v=GjWGKzu3XTk diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst deleted file mode 100644 index 5d3e3dbf3..000000000 --- a/docs/en/troubleshooting.rst +++ /dev/null @@ -1,214 +0,0 @@ -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - -.. _troubleshooting: - -Troubleshooting -=============== - -Flashing problems can be fiddly to troubleshoot. Try the suggestions here if you're having problems: - -Bootloader Won't Respond ------------------------- - -If you see errors like "Failed to connect" then your chip is probably not entering the bootloader properly: - -* Check you are passing the correct serial port on the command line. -* Check you have permissions to access the serial port, and other software (such as modem-manager on Linux) is not trying to interact with it. A common pitfall is leaving a serial terminal accessing this port open in another window and forgetting about it. -* Check the chip is receiving 3.3V from a stable power source (see `Insufficient Power`_ for more details.) -* Check that all pins are connected as described in :ref:`boot-mode`. Check the voltages at each pin with a multimeter, "high" pins should be close to 3.3V and "low" pins should be close to 0V. -* If you have connected other devices to GPIO pins, try removing them and see if esptool starts working. -* Try using a slower baud rate (``-b 9600`` is a very slow value that you can use to verify it's not a baud rate problem). - -Writing to Flash Fails Part Way Through ---------------------------------------- - -If flashing fails with random errors part way through, retry with a lower baud rate. - -Power stability problems may also cause this (see `Insufficient Power`_.) - -Writing to Flash Succeeds but Program Doesn't Run -------------------------------------------------- - -If esptool can flash your module with ``write_flash`` but your program doesn't run, check the following: - -Wrong Flash Mode -^^^^^^^^^^^^^^^^ - -Some devices only support the ``dio`` flash mode. Writing to flash with ``qio`` mode will succeed but the chip can't read the flash back to run - so nothing happens on boot. Try passing the ``-fm dio`` option to ``write_flash``. - -See the :ref:`spi-flash-modes` page for a full description of the flash modes and how to determine which ones are supported on your device. - -Insufficient Power -^^^^^^^^^^^^^^^^^^ - -The 3.3V power supply for the ESP chip has to supply large amounts of current (up to 70mA continuous, 200-300mA peak, might be slightly higher). You also need sufficient capacitance on the power circuit to meet large spikes of power demand. - -Insufficient Capacitance -'''''''''''''''''''''''' - -If you're using a pre-made development board or module then the built-in power regulator & capacitors are usually good enough, provided the input power supply is adequate. - -.. note:: - - This is not true for some very simple pin breakout modules - `similar to this `_. These breakouts do not integrate enough capacitance to work reliably without additional components. - Surface mount OEM modules like ESP-WROOM02 and ESP-WROOM32 require an external bulk capacitor on the PCB to be reliable, consult the module datasheet. - -Power Supply Rating -''''''''''''''''''' - -It is possible to have a power supply that supplies enough current for the serial bootloader stage with esptool, but not enough for normal firmware operation. You may see the 3.3V VCC voltage droop down if you measure it with a multimeter, but you can have problems even if this isn't happening. - -Try swapping in a 3.3V supply with a higher current rating, add capacitors to the power line, and/or shorten any 3.3V power wires. - -The 3.3V output from FTDI FT232R chips/adapters or Arduino boards *do not* supply sufficient current to power an ESP chip (it may seem to work sometimes, but it won't work reliably). Other USB TTL/serial adapters may also be marginal. - -Missing Bootloader -^^^^^^^^^^^^^^^^^^ -.. only:: esp8266 - - The `ESP8266 SDK `_ uses a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. - On ESP8266, firmware bootloader image (with a filename like ``boot_v1.x.bin``) has to be flashed at offset {IDF_TARGET_BOOTLOADER_OFFSET}. If the firmware bootloader is missing then the ESP8266 will not boot. - - Refer to ESP8266 SDK documentation for details regarding which binaries need to be flashed at which offsets. - -.. only:: not esp8266 - - `ESP-IDF `_ and uses a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. - On {IDF_TARGET_NAME}, the bootloader image should be flashed by ESP-IDF at offset {IDF_TARGET_BOOTLOADER_OFFSET}. - - Refer to ESP-IDF documentation for details regarding which binaries need to be flashed at which offsets. - -SPI Pins Which Must Be Disconnected -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Compared to the ROM bootloader that esptool talks to, a running firmware uses more of the chip's pins to access the SPI flash. - -If you set "Quad I/O" mode (``-fm qio``, the esptool default) then GPIOs 7, 8, 9 & 10 are used for reading the SPI flash and must be otherwise disconnected. - -If you set "Dual I/O" mode (``-fm dio``) then GPIOs 7 & 8 are used for reading the SPI flash and must be otherwise disconnected. - -Try disconnecting anything from those pins (and/or swap to Dual I/O mode if you were previously using Quad I/O mode but want to attach things to GPIOs 9 & 10). Note that if GPIOs 9 & 10 are also connected to input pins on the SPI flash chip, they may still be unsuitable for use as general purpose I/O. - -In addition to these pins, GPIOs 6 & 11 are also used to access the SPI flash (in all modes). However flashing will usually fail completely if these pins are connected incorrectly. - -Early Stage Crash ------------------ - -.. only:: esp8266 - - Use any of `serial terminal programs`_ to view the boot log. (ESP8266 baud rate is 74880bps). See if the program is crashing during early startup or outputting an error message. - -.. only:: not esp8266 - - Use any of `serial terminal programs`_ to view the boot log. ({IDF_TARGET_NAME} baud rate is 115200bps). See if the program is crashing during early startup or outputting an error message. - -.. only:: not esp8266 and not esp32 and not esp32c2 - - Issues When Using USB-Serial/JTAG or USB-OTG - -------------------------------------------- - - When working with ESP chips that implement a `USB-Serial/JTAG Controller `_ or a `USB-OTG console `_, it's essential to be aware of potential issues related to the loaded application interfering with or reprogramming the GPIO pins used for USB communication. - - If the application accidentally reconfigures the USB peripheral pins or disables the USB peripheral, the device disappears from the system. You can also encounter unstable flashing or errors like ``OSError: [Errno 71] Protocol error``. - - If that happens, try :ref:`manually entering the download mode ` and then using the :ref:`erase_flash ` command to wipe the flash memory. Then, make sure to fix the issue in the application before flashing again. - -Serial Terminal Programs ------------------------- - -There are many serial terminal programs suitable for debugging & serial interaction. The pySerial module (which is required for ``esptool``) includes one such command line terminal program - miniterm.py. For more details `see the related pySerial documentation `_ or run ``miniterm -h``. -For exact serial port configuration values, see :ref:`serial-port-settings`. - -.. only:: esp8266 - - Note that not every serial program supports the unusual ESP8266 74880bps "boot log" baud rate. Support is especially sparse on Linux. miniterm.py supports this baud rate on all platforms. - -Tracing Esptool Interactions ----------------------------- - -Running ``esptool.py --trace`` will dump all serial interactions to the standard output (this is *a lot* of output). This can be helpful when debugging issues with the serial connection, or when providing information for bug reports. - -See :ref:`the related Advanced Topics page ` for more information. - -Configuration File ------------------- - -Although ``esptool.py`` has been tuned to work in the widest possible range of environments, an incompatible combination of hardware, OS, and drivers might cause it to fail. If you suspect this is the case, a custom configuration of internal variables might be necessary. - -These variables and options can be specified in a configuration file. See :ref:`the related Configuration File page ` for more information. - -Common Errors -------------- - -This is a non-exhaustive list of the most common esptool errors together with explanations of possible causes and fixes. Before reading any error-specific advice, it is highly recommended to go through all of the `Troubleshooting`_ section first. - -No serial data received. -^^^^^^^^^^^^^^^^^^^^^^^^ - -Esptool didn't receive any byte of data or a successful :ref:`slip packet `. This error usually implies some kind of a hardware issue. This may be because the hardware is not working properly at all, the RX/TX serial lines are not connected, or because there is some problem with :ref:`resetting into the download mode `. - -.. only:: esp8266 - - .. attention:: - - There is a known issue regarding ESP8266 with the CH340 USB-to-serial converter (this includes NodeMCU and Wemos D1 mini devkits) on Linux. The regression affects only certain kernel versions. See `#653 `_ for details. - - On ESP8266, this error might be the result of a wrong boot mode. If your devkit supports this, try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. - -.. only:: not esp8266 - - Wrong boot mode detected (0xXX)! The chip needs to be in download mode. - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Communication with the chip works (the ROM boot log is detected), but it is not being reset into the download mode automatically. - - To resolve this, check the autoreset circuitry (if your board has it), or try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. - - Download mode successfully detected, but getting no sync reply: The serial TX path seems to be down. - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - The chip successfully resets into the download mode and sends data to the host computer, but doesn't receive any response sent by ``esptool``. This implies a problem with the TX line running from the host to the ESP device. Double-check your board or breadboard circuit for any problems. - -Invalid head of packet (0xXX): Possible serial noise or corruption. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This error is usually caused by one of the following reasons: - -.. list:: - - :esp8266: * The chip is not resetting into the download mode. If the chip runs in a normal boot from flash mode, the ROM writes a log to UART when booting (see :ref:`ESP8266 boot log ` for more information). This data in the serial buffer result in "Invalid head of packet". You can verify this by connecting with any of `Serial Terminal Programs`_ and seeing what data is the chip sending. If this turns out to be true, check the autoreset circuitry (if your board has it), or try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. - * Using bad quality USB cable. - * Sometimes breadboards can short the SPI flash pins on the board and cause this kind of problem. Try removing your development board from the breadboard. - * The chip might be browning out during flashing. FTDI chips' internal 3.3V regulator is not enough to power an ESP, see `Insufficient Power`_. - -Other things to try: - -.. list:: - - * Try to sync and communicate at a much lower baud rate, e.g. ``esptool.py --baud 9600 ...``. - * Try `tracing the interactions `_ running ``esptool.py --trace ...`` and see if anything is received back at all. - * Try skipping chip autodetection by specifying the chip type, run ``esptool.py --chip {IDF_TARGET_NAME} ...``. - -If none of the above mentioned fixes help and your problem persists, please `open a new issue `_. - -A serial exception error occurred -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``esptool.py`` uses the `pySerial `_ Python module for accessing the serial port. -If pySerial cannot operate normally, it raises an error and terminates. Some of the most common pySerial error causes are: - -.. list:: - - * You don't have permission to access the port. - * The port is being already used by other software. - * The port doesn't exist. - * The device gets unexpectedly disconnected. - * The necessary serial port drivers are not installed or are faulty. - -An example of a pySerial error: - -.. code-block:: none - - A serial exception error occurred: read failed: [Errno 6] Device not configured - -Errors originating from pySerial are, therefore, not a problem with ``esptool.py``, but are usually caused by a problem with hardware or drivers. diff --git a/docs/en/versions.rst b/docs/en/versions.rst deleted file mode 100644 index 648701e06..000000000 --- a/docs/en/versions.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _versions: - -Versions -======== - -Starting from ``v4.0.0``, ``esptool.py`` adopts the `semantic versioning specification `_, following the ``MAJOR.MINOR.PATCH`` version number. - -Major release ``v4`` is under active development, receiving new features and bugfixes, while ``v3`` only keeps receiving important bugfixes. - -There are no support periods defined and bugfixes are not planned, therefore it is strongly recommended to install the latest version possible. - -.. note:: - - The following information is directed mainly towards package maintainers. Regular users should always use the most recent version of ``esptool.py`` to benefit from the latest features and bugfixes. - -Use the latest esptool (recommended) ------------------------------------- - -If your use case doesn't impose any constraints on ``esptool.py``, the latest release should be always used. -To see the latest available version and its release notes, visit the `release page on GitHub `_. - -To get the latest possible version, simply define your dependency as ``esptool`` (without any release operator and a version identifier). - -Use the latest bugfix release of a minor esptool release --------------------------------------------------------- - -Some use cases might require a specific ``esptool.py`` version without getting new features, but with automatic bugfixes. - -This can be achieved by defining your dependency as ``esptool~=4.0.1`` (explicitly stating the ``MAJOR``, ``MINOR``, and ``PATCH`` numbers). -This notation selects the latest version of ``esptool.py``, greater than or equal to ``v4.0.1``, but still in the ``v4.0.*`` version (this compatible release clause is approximately equivalent to the pair of comparison clauses ``>= 4.0.1``, ``== 4.0.*``). -So, for example, ``v4.1.0`` won't be downloaded. More information about compatible release clauses `can be found here `_. - -Use the latest esptool without any future breaking change ---------------------------------------------------------- - -If you also want to get new features (instead of just bugfixes), define your version requirement as ``esptool~=4.0`` (explicitly stating only the ``MAJOR`` and ``MINOR`` numbers). This way the latest minor versions (``>= 4.0``, ``== 4.*``) are automatically installed. -Backward-compatibility is still ensured, because ``esptool.py`` respects the semantic versioning specification (which states that breaking changes should occur only in ``MAJOR`` versions). - -Use the previous major esptool release (only if you cannot upgrade) -------------------------------------------------------------------- - -If your use case is not compatible with the latest ``MAJOR`` release of ``esptool.py``, a previous compatible version has to be specified. -This can be achieved by defining your dependency as ``esptool~=3.0`` (explicitly stating your desired ``MAJOR`` number and at least also the ``MINOR`` number, ``PATCH`` can also be specified). - -Use a specific esptool release ------------------------------- - -If a very specific release is required, define your dependency as ``esptool==4.1.2``. This specific version will be used and no new features or bugfixes will be automatically installed. diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 34d2904ed..000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -esp-docs==1.4.* diff --git a/docs/utils.sh b/docs/utils.sh deleted file mode 100644 index 84f374899..000000000 --- a/docs/utils.sh +++ /dev/null @@ -1,18 +0,0 @@ -# Bash helper functions for adding SSH keys - -function add_ssh_keys() { - local key_string="${1}" - mkdir -p ~/.ssh - chmod 700 ~/.ssh - echo -n "${key_string}" >~/.ssh/id_rsa_base64 - base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa - chmod 600 ~/.ssh/id_rsa -} - -function add_doc_server_ssh_keys() { - local key_string="${1}" - local server_url="${2}" - local server_user="${3}" - add_ssh_keys "${key_string}" - echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config -}