docs(build): add support for building H21 docs

.gitlab/ci/docs.yml

@@ -94,7 +94,7 @@ check_docs_lang_sync:
   parallel:
     matrix:
       - DOCLANG: ["en", "zh_CN"]
-        DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32c61", "esp32c5","esp32h2", "esp32p4"]
+        DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32c61", "esp32c5","esp32h2", "esp32h21", "esp32p4"]
 
 check_docs_gh_links:
   image: $ESP_IDF_DOC_ENV_IMAGE

components/esp_hw_support/port/esp32h21/Kconfig.mac

@@ -0,0 +1,18 @@
+choice ESP32H21_UNIVERSAL_MAC_ADDRESSES
+    bool "Number of universally administered (by IEEE) MAC address"
+    default ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO
+    help
+        Configure the number of universally administered (by IEEE) MAC addresses.
+        During initialization, MAC addresses for each network interface are generated or derived from a
+        single base MAC address.
+
+    config ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO
+        bool "Two"
+        select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO
+        select ESP_MAC_ADDR_UNIVERSE_IEEE802154
+        select ESP_MAC_ADDR_UNIVERSE_BT
+endchoice
+
+config ESP32H21_UNIVERSAL_MAC_ADDRESSES
+    int
+    default 2 if ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO

components/soc/esp32h21/include/soc/Kconfig.soc_caps.in

@@ -259,6 +259,10 @@ config SOC_ANA_CMPR_INTR_SHARE_WITH_GPIO
     bool
     default y
 
+config SOC_LEDC_CHANNEL_NUM
+    int
+    default 6
+
 config SOC_MPI_MEM_BLOCKS_NUM
     int
     default 4
@@ -327,10 +331,6 @@ config SOC_SPI_SUPPORT_CONTINUOUS_TRANS
     bool
     default y
 
-config SOC_SPI_SUPPORT_SLAVE_HD_VER2
-    bool
-    default y
-
 config SOC_SPI_SUPPORT_CLK_XTAL
     bool
     default y

components/soc/esp32h21/include/soc/adc_channel.h

@@ -0,0 +1,7 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once

components/soc/esp32h21/include/soc/soc_caps.h

@@ -279,7 +279,7 @@
 /*-------------------------- LEDC CAPS ---------------------------------------*/
 // #define SOC_LEDC_SUPPORT_PLL_DIV_CLOCK      (1)
 // #define SOC_LEDC_SUPPORT_XTAL_CLOCK         (1)
-// #define SOC_LEDC_CHANNEL_NUM                (6)
+#define SOC_LEDC_CHANNEL_NUM                (6) // Check, todo IDF-11568
 // #define SOC_LEDC_TIMER_BIT_WIDTH            (20)
 // #define SOC_LEDC_SUPPORT_FADE_STOP          (1)
 // #define SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED (1)
@@ -384,7 +384,7 @@
 #define SOC_SPI_SLAVE_SUPPORT_SEG_TRANS     1
 #define SOC_SPI_SUPPORT_CD_SIG              1
 #define SOC_SPI_SUPPORT_CONTINUOUS_TRANS    1
-#define SOC_SPI_SUPPORT_SLAVE_HD_VER2       1
+// #define SOC_SPI_SUPPORT_SLAVE_HD_VER2       1 // TODO IDF-11587
 #define SOC_SPI_SUPPORT_CLK_XTAL            1
 #define SOC_SPI_SUPPORT_CLK_PLL_F48M        1
 #define SOC_SPI_SUPPORT_CLK_RC_FAST         1

docs/conf_common.py

@@ -169,7 +169,8 @@ TWAI_DOCS = ['api-reference/peripherals/twai.rst']
 SDM_DOCS = ['api-reference/peripherals/sdm.rst']
 
 I2C_DOCS = ['api-reference/peripherals/i2c.rst',
-            'api-reference/peripherals/lcd/i2c_lcd.rst']
+            'api-reference/peripherals/lcd/i2c_lcd.rst',
+            'api-reference/peripherals/i2c_slave_v1.rst']
 
 SPI_DOCS = ['api-reference/peripherals/spi_master.rst',
             'api-reference/peripherals/spi_slave.rst',

docs/docs_not_updated/esp32h21.txt

@@ -0,0 +1,296 @@
+index.rst
+api-guides/openthread.rst
+api-guides/index.rst
+api-guides/c.rst
+api-guides/reproducible-builds.rst
+api-guides/core_dump_internals.rst
+api-guides/error-handling.rst
+api-guides/wifi-expansion.rst
+api-guides/deep-sleep-stub.rst
+api-guides/performance/index.rst
+api-guides/performance/ram-usage.rst
+api-guides/performance/speed.rst
+api-guides/performance/size.rst
+api-guides/app_trace.rst
+api-guides/esp-wifi-mesh.rst
+api-guides/startup.rst
+api-guides/usb-serial-jtag-console.rst
+api-guides/build-system.rst
+api-guides/thread-local-storage.rst
+api-guides/memory-types.rst
+api-guides/cplusplus.rst
+api-guides/core_dump.rst
+api-guides/lwip.rst
+api-guides/hardware-abstraction.rst
+api-guides/host-apps.rst
+api-guides/esp-ble-mesh/ble-mesh-faq.rst
+api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
+api-guides/esp-ble-mesh/ble-mesh-index.rst
+api-guides/esp-ble-mesh/ble-mesh-terminology.rst
+api-guides/esp-ble-mesh/ble-mesh-architecture.rst
+api-guides/phy.rst
+api-guides/stdio.rst
+api-guides/flash_psram_config.rst
+api-guides/classic-bt/index.rst
+api-guides/classic-bt/overview.rst
+api-guides/unit-tests.rst
+api-guides/external-ram.rst
+api-guides/low-power-mode/index.rst
+api-guides/low-power-mode/low-power-mode-wifi.rst
+api-guides/low-power-mode/low-power-mode-soc.rst
+api-guides/general-notes.rst
+api-guides/wifi.rst
+api-guides/ble/index.rst
+api-guides/ble/overview.rst
+api-guides/ble/get-started/ble-device-discovery.rst
+api-guides/ble/get-started/ble-introduction.rst
+api-guides/ble/get-started/ble-data-exchange.rst
+api-guides/ble/get-started/ble-connection.rst
+api-guides/ble/host-feature-support-status.rst
+api-guides/ble/ble-qualification.rst
+api-guides/ble/blufi.rst
+api-guides/ble/ble-feature-support-status.rst
+api-guides/file-system-considerations.rst
+api-guides/jtag-debugging/index.rst
+api-guides/jtag-debugging/building-openocd-macos.rst
+api-guides/jtag-debugging/debugging-examples.rst
+api-guides/jtag-debugging/building-openocd-windows.rst
+api-guides/jtag-debugging/configure-ft2232h-jtag.rst
+api-guides/jtag-debugging/configure-other-jtag.rst
+api-guides/jtag-debugging/using-debugger.rst
+api-guides/jtag-debugging/building-openocd-linux.rst
+api-guides/jtag-debugging/tips-and-quirks.rst
+api-guides/jtag-debugging/configure-builtin-jtag.rst
+api-guides/bootloader.rst
+api-guides/hlinterrupts.rst
+api-guides/kconfig/index.rst
+api-guides/kconfig/project-configuration-guide.rst
+api-guides/kconfig/component-configuration-guide.rst
+api-guides/kconfig/configuration_structure.rst
+api-guides/inc/linux-host-requirements.rst
+api-guides/fatal-errors.rst
+api-guides/wifi-security.rst
+api-guides/RF_calibration.rst
+api-guides/usb-otg-console.rst
+api-guides/partition-tables.rst
+api-guides/linker-script-generation.rst
+api-guides/current-consumption-measurement-modules.rst
+api-guides/coexist.rst
+api-guides/wireshark-user-guide.rst
+api-guides/code-quality/index.rst
+api-guides/code-quality/static-analyzer.rst
+api-guides/dfu.rst
+about.rst
+get-started/index.rst
+get-started/flashing-troubleshooting.rst
+get-started/windows-setup.rst
+get-started/establish-serial-connection.rst
+get-started/windows-start-project.rst
+get-started/start-project.rst
+get-started/linux-macos-start-project.rst
+get-started/linux-macos-setup.rst
+get-started/windows-setup-update.rst
+hw-reference/index.rst
+api-reference/index.rst
+api-reference/network/index.rst
+api-reference/network/esp_eth.rst
+api-reference/network/esp-wifi-mesh.rst
+api-reference/network/esp_smartconfig.rst
+api-reference/network/esp_wifi.rst
+api-reference/network/esp_netif_programming.rst
+api-reference/network/esp_dpp.rst
+api-reference/network/esp_nan.rst
+api-reference/network/esp_now.rst
+api-reference/network/esp_netif_driver.rst
+api-reference/network/esp_netif.rst
+api-reference/network/esp_openthread.rst
+api-reference/provisioning/index.rst
+api-reference/provisioning/provisioning.rst
+api-reference/provisioning/protocomm.rst
+api-reference/provisioning/wifi_provisioning.rst
+api-reference/template.rst
+api-reference/kconfig-reference.rst
+api-reference/protocols/index.rst
+api-reference/protocols/esp_crt_bundle.rst
+api-reference/protocols/mdns.rst
+api-reference/protocols/asio.rst
+api-reference/protocols/mbedtls.rst
+api-reference/protocols/modbus.rst
+api-reference/protocols/icmp_echo.rst
+api-reference/protocols/esp_serial_slave_link.rst
+api-reference/protocols/esp_sdio_slave_protocol.rst
+api-reference/protocols/esp_https_server.rst
+api-reference/protocols/esp_local_ctrl.rst
+api-reference/protocols/esp_tls.rst
+api-reference/protocols/esp_spi_slave_protocol.rst
+api-reference/protocols/esp_http_client.rst
+api-reference/protocols/mqtt.rst
+api-reference/protocols/esp_http_server.rst
+api-reference/storage/mass_mfg.rst
+api-reference/storage/index.rst
+api-reference/storage/sdmmc.rst
+api-reference/storage/nvs_bootloader.rst
+api-reference/storage/wear-levelling.rst
+api-reference/storage/nvs_partition_gen.rst
+api-reference/storage/spiffs.rst
+api-reference/storage/nvs_flash.rst
+api-reference/storage/vfs.rst
+api-reference/storage/nvs_partition_parse.rst
+api-reference/storage/storage-security.rst
+api-reference/storage/fatfs.rst
+api-reference/storage/fatfsgen.rst
+api-reference/storage/nvs_encryption.rst
+api-reference/storage/partition.rst
+api-reference/error-codes.rst
+api-reference/bluetooth/index.rst
+api-reference/bluetooth/esp_gatts.rst
+api-reference/bluetooth/esp_hf_ag.rst
+api-reference/bluetooth/esp_gattc.rst
+api-reference/bluetooth/bt_le.rst
+api-reference/bluetooth/controller_vhci.rst
+api-reference/bluetooth/esp_spp.rst
+api-reference/bluetooth/esp_sdp.rst
+api-reference/bluetooth/esp_blufi.rst
+api-reference/bluetooth/bt_common.rst
+api-reference/bluetooth/esp_hf_client.rst
+api-reference/bluetooth/esp_hidh.rst
+api-reference/bluetooth/esp_gap_ble.rst
+api-reference/bluetooth/esp_avrc.rst
+api-reference/bluetooth/esp_gatt_defs.rst
+api-reference/bluetooth/nimble/index.rst
+api-reference/bluetooth/esp_bt_main.rst
+api-reference/bluetooth/esp_bt_device.rst
+api-reference/bluetooth/esp-ble-mesh.rst
+api-reference/bluetooth/esp_hidd.rst
+api-reference/bluetooth/esp_bt_defs.rst
+api-reference/bluetooth/esp_l2cap_bt.rst
+api-reference/bluetooth/esp_gap_bt.rst
+api-reference/bluetooth/classic_bt.rst
+api-reference/bluetooth/esp_a2dp.rst
+api-reference/bluetooth/esp_hf_defs.rst
+api-reference/peripherals/cap_touch_sens.rst
+api-reference/peripherals/index.rst
+api-reference/peripherals/rmt.rst
+api-reference/peripherals/ds.rst
+api-reference/peripherals/gptimer.rst
+api-reference/peripherals/sdio_slave.rst
+api-reference/peripherals/bitscrambler.rst
+api-reference/peripherals/temp_sensor.rst
+api-reference/peripherals/usb_device.rst
+api-reference/peripherals/i2c.rst
+api-reference/peripherals/jpeg.rst
+api-reference/peripherals/mcpwm.rst
+api-reference/peripherals/usb_host.rst
+api-reference/peripherals/clk_tree.rst
+api-reference/peripherals/camera_driver.rst
+api-reference/peripherals/touch_element.rst
+api-reference/peripherals/spi_master.rst
+api-reference/peripherals/adc_oneshot.rst
+api-reference/peripherals/twai.rst
+api-reference/peripherals/etm.rst
+api-reference/peripherals/sdspi_share.rst
+api-reference/peripherals/ana_cmpr.rst
+api-reference/peripherals/i2c_slave_v1.rst
+api-reference/peripherals/adc_continuous.rst
+api-reference/peripherals/hmac.rst
+api-reference/peripherals/uart.rst
+api-reference/peripherals/sdspi_host.rst
+api-reference/peripherals/spi_slave_hd.rst
+api-reference/peripherals/vad.rst
+api-reference/peripherals/i2s.rst
+api-reference/peripherals/isp.rst
+api-reference/peripherals/usb_host/usb_host_notes_usbh.rst
+api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
+api-reference/peripherals/usb_host/usb_host_notes_arch.rst
+api-reference/peripherals/usb_host/usb_host_notes_index.rst
+api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst
+api-reference/peripherals/usb_host/usb_host_notes_design.rst
+api-reference/peripherals/usb_host/usb_host_notes_enum.rst
+api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst
+api-reference/peripherals/dedic_gpio.rst
+api-reference/peripherals/sd_pullup_requirements.rst
+api-reference/peripherals/parlio.rst
+api-reference/peripherals/adc_calibration.rst
+api-reference/peripherals/lp_i2s.rst
+api-reference/peripherals/ecdsa.rst
+api-reference/peripherals/gpio.rst
+api-reference/peripherals/dac.rst
+api-reference/peripherals/spi_slave.rst
+api-reference/peripherals/spi_flash/index.rst
+api-reference/peripherals/spi_flash/spi_flash_concurrency.rst
+api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
+api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
+api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
+api-reference/peripherals/sdm.rst
+api-reference/peripherals/sdmmc_host.rst
+api-reference/peripherals/lcd/i80_lcd.rst
+api-reference/peripherals/lcd/index.rst
+api-reference/peripherals/lcd/dsi_lcd.rst
+api-reference/peripherals/lcd/i2c_lcd.rst
+api-reference/peripherals/lcd/spi_lcd.rst
+api-reference/peripherals/lcd/rgb_lcd.rst
+api-reference/peripherals/lcd/parl_lcd.rst
+api-reference/peripherals/pcnt.rst
+api-reference/peripherals/spi_features.rst
+api-reference/peripherals/ppa.rst
+api-reference/peripherals/ldo_regulator.rst
+api-reference/peripherals/ledc.rst
+api-reference/system/index.rst
+api-reference/system/freertos_idf.rst
+api-reference/system/misc_system_api.rst
+api-reference/system/chip_revision.rst
+api-reference/system/random.rst
+api-reference/system/soc_caps.rst
+api-reference/system/app_trace.rst
+api-reference/system/esp_function_with_shared_stack.rst
+api-reference/system/log.rst
+api-reference/system/mm_sync.rst
+api-reference/system/app_image_format.rst
+api-reference/system/ulp_macros.rst
+api-reference/system/ulp.rst
+api-reference/system/bootloader_image_format.rst
+api-reference/system/mm.rst
+api-reference/system/esp_https_ota.rst
+api-reference/system/perfmon.rst
+api-reference/system/wdts.rst
+api-reference/system/sleep_modes.rst
+api-reference/system/system_time.rst
+api-reference/system/himem.rst
+api-reference/system/async_memcpy.rst
+api-reference/system/console.rst
+api-reference/system/internal-unstable.rst
+api-reference/system/ulp_instruction_set.rst
+api-reference/system/ipc.rst
+api-reference/system/ota.rst
+api-reference/system/esp_event.rst
+api-reference/system/pthread.rst
+api-reference/system/esp_timer.rst
+api-reference/system/heap_debug.rst
+api-reference/system/efuse.rst
+api-reference/system/inc/power_management_esp32h21.rst
+api-reference/system/inc/show-efuse-table_ESP32-H21.rst
+api-reference/system/inc/espefuse_summary_ESP32-H21.rst
+api-reference/system/inc/espefuse_summary_ESP32-H21_dump.rst
+api-reference/system/inc/revisions_ESP32-H21.rst
+api-reference/system/esp_err.rst
+api-reference/system/freertos.rst
+api-reference/system/freertos_additions.rst
+api-reference/system/ulp-lp-core.rst
+api-reference/system/power_management.rst
+api-reference/system/ulp-risc-v.rst
+api-reference/system/mem_alloc.rst
+api-reference/system/intr_alloc.rst
+api-reference/api-conventions.rst
+security/index.rst
+security/flash-encryption.rst
+security/secure-boot-v1.rst
+security/security.rst
+security/security-features-enablement-workflows.rst
+security/secure-boot-v2.rst
+security/vulnerabilities.rst
+security/tee/index.rst
+security/tee/tee-advanced.rst
+security/tee/tee-sec-storage.rst
+security/tee/tee-ota.rst
+security/tee/tee.rst
+security/tee/tee-attestation.rst

docs/doxygen/Doxyfile_esp32h21

@@ -0,0 +1 @@
+INPUT += \

docs/en/api-guides/jtag-debugging/esp32h21.inc

@@ -0,0 +1,171 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+.. run-openocd
+
+::
+
+    openocd -f board/esp32h2-builtin.cfg
+
+.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection
+
+---
+
+.. run-openocd-output
+
+::
+
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h2-builtin.cfg
+    Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    Info : only one transport option; autoselecting 'jtag'
+    Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
+    Info : esp_usb_jtag: capabilities descriptor set to 0x2000
+    Warn : Transport "jtag" was already selected
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F)
+    Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
+    Info : clock speed 24000 kHz
+    Info : JTAG tap: esp32h2.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 1 harts
+    Info :  hart 0: XLEN=32, misa=0x40903105
+    Info : starting gdb server for esp32h2 on 3333
+    Info : Listening on port 3333 for gdb connections
+
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h2-builtin.cfg``
+
+---
+
+.. run-openocd-upload
+
+::
+
+    openocd -f board/esp32h2-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
+
+---
+
+.. run-openocd-src-linux
+
+.. code-block:: bash
+
+    src/openocd -f board/esp32h2-builtin.cfg
+
+---
+
+.. run-openocd-src-win
+
+.. code-block:: batch
+
+    src\openocd -f board/esp32h2-builtin.cfg
+
+---
+
+.. idf-py-openocd-default-cfg
+
+.. |idf-py-def-cfg| replace:: ``-f board/esp32h2-builtin.cfg``
+
+---
+
+.. run-openocd-appimage-offset
+
+::
+
+    openocd -f board/esp32h2-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
+
+---
+
+.. openocd-cfg-files
+
+.. list-table:: OpenOCD configuration files for ESP32-H2
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Name
+      - Description
+    * - ``board/esp32h2-builtin.cfg``
+      - Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration.
+    * - ``board/esp32h2-ftdi.cfg``
+      - Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
+    * - ``target/esp32h2.cfg``
+      - ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+    * - ``interface/esp_usb_jtag.cfg``
+      - JTAG adapter configuration file for ESP32-H2.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-Prog boards.
+
+---
+
+.. openocd-target-specific-config-vars
+
+---
+
+---
+
+.. jtag-pins
+
+.. list-table:: ESP32-H2 pins and JTAG signals
+    :widths: 25 75
+    :header-rows: 1
+
+    * - ESP32-H2 Pin
+      - JTAG Signal
+    * - MTDO / GPIO3
+      - TDO
+    * - MTDI / GPIO5
+      - TDI
+    * - MTCK / GPIO4
+      - TCK
+    * - MTMS / GPIO2
+      - TMS
+
+.. |jtag-sel-gpio| replace:: GPIO25
+.. |jtag-gpio-list| replace:: GPIO2-GPIO5
+
+---
+
+.. run-openocd-d3
+
+::
+
+    openocd -l openocd_log.txt -d3 -f board/esp32h2-builtin.cfg
+
+---
+
+.. run-openocd-d3-tee
+
+::
+
+    openocd -d3 -f board/esp32h2-builtin.cfg 2>&1 | tee openocd.log
+
+---
+
+.. run-gdb-remotelog
+
+::
+
+    riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+
+---
+
+.. devkit-defs
+
+.. |devkit-name| replace:: ESP32-H2
+.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>`
+
+---
+
+.. devkit-hw-config
+
+* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging.
+
+---

docs/en/api-reference/peripherals/gpio/esp32h21.inc

@@ -0,0 +1,18 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+.. gpio-summary
+
+  To be updated
+
+.. note::
+
+  To be updated
+
+---

docs/en/api-reference/system/inc/espefuse_summary_ESP32-H21.rst

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+   To be updated

docs/en/api-reference/system/inc/espefuse_summary_ESP32-H21_dump.rst

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+    To be updated

docs/en/api-reference/system/inc/power_management_esp32h21.rst

@@ -0,0 +1,7 @@
+
+.. flat-table::
+    :widths: 1 3 3
+
+    * - Max CPU Frequency Set
+      - Lock Acquisition
+      - CPU and APB Frequencies

docs/en/api-reference/system/inc/revisions_ESP32-H21.rst

@@ -0,0 +1,8 @@
+
+.. list-table::
+    :header-rows: 1
+    :width: 2 5
+    :align: center
+
+    * - ECO
+      - Revision (Major.Minor)

docs/en/api-reference/system/inc/show-efuse-table_ESP32-H21.rst

@@ -0,0 +1,4 @@
+
+.. code-block:: none
+
+    To be updated

docs/en/get-started/esp32h21_output_log.inc

@@ -0,0 +1,5 @@
+.. output_log
+
+.. code-block:: none
+
+    To be updated

docs/en/security/esp32h21_log.inc

@@ -0,0 +1,17 @@
+
+.. first_boot_enc
+
+.. code-block:: none
+
+    To be updated
+
+------
+
+.. already_en_enc
+
+.. code-block:: none
+
+    To be updated
+
+
+------

docs/zh_CN/api-guides/jtag-debugging/esp32h21.inc

@@ -0,0 +1,171 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+.. run-openocd
+
+::
+
+    openocd -f board/esp32h21-builtin.cfg
+
+.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection
+
+---
+
+.. run-openocd-output
+
+::
+
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h21-builtin.cfg
+    Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    Info : only one transport option; autoselecting 'jtag'
+    Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
+    Info : esp_usb_jtag: capabilities descriptor set to 0x2000
+    Warn : Transport "jtag" was already selected
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F)
+    Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
+    Info : clock speed 24000 kHz
+    Info : JTAG tap: esp32h21.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 1 harts
+    Info :  hart 0: XLEN=32, misa=0x40903105
+    Info : starting gdb server for esp32h21 on 3333
+    Info : Listening on port 3333 for gdb connections
+
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h21-builtin.cfg``
+
+---
+
+.. run-openocd-upload
+
+::
+
+    openocd -f board/esp32h21-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
+
+---
+
+.. run-openocd-src-linux
+
+.. code-block:: bash
+
+    src/openocd -f board/esp32h21-builtin.cfg
+
+---
+
+.. run-openocd-src-win
+
+.. code-block:: batch
+
+    src\openocd -f board/esp32h21-builtin.cfg
+
+---
+
+.. idf-py-openocd-default-cfg
+
+.. |idf-py-def-cfg| replace:: ``-f board/esp32h21-builtin.cfg``
+
+---
+
+.. run-openocd-appimage-offset
+
+::
+
+    openocd -f board/esp32h21-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
+
+---
+
+.. openocd-cfg-files
+
+.. list-table:: OpenOCD configuration files for ESP32-H2
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Name
+      - Description
+    * - ``board/esp32h21-builtin.cfg``
+      - Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration.
+    * - ``board/esp32h21-ftdi.cfg``
+      - Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
+    * - ``target/esp32h21.cfg``
+      - ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+    * - ``interface/esp_usb_jtag.cfg``
+      - JTAG adapter configuration file for ESP32-H2.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-Prog boards.
+
+---
+
+.. openocd-target-specific-config-vars
+
+---
+
+---
+
+.. jtag-pins
+
+.. list-table:: ESP32-H2 pins and JTAG signals
+    :widths: 25 75
+    :header-rows: 1
+
+    * - ESP32-H2 Pin
+      - JTAG Signal
+    * - MTDO / GPIO3
+      - TDO
+    * - MTDI / GPIO5
+      - TDI
+    * - MTCK / GPIO4
+      - TCK
+    * - MTMS / GPIO2
+      - TMS
+
+.. |jtag-sel-gpio| replace:: GPIO25
+.. |jtag-gpio-list| replace:: GPIO2-GPIO5
+
+---
+
+.. run-openocd-d3
+
+::
+
+    openocd -l openocd_log.txt -d3 -f board/esp32h21-builtin.cfg
+
+---
+
+.. run-openocd-d3-tee
+
+::
+
+    openocd -d3 -f board/esp32h21-builtin.cfg 2>&1 | tee openocd.log
+
+---
+
+.. run-gdb-remotelog
+
+::
+
+    riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+
+---
+
+.. devkit-defs
+
+.. |devkit-name| replace:: ESP32-H2
+.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>`
+
+---
+
+.. devkit-hw-config
+
+* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging.
+
+---

docs/zh_CN/api-reference/peripherals/gpio/esp32h21.inc

@@ -0,0 +1,18 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+.. gpio-summary
+
+  To be updated
+
+.. note::
+
+  To be updated
+
+---

docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-H21.rst

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+   To be updated

docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-H21_dump.rst

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+    To be updated

docs/zh_CN/api-reference/system/inc/power_management_esp32h21.rst

@@ -0,0 +1,7 @@
+
+.. flat-table::
+    :widths: 1 3 3
+
+    * - Max CPU Frequency Set
+      - Lock Acquisition
+      - CPU and APB Frequencies

docs/zh_CN/api-reference/system/inc/revisions_ESP32-H21.rst

@@ -0,0 +1,8 @@
+
+.. list-table::
+    :header-rows: 1
+    :width: 2 5
+    :align: center
+
+    * - ECO
+      - Revision (Major.Minor)

docs/zh_CN/api-reference/system/inc/show-efuse-table_ESP32-H21.rst

@@ -0,0 +1,4 @@
+
+.. code-block:: none
+
+    To be updated

docs/zh_CN/get-started/esp32h21_output_log.inc

@@ -0,0 +1,5 @@
+.. output_log
+
+.. code-block:: none
+
+    To be updated

docs/zh_CN/security/esp32h21_log.inc

@@ -0,0 +1,17 @@
+
+.. first_boot_enc
+
+.. code-block:: none
+
+    To be updated
+
+------
+
+.. already_en_enc
+
+.. code-block:: none
+
+    To be updated
+
+
+------