docs: add support for building H2 docs

.gitlab/ci/docs.yml

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

components/esp_hw_support/port/esp32h2/Kconfig.mac

@@ -1 +1,5 @@
 # ESP32H2-TODO: MAC support
+
+choice ESP32H2_UNIVERSAL_MAC_ADDRESSES
+    bool "Number of universally administered (by IEEE) MAC address"
+endchoice

docs/conf_common.py

@@ -32,8 +32,9 @@ BT_DOCS = ['api-guides/blufi.rst',
            'api-reference/bluetooth/esp_gattc.rst',
            'api-reference/bluetooth/esp_blufi.rst',
            'api-reference/bluetooth/index.rst',
-           'api-reference/bluetooth/nimble/index.rst',
-           'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
+           'api-reference/bluetooth/nimble/index.rst']
+
+BLE_DOCS = ['migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
 
 BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst',
@@ -154,6 +155,7 @@ ESP32C6_DOCS = ['api-guides/RF_calibration.rst']
 
 # format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
 conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
+                            'SOC_BLE_SUPPORTED':BLE_DOCS,
                             'SOC_BLE_MESH_SUPPORTED':BLE_MESH_DOCS,
                             'SOC_WIFI_SUPPORTED':WIFI_DOCS,
                             'SOC_BT_CLASSIC_SUPPORTED':CLASSIC_BT_DOCS,

docs/docs_not_updated/esp32h2.txt

@@ -0,0 +1,275 @@
+languages
+contribute/esp-idf-tests-with-pytest
+contribute/contributor-agreement
+contribute/documenting-code
+contribute/creating-examples
+contribute/style-guide
+contribute/copyright-guide
+contribute/install-pre-commit-hook
+contribute/index
+api-guides/core_dump_internals
+api-guides/event-handling
+api-guides/performance/speed
+api-guides/performance/size
+api-guides/performance/ram-usage
+api-guides/performance/index
+api-guides/jtag-debugging/debugging-examples
+api-guides/jtag-debugging/configure-ft2232h-jtag
+api-guides/jtag-debugging/tips-and-quirks
+api-guides/jtag-debugging/using-debugger
+api-guides/jtag-debugging/building-openocd-macos
+api-guides/jtag-debugging/building-openocd-linux
+api-guides/jtag-debugging/esp32h2.inc
+api-guides/jtag-debugging/configure-other-jtag
+api-guides/jtag-debugging/building-openocd-windows
+api-guides/jtag-debugging/index
+api-guides/jtag-debugging/esp32.inc
+api-guides/jtag-debugging/configure-builtin-jtag
+api-guides/partition-tables
+api-guides/app_trace
+api-guides/thread-local-storage
+api-guides/error-handling
+api-guides/tools/idf-tools
+api-guides/tools/idf-clang-tidy
+api-guides/tools/idf-component-manager
+api-guides/tools/idf-py
+api-guides/tools/idf-windows-installer
+api-guides/tools/idf-monitor
+api-guides/tools/idf-tools-notes.inc
+api-guides/tools/idf-docker-image
+api-guides/tools/index
+api-guides/startup
+api-guides/hlinterrupts
+api-guides/RF_calibration
+api-guides/unit-tests
+api-guides/deep-sleep-stub
+api-guides/blufi
+api-guides/lwip
+api-guides/coexist
+api-guides/flash_psram_config
+api-guides/usb-serial-jtag-console
+api-guides/linker-script-generation
+api-guides/wifi
+api-guides/usb-otg-console
+api-guides/wireshark-user-guide
+api-guides/bootloader
+api-guides/esp-wifi-mesh
+api-guides/cplusplus
+api-guides/SYSVIEW_FreeRTOS.txt
+api-guides/build-system
+api-guides/freertos-smp
+api-guides/core_dump
+api-guides/inc/linux-host-requirements
+api-guides/dfu
+api-guides/esp-ble-mesh/ble-mesh-index
+api-guides/esp-ble-mesh/ble-mesh-feature-list
+api-guides/esp-ble-mesh/ble-mesh-terminology
+api-guides/esp-ble-mesh/ble-mesh-architecture
+api-guides/esp-ble-mesh/ble-mesh-faq
+api-guides/external-ram
+api-guides/reproducible-builds
+api-guides/hardware-abstraction
+api-guides/wifi-security
+api-guides/host-apps
+api-guides/index
+api-guides/openthread
+api-guides/fatal-errors
+api-guides/memory-types
+api-guides/general-notes
+third-party-tools/platformio
+COPYRIGHT
+libraries-and-frameworks/libs-frameworks
+libraries-and-frameworks/index
+libraries-and-frameworks/cloud-frameworks
+versions
+api-reference/api-conventions
+api-reference/template
+api-reference/provisioning/protocomm
+api-reference/provisioning/provisioning
+api-reference/provisioning/index
+api-reference/provisioning/wifi_provisioning
+api-reference/storage/vfs
+api-reference/storage/spiffs
+api-reference/storage/wear-levelling
+api-reference/storage/fatfs
+api-reference/storage/nvs_partition_gen
+api-reference/storage/nvs_flash
+api-reference/storage/partition
+api-reference/storage/sdmmc
+api-reference/storage/mass_mfg
+api-reference/storage/index
+api-reference/storage/nvs_partition_parse
+api-reference/peripherals/sdspi_share
+api-reference/peripherals/gpio/esp32h2.inc
+api-reference/peripherals/adc_continuous
+api-reference/peripherals/adc_oneshot
+api-reference/peripherals/usb_host
+api-reference/peripherals/twai
+api-reference/peripherals/hmac
+api-reference/peripherals/usb_device
+api-reference/peripherals/gpio
+api-reference/peripherals/sdspi_host
+api-reference/peripherals/dac
+api-reference/peripherals/spi_slave
+api-reference/peripherals/etm
+api-reference/peripherals/i2s
+api-reference/peripherals/gptimer
+api-reference/peripherals/pcnt
+api-reference/peripherals/touch_element
+api-reference/peripherals/lcd
+api-reference/peripherals/mcpwm
+api-reference/peripherals/secure_element
+api-reference/peripherals/ledc
+api-reference/peripherals/temp_sensor
+api-reference/peripherals/spi_features
+api-reference/peripherals/sdio_slave
+api-reference/peripherals/clk_tree
+api-reference/peripherals/spi_flash/xip_from_psram.inc
+api-reference/peripherals/spi_flash/spi_flash_concurrency
+api-reference/peripherals/spi_flash/spi_flash_override_driver
+api-reference/peripherals/spi_flash/spi_flash_optional_feature
+api-reference/peripherals/spi_flash/index
+api-reference/peripherals/spi_flash/auto_suspend.inc
+api-reference/peripherals/sdm
+api-reference/peripherals/touch_pad
+api-reference/peripherals/adc_calibration
+api-reference/peripherals/spi_slave_hd
+api-reference/peripherals/ds
+api-reference/peripherals/i2c
+api-reference/peripherals/dedic_gpio
+api-reference/peripherals/sd_pullup_requirements
+api-reference/peripherals/spi_master
+api-reference/peripherals/index
+api-reference/peripherals/sdmmc_host
+api-reference/peripherals/uart
+api-reference/peripherals/rmt
+api-reference/kconfig
+api-reference/network/esp_openthread
+api-reference/network/esp_eth
+api-reference/network/esp_netif_driver
+api-reference/network/esp_dpp
+api-reference/network/esp_now
+api-reference/network/esp-wifi-mesh
+api-reference/network/esp_smartconfig
+api-reference/network/esp_wifi
+api-reference/network/index
+api-reference/network/esp_netif
+api-reference/system/sleep_modes
+api-reference/system/ota
+api-reference/system/app_trace
+api-reference/system/ulp_macros
+api-reference/system/perfmon
+api-reference/system/ulp
+api-reference/system/esp_function_with_shared_stack
+api-reference/system/efuse
+api-reference/system/chip_revision
+api-reference/system/ulp_instruction_set
+api-reference/system/async_memcpy
+api-reference/system/random
+api-reference/system/esp_timer
+api-reference/system/esp_event
+api-reference/system/freertos
+api-reference/system/system_time
+api-reference/system/log
+api-reference/system/soc_caps
+api-reference/system/internal-unstable
+api-reference/system/app_image_format
+api-reference/system/freertos_additions
+api-reference/system/himem
+api-reference/system/power_management
+api-reference/system/mem_alloc
+api-reference/system/wdts
+api-reference/system/misc_system_api
+api-reference/system/inc/power_management_esp32
+api-reference/system/inc/espefuse_summary_ESP32-H2
+api-reference/system/inc/revisions_ESP32-H2
+api-reference/system/inc/show-efuse-table_ESP32-H2
+api-reference/system/inc/power_management_esp32s2_and_later
+api-reference/system/heap_debug
+api-reference/system/ipc
+api-reference/system/esp_https_ota
+api-reference/system/ulp-risc-v
+api-reference/system/esp_err
+api-reference/system/console
+api-reference/system/intr_alloc
+api-reference/system/index
+api-reference/system/pthread
+api-reference/bluetooth/esp_spp
+api-reference/bluetooth/esp_l2cap_bt
+api-reference/bluetooth/esp_hidd
+api-reference/bluetooth/esp_avrc
+api-reference/bluetooth/controller_vhci
+api-reference/bluetooth/esp_bt_defs
+api-reference/bluetooth/esp_hf_ag
+api-reference/bluetooth/esp_bt_main
+api-reference/bluetooth/esp_bt_device
+api-reference/bluetooth/esp_gatts
+api-reference/bluetooth/esp_gattc
+api-reference/bluetooth/esp_sdp
+api-reference/bluetooth/bt_common
+api-reference/bluetooth/nimble
+api-reference/bluetooth/nimble/index
+api-reference/bluetooth/esp_hf_client
+api-reference/bluetooth/esp_a2dp
+api-reference/bluetooth/esp_blufi
+api-reference/bluetooth/bt_le
+api-reference/bluetooth/esp_hf_defs
+api-reference/bluetooth/esp_gap_bt
+api-reference/bluetooth/esp_gatt_defs
+api-reference/bluetooth/esp-ble-mesh
+api-reference/bluetooth/index
+api-reference/bluetooth/esp_gap_ble
+api-reference/bluetooth/classic_bt
+api-reference/error-codes
+api-reference/index
+api-reference/protocols/icmp_echo
+api-reference/protocols/esp_serial_slave_link
+api-reference/protocols/mqtt
+api-reference/protocols/mbedtls
+api-reference/protocols/esp_http_server
+api-reference/protocols/esp_sdio_slave_protocol
+api-reference/protocols/esp_local_ctrl
+api-reference/protocols/esp_crt_bundle
+api-reference/protocols/esp_http_client
+api-reference/protocols/esp_https_server
+api-reference/protocols/esp_spi_slave_protocol
+api-reference/protocols/modbus
+api-reference/protocols/esp_tls
+api-reference/protocols/mdns
+api-reference/protocols/index
+api-reference/protocols/asio
+security/flash-encryption
+security/esp32h2_log.inc
+security/security
+security/secure-boot-v2
+security/secure-boot-v1
+about
+resources
+migration-guides/release-5.x/5.1/index
+migration-guides/release-5.x/5.1/peripherals
+migration-guides/release-5.x/5.0/bluetooth-classic
+migration-guides/release-5.x/5.0/gcc
+migration-guides/release-5.x/5.0/bluetooth-low-energy
+migration-guides/release-5.x/5.0/removed-components
+migration-guides/release-5.x/5.0/protocols
+migration-guides/release-5.x/5.0/networking
+migration-guides/release-5.x/5.0/provisioning
+migration-guides/release-5.x/5.0/build-system
+migration-guides/release-5.x/5.0/storage
+migration-guides/release-5.x/5.0/index
+migration-guides/release-5.x/5.0/system
+migration-guides/release-5.x/5.0/tools
+migration-guides/release-5.x/5.0/peripherals
+migration-guides/index
+get-started/establish-serial-connection
+get-started/linux-macos-setup
+get-started/linux-macos-start-project
+get-started/windows-setup
+get-started/start-project
+get-started/flashing-troubleshooting
+get-started/windows-start-project
+get-started/index
+get-started/windows-setup-update
+404
+index
+hw-reference/index

docs/doxygen/Doxyfile_esp32h2

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

docs/en/api-guides/index.rst

@@ -34,7 +34,7 @@ API Guides
    partition-tables
    performance/index
    reproducible-builds
-   RF_calibration
+   :not esp32h2: RF_calibration
    ../security/security
    :esp32: ../security/secure-boot-v1
    ../security/secure-boot-v2

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

@@ -0,0 +1,144 @@
+.. 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
+
+::
+
+    TO BE UPDATED
+
+.. |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
+    * - TO BE UPDATED
+      - TO BE UPDATED
+
+---
+
+.. 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
+      - TDO
+    * - MTDI
+      - TDI
+    * - MTCK
+      - TCK
+    * - MTMS
+      - TMS
+
+.. |jtag-sel-gpio| replace:: TO BE UPDATED
+.. |jtag-gpio-list| replace:: TO BE UPDATED
+
+---
+
+.. 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-guides/partition-tables.rst

@@ -88,7 +88,7 @@ The ESP-IDF bootloader ignores any partition types other than ``app`` (0x00) and
 
 SubType
 ~~~~~~~
-{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`"}
+{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32h2="NOT UPDATED YET"}
 
 The 8-bit SubType field is specific to a given partition type. ESP-IDF currently only specifies the meaning of the subtype field for ``app`` and ``data`` partition types.
 

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

@@ -0,0 +1,30 @@
+.. 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
+
+The {IDF_TARGET_NAME} chip features X physical GPIO pins (GPIOX ~ GPIOX). Each pin can be used as a general-purpose I/O, or to be connected to an internal peripheral signal. Through GPIO matrix and IO MUX, peripheral input signals can be from any IO pins, and peripheral output signals can be routed to any IO pins. Together these modules provide highly configurable I/O. For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
+
+The table below provides more information on pin usage, and please note the comments in the table for GPIOs with restrictions.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 8 12 12 20
+
+    * - GPIO
+      - Analog Function
+      - LP GPIO
+      - Comments
+
+    * - GPIO0
+      -
+      -
+      -
+
+---

docs/en/api-reference/peripherals/gptimer.rst

@@ -25,7 +25,7 @@ The following sections of this document cover the typical steps to install and o
     - :ref:`gptimer-register-event-callbacks` - covers how to hook user specific code to the alarm event callback function.
     - :ref:`enable-and-disable-timer` - covers how to enable and disable the timer.
     - :ref:`start-and-stop-timer` - shows some typical use cases that start the timer with different alarm behavior.
-    :SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel.
+    :SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel.
     - :ref:`gptimer-power-management` - describes how different source clock selections can affect power consumption.
     - :ref:`gptimer-iram-safe` - describes tips on how to make the timer interrupt and IO control functions work better along with a disabled cache.
     - :ref:`gptimer-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
@@ -260,7 +260,7 @@ Alarm value can be updated dynamically inside the ISR handler callback, by chang
     ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
 
 
-.. only:: SOC_TIMER_SUPPORT_ETM
+.. only:: SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-etm-event-and-task:
 
@@ -273,7 +273,7 @@ Alarm value can be updated dynamically inside the ISR handler callback, by chang
 
     .. _gptimer-power-management:
 
-.. only:: not SOC_TIMER_SUPPORT_ETM
+.. only:: not SOC_ETM_SUPPORTED or not SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-power-management:
 

docs/en/api-reference/system/async_memcpy.rst

@@ -74,7 +74,7 @@ Uninstall driver (optional)
 
 :cpp:func:`esp_async_memcpy_uninstall` is used to uninstall asynchronous memcpy driver. It's not necessary to uninstall the driver after each memcpy operation. If you know your application won't use this driver anymore, then this API can recycle the memory for you.
 
-.. only:: SOC_GDMA_SUPPORT_ETM
+.. only:: SOC_ETM_SUPPORTED and SOC_GDMA_SUPPORT_ETM
 
     ETM Event
     ---------

docs/en/api-reference/system/esp_timer.rst

@@ -61,7 +61,7 @@ Callback functions
 Timer callbacks which are processed by ``ESP_TIMER_ISR`` method should not call the context switch call - ``portYIELD_FROM_ISR()``, instead of this you should use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function.
 The context switch will be done after all ISR dispatch timers have been processed, if required by the system.
 
-.. only:: SOC_SYSTIMER_SUPPORT_ETM
+.. only:: SOC_ETM_SUPPORTED and SOC_SYSTIMER_SUPPORT_ETM
 
     ETM Event
     ---------

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

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+    TO BE UPDATED

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

@@ -0,0 +1,6 @@
+
++------------------------+
+| Revision (Major.Minor) |
++------------------------+
+| v0.0                   |
++------------------------+

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

@@ -0,0 +1,4 @@
+
+.. code-block:: none
+
+    TO BE UPDATED

docs/en/hw-reference/index.rst

@@ -6,7 +6,7 @@ Hardware Reference
 .. toctree::
     :maxdepth: 1
 
-    Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
+    :not esp32h2: Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
     :esp32:   Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
     :esp32s2: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf>
     :esp32s3: Chip Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf>

docs/en/security/esp32h2_log.inc

@@ -0,0 +1,13 @@
+
+.. first_boot_enc
+
+TO BE UPDATED
+
+------
+
+.. already_en_enc
+
+
+TO BE UPDATED
+
+------

docs/zh_CN/api-guides/index.rst

@@ -30,7 +30,7 @@ API 指南
    openthread
    partition-tables
    performance/index
-   RF_calibration
+   :not esp32h2: RF_calibration
    ../security/security
    :esp32: ../security/secure-boot-v1
    ../security/secure-boot-v2

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

@@ -0,0 +1,144 @@
+.. 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
+
+::
+
+    TO BE UPDATED
+
+.. |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
+    * - TO BE UPDATED
+      - TO BE UPDATED
+
+---
+
+.. 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
+      - TDO
+    * - MTDI
+      - TDI
+    * - MTCK
+      - TCK
+    * - MTMS
+      - TMS
+
+.. |jtag-sel-gpio| replace:: TO BE UPDATED
+.. |jtag-gpio-list| replace:: TO BE UPDATED
+
+---
+
+.. 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/zh_CN/api-guides/partition-tables.rst

@@ -88,7 +88,7 @@ Type 字段可以指定为 app (0x00) 或者 data (0x01)，也可以直接使用
 
 SubType 字段
 ~~~~~~~~~~~~
-{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`"}
+{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32h2 = "NOT UPDATED YET"}
 
 SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种分区类型的子类型含义。
 

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

@@ -0,0 +1,30 @@
+.. 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
+
+The {IDF_TARGET_NAME} chip features X physical GPIO pins (GPIOX ~ GPIOX). Each pin can be used as a general-purpose I/O, or to be connected to an internal peripheral signal. Through GPIO matrix and IO MUX, peripheral input signals can be from any IO pins, and peripheral output signals can be routed to any IO pins. Together these modules provide highly configurable I/O. For more details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
+
+The table below provides more information on pin usage, and please note the comments in the table for GPIOs with restrictions.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 8 12 12 20
+
+    * - GPIO
+      - Analog Function
+      - LP GPIO
+      - Comments
+
+    * - GPIO0
+      -
+      -
+      -
+
+---

docs/zh_CN/api-reference/peripherals/gptimer.rst

@@ -25,7 +25,7 @@
     - :ref:`gptimer-register-event-callbacks` - 如何将用户的特定代码挂载到警报事件回调函数。
     - :ref:`enable-and-disable-timer` - 如何使能和禁用定时器。
     - :ref:`start-and-stop-timer` - 通过不同报警行为启动定时器的典型使用场景。
-    :SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - 定时器提供了哪些事件和任务可以连接到 ETM 通道上。
+    :SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - 定时器提供了哪些事件和任务可以连接到 ETM 通道上。
     - :ref:`gptimer-power-management` - 选择不同的时钟源将会如何影响功耗。
     - :ref:`gptimer-iram-safe` - 在 cache 禁用的情况下，如何更好地让定时器处理中断事务以及实现 IO 控制功能。
     - :ref:`gptimer-thread-safety` - 驱动程序保证哪些 API 线程安全。
@@ -260,7 +260,7 @@
     ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
 
 
-.. only:: SOC_TIMER_SUPPORT_ETM
+.. only:: SOC_ETM_SUPPORTED and SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-etm-event-and-task:
 
@@ -273,7 +273,7 @@
 
     .. _gptimer-power-management:
 
-.. only:: not SOC_TIMER_SUPPORT_ETM
+.. only:: not SOC_ETM_SUPPORTED or not SOC_TIMER_SUPPORT_ETM
 
     .. _gptimer-power-management:
 

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

@@ -0,0 +1,3 @@
+.. code-block:: none
+
+    TO BE UPDATED

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

@@ -0,0 +1,6 @@
+
++------------------------+
+| Revision (Major.Minor) |
++------------------------+
+| v0.0                   |
++------------------------+

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

@@ -0,0 +1,4 @@
+
+.. code-block:: none
+
+    TO BE UPDATED

docs/zh_CN/hw-reference/index.rst

@@ -6,7 +6,7 @@ H/W 硬件参考
 .. toctree::
     :maxdepth: 1
 
-    技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
+    :not esp32h2: 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
     :esp32:   技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>
     :esp32s2: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s2_datasheet_cn.pdf>
     :esp32s3: 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32-s3_datasheet_cn.pdf>

docs/zh_CN/security/esp32h2_log.inc

@@ -0,0 +1,13 @@
+
+.. first_boot_enc
+
+TO BE UPDATED
+
+------
+
+.. already_en_enc
+
+
+TO BE UPDATED
+
+------