From fc000cd7b7c0ff2a71f6629a8e565722dd7a91dc Mon Sep 17 00:00:00 2001 From: laokaiyao Date: Thu, 18 Apr 2024 15:13:55 +0800 Subject: [PATCH] ci(doc): enable doc build for esp32c5 --- .gitlab/ci/docs.yml | 2 +- .../soc/esp32c5/include/soc/gpio_sig_map.h | 17 +++++++++++++++++ components/ulp/CMakeLists.txt | 2 +- docs/conf_common.py | 11 +++++++++++ docs/en/api-guides/performance/ram-usage.rst | 6 +++--- docs/en/api-reference/peripherals/index.rst | 10 +++++----- .../peripherals/spi_flash/index.rst | 5 +++++ docs/en/api-reference/protocols/mbedtls.rst | 2 +- docs/en/api-reference/storage/sdmmc.rst | 2 +- docs/zh_CN/api-guides/performance/ram-usage.rst | 6 +++--- docs/zh_CN/api-reference/peripherals/index.rst | 10 +++++----- .../peripherals/spi_flash/index.rst | 5 +++++ docs/zh_CN/api-reference/protocols/mbedtls.rst | 2 +- docs/zh_CN/api-reference/storage/sdmmc.rst | 2 +- 14 files changed, 60 insertions(+), 22 deletions(-) create mode 100644 components/soc/esp32c5/include/soc/gpio_sig_map.h diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index 2368f0f7ee..5699a10d12 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -102,7 +102,7 @@ check_docs_lang_sync: parallel: matrix: - DOCLANG: ["en", "zh_CN"] - DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32h2", "esp32p4"] + DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32c5","esp32h2", "esp32p4"] check_docs_gh_links: image: $ESP_IDF_DOC_ENV_IMAGE diff --git a/components/soc/esp32c5/include/soc/gpio_sig_map.h b/components/soc/esp32c5/include/soc/gpio_sig_map.h new file mode 100644 index 0000000000..b7a085102d --- /dev/null +++ b/components/soc/esp32c5/include/soc/gpio_sig_map.h @@ -0,0 +1,17 @@ +/* + * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#pragma once + +#include "sdkconfig.h" + +// TODO: IDF-9197 This file is created to glob the gpio_sig_map.h files correctly in esp-docs + +#if CONFIG_IDF_TARGET_ESP32C5_BETA3_VERSION +#include "../../beta3/include/soc/gpio_sig_map.h" +#elif CONFIG_IDF_TARGET_ESP32C5_MP_VERSION +#include "../../mp/include/soc/gpio_sig_map.h" +#endif diff --git a/components/ulp/CMakeLists.txt b/components/ulp/CMakeLists.txt index ba78779040..ec5571d9c6 100644 --- a/components/ulp/CMakeLists.txt +++ b/components/ulp/CMakeLists.txt @@ -7,7 +7,7 @@ endif() set(srcs "") set(includes "") -if(CONFIG_ULP_COPROC_ENABLED OR (CONFIG_IDF_DOC_BUILD AND CONFIG_SOC_ULP_SUPPORTED)) +if(CONFIG_ULP_COPROC_ENABLED OR CONFIG_IDF_DOC_BUILD) list(APPEND includes ulp_common/include) endif() diff --git a/docs/conf_common.py b/docs/conf_common.py index 3186e4cfa6..812210c89c 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -150,6 +150,15 @@ 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'] + +SPI_DOCS = ['api-reference/peripherals/spi_master.rst', + 'api-reference/peripherals/spi_slave.rst', + 'api-reference/peripherals/sdspi_host.rst', + 'api-reference/peripherals/sdspi_share.rst', + 'api-reference/peripherals/lcd/spi_lcd.rst'] + I2S_DOCS = ['api-reference/peripherals/i2s.rst'] ISP_DOCS = ['api-reference/peripherals/isp.rst'] @@ -254,6 +263,8 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS, 'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS, 'SOC_TEMP_SENSOR_SUPPORTED':TEMP_SENSOR_DOCS, 'SOC_TWAI_SUPPORTED':TWAI_DOCS, + 'SOC_I2C_SUPPORTED':I2C_DOCS, + 'SOC_GPSPI_SUPPORTED':SPI_DOCS, 'SOC_I2S_SUPPORTED':I2S_DOCS, 'SOC_ISP_SUPPORTED':ISP_DOCS, 'SOC_RTC_MEM_SUPPORTED': RTC_MEM_DOCS, diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst index 1dd23214c4..6ef063cde7 100644 --- a/docs/en/api-guides/performance/ram-usage.rst +++ b/docs/en/api-guides/performance/ram-usage.rst @@ -155,11 +155,11 @@ The following options will reduce IRAM usage of some ESP-IDF features: :esp32: - Disabling :ref:`CONFIG_SPI_FLASH_ROM_DRIVER_PATCH` frees some IRAM but is only available in some flash configurations, see the configuration item help text. :esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :ref:`CONFIG_ESP32_REV_MIN` to ``3`` disables PSRAM bug workarounds, saving 10 KB or more of IRAM. - Disabling :ref:`CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR` prevents posting ``esp_event`` events from :ref:`iram-safe-interrupt-handlers` but saves some IRAM. - - Disabling :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` prevents spi_master interrupts from being serviced while writing to flash, and may otherwise reduce spi_master performance, but saves some IRAM. - - Disabling :ref:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` prevents spi_slave interrupts from being serviced while writing to flash, which saves some IRAM. + :SOC_GPSPI_SUPPORTED: - Disabling :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` prevents spi_master interrupts from being serviced while writing to flash, and may otherwise reduce spi_master performance, but saves some IRAM. + :SOC_GPSPI_SUPPORTED: - Disabling :ref:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` prevents spi_slave interrupts from being serviced while writing to flash, which saves some IRAM. - Setting :ref:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` to disable assertion for HAL component saves some IRAM, especially for HAL code who calls ``HAL_ASSERT`` a lot and resides in IRAM. - Refer to the sdkconfig menu ``Auto-detect Flash chips``, and you can disable flash drivers which you do not need to save some IRAM. - - Enable :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`. Provided that :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` is not enabled and the heap functions are not incorrectly used from ISRs, this option is safe to enable in all configurations. + :SOC_GPSPI_SUPPORTED: - Enable :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`. Provided that :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` is not enabled and the heap functions are not incorrectly used from ISRs, this option is safe to enable in all configurations. :esp32c2: - Enable :ref:`CONFIG_BT_RELEASE_IRAM`. Release BT text section and merge BT data, bss & text into a large free heap region when ``esp_bt_mem_release`` is called. This makes Bluetooth unavailable until the next restart, but saving ~22 KB or more of IRAM. .. only:: esp32 diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index a4cd5e7271..5094e38dd7 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -20,7 +20,7 @@ Peripherals API :SOC_DEDICATED_GPIO_SUPPORTED: dedic_gpio :SOC_HMAC_SUPPORTED: hmac :SOC_DIG_SIGN_SUPPORTED: ds - i2c + :SOC_I2C_SUPPORTED: i2c :SOC_I2S_SUPPORTED: i2s :SOC_ISP_SUPPORTED: isp :SOC_JPEG_CODEC_SUPPORTED: jpeg @@ -33,12 +33,12 @@ Peripherals API :SOC_RMT_SUPPORTED: rmt :SOC_SDMMC_HOST_SUPPORTED or SOC_SDIO_SLAVE_SUPPORTED: sd_pullup_requirements :SOC_SDMMC_HOST_SUPPORTED: sdmmc_host - sdspi_host + :SOC_GPSPI_SUPPORTED: sdspi_host :SOC_SDIO_SLAVE_SUPPORTED: sdio_slave :SOC_SDM_SUPPORTED: sdm - spi_flash/index - spi_master - spi_slave + :SOC_SPI_FLASH_SUPPORTED: spi_flash/index + :SOC_GPSPI_SUPPORTED: spi_master + :SOC_GPSPI_SUPPORTED: spi_slave :SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd :SOC_TEMP_SENSOR_SUPPORTED: temp_sensor :SOC_TOUCH_SENSOR_SUPPORTED: touch_pad diff --git a/docs/en/api-reference/peripherals/spi_flash/index.rst b/docs/en/api-reference/peripherals/spi_flash/index.rst index 08858dd3b5..9b1c4053a6 100644 --- a/docs/en/api-reference/peripherals/spi_flash/index.rst +++ b/docs/en/api-reference/peripherals/spi_flash/index.rst @@ -206,6 +206,11 @@ The chip driver relies on the host driver. OS Functions ^^^^^^^^^^^^ +.. toctree:: + :hidden: + + ../spi_features + Currently the OS function layer provides entries of a lock and delay. The lock (see :ref:`spi_bus_lock`) is used to resolve the conflicts among the access of devices on the same SPI bus, and the SPI Flash chip access. E.g. diff --git a/docs/en/api-reference/protocols/mbedtls.rst b/docs/en/api-reference/protocols/mbedtls.rst index 1459125fcc..dcb76ceaea 100644 --- a/docs/en/api-reference/protocols/mbedtls.rst +++ b/docs/en/api-reference/protocols/mbedtls.rst @@ -68,7 +68,7 @@ Following is a brief list of important config options accessible at ``Component - :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: Support for trusted root certificate bundle (more about this: :doc:`/api-reference/protocols/esp_crt_bundle`) - :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Client session tickets - :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Server session tickets - - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: Support for hardware SHA acceleration + :SOC_SHA_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: Support for hardware SHA acceleration :SOC_AES_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`: Support for hardware AES acceleration :SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: Support for hardware MPI (bignum) acceleration :SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: Support for hardware ECC acceleration diff --git a/docs/en/api-reference/storage/sdmmc.rst b/docs/en/api-reference/storage/sdmmc.rst index 8cffc601db..9af6eec9bb 100644 --- a/docs/en/api-reference/storage/sdmmc.rst +++ b/docs/en/api-reference/storage/sdmmc.rst @@ -10,7 +10,7 @@ The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. .. list:: :SOC_SDMMC_HOST_SUPPORTED: - SDMMC host driver (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h`), see :doc:`SDMMC Host API <../peripherals/sdmmc_host>` for more details. - - SDSPI host driver (:component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`), see :doc:`SD SPI Host API <../peripherals/sdspi_host>` for more details. + :SOC_GPSPI_SUPPORTED: - SDSPI host driver (:component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`), see :doc:`SD SPI Host API <../peripherals/sdspi_host>` for more details. Protocol Layer vs Host Layer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/performance/ram-usage.rst b/docs/zh_CN/api-guides/performance/ram-usage.rst index f3325eb5c5..1c912bac76 100644 --- a/docs/zh_CN/api-guides/performance/ram-usage.rst +++ b/docs/zh_CN/api-guides/performance/ram-usage.rst @@ -155,11 +155,11 @@ IRAM 优化 :esp32: - 禁用 :ref:`CONFIG_SPI_FLASH_ROM_DRIVER_PATCH` 选项可以释放一些 IRAM，但仅适用于某些 flash 配置，详情请参阅配置项帮助文档。 :esp32: - 如果应用程序基于 ESP32 rev. 3 (ECO3)，且使用 PSRAM，设置 :ref:`CONFIG_ESP32_REV_MIN` 为 ``3``，可以禁用 PSRAM 的错误处理程序，节省 10 KB 乃至更多的 IRAM。 - 禁用 :ref:`CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR` 可以防止从 :ref:`iram-safe-interrupt-handlers` 中发布 ``esp_event`` 事件，节省 IRAM 空间。 - - 禁用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 可以防止在写入 flash 时发生 spi_master 中断，节省 IRAM 空间，但可能影响 spi_master 的性能。 - - 禁用 :ref:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` 可以防止在写入 flash 时发生 spi_slave 中断，节省 IRAM 空间。 + :SOC_GPSPI_SUPPORTED: - 禁用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 可以防止在写入 flash 时发生 spi_master 中断，节省 IRAM 空间，但可能影响 spi_master 的性能。 + :SOC_GPSPI_SUPPORTED: - 禁用 :ref:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` 可以防止在写入 flash 时发生 spi_slave 中断，节省 IRAM 空间。 - 设置 :ref:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` 为禁用 HAL 组件的断言，可以节省 IRAM 空间，对于经常调用 ``HAL_ASSERT`` 且位于 IRAM 中的 HAL 代码尤为如此。 - 要禁用不需要的 flash 驱动程序，节省 IRAM 空间，请参阅 sdkconfig 菜单中的 ``Auto-detect Flash chips`` 选项。 - - 启用 :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`。只要未启用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 选项，且没有从 ISR 中错误地调用堆函数，就可以在所有配置中安全启用此选项。 + :SOC_GPSPI_SUPPORTED: - 启用 :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`。只要未启用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 选项，且没有从 ISR 中错误地调用堆函数，就可以在所有配置中安全启用此选项。 :esp32c2: - 启用 :ref:`CONFIG_BT_RELEASE_IRAM`。 蓝牙所使用的 data，bss 和 text 段已经被分配在连续的RAM区间。当调用 ``esp_bt_mem_release`` 时，这些段都会被添加到 Heap 中。 这将节省约 22 KB 的 RAM。但要再次使用蓝牙功能，需要重启程序。 .. only:: esp32 diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 08cbcdb73a..36c28c3131 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -19,7 +19,7 @@ :SOC_DEDICATED_GPIO_SUPPORTED: dedic_gpio :SOC_HMAC_SUPPORTED: hmac :SOC_DIG_SIGN_SUPPORTED: ds - i2c + :SOC_I2C_SUPPORTED: i2c :SOC_I2S_SUPPORTED: i2s :SOC_ISP_SUPPORTED: isp lcd/index @@ -32,12 +32,12 @@ :SOC_RMT_SUPPORTED: rmt :SOC_SDMMC_HOST_SUPPORTED or SOC_SDIO_SLAVE_SUPPORTED: sd_pullup_requirements :SOC_SDMMC_HOST_SUPPORTED: sdmmc_host - sdspi_host + :SOC_GPSPI_SUPPORTED: sdspi_host :SOC_SDIO_SLAVE_SUPPORTED: sdio_slave :SOC_SDM_SUPPORTED: sdm - spi_flash/index - spi_master - spi_slave + :SOC_SPI_FLASH_SUPPORTED: spi_flash/index + :SOC_GPSPI_SUPPORTED: spi_master + :SOC_GPSPI_SUPPORTED: spi_slave :SOC_SPI_SUPPORT_SLAVE_HD_VER2: spi_slave_hd :SOC_JPEG_CODEC_SUPPORTED: jpeg :SOC_TEMP_SENSOR_SUPPORTED: temp_sensor diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst index c8467755b5..89e899569e 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst @@ -206,6 +206,11 @@ SPI flash 实现 OS 函数 ^^^^^^^^^^^^ +.. toctree:: + :hidden: + + ../spi_features + OS 函数层目前支持访问锁和延迟的方法。 锁（见 :ref:`spi_bus_lock`）用于解决同一 SPI 总线上的设备访问和 SPI flash 芯片访问之间的冲突。例如： diff --git a/docs/zh_CN/api-reference/protocols/mbedtls.rst b/docs/zh_CN/api-reference/protocols/mbedtls.rst index 41f5336f31..830c4b4d54 100644 --- a/docs/zh_CN/api-reference/protocols/mbedtls.rst +++ b/docs/zh_CN/api-reference/protocols/mbedtls.rst @@ -68,7 +68,7 @@ ESP-IDF 中的示例使用 :doc:`/api-reference/protocols/esp_tls`，为访问 - :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: 支持受信任的根证书包（更多信息请参考 :doc:`/api-reference/protocols/esp_crt_bundle`） - :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: 支持 TLS 会话恢复：客户端会话票证 - :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: 支持 TLS 会话恢复：服务会话票证 - - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: 支持硬件 SHA 加速 + :SOC_SHA_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: 支持硬件 SHA 加速 :SOC_AES_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`: 支持硬件 AES 加速 :SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: 支持硬件 MPI (bignum) 加速 :SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: 支持硬件 ECC 加速 diff --git a/docs/zh_CN/api-reference/storage/sdmmc.rst b/docs/zh_CN/api-reference/storage/sdmmc.rst index 1aa99edbda..0610d47312 100644 --- a/docs/zh_CN/api-reference/storage/sdmmc.rst +++ b/docs/zh_CN/api-reference/storage/sdmmc.rst @@ -19,7 +19,7 @@ SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`esp_driver_sdmmc/in .. list:: :SOC_SDMMC_HOST_SUPPORTED: - 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>` - - 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>` + :SOC_GPSPI_SUPPORTED: - 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>` .. only:: SOC_SDMMC_HOST_SUPPORTED