From bdfda351bd62413eaaf7566fbcd1f3676c54421b Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 24 May 2021 15:08:00 +0800 Subject: [PATCH] build docs: enable building of S3 docs * Added suport for building esp32s3 docs * Fixed all related warnings * Activated building of S3 docs for build HTML fast CI job --- .gitlab/ci/docs.yml | 7 + components/soc/esp32s3/include/soc/soc_caps.h | 4 +- .../esp32s3/include/soc/timer_group_caps.h | 17 -- components/ulp/README.rst | 7 +- docs/build_docs.py | 2 +- docs/conf_common.py | 5 +- docs/doxygen/Doxyfile_esp32s3 | 8 + docs/en/api-guides/jtag-debugging/esp32s3.inc | 160 ++++++++++++++++++ docs/en/api-reference/peripherals/index.rst | 3 +- docs/en/index.rst | 6 + docs/en/security/esp32s3_log.inc | 17 ++ docs/idf_extensions/build_system/__init__.py | 2 +- docs/idf_extensions/format_idf_target.py | 8 +- .../api-guides/jtag-debugging/esp32s3.inc | 160 ++++++++++++++++++ .../zh_CN/api-reference/peripherals/index.rst | 1 + docs/zh_CN/index.rst | 6 + docs/zh_CN/security/esp32s3_log.inc | 17 ++ .../wifi/iperf/sdkconfig.defaults.esp32s3 | 26 +++ tools/ci/mypy_ignore_list.txt | 1 + 19 files changed, 427 insertions(+), 30 deletions(-) delete mode 100644 components/soc/esp32s3/include/soc/timer_group_caps.h create mode 100644 docs/doxygen/Doxyfile_esp32s3 create mode 100644 docs/en/api-guides/jtag-debugging/esp32s3.inc create mode 100644 docs/en/security/esp32s3_log.inc create mode 100644 docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc create mode 100644 docs/zh_CN/security/esp32s3_log.inc create mode 100644 examples/wifi/iperf/sdkconfig.defaults.esp32s3 diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index a0ce8e715e..9f20bbded7 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -125,6 +125,13 @@ build_docs_html_fast: variables: DOC_BUILDERS: "html" DOCS_FAST_BUILD: "yes" + # matrix is redefined to include esp32s3 here + # that we can build for S3 MRs during bringup phase without + # anything being built and published from master branch + parallel: + matrix: + - DOCLANG: ["en", "zh_CN"] + DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3"] build_docs_pdf: extends: diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h index c3f8cd0fc8..df7980380a 100644 --- a/components/soc/esp32s3/include/soc/soc_caps.h +++ b/components/soc/esp32s3/include/soc/soc_caps.h @@ -17,8 +17,8 @@ #define SOC_ULP_SUPPORTED 1 #define SOC_RTC_SLOW_MEM_SUPPORTED 1 #define SOC_CCOMP_TIMER_SUPPORTED 1 -#define SOC_DIG_SIGN_SUPPORTED 1 -#define SOC_HMAC_SUPPORTED 1 +#define SOC_DIG_SIGN_SUPPORTED 0 +#define SOC_HMAC_SUPPORTED 0 #define SOC_ASYNC_MEMCPY_SUPPORTED 1 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3 #define SOC_SDMMC_HOST_SUPPORTED 1 diff --git a/components/soc/esp32s3/include/soc/timer_group_caps.h b/components/soc/esp32s3/include/soc/timer_group_caps.h deleted file mode 100644 index 67d138d9ca..0000000000 --- a/components/soc/esp32s3/include/soc/timer_group_caps.h +++ /dev/null @@ -1,17 +0,0 @@ -// Copyright 2015-2020 Espressif Systems (Shanghai) PTE LTD -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#pragma once - -#define SOC_TIMER_GROUP_SUPPORT_XTAL diff --git a/components/ulp/README.rst b/components/ulp/README.rst index fbe1dafcea..3f71fa7710 100644 --- a/components/ulp/README.rst +++ b/components/ulp/README.rst @@ -24,7 +24,7 @@ The ``program`` array is an array of ``ulp_insn_t``, i.e. ULP coprocessor instru Load and store instructions use addresses expressed in 32-bit words. Address 0 corresponds to the first word of ``RTC_SLOW_MEM`` (which is address 0x50000000 as seen by the main CPUs). -To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label. +To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label. Implementation note: these ``M_`` preprocessor defines will be translated into two ``ulp_insn_t`` values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the the extra ``ulp_insn_t`` token which contains the label numer. @@ -67,6 +67,7 @@ Header File :esp32: - :component_file:`ulp/include/esp32/ulp.h` :esp32s2: - :component_file:`ulp/include/esp32s2/ulp.h` + :esp32s3: - :component_file:`ulp/include/esp32s3/ulp.h` Functions ^^^^^^^^^ @@ -88,12 +89,12 @@ ULP coprocessor registers ^^^^^^^^^^^^^^^^^^^^^^^^^ ULP co-processor has 4 16-bit general purpose registers. All registers have same functionality, with one exception. R0 register is used by some of the compare-and-branch instructions as a source register. - + These definitions can be used for all instructions which require a register. .. doxygengroup:: ulp_registers :content-only: - + ULP coprocessor instruction defines ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/build_docs.py b/docs/build_docs.py index 6841f0bb5c..4ea2346522 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -39,7 +39,7 @@ from collections import namedtuple from packaging import version LANGUAGES = ['en', 'zh_CN'] -TARGETS = ['esp32', 'esp32s2', 'esp32c3'] +TARGETS = ['esp32', 'esp32s2', 'esp32s3', 'esp32c3'] SPHINX_WARN_LOG = 'sphinx-warning-log.txt' SPHINX_SANITIZED_LOG = 'sphinx-warning-log-sanitized.txt' diff --git a/docs/conf_common.py b/docs/conf_common.py index 19d734c25d..60b8ba8c91 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -178,7 +178,7 @@ RISCV_COPROC_DOCS = ['api-guides/ulp-risc-v.rst',] XTENSA_DOCS = ['api-guides/hlinterrupts.rst', 'api-reference/system/perfmon.rst'] -RISCV_DOCS = [] +RISCV_DOCS = [] # type: list[str] ESP32_DOCS = ['api-guides/ulp_instruction_set.rst', 'api-reference/system/himem.rst', @@ -200,6 +200,8 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**', 'api-reference/peripherals/touch_element.rst', 'api-reference/peripherals/dac.rst'] + FTDI_JTAG_DOCS +ESP32S3_DOCS = ['api-reference/system/ipc.rst'] + # No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below. ESP32C3_DOCS = ['hw-reference/esp32c3/**'] @@ -224,6 +226,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS, 'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS, 'esp32':ESP32_DOCS, 'esp32s2':ESP32S2_DOCS, + 'esp32s3':ESP32S3_DOCS, 'esp32c3':ESP32C3_DOCS} # The reST default role (used for this markup: `text`) to use for all diff --git a/docs/doxygen/Doxyfile_esp32s3 b/docs/doxygen/Doxyfile_esp32s3 new file mode 100644 index 0000000000..ccee7a0e58 --- /dev/null +++ b/docs/doxygen/Doxyfile_esp32s3 @@ -0,0 +1,8 @@ +INPUT += \ + $(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \ + $(IDF_PATH)/components/hal/include/hal/mcpwm_types.h \ + $(IDF_PATH)/components/driver/include/driver/mcpwm.h \ + $(IDF_PATH)/components/hal/include/hal/pcnt_types.h \ + $(IDF_PATH)/components/driver/include/driver/pcnt.h \ + $(IDF_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \ + $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h diff --git a/docs/en/api-guides/jtag-debugging/esp32s3.inc b/docs/en/api-guides/jtag-debugging/esp32s3.inc new file mode 100644 index 0000000000..d83f3bd074 --- /dev/null +++ b/docs/en/api-guides/jtag-debugging/esp32s3.inc @@ -0,0 +1,160 @@ +.. 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/esp32s3.cfg + +.. |run-openocd-device-name| replace:: ESP32-S3 + +--- + +.. run-openocd-output + +:: + + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s3.cfg + Open On-Chip Debugger v0.10.0-esp32-20200420 (2020-04-20-16:15) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + none separate + adapter speed: 20000 kHz + force hard breakpoints + Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling" + Info : clock speed 20000 kHz + Info : JTAG tap: esp32s3.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : esp32s3: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + Info : esp32s3: Core was reset (pwrstat=0x5F, after clear 0x0F). + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s3.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32s3.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32s3.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board/esp32s3.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32s3.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32s3.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: OpenOCD configuration files for ESP32-S3 + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``board/esp32s3.cfg`` + - Board configuration file for ESP32-S3, includes target and adapter configuration. + * - ``target/esp32s3.cfg`` + - ESP32-S3 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``interface/ftdi/esp32s3.cfg`` + - JTAG adapter configuration file for ESP32-S3 board. + * - ``interface/ftdi/esp32_devkitj_v1.cfg`` + - JTAG adapter configuration file for ESP-Prog boards. + +--- + +.. openocd-target-specific-config-vars + +--- + +--- + +.. jtag-pins + +.. list-table:: ESP32-S3 pins and JTAG signals + :widths: 25 75 + :header-rows: 1 + + * - ESP32-S3 Pin + - JTAG Signal + * - MTDO + - TDO + * - MTDI + - TDI + * - MTCK + - TCK + * - MTMS + - TMS + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32s3.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32s3.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s3-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP32-S3 +.. |devkit-name-with-link| replace:: :doc:`ESP32-S3 <../../hw-reference/index>` + +--- + +.. devkit-hw-config + +* Out of the box, ESP32-S3 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. + +--- diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index a10c5763e3..d82023c12c 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -6,7 +6,6 @@ Peripherals API .. toctree:: :maxdepth: 1 - ADC :SOC_DAC_SUPPORTED: DAC General Purpose Timer @@ -20,7 +19,7 @@ Peripherals API :SOC_MCPWM_SUPPORTED: MCPWM :SOC_PCNT_SUPPORTED: Pulse Counter Remote Control - :esp32: SD Pull-up Requirements + :esp32 or esp32s3: SD Pull-up Requirements :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host SD SPI Host :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave diff --git a/docs/en/index.rst b/docs/en/index.rst index 29fde1d2f9..5fc39188a2 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -18,6 +18,12 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf &1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s3-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP32-S3 +.. |devkit-name-with-link| replace:: :doc:`ESP32-S3 <../../hw-reference/index>` + +--- + +.. devkit-hw-config + +* Out of the box, ESP32-S3 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. + +--- diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 5dd2a718fe..1c0336c046 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -19,6 +19,7 @@ :SOC_MCPWM_SUPPORTED: MCPWM :SOC_PCNT_SUPPORTED: Pulse Counter Remote Control + :esp32 or esp32s3: SD Pull-up Requirements :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host SD SPI Host :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index e9a96fe48d..f7f39628b4 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -18,6 +18,12 @@ ESP-IDF 编程指南 本文档仅包含针对 {IDF_TARGET_NAME} 芯片的 ESP-IDF 使用。 +.. only:: esp32s3 + + .. warning:: + + ESP32-S3 的相关文档尚未全部更新完毕。 + ================== ================== ================== |快速入门|_ |API 参考|_ |H/W 参考|_ ------------------ ------------------ ------------------ diff --git a/docs/zh_CN/security/esp32s3_log.inc b/docs/zh_CN/security/esp32s3_log.inc new file mode 100644 index 0000000000..b72707a27b --- /dev/null +++ b/docs/zh_CN/security/esp32s3_log.inc @@ -0,0 +1,17 @@ + +.. first_boot_enc + +.. code-block:: none + + TODO + + +------ + +.. already_en_enc + +.. code-block:: none + + TODO + +------ diff --git a/examples/wifi/iperf/sdkconfig.defaults.esp32s3 b/examples/wifi/iperf/sdkconfig.defaults.esp32s3 new file mode 100644 index 0000000000..a7dde05537 --- /dev/null +++ b/examples/wifi/iperf/sdkconfig.defaults.esp32s3 @@ -0,0 +1,26 @@ +# +# ESP32S3-specific +# +CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM=8 +CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM=24 +CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM=24 +CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED=y +CONFIG_ESP32_WIFI_TX_BA_WIN=16 +CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED=y +CONFIG_ESP32_WIFI_RX_BA_WIN=16 + +CONFIG_LWIP_TCP_SND_BUF_DEFAULT=28000 +CONFIG_LWIP_TCP_WND_DEFAULT=28000 +CONFIG_LWIP_TCP_RECVMBOX_SIZE=32 +CONFIG_LWIP_UDP_RECVMBOX_SIZE=32 +CONFIG_LWIP_TCPIP_RECVMBOX_SIZE=32 + +CONFIG_ESP32S3_DEFAULT_CPU_FREQ_240=y +CONFIG_ESP32S3_DEFAULT_CPU_FREQ_MHZ=240 + +CONFIG_ESPTOOLPY_FLASHMODE_QIO=y +CONFIG_ESPTOOLPY_FLASHFREQ_80M=y + +CONFIG_ESP32S3_INSTRUCTION_CACHE_16KB=y +CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_16B=y +CONFIG_ESP32S3_INSTRUCTION_CACHE_WRAP=y diff --git a/tools/ci/mypy_ignore_list.txt b/tools/ci/mypy_ignore_list.txt index 0bfbbe2e9d..607dcec956 100644 --- a/tools/ci/mypy_ignore_list.txt +++ b/tools/ci/mypy_ignore_list.txt @@ -33,6 +33,7 @@ docs/extensions/list_filter.py docs/extensions/toctree_filter.py docs/generate_chart.py docs/get_github_rev.py +docs/idf_extensions/build_system/__init__.py docs/idf_extensions/esp_err_definitions.py docs/idf_extensions/exclude_docs.py docs/idf_extensions/format_idf_target.py