espefuse: Update doc

espressif · Aug 17, 2022 · 5e0c1e8 · 5e0c1e8
1 parent 8d29568
commit 5e0c1e8
Show file tree

Hide file tree

Showing 22 changed files with 2,301 additions and 468 deletions.
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -18,14 +18,11 @@
 ESP8266_DOCS = []
 
 ESP32_DOCS = [
-    "espefuse/index.rst",
-    "espsecure/index.rst",
+    "espefuse/*",
+    "espsecure/*",
 ]
 
-ESP32S2_DOCS = [
-    "espefuse/index.rst",
-    "espsecure/index.rst",
-]
+ESP32S2_DOCS = ESP32_DOCS
 
 ESP32C3_DOCS = ESP32S2_DOCS
 

diff --git a/docs/en/espefuse/adc-info-cmd.rst b/docs/en/espefuse/adc-info-cmd.rst
@@ -0,0 +1,60 @@
+.. _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
@@ -0,0 +1,74 @@
+.. _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
@@ -0,0 +1,59 @@
+.. _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
@@ -0,0 +1,120 @@
+.. _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