1.. _burn-efuse-cmd:
2
3Burn Efuse
4==========
5
6The ``espefuse.py burn_efuse`` command burns eFuses. The arguments to ``burn_efuse`` are eFuse names (as shown in summary output) and new values.
7
8Positional arguments:
9
10- ``eFuse name``
11- ``value``
12
13Optional arguments:
14
15* ``--force``. Suppress an error to burn eFuses. The tool checks for incompatible eFuse states to prevent them from burning and potentially **bricking the chip**. Use this flag only if you are sure. This will suppress the eFuse incompatibility error.
16
17It can be list of eFuse names and values (like EFUSE_NAME1 1 EFUSE_NAME2 7 EFUSE_NAME3 10 etc.).
18
19New 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.
20
21This 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.
22
23.. code-block:: none
24
25    > espefuse.py --port /dev/ttyUSB0 burn_efuse   DIS_USB_JTAG 1   VDD_SPI_AS_GPIO 1
26
27    === Run "burn_efuse" command ===
28    The efuses to burn:
29    from BLOCK0
30        - DIS_USB_JTAG
31        - VDD_SPI_AS_GPIO
32
33    Burning efuses:
34
35        - 'DIS_USB_JTAG' (Disables USB JTAG. JTAG access via pads is controlled separately) 0b0 -> 0b1
36        - 'VDD_SPI_AS_GPIO' (Set this bit to vdd spi pin function as gpio) 0b0 -> 0b1
37
38    Check all blocks for burn...
39    idx, BLOCK_NAME,          Conclusion
40    [00] BLOCK0               is empty, will burn the new value
41    .
42    This is an irreversible operation!
43    Type 'BURN' (all capitals) to continue.
44
45By default, ``espefuse.py`` will ask you to type ``BURN`` before it permanently sets eFuses. The ``--do-not-confirm`` option allows you to bypass this.
46
47.. code-block:: none
48
49    BURN
50    BURN BLOCK0  - OK (write block == read block)
51    Reading updated efuses...
52    Checking efuses...
53    Successful
54
55.. _espefuse-spi-flash-pins:
56
57SPI Flash Pins
58--------------
59
60The following efuses configure the SPI flash pins which are used to boot:
61
62.. only:: esp32
63
64    .. code-block:: none
65
66        SPI_PAD_CONFIG_CLK     Override SD_CLK pad (GPIO6/SPICLK)                = 0 R/W (0x0)
67        SPI_PAD_CONFIG_Q       Override SD_DATA_0 pad (GPIO7/SPIQ)               = 0 R/W (0x0)
68        SPI_PAD_CONFIG_D       Override SD_DATA_1 pad (GPIO8/SPID)               = 0 R/W (0x0)
69        SPI_PAD_CONFIG_HD      Override SD_DATA_2 pad (GPIO9/SPIHD)              = 0 R/W (0x0)
70        SPI_PAD_CONFIG_CS0     Override SD_CMD pad (GPIO11/SPICS0)               = 0 R/W (0x0)
71
72.. only:: not esp32
73
74    .. code-block:: none
75
76        Spi_Pad_Config fuses:
77        SPI_PAD_CONFIG_CLK (BLOCK1)              SPI CLK pad                                        = 0 R/W (0b000000)
78        SPI_PAD_CONFIG_Q (BLOCK1)                SPI Q (D1) pad                                     = 0 R/W (0b000000)
79        SPI_PAD_CONFIG_D (BLOCK1)                SPI D (D0) pad                                     = 0 R/W (0b000000)
80        SPI_PAD_CONFIG_CS (BLOCK1)               SPI CS pad                                         = 0 R/W (0b000000)
81        SPI_PAD_CONFIG_HD (BLOCK1)               SPI HD (D3) pad                                    = 0 R/W (0b000000)
82        SPI_PAD_CONFIG_WP (BLOCK1)               SPI WP (D2) pad                                    = 0 R/W (0b000000)
83        SPI_PAD_CONFIG_DQS (BLOCK1)              SPI DQS pad                                        = 0 R/W (0b000000)
84        SPI_PAD_CONFIG_D4 (BLOCK1)               SPI D4 pad                                         = 0 R/W (0b000000)
85        SPI_PAD_CONFIG_D5 (BLOCK1)               SPI D5 pad                                         = 0 R/W (0b000000)
86        SPI_PAD_CONFIG_D6 (BLOCK1)               SPI D6 pad                                         = 0 R/W (0b000000)
87        SPI_PAD_CONFIG_D7 (BLOCK1)               SPI D7 pad                                         = 0 R/W (0b000000)
88
89On {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.
90
91On {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.
92
93In 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.
94
95If these eFuses are burned, GPIO1 (U0TXD pin) is no longer consulted to set the boot mode from SPI to HSPI flash on reset.
96
97These 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.)
98
99For example:
100
101.. code-block:: none
102
103    SPI_PAD_CONFIG_CS0     Override SD_CMD pad (GPIO11/SPICS0)               = 32 R/W (0x1e)
104
105If using the ``burn_efuse`` command to configure these pins, always specify the actual GPIO number you wish to set.
106