blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-10 01:29:21 -04:00
Code Issues Projects Releases Wiki Activity

build docs: enable building of S3 docs

Browse Source 
* Added suport for building esp32s3 docs
 * Fixed all related warnings
 * Activated building of S3 docs for build HTML fast CI job
This commit is contained in:
Marius Vikhammer 2021-05-24 15:08:00 +08:00
parent d995086621
commit bdfda351bd
19 changed files with 427 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.gitlab/ci/docs.yml
View File

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

4
components/soc/esp32s3/include/soc/soc_caps.h
View File

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

17
components/soc/esp32s3/include/soc/timer_group_caps.h
View File

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

1
components/ulp/README.rst
View File

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

2
docs/build_docs.py
View File

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

5
docs/conf_common.py
View File

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

8
docs/doxygen/Doxyfile_esp32s3 Normal file
View File

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

160
docs/en/api-guides/jtag-debugging/esp32s3.inc Normal file
View File

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

3
docs/en/api-reference/peripherals/index.rst
View File

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

6
docs/en/index.rst
View File

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

17
docs/en/security/esp32s3_log.inc Normal file
View File

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

2
docs/idf_extensions/build_system/__init__.py
View File

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

8
docs/idf_extensions/format_idf_target.py
View File

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

160
docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc Normal file
View File

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

1
docs/zh_CN/api-reference/peripherals/index.rst
View File

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

6
docs/zh_CN/index.rst
View File

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

17
docs/zh_CN/security/esp32s3_log.inc Normal file
View File

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

26
examples/wifi/iperf/sdkconfig.defaults.esp32s3 Normal file
View File

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

1
tools/ci/mypy_ignore_list.txt
View File

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