docs: add c2, c6 and h2 as build targets

espressif · Jun 2, 2023 · 590fb55 · 590fb55
1 parent b137d3d
commit 590fb55
Show file tree

Hide file tree

Showing 10 changed files with 111 additions and 36 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -427,7 +427,7 @@ build_docs:
   script:
     - cd docs
     - pip install -r requirements.txt --prefer-binary
-    - build-docs -l en -t {esp8266,esp32,esp32s2,esp32c3,esp32s3}
+    - build-docs -l en -t {esp8266,esp32,esp32s2,esp32c3,esp32s3,esp32c2,esp32c6,esp32h2}
 
 .deploy_docs_template:
   stage: deploy_docs

diff --git a/docs/_static/esptool_versions.js b/docs/_static/esptool_versions.js
@@ -9,5 +9,8 @@ var DOCUMENTATION_VERSIONS = {
        { text: "ESP32-S2", value: "esp32s2" },
        { text: "ESP32-S3", value: "esp32s3" },
        { text: "ESP32-C3", value: "esp32c3" },
+       { text: "ESP32-C2", value: "esp32c2" },
+       { text: "ESP32-C6", value: "esp32c6" },
+       { text: "ESP32-H2", value: "esp32h2" },
     ]
 };
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -1,7 +1,16 @@
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
 languages = ["en"]
-idf_targets = ["esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3"]
+idf_targets = [
+    "esp8266",
+    "esp32",
+    "esp32s2",
+    "esp32s3",
+    "esp32c3",
+    "esp32c2",
+    "esp32c6",
+    "esp32h2",
+]
 
 # link roles config
 github_repo = "espressif/esptool"
@@ -28,12 +37,21 @@
 
 ESP32S3_DOCS = ESP32S2_DOCS
 
+ESP32C2_DOCS = ESP32S3_DOCS
+
+ESP32C6_DOCS = ESP32C2_DOCS
+
+ESP32H2_DOCS = ESP32C6_DOCS
+
 conditional_include_dict = {
     "esp8266": ESP8266_DOCS,
     "esp32": ESP32_DOCS,
     "esp32s2": ESP32S2_DOCS,
     "esp32c3": ESP32C3_DOCS,
     "esp32s3": ESP32S3_DOCS,
+    "esp32c2": ESP32C2_DOCS,
+    "esp32c6": ESP32C6_DOCS,
+    "esp32h2": ESP32H2_DOCS,
 }
 
 # Extra options required by sphinx_idf_theme

diff --git a/docs/en/advanced-topics/boot-mode-selection.rst b/docs/en/advanced-topics/boot-mode-selection.rst
@@ -1,8 +1,8 @@
-{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c3="GPIO9"}
+{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0"}
 
-{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO2", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46", esp32c3="GPIO8"}
+{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46"}
 
-{IDF_TARGET_BOOTLOADER_OFFSET:default="0", esp8266="0", esp32="1000", esp32s2="1000", esp32s3="0", esp32c3="0"}
+{IDF_TARGET_BOOTLOADER_OFFSET:default="0",esp32="1000", esp32s2="1000"}
 
 .. _boot-mode:
 
@@ -84,7 +84,7 @@ This guide explains how to select the boot mode correctly and describes the boot
 
       {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be either left unconnected/floating, or driven Low, in order to enter the serial bootloader.
 
-   .. only:: esp32c3
+   .. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6
 
       {IDF_TARGET_STRAP_BOOT_2_GPIO} must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of {IDF_TARGET_STRAP_BOOT_2_GPIO} = 0 and {IDF_TARGET_STRAP_BOOT_GPIO} = 0 is invalid and will trigger unexpected behavior.
 

diff --git a/docs/en/advanced-topics/firmware-image-format.rst b/docs/en/advanced-topics/firmware-image-format.rst
@@ -1,3 +1,12 @@
+{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"}
+
+{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"}
+
+{IDF_TARGET_FLASH_FREQ_1:default="26", esp32c2="20", esp32h2="16"}
+
+{IDF_TARGET_FLASH_FREQ_2:default="20", esp32c2="15", esp32h2="12"}
+
+
 .. _image-format:
 
 Firmware Image Format
@@ -37,29 +46,67 @@ The image header is 8 bytes long:
     | 4-7    | Entry point address                                                                              |
     +--------+--------------------------------------------------------------------------------------------------+
 
-.. only:: not esp8266
-
-    +--------+--------------------------------------------------------------------------------------------------+
-    | Byte   | Description                                                                                      |
-    +========+==================================================================================================+
-    | 0      | Magic number (always ``0xE9``)                                                                   |
-    +--------+--------------------------------------------------------------------------------------------------+
-    | 1      | Number of segments                                                                               |
-    +--------+--------------------------------------------------------------------------------------------------+
-    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                            |
-    +--------+--------------------------------------------------------------------------------------------------+
-    | 3      | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB)   |
-    |        |                                                                                                  |
-    |        | Low four bits - Flash frequency (``0`` = 40MHz, ``1`` = 26MHz, ``2`` = 20MHz, ``0xf`` = 80MHz)   |
-    +--------+--------------------------------------------------------------------------------------------------+
-    | 4-7    | Entry point address                                                                              |
-    +--------+--------------------------------------------------------------------------------------------------+
-
-.. only:: esp32c2 or esp32h2
 
-    .. fail_when_new_target_added::
+.. only:: esp32s2 or esp32s3
+
+    +--------+------------------------------------------------------------------------------------------------+
+    | Byte   | Description                                                                                    |
+    +========+================================================================================================+
+    | 0      | Magic number (always ``0xE9``)                                                                 |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 1      | Number of segments                                                                             |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                          |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 3      | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB, |
+    |        | ``5`` = 32MB, ``6`` = 64MB, ``7`` = 128MB")                                                    |
+    |        |                                                                                                |
+    |        | Low four bits - Flash frequency (``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``1`` = {IDF_TARGET_FLASH_FREQ_1}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz, ``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz) |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 4-7    | Entry point address                                                                            |
+    +--------+------------------------------------------------------------------------------------------------+
+
+
+.. only:: esp32c6
+
+    +--------+------------------------------------------------------------------------------------------------+
+    | Byte   | Description                                                                                    |
+    +========+================================================================================================+
+    | 0      | Magic number (always ``0xE9``)                                                                 |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 1      | Number of segments                                                                             |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                          |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 3      | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB) |
+    |        |                                                                                                |
+    |        | Low four bits - Flash frequency (``0`` = 80MHz, ``0`` = 40MHz, ``2`` = 20MHz)                  |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 4-7    | Entry point address                                                                            |
+    +--------+------------------------------------------------------------------------------------------------+
+
+    .. note::
+        Flash frequency with value ``0`` can mean either 80MHz or 40MHz based on MSPI clock source mode.
+
+
+.. only:: not (esp8266 or esp32c6 or esp32s3 or esp32s2)
+
+    +--------+------------------------------------------------------------------------------------------------+
+    | Byte   | Description                                                                                    |
+    +========+================================================================================================+
+    | 0      | Magic number (always ``0xE9``)                                                                 |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 1      | Number of segments                                                                             |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 2      | SPI Flash Mode (``0`` = QIO, ``1`` = QOUT, ``2`` = DIO, ``3`` = DOUT)                          |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 3      | High four bits - Flash size (``0`` = 1MB, ``1`` = 2MB, ``2`` = 4MB, ``3`` = 8MB, ``4`` = 16MB) |
+    |        |                                                                                                |
+    |        | Low four bits - Flash frequency (``0`` = {IDF_TARGET_FLASH_FREQ_0}MHz, ``1`` = {IDF_TARGET_FLASH_FREQ_1}MHz, ``2`` = {IDF_TARGET_FLASH_FREQ_2}MHz, ``0xf`` = {IDF_TARGET_FLASH_FREQ_F}MHz) |
+    +--------+------------------------------------------------------------------------------------------------+
+    | 4-7    | Entry point address                                                                            |
+    +--------+------------------------------------------------------------------------------------------------+
 
-        TODO: Update flash frequency lists to be esp32c2 or esp32h2 specific
 
 ``esptool.py`` overrides the 2nd and 3rd (start from 0) bytes according to the SPI flash info provided through command line option, but only if there is no SHA256 digest appended after the image. Therefore, if you would like to change SPI flash info during flashing, i.e. with the ``esptool.py write_flash`` command, then generate images without SHA256 digests. This can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument.
 

diff --git a/docs/en/esptool/advanced-commands.rst b/docs/en/esptool/advanced-commands.rst
@@ -1,4 +1,4 @@
-{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp8266="0x0", esp32="0x1000", esp32s2="0x1000", esp32s3="0x0", esp32c3="0x0"}
+{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"}
 
 .. _advanced-commands:
 

diff --git a/docs/en/esptool/advanced-options.rst b/docs/en/esptool/advanced-options.rst
@@ -22,7 +22,7 @@ The ``--before`` argument allows you to specify whether the chip needs resetting
     * ``--before default_reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode.
     * ``--before no_reset`` will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
     * ``--before no_reset_no_sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader <stub>` and you want to avoid resetting the chip and uploading the stub again.
-    :esp32c3 or esp32s3: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
+    :esp32c3 or esp32s3 or esp32c6 or esp32h2: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
 
 Reset After Operation
 ^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/en/esptool/flash-modes.rst b/docs/en/esptool/flash-modes.rst
@@ -1,4 +1,11 @@
-{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp8266="0x0", esp32="0x1000", esp32s2="0x1000", esp32s3="0x0", esp32c3="0x0"}
+{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"}
+
+{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"}
+
+{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"}
+
+{IDF_TARGET_FLASH_FREQ:default="``40m``, ``26m``, ``20m``, ``80m``", esp32c2="``30m``, ``20m``, ``15m``, ``60m``", esp32h2="``24m``, ``16m``, ``12m``, ``48m``", esp32c6="``40m``, ``20m``, ``80m``"}
+
 
 .. _flash-modes:
 
@@ -36,9 +43,9 @@ For a full explanation of these modes, see the :ref:`SPI Flash Modes page <spi-f
 Flash Frequency (--flash_freq, -ff)
 ------------------------------------
 
-Clock frequency for SPI flash interactions. Valid values are ``keep``, ``40m``, ``26m``, ``20m``, ``80m`` (MHz). The default is ``keep``, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ``ESPTOOL_FF``.
+Clock frequency for SPI flash interactions. Valid values are ``keep``, {IDF_TARGET_FLASH_FREQ} (MHz). The default is ``keep``, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ``ESPTOOL_FF``.
 
-The flash chip connected to most chips works with 40MHz clock speeds, but you can try lower values if the device won't boot. The highest 80MHz flash clock speed will give the best performance, but may cause crashing if the flash or board design is not capable of this speed.
+The flash chip connected to most chips works with {IDF_TARGET_FLASH_FREQ_0}MHz clock speeds, but you can try lower values if the device won't boot. The highest {IDF_TARGET_FLASH_FREQ_F}MHz flash clock speed will give the best performance, but may cause crashing if the flash or board design is not capable of this speed.
 
 Flash Size (--flash_size, -fs)
 -------------------------------
@@ -49,13 +56,13 @@ Size of the SPI flash, given in megabytes.
 
     Valid values are: ``keep``, ``detect``, ``256KB``, ``512KB``, ``1MB``, ``2MB``, ``4MB``, ``2MB-c1``, ``4MB-c1``, ``8MB``, ``16MB``
 
-.. only:: esp32 or esp32c3
+.. only:: esp32 or esp32c3 or esp32c6 or esp32c2 or esp32h2
 
     Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``
 
 .. only:: esp32s2 or esp32s3
 
-    Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``, ``32MB``, ``64MB``
+    Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``, ``32MB``, ``64MB``, ``128MB``
 
 .. note::
 

diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst
@@ -1,4 +1,4 @@
-{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp8266="0x0", esp32="0x1000", esp32s2="0x1000", esp32s3="0x0", esp32c3="0x0"}
+{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"}
 
 .. _troubleshooting:
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1 @@
-esp-docs==1.0.*
+esp-docs==1.4.*