From da947d736f2b35de1790aaa255bf7113a91d89d2 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 29 Oct 2020 09:57:09 +0800 Subject: [PATCH] Docs: Add C3 support to build_docs --- components/esp_common/sdkconfig.rename | 2 - components/esp_gdbstub/sdkconfig.rename | 5 + docs/conf_common.py | 31 +++- docs/{Doxyfile => doxygen/Doxyfile_common} | 11 +- docs/doxygen/Doxyfile_esp32 | 4 + docs/doxygen/Doxyfile_esp32c3 | 3 + docs/doxygen/Doxyfile_esp32s2 | 7 + docs/en/api-guides/general-notes.rst | 32 ++-- docs/en/api-guides/index.rst | 6 +- docs/en/api-guides/jtag-debugging/esp32c3.inc | 160 ++++++++++++++++++ .../jtag-debugging/tips-and-quirks.rst | 2 +- docs/en/api-reference/peripherals/adc.rst | 4 +- docs/en/api-reference/peripherals/gpio.rst | 21 ++- docs/en/api-reference/peripherals/index.rst | 6 +- docs/en/api-reference/system/mem_alloc.rst | 16 +- docs/en/api-reference/template.rst | 16 +- docs/en/contribute/add-ons-reference.rst | 2 +- docs/idf_extensions/build_system/__init__.py | 10 +- docs/idf_extensions/exclude_docs.py | 10 +- docs/idf_extensions/format_idf_target.py | 12 +- docs/idf_extensions/run_doxygen.py | 16 +- docs/zh_CN/api-guides/general-notes.rst | 42 ++--- docs/zh_CN/api-guides/index.rst | 6 +- .../api-guides/jtag-debugging/esp32c3.inc | 160 ++++++++++++++++++ .../jtag-debugging/tips-and-quirks.rst | 2 +- .../api-guides/linker-script-generation.rst | 8 +- .../zh_CN/api-reference/peripherals/index.rst | 6 +- docs/zh_CN/contribute/add-ons-reference.rst | 4 +- 28 files changed, 501 insertions(+), 103 deletions(-) create mode 100644 components/esp_gdbstub/sdkconfig.rename rename docs/{Doxyfile => doxygen/Doxyfile_common} (97%) create mode 100644 docs/doxygen/Doxyfile_esp32 create mode 100644 docs/doxygen/Doxyfile_esp32c3 create mode 100644 docs/doxygen/Doxyfile_esp32s2 create mode 100644 docs/en/api-guides/jtag-debugging/esp32c3.inc create mode 100644 docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc diff --git a/components/esp_common/sdkconfig.rename b/components/esp_common/sdkconfig.rename index 169f49a057..2a9c6c122b 100644 --- a/components/esp_common/sdkconfig.rename +++ b/components/esp_common/sdkconfig.rename @@ -16,8 +16,6 @@ CONFIG_CONSOLE_UART_CUSTOM_NUM_1 CONFIG_ESP_CONSOLE_UART_ CONFIG_CONSOLE_UART_TX_GPIO CONFIG_ESP_CONSOLE_UART_TX_GPIO CONFIG_CONSOLE_UART_RX_GPIO CONFIG_ESP_CONSOLE_UART_RX_GPIO CONFIG_CONSOLE_UART_BAUDRATE CONFIG_ESP_CONSOLE_UART_BAUDRATE -CONFIG_GDBSTUB_SUPPORT_TASKS CONFIG_ESP_GDBSTUB_SUPPORT_TASKS -CONFIG_GDBSTUB_MAX_TASKS CONFIG_ESP_GDBSTUB_MAX_TASKS CONFIG_INT_WDT CONFIG_ESP_INT_WDT CONFIG_INT_WDT_TIMEOUT_MS CONFIG_ESP_INT_WDT_TIMEOUT_MS CONFIG_INT_WDT_CHECK_CPU1 CONFIG_ESP_INT_WDT_CHECK_CPU1 diff --git a/components/esp_gdbstub/sdkconfig.rename b/components/esp_gdbstub/sdkconfig.rename new file mode 100644 index 0000000000..375c01a0fa --- /dev/null +++ b/components/esp_gdbstub/sdkconfig.rename @@ -0,0 +1,5 @@ +# sdkconfig replacement configurations for deprecated options formatted as +# CONFIG_DEPRECATED_OPTION CONFIG_NEW_OPTION + +CONFIG_GDBSTUB_SUPPORT_TASKS CONFIG_ESP_GDBSTUB_SUPPORT_TASKS +CONFIG_GDBSTUB_MAX_TASKS CONFIG_ESP_GDBSTUB_MAX_TASKS diff --git a/docs/conf_common.py b/docs/conf_common.py index 2132d08615..88f9e179f4 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -133,7 +133,6 @@ print('Version: {0} Release: {1}'.format(version, release)) # directories to ignore when looking for source files. exclude_patterns = ['**/inc/**', '_static/', '_build/**'] - BT_DOCS = ['api-guides/blufi.rst', 'api-guides/esp-ble-mesh/**', 'api-reference/bluetooth/**'] @@ -147,6 +146,14 @@ MCPWM_DOCS = ['api-reference/peripherals/mcpwm.rst'] DEDIC_GPIO_DOCS = ['api-reference/peripherals/dedic_gpio.rst'] +PCNT_DOCS = ['api-reference/peripherals/pcnt.rst'] + +DAC_DOCS = ['api-reference/peripherals/dac.rst'] + +TOUCH_SENSOR_DOCS = ['api-reference/peripherals/touch_pad.rst'] + +SPIRAM_DOCS = ['api-guides/external-ram.rst'] + LEGACY_DOCS = ['api-guides/build-system-legacy.rst', 'gnu-make-legacy.rst', 'api-guides/ulp-legacy.rst', @@ -155,12 +162,19 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst', USB_DOCS = ['api-reference/peripherals/usb.rst'] +ULP_DOCS = ['api-guides/ulp.rst', 'api-guides/ulp_macros.rst'] + +XTENSA_DOCS = ['api-guides/hlinterrupts.rst'] + +RISCV_DOCS = ['api-guides/hlinterrupts.rst'] + ESP32_DOCS = ['api-guides/ulp_instruction_set.rst', 'api-reference/system/himem.rst', 'api-guides/RF_calibration.rst', 'api-reference/system/ipc.rst', 'security/secure-boot-v1.rst', 'api-reference/peripherals/secure_element.rst', + 'api-reference/peripherals/dac.rst', 'hw-reference/esp32/**'] + LEGACY_DOCS ESP32S2_DOCS = ['hw-reference/esp32s2/**', @@ -173,7 +187,10 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**', 'api-reference/peripherals/spi_slave_hd.rst', 'api-reference/peripherals/temp_sensor.rst', 'api-reference/system/async_memcpy.rst', - 'api-reference/peripherals/usb.rst'] + 'api-reference/peripherals/usb.rst', + 'api-reference/peripherals/dac.rst'] + +ESP32C3_DOCS = [] # 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, @@ -182,8 +199,16 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS, 'SOC_MCPWM_SUPPORTED':MCPWM_DOCS, 'SOC_USB_SUPPORTED':USB_DOCS, 'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS, + 'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS, + 'SOC_PCNT_SUPPORTED':PCNT_DOCS, + 'SOC_DAC_PERIPH_NUM':DAC_DOCS, + 'SOC_TOUCH_SENSOR_NUM':TOUCH_SENSOR_DOCS, + 'SOC_ULP_SUPPORTED':ULP_DOCS, + 'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS, + 'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS, 'esp32':ESP32_DOCS, - 'esp32s2':ESP32S2_DOCS} + 'esp32s2':ESP32S2_DOCS, + 'esp32c3':ESP32C3_DOCS} # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/Doxyfile b/docs/doxygen/Doxyfile_common similarity index 97% rename from docs/Doxyfile rename to docs/doxygen/Doxyfile_common index c9a023aec4..ce10817178 100644 --- a/docs/Doxyfile +++ b/docs/doxygen/Doxyfile_common @@ -109,9 +109,7 @@ INPUT = \ $(IDF_PATH)/components/driver/include/driver/spi_slave.h \ $(IDF_PATH)/components/driver/include/driver/spi_slave_hd.h \ $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/adc.h \ - $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/dac.h \ $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \ - $(IDF_PATH)/components/driver/esp32s2/include/driver/temp_sensor.h \ $(IDF_PATH)/components/driver/include/driver/timer.h \ $(IDF_PATH)/components/driver/include/driver/touch_sensor_common.h \ $(IDF_PATH)/components/driver/include/driver/twai.h \ @@ -119,8 +117,6 @@ INPUT = \ $(IDF_PATH)/components/driver/include/driver/dac_common.h \ $(IDF_PATH)/components/driver/include/driver/uart.h \ $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \ - $(IDF_PATH)/components/esp32s2/include/esp_hmac.h \ - $(IDF_PATH)/components/esp32s2/include/esp_ds.h \ $(IDF_PATH)/components/hal/include/hal/dma_types.h \ $(IDF_PATH)/components/hal/include/hal/gpio_types.h \ $(IDF_PATH)/components/hal/include/hal/uart_types.h \ @@ -235,8 +231,6 @@ INPUT = \ $(IDF_PATH)/components/heap/include/esp_heap_trace.h \ $(IDF_PATH)/components/heap/include/esp_heap_caps_init.h \ $(IDF_PATH)/components/heap/include/multi_heap.h \ - ## Himem - $(IDF_PATH)/components/esp32/include/esp32/himem.h \ ## Interrupt Allocation $(IDF_PATH)/components/esp_system/include/esp_intr_alloc.h \ ## Watchdogs @@ -270,8 +264,6 @@ INPUT = \ ## ULP Coprocessor - API Guides ## ## NOTE: for line below header_file.inc is not used - $(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \ - $(IDF_PATH)/components/ulp/include/esp32s2/ulp_riscv.h \ $(IDF_PATH)/components/ulp/include/ulp_common.h \ ## ## Application Level Tracing - API Reference @@ -318,6 +310,9 @@ INPUT = \ $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h +## Target specific headers are in seperate Doxyfile files +@INCLUDE = $(IDF_PATH)/docs/doxygen/Doxyfile_$(IDF_TARGET) + ## Get warnings for functions that have no documentation for their parameters or return value ## WARN_NO_PARAMDOC = YES diff --git a/docs/doxygen/Doxyfile_esp32 b/docs/doxygen/Doxyfile_esp32 new file mode 100644 index 0000000000..d405baf101 --- /dev/null +++ b/docs/doxygen/Doxyfile_esp32 @@ -0,0 +1,4 @@ +INPUT += \ + $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/dac.h \ + $(IDF_PATH)/components/esp32/include/esp32/himem.h \ + $(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h diff --git a/docs/doxygen/Doxyfile_esp32c3 b/docs/doxygen/Doxyfile_esp32c3 new file mode 100644 index 0000000000..6a349aecc6 --- /dev/null +++ b/docs/doxygen/Doxyfile_esp32c3 @@ -0,0 +1,3 @@ +INPUT += \ + $(IDF_PATH)/components/driver/esp32c3/include/driver/temp_sensor.h \ + $(IDF_PATH)/components/esp32c3/include/esp_hmac.h diff --git a/docs/doxygen/Doxyfile_esp32s2 b/docs/doxygen/Doxyfile_esp32s2 new file mode 100644 index 0000000000..c2768452d5 --- /dev/null +++ b/docs/doxygen/Doxyfile_esp32s2 @@ -0,0 +1,7 @@ +INPUT += \ + $(IDF_PATH)/components/driver/esp32s2/include/driver/temp_sensor.h \ + $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/driver/dac.h \ + $(IDF_PATH)/components/esp32s2/include/esp_hmac.h \ + $(IDF_PATH)/components/esp32s2/include/esp_ds.h \ + $(IDF_PATH)/components/ulp/include/esp32s2/ulp_riscv.h \ + $(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h diff --git a/docs/en/api-guides/general-notes.rst b/docs/en/api-guides/general-notes.rst index 84fa489a51..58e4a14290 100644 --- a/docs/en/api-guides/general-notes.rst +++ b/docs/en/api-guides/general-notes.rst @@ -170,20 +170,20 @@ Or:: Placing DMA buffers in the stack is still allowed, though you have to keep in mind: -1. Never try to do this if the stack is in the pSRAM. If the stack of a task is placed in the pSRAM, several steps have - to be taken as described in :doc:`external-ram` (at least ``SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY`` option enabled in - the menuconfig). Make sure your task is not in the pSRAM. -2. Use macro ``WORD_ALIGNED_ATTR`` in functions before variables to place them in proper positions like:: +.. list:: - void app_main() - { - uint8_t stuff; - WORD_ALIGNED_ATTR uint8_t buffer[]="I want to send something"; //or the buffer will be placed right after stuff. - // initialization code... - spi_transaction_t temp = { - .tx_buffer = buffer, - .length = 8*sizeof(buffer), - }; - spi_device_transmit( spi, &temp ); - // other stuff - } + :SOC_SPIRAM_SUPPORTED: - Never try to do this if the stack is in the pSRAM. If the stack of a task is placed in the pSRAM, several steps have to be taken as described in :doc:`external-ram` (at least ``SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY`` option enabled in the menuconfig). Make sure your task is not in the pSRAM. + - Use macro ``WORD_ALIGNED_ATTR`` in functions before variables to place them in proper positions like:: + + void app_main() + { + uint8_t stuff; + WORD_ALIGNED_ATTR uint8_t buffer[]="I want to send something"; //or the buffer will be placed right after stuff. + // initialization code... + spi_transaction_t temp = { + .tx_buffer = buffer, + .length = 8*sizeof(buffer), + }; + spi_device_transmit( spi, &temp ); + // other stuff + } diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 29e5dbc5b5..12ed3e7ca6 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -17,13 +17,13 @@ API Guides ESP-MESH (Wi-Fi) Core Dump Event Handling - External SPI-connected RAM + :SOC_SPIRAM_SUPPORTED: External SPI-connected RAM Fatal Errors Flash Encryption <../security/flash-encryption> FreeRTOS SMP Changes General Notes Hardware Abstraction - High Level Interrupts + :CONFIG_IDF_TARGET_ARCH_XTENSA: High Level Interrupts JTAG Debugging Linker Script Generation lwIP TCP/IP Stack @@ -34,7 +34,7 @@ API Guides Secure Boot V2 <../security/secure-boot-v2> Thread Local Storage Tools - ULP Coprocessor + :SOC_ULP_SUPPORTED: ULP Coprocessor :esp32: ULP Coprocessor (Legacy GNU Make) :esp32s2: ULP-RISC-V Coprocessor Unit Testing diff --git a/docs/en/api-guides/jtag-debugging/esp32c3.inc b/docs/en/api-guides/jtag-debugging/esp32c3.inc new file mode 100644 index 0000000000..26f3b2424d --- /dev/null +++ b/docs/en/api-guides/jtag-debugging/esp32c3.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/Xcfg + +.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 board + +--- + +.. run-openocd-output + +:: + + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.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: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F). + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: OpenOCD configuration files for ESP32-S2 + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``board/esp32s2-kaluga-1.cfg`` + - Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration. + * - ``target/esp32s2.cfg`` + - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``interface/ftdi/esp32s2_kaluga_v1.cfg`` + - JTAG adapter configuration file for ESP32-S2-Kaluga-1 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-S2 pins and JTAG signals + :widths: 25 75 + :header-rows: 1 + + * - ESP32-S2 Pin + - JTAG Signal + * - MTDO / GPIO40 + - TDO + * - MTDI / GPIO41 + - TDI + * - MTCK / GPIO39 + - TCK + * - MTMS / GPIO42 + - TMS + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP-S2-Kaluga-1 +.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>` + +--- + +.. devkit-hw-config + +* Out of the box, ESP32-S2-Kaluga-1 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-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 4a5672dc47..beed1f4b4e 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -90,7 +90,7 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task .. _jtag-debugging-tip-optimize-jtag-speed: -.. only:: esp32s2 +.. only:: not esp32 .. _jtag-debugging-tip-optimize-jtag-speed: diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index f912c9503e..b5876ffe1b 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -51,7 +51,9 @@ Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor. -This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above. +.. only:: SOC_ULP_SUPPORTED + + This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above. There is another specific function :cpp:func:`adc_vref_to_gpio` used to route internal reference voltage to a GPIO pin. It comes handy to calibrate ADC reading and this is discussed in section :ref:`adc-api-adc-calibration`. diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index 232b2033c7..da2a79c3d5 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -19,7 +19,15 @@ Overview - GPIO46 is fixed to pull-down and is input only -There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use. +.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED + + There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when: + + .. list:: + + - In deep sleep + :SOC_ULP_SUPPORTED: - The :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running + - Analog functions such as ADC/DAC/etc are in use. Application Example ------------------- @@ -32,10 +40,13 @@ API Reference - Normal GPIO .. include-build-file:: inc/gpio.inc .. include-build-file:: inc/gpio_types.inc -API Reference - RTC GPIO ------------------------- -.. include-build-file:: inc/rtc_io.inc -.. include-build-file:: inc/rtc_io_types.inc +.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED + + API Reference - RTC GPIO + ------------------------ + + .. include-build-file:: inc/rtc_io.inc + .. include-build-file:: inc/rtc_io_types.inc diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 12cd73fa8f..8bed6cd101 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -8,7 +8,7 @@ Peripherals API ADC - DAC + :SOC_DAC_PERIPH_NUM: DAC GPIO (including RTC low power I/O) :SOC_DEDICATED_GPIO_SUPPORTED: Dedicated GPIO :esp32s2: HMAC @@ -17,7 +17,7 @@ Peripherals API I2S LED Control :SOC_MCPWM_SUPPORTED: MCPWM - Pulse Counter + :SOC_PCNT_SUPPORTED: Pulse Counter Remote Control :esp32: SD Pull-up Requirements :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host @@ -30,7 +30,7 @@ Peripherals API :esp32s2: SPI Slave Half Duplex :esp32s2: Temp sensor Timer - Touch Sensor + :SOC_TOUCH_SENSOR_NUM: Touch Sensor TWAI UART :SOC_USB_SUPPORTED: USB diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index a288834d0a..3f32dadd97 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -26,7 +26,9 @@ The {IDF_TARGET_NAME} contains multiple types of RAM: For more details on these internal memory types, see :ref:`memory-layout`. -It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM ` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM. +.. only:: SOC_SPIRAM_SUPPORTED + + It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM ` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM. DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and writes). When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls ``heap_caps_malloc(size, MALLOC_CAP_8BIT)`` in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:`heap_caps_get_free_size(MALLOC_CAP_8BIT)`. @@ -100,14 +102,16 @@ which it can't do for a normal malloc() call. This can help to use all the avail Memory allocated with ``MALLOC_CAP_32BIT`` can *only* be accessed via 32-bit reads and writes, any other type of access will generate a fatal LoadStoreError exception. -External SPI Memory -^^^^^^^^^^^^^^^^^^^ +.. only:: SOC_SPIRAM_SUPPORTED -When :doc:`external RAM ` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details. + External SPI Memory + ^^^^^^^^^^^^^^^^^^^ -.. only:: esp32 + When :doc:`external RAM ` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details. - To use the region above the 4MiB limit, you can use the :doc:`himem API`. + .. only:: esp32 + + To use the region above the 4MiB limit, you can use the :doc:`himem API`. API Reference - Heap Allocation diff --git a/docs/en/api-reference/template.rst b/docs/en/api-reference/template.rst index b536d875db..0ad41e8800 100644 --- a/docs/en/api-reference/template.rst +++ b/docs/en/api-reference/template.rst @@ -1,4 +1,4 @@ -API Documentation Template +API Documentation Template ========================== .. note:: @@ -23,7 +23,7 @@ Overview *INSTRUCTIONS* - 1. Provide overview where and how this API may be used. + 1. Provide overview where and how this API may be used. 2. Where applicable include code snippets to illustrate functionality of particular functions. 3. To distinguish between sections, use the following `heading levels `_: @@ -49,7 +49,7 @@ Application Example 6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part. 7. Include flow diagram and screenshots of application output if applicable. 8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``. - + API Reference ------------- @@ -60,8 +60,8 @@ API Reference *INSTRUCTIONS* 1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`. - - 1. Update is done on each documentation build by invoking Sphinx extension :idf_file:`docs/idf_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/Doxyfile`. + + 1. Update is done on each documentation build by invoking Sphinx extension :idf_file:`docs/idf_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile_common`. 1. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files:: @@ -80,7 +80,7 @@ API Reference .. include-build-file:: inc/esp_wifi.inc For example see :idf_file:`docs/en/api-reference/network/esp_wifi.rst` - + 1. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example. Below is the list of common ``.. doxygen...::`` directives: @@ -98,6 +98,6 @@ API Reference * :component_file:`path_to/header_file.h` - 1. In any case, to generate API reference, the file :idf_file:`docs/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented. - + 1. In any case, to generate API reference, the file :idf_file:`docs/doxygen/Doxyfile_common` should be updated with paths to ``*.h`` headers that are being documented. + 1. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required. diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index 75683cae98..ffbc7bb6a1 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -172,7 +172,7 @@ Other Extensions Subscribes to ``idf-defines-generated`` as it relies on the sphinx tags to determine which documents to exclude :idf_file:`docs/idf_extensions/run_doxygen.py` - Subscribes to ``idf-defines-generated`` event and runs Doxygen (:idf_file:`docs/Doxyfile`) to generate XML files describing key headers, and then runs Breathe to convert these to ``.inc`` files which can be included directly into API reference pages. + Subscribes to ``idf-defines-generated`` event and runs Doxygen (:idf_file:`docs/doxygen/Doxyfile_common`) to generate XML files describing key headers, and then runs Breathe to convert these to ``.inc`` files which can be included directly into API reference pages. Pushes a number of target-specific custom environment variables into Doxygen, including all macros defined in the project's default ``sdkconfig.h`` file and all macros defined in all ``soc`` component ``xxx_caps.h`` headers. This means that public API headers can depend on target-specific configuration options or ``soc`` capabilities headers options as ``#ifdef`` & ``#if`` preprocessor selections in the header. diff --git a/docs/idf_extensions/build_system/__init__.py b/docs/idf_extensions/build_system/__init__.py index 8265c30ad2..9332a0f10e 100644 --- a/docs/idf_extensions/build_system/__init__.py +++ b/docs/idf_extensions/build_system/__init__.py @@ -15,6 +15,9 @@ import json # this directory also contains the dummy IDF project project_path = os.path.abspath(os.path.dirname(__file__)) +# Targets which needs --preview to build +PREVIEW_TARGETS = ['esp32c3'] + def setup(app): # Setup some common paths @@ -71,7 +74,12 @@ def generate_idf_info(app, config): # (not much slower than 'reconfigure', avoids any potential config & build versioning problems shutil.rmtree(cmake_build_dir, ignore_errors=True) print("Starting new dummy IDF project... ") - subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) + + if (app.config.idf_target in PREVIEW_TARGETS): + subprocess.check_call(idf_py + ["--preview", "set-target", app.config.idf_target]) + else: + subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) + print("Running CMake on dummy project...") subprocess.check_call(idf_py + ["reconfigure"]) diff --git a/docs/idf_extensions/exclude_docs.py b/docs/idf_extensions/exclude_docs.py index 8b589c9eb2..769e9e5400 100644 --- a/docs/idf_extensions/exclude_docs.py +++ b/docs/idf_extensions/exclude_docs.py @@ -9,9 +9,17 @@ def update_exclude_patterns(app, config): if config.docs_to_build: build_subset(app, config) + include_set = set() + exclude_set = set() + for tag, docs in config.conditional_include_dict.items(): if not app.tags.has(tag): - app.config.exclude_patterns.extend(docs) + exclude_set.update(docs) + else: + include_set.update(docs) + # Do not exclude docs that have been explicitly included, e.g. if a doc is listed in both + # ESP32_DOCS and ESP32S2_DOCS it will be included for those targets. + app.config.exclude_patterns.extend(exclude_set - include_set) def build_subset(app, config): diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py index cc726d5549..d96f7804ec 100644 --- a/docs/idf_extensions/format_idf_target.py +++ b/docs/idf_extensions/format_idf_target.py @@ -50,15 +50,17 @@ 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'} - TOOLCHAIN_NAMES = {'esp32': 'esp32', 'esp32s2': 'esp32s2'} - CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2'} + TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2', 'esp32c3': 'ESP32-C3'} + TOOLCHAIN_NAMES = {'esp32': 'esp32', 'esp32s2': 'esp32s2', 'esp32c3': 'esp32c3'} + CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2', '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'} + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf', + 'esp32c3': '#'} 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'} + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf', + 'esp32c3': '#'} RE_PATTERN = re.compile(r'^\s*{IDF_TARGET_(\w+?):(.+?)}', re.MULTILINE) def __init__(self): diff --git a/docs/idf_extensions/run_doxygen.py b/docs/idf_extensions/run_doxygen.py index 7aaa89cd67..4fea153fd2 100644 --- a/docs/idf_extensions/run_doxygen.py +++ b/docs/idf_extensions/run_doxygen.py @@ -37,8 +37,10 @@ def generate_doxygen(app, defines): "IDF_PATH": app.config.idf_path, "IDF_TARGET": app.config.idf_target, }) - doxyfile = os.path.join(app.config.docs_root, "Doxyfile") - print("Running doxygen with doxyfile {}".format(doxyfile)) + doxyfile_dir = os.path.join(app.config.docs_root, "doxygen") + doxyfile_main = os.path.join(doxyfile_dir, "Doxyfile_common") + doxyfile_target = os.path.join(doxyfile_dir, "Doxyfile_" + app.config.idf_target) + print("Running doxygen with doxyfiles {} and {}".format(doxyfile_main, doxyfile_target)) # It's possible to have doxygen log warnings to a file using WARN_LOGFILE directive, # but in some cases it will still log an error to stderr and return success! @@ -48,17 +50,18 @@ def generate_doxygen(app, defines): with open(logfile, "w") as f: # note: run Doxygen in the build directory, so the xml & xml_in files end up in there - subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir, stderr=f) + subprocess.check_call(["doxygen", doxyfile_main], env=doxy_env, cwd=build_dir, stderr=f) # Doxygen has generated XML files in 'xml' directory. # Copy them to 'xml_in', only touching the files which have changed. copy_if_modified(os.path.join(build_dir, 'xml/'), os.path.join(build_dir, 'xml_in/')) # Generate 'api_name.inc' files from the Doxygen XML files - convert_api_xml_to_inc(app, doxyfile) + doxygen_paths = [doxyfile_main, doxyfile_target] + convert_api_xml_to_inc(app, doxygen_paths) -def convert_api_xml_to_inc(app, doxyfile): +def convert_api_xml_to_inc(app, doxyfiles): """ Generate header_file.inc files with API reference made of doxygen directives for each header file @@ -75,7 +78,8 @@ def convert_api_xml_to_inc(app, doxyfile): if not os.path.exists(inc_directory_path): os.makedirs(inc_directory_path) - header_paths = get_doxyfile_input_paths(app, doxyfile) + header_paths = [p for d in doxyfiles for p in get_doxyfile_input_paths(app, d)] + print("Generating 'api_name.inc' files with Doxygen directives") for header_file_path in header_paths: api_name = get_api_name(header_file_path) diff --git a/docs/zh_CN/api-guides/general-notes.rst b/docs/zh_CN/api-guides/general-notes.rst index b808879739..11b07a2549 100644 --- a/docs/zh_CN/api-guides/general-notes.rst +++ b/docs/zh_CN/api-guides/general-notes.rst @@ -292,26 +292,28 @@ DMA 能力要求 在堆栈中放置 DMA 缓冲区仍然是允许的，但是你必须记住： -1. 如果堆栈在 pSRAM 中，切勿尝试这么做，因为堆栈在 pSRAM 中的话就要按照 - :doc:`片外SRAM ` 文档介绍的步骤来操作（至少要在 - ``menuconfig`` 中使能 - ``SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY`` ），所以请确保你的任务不在 - pSRAM 中。 +.. list:: -2. 在函数中使用 ``WORD_ALIGNED_ATTR`` - 宏来修饰变量，将其放在适当的位置上，比如： + :SOC_SPIRAM_SUPPORTED:- 如果堆栈在 pSRAM 中，切勿尝试这么做，因为堆栈在 pSRAM 中的话就要按照 + :doc:`片外SRAM ` 文档介绍的步骤来操作（至少要在 + ``menuconfig`` 中使能 + ``SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY`` ），所以请确保你的任务不在 + pSRAM 中。 - .. code:: c + - 在函数中使用 ``WORD_ALIGNED_ATTR`` + 宏来修饰变量，将其放在适当的位置上，比如： - void app_main() - { - uint8_t stuff; - WORD_ALIGNED_ATTR uint8_t buffer[]="I want to send something"; //否则buffer数组会被存储在stuff变量的后面 - // 初始化代码... - spi_transaction_t temp = { - .tx_buffer = buffer, - .length = 8*sizeof(buffer), - }; - spi_device_transmit( spi, &temp ); - // 其他程序 - } + .. code:: c + + void app_main() + { + uint8_t stuff; + WORD_ALIGNED_ATTR uint8_t buffer[]="I want to send something"; //否则buffer数组会被存储在stuff变量的后面 + // 初始化代码... + spi_transaction_t temp = { + .tx_buffer = buffer, + .length = 8*sizeof(buffer), + }; + spi_device_transmit( spi, &temp ); + // 其他程序 + } diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index ac06b4ddb3..d56c3f6886 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -18,13 +18,13 @@ API 指南 FreeRTOS SMP Changes Thread Local Storage 硬件抽象层 - High Level Interrupts + :CONFIG_IDF_TARGET_ARCH_XTENSA: High Level Interrupts JTAG 调试 引导加载程序 分区表 :esp32: Secure Boot <../security/secure-boot-v1> Secure Boot V2 <../security/secure-boot-v2> - ULP 协处理器 + :SOC_ULP_SUPPORTED: ULP 协处理器 :esp32: ULP (传统 GNU Make) :esp32s2: ULP-RISC-V Coprocessor 单元测试 @@ -36,7 +36,7 @@ API 指南 :SOC_BT_SUPPORTED: ESP-BLE-MESH ESP-MESH (Wi-Fi) :SOC_BT_SUPPORTED: BluFi - External SPI-connected RAM + :SOC_SPIRAM_SUPPORTED: External SPI-connected RAM 链接脚本生成机制 LwIP Tools diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc new file mode 100644 index 0000000000..8863c522e4 --- /dev/null +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32c3.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/esp32s2-kaluga-1.cfg + +.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 开发板 + +--- + +.. run-openocd-output + +:: + + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.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: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F). + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件 + :widths: 25 75 + :header-rows: 1 + + * - 名字 + - 描述 + * - ``board/esp32s2-kaluga-1.cfg`` + - ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置 + * - ``target/esp32s2.cfg`` + - ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用 + * - ``interface/ftdi/esp32s2_kaluga_v1.cfg`` + - 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件 + * - ``interface/ftdi/esp32_devkitj_v1.cfg`` + - 适用于 ESP-Prog 板子的 JTAG 适配器配置文件 + +--- + +.. openocd-target-specific-config-vars + +--- + +--- + +.. jtag-pins + +.. list-table:: ESP32-S2 引脚和 JTAG 接口信号 + :widths: 25 75 + :header-rows: 1 + + * - ESP32-S2 引脚 + - JTAG 信号 + * - MTDO / GPIO40 + - TDO + * - MTDI / GPIO41 + - TDI + * - MTCK / GPIO39 + - TCK + * - MTMS / GPIO42 + - TMS + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP-S2-Kaluga-1 +.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>` + +--- + +.. devkit-hw-config + +* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。 + +--- diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index 1f61c14408..c78dba379b 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -84,7 +84,7 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT .. _jtag-debugging-tip-optimize-jtag-speed: -.. only:: esp32s2 +.. only:: not esp32 .. _jtag-debugging-tip-optimize-jtag-speed: diff --git a/docs/zh_CN/api-guides/linker-script-generation.rst b/docs/zh_CN/api-guides/linker-script-generation.rst index 343517ea2d..1287272ec8 100644 --- a/docs/zh_CN/api-guides/linker-script-generation.rst +++ b/docs/zh_CN/api-guides/linker-script-generation.rst @@ -5,7 +5,7 @@ 概述 ---- -用于存放代码和数据的 :ref:` 内存区域 `有多个。代码和只读数据默认存放在 flash 中，可写数据存放在 RAM 中。不过有时，我们必须更改默认存放区域，例如为了提高性能，将关键代码存放到 RAM 中，或者将代码存放到 RTC 存储器中以便在 :doc:`唤醒桩 ` 和 :doc:`ULP 协处理器 ` 中使用。 +用于存放代码和数据的 :ref:` 内存区域 `有多个。代码和只读数据默认存放在 flash 中，可写数据存放在 RAM 中。不过有时，我们必须更改默认存放区域，例如为了提高性能，将关键代码存放到 RAM 中，或者将代码存放到 RTC 存储器中以便在 :doc:`唤醒桩 ` 和 ULP 协处理器中使用。 链接脚本生成机制可以让用户指定代码和数据在 ESP-IDF 组件中的存放区域。组件包含如何存放符号、目标或完整库的信息。在构建应用程序时，组件中的这些信息会被收集、解析并处理；生成的存放规则用于链接应用程序。 @@ -30,7 +30,7 @@ - 名为 ``my_component`` 的组件，在构建过程中存储为 ``libmy_component.a`` 库文件 - 库文件包含的三个源文件：``my_src1.c``、``my_src2.c`` 和 ``my_src3.c``，编译后分别为 ``my_src1.o``、``my_src2.o`` 和 ``my_src3.o``, - 在 ``my_src1.o`` 定义的 ``my_function1`` 功能；在 ``my_src2.o`` 定义的 ``my_function2`` 功能 -- 存储在 ``my_component`` 下 Kconfig 中的布尔类型配置 ``PERFORMANCE_MODE`` (y/n) 和整数类型配置 ``PERFORMANCE_LEVEL`` （范围是 0-3） +- 存储在 ``my_component`` 下 Kconfig 中的布尔类型配置 ``PERFORMANCE_MODE`` (y/n) 和整数类型配置 ``PERFORMANCE_LEVEL`` （范围是 0-3） 创建和指定链接片段文件 ^^^^^^^^^^^^^^^^^^^^^^ @@ -229,7 +229,7 @@ CMake ... - 类型：片段类型，可以为 ``段``、``协议`` 或 ``映射``。 -- 名称：片段名称，指定片段类型的片段名称应唯一。 +- 名称：片段名称，指定片段类型的片段名称应唯一。 - 键值：片段内容。每个片段类型可支持不同的键值和不同的键值语法。 .. note:: @@ -538,4 +538,4 @@ ESP-IDF v4.0 变更了链接脚本片段文件使用的一些语法： 这是根据默认协议条目 ``iram -> iram0_text`` 生成的规则。默认协议指定了 ``iram -> iram0_text`` 条目，因此生成的规则同样也放在被 ``iram0_text`` 标记的地方。由于该规则是根据默认协议生成的，因此在同一目标下收集的所有规则下排在第一位。 目前使用的链接脚本模板是 :component_file:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`，由 ``{IDF_TARGET_PATH_NAME}`` 组件指定，生成的脚本存放在构建目录下。 - + diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 5f45982d30..55f98ec1b8 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -7,7 +7,7 @@ :maxdepth: 1 ADC - DAC + :SOC_DAC_PERIPH_NUM: DAC GPIO (包括 RTC 低功耗 I/O) :SOC_DEDICATED_GPIO_SUPPORTED: 专用 GPIO :esp32s2: HMAC @@ -16,7 +16,7 @@ I2S LED Control :SOC_MCPWM_SUPPORTED: MCPWM - Pulse Counter + :SOC_PCNT_SUPPORTED: Pulse Counter Remote Control :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host SD SPI Host @@ -28,7 +28,7 @@ :esp32s2: SPI Slave 半双工 (half duplex) :esp32s2: Temp sensor Timer - Touch Sensor + :SOC_TOUCH_SENSOR_NUM: Touch Sensor TWAI UART :SOC_USB_SUPPORTED: USB diff --git a/docs/zh_CN/contribute/add-ons-reference.rst b/docs/zh_CN/contribute/add-ons-reference.rst index fbfa307847..5f433a5d12 100644 --- a/docs/zh_CN/contribute/add-ons-reference.rst +++ b/docs/zh_CN/contribute/add-ons-reference.rst @@ -144,7 +144,7 @@ CMake 项目模型运行完成后，系统将在构建初期发出 ``idf-info`` :idf_file:`docs/idf_extensions/format_idf_target.py` 通过将 idf_target 发送至 Sphinx 命令行替换 target 相关名称的扩展功能。例如： - This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` + This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` 删掉退格键后，将被渲染为 @@ -179,7 +179,7 @@ CMake 项目模型运行完成后，系统将在构建初期发出 ``idf-info`` 订阅 ``idf-defines-generated`` 事件，因为该扩展功能需要根据 Sphinx 标签来决定需排除哪些文档。 :idf_file:`docs/idf_extensions/run_doxygen.py` - 订阅 ``idf-defines-generated`` 事件，运行 Doxygen (:idf_file:`docs/Doxyfile`) 生成描述密钥头文件的 XML 文件，然后运行 Breathe 将这些文件转换为可直接被添加至 API 参考页面的 ``.inc`` 文件。 + 订阅 ``idf-defines-generated`` 事件，运行 Doxygen (:idf_file:`docs/doxygen/Doxyfile_common`) 生成描述密钥头文件的 XML 文件，然后运行 Breathe 将这些文件转换为可直接被添加至 API 参考页面的 ``.inc`` 文件。 将一些特定目标的自定义环境变量推入 Doxygen 中，包括项目的默认 ``sdkconfig.h`` 文件内定义的所有宏包以及 ``soc`` 部件 ``xxx_caps.h`` 的头文件中定义的所有宏包。这意味着，公共 API 头文件可以依赖于特定目标的配置选项或者 ``soc`` 功能头文件选项，如头文件中 ``#ifdef`` & ``#if`` 预处理器选项。