docs: fix minor issues and improve vague statements

CONTRIBUTING.rst

@@ -73,7 +73,7 @@ Code Style & Static Analysis
 
 Please follow these coding standards when writing code for ``esptool.py``:
 
-Pre-commit checks
+Pre-Commit Checks
 """""""""""""""""
 
 `pre-commit <https://pre-commit.com/>`_ is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review.
@@ -104,13 +104,13 @@ Ruff
 
 When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools.
 
-Shinx-lint
-""""""""""
+Sphinx-Lint
+"""""""""""
 
 The documentation is checked for stylistic and formal issues by ``sphinx-lint``.
 
 
-Codespell check
+Codespell Check
 """""""""""""""
 
 This repository utilizes an automatic `spell checker <https://github.com/codespell-project/codespell>`_ integrated into the pre-commit process. If any spelling issues are detected, the recommended corrections will be applied automatically to the file, ready for commit.
@@ -143,7 +143,7 @@ The following tests are not run automatically by GitHub Actions, because they ne
 
    ``pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400``
 
-   Or to run the TestFlashing suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:
+   Or to run the ``TestFlashing`` suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:
 
    ``pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing``
 
@@ -171,9 +171,7 @@ The whole test suite (without the tests needing an actual hardware or installati
 Pull Request Process
 --------------------
 
-.. note::
-
-   If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available.
+If you would like to contribute to the flasher stub, please see the `Flasher stub repository <https://github.com/espressif/esptool-legacy-flasher-stub>`_.
 
 After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
 

docs/en/advanced-topics/diag/firmware_image_ext_header_format.diag

@@ -0,0 +1,15 @@
+packetdiag command_packet_format{
+    colwidth = 16
+    node_width = 50
+    node_height = 50
+    default_fontsize = 16
+
+    0: "WP";
+    1-3: "Drive settings";
+    4-5: "Chip ID";
+    6: "Rev." [color = grey];
+    7-8: "Min rev.";
+    9-10: "Max rev.";
+    11-14: "Reserved" [color = grey];
+    15: "Hash";
+}

docs/en/advanced-topics/diag/firmware_image_format.diag

@@ -0,0 +1,12 @@
+packetdiag command_packet_format{
+    colwidth = 16
+    node_width = 50
+    node_height = 50
+    default_fontsize = 16
+
+    0-7: "Image header";
+    8-23: "Image extended header";
+    24-31: "Segmets" [color = lightgrey];
+    32-47: "..." [color = lightgrey];
+    48-63: "Footer";
+}

docs/en/advanced-topics/diag/firmware_image_format_esp8266.diag

@@ -0,0 +1,11 @@
+packetdiag command_packet_format{
+    colwidth = 16
+    node_width = 50
+    node_height = 50
+    default_fontsize = 16
+
+    0-7: "Image header";
+    8-23: "Segmets" [color = lightgrey];
+    24-31: "..." [color = lightgrey];
+    32-47: "Footer";
+}

docs/en/advanced-topics/diag/firmware_image_header_format.diag

@@ -0,0 +1,12 @@
+packetdiag command_packet_format{
+    colwidth = 8
+    node_width = 100
+    node_height = 50
+    default_fontsize = 16
+
+    0: "0xE9";
+    1: "Number of\nsegments";
+    2: "Flash Mode";
+    3: "Flash\nsize/freq";
+    4-7: "Entry point";
+}

docs/en/advanced-topics/firmware-image-format.rst

@@ -18,15 +18,27 @@ This is technical documentation for the firmware image format used by the ROM bo
 
 .. only:: esp8266
 
+    .. packetdiag:: diag/firmware_image_format_esp8266.diag
+        :caption: Firmware image format
+        :align: center
+
     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
 
+    .. packetdiag:: diag/firmware_image_format.diag
+        :caption: Firmware image format
+        :align: center
+
     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
 -----------
 
+.. packetdiag:: diag/firmware_image_header_format.diag
+    :caption: Firmware image header
+    :align: center
+
 The image header is 8 bytes long:
 
 .. only:: esp8266
@@ -128,7 +140,10 @@ The image header is 8 bytes long:
     +--------+------------------------------------------------------------------------------------------------+
 
 
-``esptool.py`` overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line option. These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of {IDF_TARGET_BOOTLOADER_OFFSET}), in this case, the appended SHA256 digest is also updated to reflect the header changes. Generating images without SHA256 digest can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument.
+``esptool.py`` overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line options (see :ref:`flash-modes`).
+These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of {IDF_TARGET_BOOTLOADER_OFFSET}).
+In this case, the appended SHA256 digest, which is a cryptographic hash used to verify the integrity of the image, is also updated to reflect the header changes.
+Generating images without SHA256 digest can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument.
 
 .. only:: esp8266
 
@@ -139,12 +154,14 @@ The image header is 8 bytes long:
     Extended File Header
     --------------------
 
-    The 16-byte long extended header comes right after the image header, individual segments come right after it:
+    .. packetdiag:: diag/firmware_image_ext_header_format.diag
+        :caption: Extended File Header
+        :align: center
 
     +--------+---------------------------------------------------------------------------------------------------------+
     | Byte   | Description                                                                                             |
     +========+=========================================================================================================+
-    | 0      | WP pin when SPI pins set via efuse (read by ROM bootloader)                                             |
+    | 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)                                          |
     +--------+---------------------------------------------------------------------------------------------------------+

docs/en/advanced-topics/serial-protocol.rst

@@ -7,11 +7,7 @@ This is technical documentation for the serial protocol used by the UART bootloa
 
 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.
+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 behavior. Pass ``--no-stub`` to esptool in order to disable the stub loader. See :ref:`stub` for more information.
 
 .. note::
 
@@ -78,7 +74,7 @@ Each received command will result in a response SLIP packet sent from the ESP ch
 | 8..n   | Data        | Variable length data payload. Length indicated by "Size" field.                                              |
 +--------+-------------+--------------------------------------------------------------------------------------------------------------+
 
-Status bytes
+Status Bytes
 """"""""""""
 
 The final bytes of the Data payload indicate command status:
@@ -153,7 +149,7 @@ After sending a command, the host should continue to read response packets until
 Commands
 ^^^^^^^^
 
-Supported by stub loader and ROM loader
+Supported by Stub Loader and ROM Loader
 """""""""""""""""""""""""""""""""""""""
 
 .. only:: esp8266
@@ -259,10 +255,10 @@ Supported by stub loader and ROM loader
     | ``0x14``   | GET_SECURITY_INFO    | Read chip security info                                        |                                                                                                                                                                                                                                                | {IDF_TARGET_SECURITY_INFO}    |
     +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
-Supported by stub loader only
+Supported by Stub Loader Only
 """""""""""""""""""""""""""""
 
-ROM loaders will not recognise these commands.
+ROM loaders will not recognize these commands.
 
 +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+
 | Byte       | Name              | Description                       | Input                                                                                                                   | Output   |
@@ -349,7 +345,7 @@ All three of these sequences follow a similar pattern:
 *  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 stub loader does just-in-time erasing as it writes data, to maximize 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.
 
@@ -382,7 +378,7 @@ The SPI_FLASH_MD5 command passes the start address in flash and the size of data
 SPI Configuration Commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-SPI Attach command
+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.
@@ -413,15 +409,15 @@ The SPI _ATTACH command enables the SPI flash interface. It takes a 32-bit data
     | (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.)
+    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:
 
     .. only:: esp32
 
         * 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.
+        * 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.
 
@@ -436,7 +432,7 @@ The SPI_SET_PARAMS command sets some parameters of the attached SPI flash chip (
 
 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 <https://github.com/espressif/esptool/blob/da31d9d7a1bb496995f8e30a6be259689948e43e/esptool.py#L655>`__ in esptool for the values which it sends.
 
-32-bit Read/Write
+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.

docs/en/advanced-topics/spi-flash-modes.rst

@@ -74,6 +74,20 @@ In ``qout`` mode, the host uses the "Quad Output Fast Read" (6BH) command to rea
 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".
 
+.. only:: esp32s3
+
+  Octal SPI
+  ^^^^^^^^^
+
+  Some ESP chips additionally support Octal SPI mode. This mode uses 8 pins for communication with the SPI flash chip, and allows for even faster data transfers than Quad SPI. This mode added four additional pins (SPIIO4~7) compared to Quad SPI for data transfers.
+
+  The 1st and 2nd bootloaders don't support ``opi`` mode. Because of that esptool doesn't use ``opi`` and ``dout`` is used instead. The bootloader retrieves the information from eFuse and effectively replaces the mode.
+
+  .. note::
+
+    Use the ``esptool.py flash_id`` command to check if your ESP is using Quad or Octal SPI mode. It prints information based on the eFuse settings.
+
+
 Frequently Asked Questions
 --------------------------
 

docs/en/espefuse/burn-bit-cmd.rst

@@ -3,12 +3,12 @@
 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.
+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.).
+- ``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:
 
@@ -39,7 +39,7 @@ Burning bits to BLOCK2:
     Reading updated efuses...
     Successful
 
-Burning In Multiple Blocks
+Burning in Multiple Blocks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: none

docs/en/espefuse/burn-block-data-cmd.rst

@@ -10,7 +10,7 @@ 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.
+* ``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.).
 

docs/en/espefuse/burn-efuse-cmd.rst

@@ -1,6 +1,6 @@
 .. _burn-efuse-cmd:
 
-Burn Efuse
+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.
@@ -90,7 +90,7 @@ On {IDF_TARGET_NAME} chips without integrated SPI flash, these eFuses are left z
 
 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.
+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 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.
 

docs/en/espefuse/burn-key-cmd.rst

@@ -155,7 +155,7 @@ By default, when an encryption key block is burned it is also read and write pro
 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.
+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.