Skip to content

Commit

Permalink
docs(sphinx-lint): Fix issues reported by sphinx-lint before adding i…
Browse files Browse the repository at this point in the history 
…t to pre-commit
  • Loading branch information
Jan Beran committed Feb 12, 2024
1 parent 1de1a26 commit 6282f98
Show file tree
Hide file tree
Showing 20 changed files with 395 additions and 392 deletions.
7 changes: 6 additions & 1 deletion CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,14 +96,19 @@ Conventional Commits
Ruff
""""

``esptool.py`` is `PEP8 <https://peps.python.org/pep-0008/>` compliant and enforces this style guide. For compliancy checking, we use `ruff <https://docs.astral.sh/ruff/>`.
``esptool.py`` is `PEP8 <https://peps.python.org/pep-0008/>`_ compliant and enforces this style guide. For compliancy checking, we use `ruff <https://docs.astral.sh/ruff/>`_.
``Ruff`` also auto-format files in the same style as previously used ``black``.


``Ruff`` and ``Conventional Precommit Linter`` tools will be automatically run by ``pre-commit`` if that is configured. To check your code manually before submitting, run ``python -m ruff`` (this tool is installed as part of the development requirements shown at the beginning of this document).

When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools.

Shinx-lint
""""""""""

The documentation is checked for stylistic and formal issues by ``sphinx-lint``.

Automated Integration Tests
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
4 changes: 2 additions & 2 deletions docs/en/espefuse/burn-bit-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Burning bits to BLOCK2:
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
Expand Down Expand Up @@ -65,7 +65,7 @@ Burning In Multiple Blocks
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
Expand Down
2 changes: 1 addition & 1 deletion docs/en/espefuse/burn-block-data-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Optional arguments:
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
Expand Down
22 changes: 11 additions & 11 deletions docs/en/espefuse/burn-custom-mac-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
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
Expand All @@ -47,12 +47,12 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
> 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 (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
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

Expand All @@ -75,7 +75,7 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
(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
Expand All @@ -88,8 +88,8 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
> 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
CUSTOM_MAC (BLOCK1) Custom MAC addr
= 48:63:92:15:72:16 (OK) R/W
.. only:: esp32c3 or esp32s2 or esp32s3

Expand All @@ -105,7 +105,7 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
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
Expand All @@ -116,5 +116,5 @@ If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already h
> espefuse.py summary
...
CUSTOM_MAC (BLOCK3) Custom MAC Address
= 48:63:92:15:72:16 (OK) R/W
CUSTOM_MAC (BLOCK3) Custom MAC Address
= 48:63:92:15:72:16 (OK) R/W
34 changes: 17 additions & 17 deletions docs/en/espefuse/burn-key-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Optional arguments:

.. 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.
{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.

Expand Down Expand Up @@ -166,7 +166,7 @@ Usage

.. code-block:: none
> espefuse.py burn_key flash_encryption 256bit_fe_key.bin
> espefuse.py burn_key flash_encryption 256bit_fe_key.bin
=== Run "burn_key" command ===
Sensitive data will be hidden (see --show-sensitive-info)
Expand All @@ -177,13 +177,13 @@ Usage
Disabling write to key block
Burn keys in efuse blocks.
The key block will be read and write protected
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
Expand All @@ -196,15 +196,15 @@ Usage
> espefuse.py summary
...
BLOCK1 (BLOCK1): Flash encryption key
= ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/-
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
Expand All @@ -219,12 +219,12 @@ Usage
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)
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
Expand All @@ -236,8 +236,8 @@ Usage
> 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
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

Expand Down Expand Up @@ -280,7 +280,7 @@ Usage
[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
Expand All @@ -297,12 +297,12 @@ Usage
...
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/-
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/-
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

Expand Down Expand Up @@ -336,7 +336,7 @@ Usage
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
Expand Down
40 changes: 20 additions & 20 deletions docs/en/espefuse/burn-key-digest-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
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 <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html#signature-block-format>`_.
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 <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html#signature-block-format>`_.

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``].
: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

Expand Down Expand Up @@ -55,7 +55,7 @@ Usage
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
Expand All @@ -66,16 +66,16 @@ Usage
> 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/-
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
> espefuse.py burn_key_digest secure_boot_v2_ecdsa192.pem
=== Run "burn_key_digest" command ===
Sensitive data will be hidden (see --show-sensitive-info)
Expand All @@ -87,7 +87,7 @@ Usage
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
Expand All @@ -97,18 +97,18 @@ Usage
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
= 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.
= 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

Expand Down Expand Up @@ -143,7 +143,7 @@ Usage
[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
Expand All @@ -162,13 +162,13 @@ Usage
...
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/-
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
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
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/-
2 changes: 1 addition & 1 deletion docs/en/espefuse/check-error-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Repairs encoding errors in eFuse blocks, if possible.
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.
Recovery of block coding errors.
This is an irreversible operation!
Type 'BURN' (all capitals) to continue.
BURN
Expand Down
3 changes: 1 addition & 2 deletions docs/en/espefuse/dump-cmd.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ The order of registers in the dump:
.. only:: not esp32 and not esp32c2

.. code-block:: none
> espefuse.py dump
Connecting....
Expand Down Expand Up @@ -111,4 +111,3 @@ These dump files can be written to another chip:
> espefuse.py burn_block_data BLOCK0 backup/chip1/blk0.bin \
BLOCK1 backup/chip1/blk1.bin \
BLOCK2 backup/chip1/blk2.bin
Loading

0 comments on commit 6282f98

Please sign in to comment.