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

@@ -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:

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

components/soc/esp32s3/include/soc/timer_group_caps.h

@@ -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

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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

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'

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

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

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" <all other options>
+
+---
+
+.. 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.
+
+---

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

@@ -6,7 +6,6 @@ Peripherals API
 .. toctree::
     :maxdepth: 1
 
-
     ADC <adc>
     :SOC_DAC_SUPPORTED: DAC <dac>
     General Purpose Timer <timer>
@@ -20,7 +19,7 @@ Peripherals API
     :SOC_MCPWM_SUPPORTED: MCPWM <mcpwm>
     :SOC_PCNT_SUPPORTED: Pulse Counter <pcnt>
     Remote Control <rmt>
-    :esp32: SD Pull-up Requirements <sd_pullup_requirements>
+    :esp32 or esp32s3: SD Pull-up Requirements <sd_pullup_requirements>
     :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host <sdmmc_host>
     SD SPI Host <sdspi_host>
     :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave <sdio_slave>

docs/en/index.rst

@@ -18,6 +18,12 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
 
     This document describes using ESP-IDF with the {IDF_TARGET_NAME} SoC.
 
+.. only:: esp32s3
+
+    .. warning::
+
+        Not all documents are updated for ESP32-S3 yet.
+
 ==================  ==================  ==================
 |Get Started|_      |API Reference|_    |H/W Reference|_
 ------------------  ------------------  ------------------

docs/en/security/esp32s3_log.inc

@@ -0,0 +1,17 @@
+
+.. first_boot_enc
+
+.. code-block:: none
+
+  TODO
+
+
+------
+
+.. already_en_enc
+
+.. code-block:: none
+
+  TODO
+
+------

docs/idf_extensions/build_system/__init__.py

@@ -16,7 +16,7 @@ import sys
 project_path = os.path.abspath(os.path.dirname(__file__))
 
 # Targets which needs --preview to build
-PREVIEW_TARGETS = []
+PREVIEW_TARGETS = ['esp32s3']
 
 
 def setup(app):

docs/idf_extensions/format_idf_target.py

@@ -51,16 +51,18 @@ class StringSubstituter:
         This will define a replacement of the tag {IDF_TARGET_TX_PIN} in the current rst-file, see e.g. uart.rst for example
 
     """
-    TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2', 'esp32c3': 'ESP32-C3'}
-    TOOLCHAIN_PREFIX = {'esp32': 'xtensa-esp32-elf', 'esp32s2': 'xtensa-esp32s2-elf', 'esp32c3': 'riscv32-esp-elf'}
-    CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2', 'esp32c3': 'ESP32C3'}
+    TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2', 'esp32s3': 'ESP32-S3', 'esp32c3': 'ESP32-C3'}
+    TOOLCHAIN_PREFIX = {'esp32': 'xtensa-esp32-elf', 'esp32s2': 'xtensa-esp32s2-elf', 'esp32s3': 'xtensa-esp32s3-elf', 'esp32c3': 'riscv32-esp-elf'}
+    CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2', 'esp32s3': 'ESP32S3', 'esp32c3': 'ESP32C3'}
 
     TRM_EN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf',
                   'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf',
+                  'esp32s3': '#',
                   'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf'}
 
     TRM_CN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf',
                   'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf',
+                  'esp32s3': '#',
                   'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_cn.pdf'}
     RE_PATTERN = re.compile(r'^\s*{IDF_TARGET_(\w+?):(.+?)}', re.MULTILINE)
 

docs/zh_CN/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" <all other options>
+
+---
+
+.. 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.
+
+---

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

@@ -19,6 +19,7 @@
     :SOC_MCPWM_SUPPORTED: MCPWM <mcpwm>
     :SOC_PCNT_SUPPORTED: Pulse Counter <pcnt>
     Remote Control <rmt>
+    :esp32 or esp32s3: SD Pull-up Requirements <sd_pullup_requirements>
     :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host <sdmmc_host>
     SD SPI Host <sdspi_host>
     :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave <sdio_slave>

docs/zh_CN/index.rst

@@ -18,6 +18,12 @@ ESP-IDF 编程指南
 
     本文档仅包含针对 {IDF_TARGET_NAME} 芯片的 ESP-IDF 使用。
 
+.. only:: esp32s3
+
+    .. warning::
+
+        ESP32-S3 的相关文档尚未全部更新完毕。
+
 ==================  ==================  ==================
 |快速入门|_          |API 参考|_         |H/W 参考|_
 ------------------  ------------------  ------------------

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
+
+------

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

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