1.. _espefuse: 2 3espefuse.py 4=========== 5 6``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). 7 8.. warning:: 9 10 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. 11 12For more details about Espressif chips eFuse features, see the `Technical Reference Manual <https://www.espressif.com/en/support/documents/technical-documents>`__. 13 14``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. 15 16Initial State of Efuses 17----------------------- 18 19On relatively new chip, most eFuses are unburned (value 0). Some eFuses are already burned at the factory stage: 20 21- MAC (Factory MAC Address). 22- ADC calibration 23- Chip package and revision. 24- etc. 25 26Supported Commands 27------------------ 28 29.. toctree:: 30 :maxdepth: 1 31 32 dump <dump-cmd> 33 summary <summary-cmd> 34 burn_efuse <burn-efuse-cmd> 35 burn_block_data <burn-block-data-cmd> 36 burn_bit <burn-bit-cmd> 37 read_protect_efuse and write_protect_efuse <read-write-protections-cmd> 38 burn_key <burn-key-cmd> 39 burn_key_digest <burn-key-digest-cmd> 40 burn_custom_mac <burn-custom-mac-cmd> 41 get_custom_mac <get-custom-mac-cmd> 42 adc_info <adc-info-cmd> 43 set_flash_voltage <set-flash-voltage-cmd> 44 execute_scripts <execute-scripts-cmd> 45 check_error <check-error-cmd> 46 47Optional General Arguments Of Commands 48-------------------------------------- 49 50- ``-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``. 51- ``--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. 52- ``--baud``, ``-b`` - Serial port baud rate, the same as for esptool. 53- ``--port``, ``-p`` - Serial port device, ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows). 54- ``--before`` - What to do before connecting to the chip: ``default_reset``, ``no_reset``, ``esp32r1``, ``no_reset_no_sync``. 55- ``--debug``, ``-d`` - Show debugging information. 56- ``--virt`` - For host tests. The tool will work in the virtual mode (without connecting to a chip). 57- ``--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``. 58- ``--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. 59- ``--extend-efuse-table`` - CSV file from `ESP-IDF <https://docs.espressif.com/projects/esp-idf/>`_ (esp_efuse_custom_table.csv). 60 61Virtual mode 62^^^^^^^^^^^^ 63 64This 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. 65 66Confirmation 67^^^^^^^^^^^^ 68 69Each 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. 70 71Coding Scheme 72------------- 73 74The 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. 75 76{IDF_TARGET_NAME} supports the following coding schemes: 77 78.. only:: esp32 79 80 * ``None`` no need any special encoding data. BLOCK0 is always None. 81 * ``3/4``, requires encoding data. The BLOCK length is reduced from 256 bits to 192 bits. 82 * ``Repeat`` not supported by this tool and IDF. The BLOCK length is reduced from 256 bits to 128 bits. 83 84 BLOCK1-3 can have any of this coding scheme. It depends on the ``CODING_SCHEME`` eFuse. 85 86.. only:: not esp32 87 88 * ``None`` no need any special encoding data, but internally it copies data four times. BLOCK0. 89 * ``RS`` (Reed-Solomon), it uses 6 bytes of automatic error correction. 90 91 Rest eFuse blocks from BLOCK1 to BLOCK(max) have ``RS`` coding scheme. 92 93This tool automatically adds encoding data to the burning data if it requires. Encoded data is calculated individually for each block. 94 95All 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. 96 97Burning Efuse 98------------- 99 100Burning 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. 101 102.. _perform-multiple-operations: 103 104Perform Multiple Operations In A Single Espefuse Run 105---------------------------------------------------- 106 107Some 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. 108 109The 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. 110 111.. code-block:: none 112 113 > espefuse.py -c esp32c2 \ 114 burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \ 115 burn_key BLOCK_KEY0 images/efuse/128bit_key.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS 116 117Extend Efuse Table 118------------------ 119 120This tool supports the use of `CSV files <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/efuse.html#description-csv-file>`_ from the `ESP-IDF <https://docs.espressif.com/projects/esp-idf/>`_ (e.g., ``esp_efuse_custom_table.csv``) to add custom eFuse fields. You can use this argument with any supported commands to access these custom eFuses. 121 122.. code-block:: none 123 124 > espefuse.py -c esp32 --extend-efuse-table path/esp_efuse_custom_table.csv summary 125 126Below is an example of an ``esp_efuse_custom_table.csv`` file. This example demonstrates how to define single eFuse fields, ``structured eFuse fields`` and ``non-sequential bit fields``: 127 128.. code-block:: none 129 130 MODULE_VERSION, EFUSE_BLK3, 56, 8, Module version 131 DEVICE_ROLE, EFUSE_BLK3, 64, 3, Device role 132 SETTING_1, EFUSE_BLK3, 67, 6, [SETTING_1_ALT_NAME] Setting 1 133 SETTING_2, EFUSE_BLK3, 73, 5, Setting 2 134 ID_NUM, EFUSE_BLK3, 140, 8, [MY_ID_NUM] comment 135 , EFUSE_BLK3, 132, 8, [MY_ID_NUM] comment 136 , EFUSE_BLK3, 122, 8, [MY_ID_NUM] comment 137 CUSTOM_SECURE_VERSION, EFUSE_BLK3, 78, 16, Custom secure version 138 ID_NUMK, EFUSE_BLK3, 150, 8, [MY_ID_NUMK] comment 139 , EFUSE_BLK3, 182, 8, [MY_ID_NUMK] comment 140 MY_DATA, EFUSE_BLK3, 190, 10, My data 141 MY_DATA.FIELD1, EFUSE_BLK3, 190, 7, Field1 142 143When you include this CSV file, the tool will generate a new section in the summary called ``User fuses``. 144 145.. code-block:: none 146 147 User fuses: 148 MODULE_VERSION (BLOCK3) Module version (56-63) = 0 R/W (0x00) 149 DEVICE_ROLE (BLOCK3) Device role (64-66) = 0 R/W (0b000) 150 SETTING_1 (BLOCK3) [SETTING_1_ALT_NAME] Setting 1 (67-72) = 0 R/W (0b000000) 151 SETTING_2 (BLOCK3) Setting 2 (73-77) = 0 R/W (0b00000) 152 ID_NUM_0 (BLOCK3) [MY_ID_NUM] comment (140-147) = 0 R/W (0x00) 153 ID_NUM_1 (BLOCK3) [MY_ID_NUM] comment (132-139) = 0 R/W (0x00) 154 ID_NUM_2 (BLOCK3) [MY_ID_NUM] comment (122-129) = 0 R/W (0x00) 155 CUSTOM_SECURE_VERSION (BLOCK3) Custom secure version (78-93) = 0 R/W (0x0000) 156 ID_NUMK_0 (BLOCK3) [MY_ID_NUMK] comment (150-157) = 0 R/W (0x00) 157 ID_NUMK_1 (BLOCK3) [MY_ID_NUMK] comment (182-189) = 0 R/W (0x00) 158 MY_DATA (BLOCK3) My data (190-199) = 0 R/W (0b0000000000) 159 MY_DATA_FIELD1 (BLOCK3) Field1 (190-196) = 0 R/W (0b0000000) 160 161You can reference these fields using the names and aliases provided in the CSV file. For non-sequential bits, the names are modified slightly with the addition of _0 and _1 postfixes for every sub-field, to ensure safer handling. 162 163For the current example, you can reference the custom fields with the following names: MODULE_VERSION, DEVICE_ROLE, SETTING_1, SETTING_2, ID_NUM_0, ID_NUM_1, ID_NUM_2, CUSTOM_SECURE_VERSION, ID_NUMK_0, ID_NUMK_1, MY_DATA, MY_DATA_FIELD1; and alises: SETTING_1_ALT_NAME, MY_ID_NUM_0, MY_ID_NUM_1, MY_ID_NUM_2, MY_ID_NUMK_0, MY_ID_NUMK_1. 164 165For convenience, the espefuse summary command includes the used bit range of the field in a comment, such as ``(150-157)`` len = 8 bits. 166 167For more details on the structure and usage of the CSV file, refer to the `eFuse Manager <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/efuse.html#description-csv-file>`_ chapter in the ESP-IDF documentation. 168 169Recommendations 170--------------- 171 1721. The `Technical Reference Manual <https://www.espressif.com/en/support/documents/technical-documents>`__ has a recommendation for reducing the number of burn operations as much as possible. The tool supports several ways to do this: 173 174 - Combine multiple commands into one with this :ref:`perform-multiple-operations` feature. 175 - Most commands support getting a list of arguments (eFuse names, keys). 176 1773. Make sure the power supply is stable because this may cause burning problems. 178
