From 9399f04da060aef29ae39bd97bd450f1c3c41c3c Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 22 Nov 2019 16:58:04 +1100 Subject: [PATCH] docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs --- docs/conf_common.py | 17 ++++- docs/en/api-guides/build-system.rst | 4 +- docs/en/api-guides/external-ram.rst | 33 ++-------- docs/en/api-guides/fatal-errors.rst | 29 ++++++--- .../inc/external-ram-esp32-notes.inc | 24 +++++++ docs/en/api-guides/index.rst | 10 +-- .../jtag-debugging/tips-and-quirks.rst | 9 ++- docs/en/api-guides/tools/idf-monitor.rst | 8 ++- docs/en/api-guides/ulp.rst | 4 +- docs/en/api-reference/index.rst | 2 +- docs/en/api-reference/peripherals/can.rst | 6 +- docs/en/api-reference/protocols/index.rst | 2 +- .../system/inc/power_management_esp32.rst | 40 ++++++++++++ .../api-reference/system/power_management.rst | 64 ++++++------------- docs/en/conf.py | 3 + docs/en/get-started/eclipse-setup.rst | 4 +- docs/en/get-started/index.rst | 2 +- docs/en/get-started/windows-setup.rst | 5 +- docs/toctree_filter.py | 43 +++++++++++++ docs/zh_CN/conf.py | 3 + 20 files changed, 213 insertions(+), 99 deletions(-) create mode 100644 docs/en/api-guides/inc/external-ram-esp32-notes.inc create mode 100644 docs/en/api-reference/system/inc/power_management_esp32.rst create mode 100644 docs/toctree_filter.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 6412dff2b..ee80513fd 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -105,6 +105,7 @@ extensions = ['breathe', 'doxygen_idf', 'sphinx.ext.todo', 'include_build_file', + 'toctree_filter', # from https://github.com/pfalcon/sphinx_selective_exclude 'sphinx_selective_exclude.eager_only', #'sphinx_selective_exclude.search_auto_exclude', @@ -168,7 +169,21 @@ print('Version: {0} Release: {1}'.format(version, release)) # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build','README.md'] +exclude_patterns = ['**/inc/**'] + +# Add target-specific excludes based on tags. Haven't found any better way to do this yet +def update_exclude_patterns(tags): + if "esp32" not in tags: + # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files + # note: in toctrees, these also need to be marked with a :esp32: filter + for e in ['api-guides/blufi.rst', + 'api-guides/build-system-legacy.rst', + 'api-guides/esp-ble-mesh/**', + 'api-guides/ulp-legacy.rst', + 'api-guides/unit-tests-legacy.rst', + 'api-reference/bluetooth/**', + 'get-started-legacy/**']: + exclude_patterns.append(e) # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 343330d2f..a99fdbb0f 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -5,7 +5,9 @@ Build System This document explains the implementation of the ESP-IDF build system and the concept of "components". Read this document if you want to know how to organise and build a new ESP-IDF project or component. -.. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make `, which was the default before ESP-IDF V4.0. +.. only:: esp32 + + .. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make `, which was the default before ESP-IDF V4.0. Overview diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index fa22c06d3..6aa14019a 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -119,36 +119,11 @@ External RAM use has the following restrictions: * When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below). * External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Any buffers that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` and can be freed using a standard ``free()`` call. * External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards. - * External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. However, for tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. + * External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. * By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`. If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time. - * When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. - - -Chip revisions -============== - -There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the ESP32 ECO_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: - - -ESP32 rev v0 ------------- -ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map. - - -ESP32 rev v1 ------------- -The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (ESP32 ECO 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. - -Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following: - -- Avoids using some ROM functions -- Allocates static memory for the WiFi stack - - -.. _ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf - - - +.. only:: esp32 + .. include:: inc/external-ram-esp32-notes.inc +.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 51f3ef903..7cac04253 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -38,21 +38,27 @@ For some of the system level checks (interrupt watchdog, cache access error), th In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes. -Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: +.. only:: esp32 -- Print registers and reboot (``CONFIG_ESP32_PANIC_PRINT_REBOOT``) — default option. + Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: + +.. only:: esp32s2 + + Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32S2_PANIC` configuration choice. The available options are: + +- Print registers and reboot — default option. This will print register values at the point of the exception, print the backtrace, and restart the chip. -- Print registers and halt (``CONFIG_ESP32_PANIC_PRINT_HALT``) +- Print registers and halt Similar to the above option, but halt instead of rebooting. External reset is required to restart the program. -- Silent reboot (``CONFIG_ESP32_PANIC_SILENT_REBOOT``) +- Silent reboot Don't print registers or backtrace, restart the chip immediately. -- Invoke GDB Stub (``CONFIG_ESP32_PANIC_GDBSTUB``) +- Invoke GDB Stub Start GDB server which can communicate with GDB over console UART port. See `GDB Stub`_ for more details. @@ -62,11 +68,11 @@ Behavior of panic handler is affected by two other configuration options. - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. -.. only:: esp32s2beta +.. only:: esp32s2 - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. -- If :doc:`Core Dump ` feature is enabled (``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` or ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` options), then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. +- If :doc:`Core Dump ` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. - If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. @@ -271,7 +277,14 @@ Other Fatal Errors Brownout ^^^^^^^^ -ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. +.. only:: esp32 + + ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. + +.. only:: esp32s2 + + ESP32-S2 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32S2_BROWNOUT_DET` and :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` options. + When brownout detector triggers, the following message is printed:: Brownout detector was triggered diff --git a/docs/en/api-guides/inc/external-ram-esp32-notes.inc b/docs/en/api-guides/inc/external-ram-esp32-notes.inc new file mode 100644 index 000000000..39a133a6a --- /dev/null +++ b/docs/en/api-guides/inc/external-ram-esp32-notes.inc @@ -0,0 +1,24 @@ +* Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. +32 +* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. + + +Chip revisions +============== + +There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the `ESP32 ECO`_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: + + +ESP32 rev v0 +------------ +ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map. + + +ESP32 rev v1 +------------ +The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 ECO`_ 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. + +Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following: + +- Avoids using some ROM functions +- Allocates static memory for the WiFi stack diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 4883d0864..bd6e61eaa 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -6,14 +6,14 @@ API Guides :maxdepth: 1 Application Level Tracing - BluFi + :esp32: BluFi Bootloader Build System - Build System (Legacy GNU Make) + :esp32: Build System (Legacy GNU Make) Console Component Deep Sleep Wake Stubs Error Handling - ESP-BLE-MESH + :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) ESP32 Core Dump Event Handling @@ -33,7 +33,7 @@ API Guides Thread Local Storage Tools ULP Coprocessor - ULP Coprocessor (Legacy GNU Make) - Unit Testing (Legacy GNU Make) + :esp32: ULP Coprocessor (Legacy GNU Make) Unit Testing + :esp32: Unit Testing (Legacy GNU Make) WiFi Driver 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 3103b0d3d..866977c5b 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -55,7 +55,14 @@ Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging which can be set at compile time: -* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. +.. only:: esp32 + + * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. + +.. only:: esp32s2 + + * :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. + * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details. Please see the :ref:`project configuration menu ` menu for more details on setting compile-time options. diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index c93b31f2f..2a5022ef0 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -103,7 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. +.. only:: esp32 + + To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. + +.. only:: esp32s2 + + To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32S2_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index ad2509e0c..5de0e49f9 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -20,7 +20,9 @@ The ULP coprocessor code is written in assembly and compiled using the `binutils If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then the ULP toolchain will already be installed. -If you are using ESP-IDF with the legacy GNU Make based build system, refer to the instructions on this page: :doc:`ulp-legacy`. +.. only:: esp32 + + If you are using ESP-IDF with the legacy GNU Make based build system, refer to the instructions on this page: :doc:`ulp-legacy`. Compiling the ULP Code ----------------------- diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 92e57f8cc..6ee0b74e7 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -6,7 +6,7 @@ API Reference .. toctree:: :maxdepth: 2 - Bluetooth + :esp32: Bluetooth Networking Peripherals Protocols diff --git a/docs/en/api-reference/peripherals/can.rst b/docs/en/api-reference/peripherals/can.rst index 944ee4b12..d6d986722 100644 --- a/docs/en/api-reference/peripherals/can.rst +++ b/docs/en/api-reference/peripherals/can.rst @@ -168,7 +168,11 @@ The operating bit rate of the CAN controller is configured using the :cpp:type:` 2. **Timing Segment 1** consists of 1 to 16 time quanta before sample point 3. **Timing Segment 2** consists of 1 to 8 time quanta after sample point -The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**. If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher. +The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**. + +.. only:: esp32 + + If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher. .. packetdiag:: ../../../_static/diagrams/can/can_bit_timing.diag :caption: Bit timing configuration for 500kbit/s given BRP = 8 diff --git a/docs/en/api-reference/protocols/index.rst b/docs/en/api-reference/protocols/index.rst index ded1cbbae..2fe021859 100644 --- a/docs/en/api-reference/protocols/index.rst +++ b/docs/en/api-reference/protocols/index.rst @@ -16,7 +16,7 @@ Application Protocols mDNS Modbus Websocket Client - ESP Serial Slave Link + :esp32: ESP Serial Slave Link Code examples for this API section are provided in the :example:`protocols` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/system/inc/power_management_esp32.rst b/docs/en/api-reference/system/inc/power_management_esp32.rst new file mode 100644 index 000000000..14177485e --- /dev/null +++ b/docs/en/api-reference/system/inc/power_management_esp32.rst @@ -0,0 +1,40 @@ +ESP32 Power Management Algorithm +-------------------------------- + +The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. + + ++---------------+---------------------------------------+-------------------------------------+ +| Max CPU | Lock Acquisition | CPU and APB Frequncies | +| Frequency Set | | | ++---------------+---------------------------------------+-------------------------------------+ +| 240 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | +| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | CPU: 240 MHz | +| | | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ +| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz | +| | | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | ``ESP_PM_CPU_FREQ_MAX`` acquired, | | CPU: 80 MHz | +| | ``ESP_PM_APB_FREQ_MAX`` not acquired | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ +| 80 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz | +| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ + + +If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by: + +- FreeRTOS tasks blocked with finite timeouts +- Timers registered with :doc:`High resolution timer ` APIs + +Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses). diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index a6e35bd91..49acb39f8 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -27,7 +27,7 @@ Enabling power management features comes at the cost of increased interrupt late Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function :cpp:func:`esp_pm_configure`. Its argument is a structure defining the frequency scaling settings, :cpp:class:`esp_pm_config_esp32_t`. In this structure, three fields need to be initialized: -- ``max_freq_mhz``: Maximum CPU frequency in MHz, i.e., the frequency used when the ``ESP_PM_CPU_FREQ_MAX`` lock is acquired. This field will usually be set to :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. +- ``max_freq_mhz``: Maximum CPU frequency in MHz, i.e., the frequency used when the ``ESP_PM_CPU_FREQ_MAX`` lock is acquired. This field will usually be set to the default CPU frequency. - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated. - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``). @@ -68,46 +68,9 @@ Lock Description ============================ ====================================================== -ESP32 Power Management Algorithm --------------------------------- +.. only:: esp32 -The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. - - -+---------------+---------------------------------------+-------------------------------------+ -| Max CPU | Lock Acquisition | CPU and APB Frequncies | -| Frequency Set | | | -+---------------+---------------------------------------+-------------------------------------+ -| 240 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | -| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | CPU: 240 MHz | -| | | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ -| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz | -| | | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | ``ESP_PM_CPU_FREQ_MAX`` acquired, | | CPU: 80 MHz | -| | ``ESP_PM_APB_FREQ_MAX`` not acquired | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ -| 80 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz | -| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ - - -If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by: - -- FreeRTOS tasks blocked with finite timeouts -- Timers registered with :doc:`High resolution timer ` APIs - -Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses). + .. include:: inc/power_management_esp32.rst Dynamic Frequency Scaling and Peripheral Drivers @@ -133,15 +96,26 @@ The following drivers will hold the ``ESP_PM_APB_FREQ_MAX`` lock while the drive - **SPI slave**: between calls to :cpp:func:`spi_slave_initialize` and :cpp:func:`spi_slave_free`. - **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`. - **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled. -- **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal". - **CAN**: between calls to :cpp:func:`can_driver_install` and :cpp:func:`can_driver_uninstall`. +.. only:: esp32 + + - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal". + The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary: -- MCPWM -- PCNT -- Sigma-delta -- Timer group +.. only:: esp32 + + - PCNT + - Sigma-delta + - Timer group + - MCPWM + +.. only:: esp32s2 + + - PCNT + - Sigma-delta + - Timer group API Reference diff --git a/docs/en/conf.py b/docs/en/conf.py index 0713b97f1..68bcf8766 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -31,3 +31,6 @@ actdiag_fontpath = '../_static/DejaVuSans.ttf' nwdiag_fontpath = '../_static/DejaVuSans.ttf' rackdiag_fontpath = '../_static/DejaVuSans.ttf' packetdiag_fontpath = '../_static/DejaVuSans.ttf' + +update_exclude_patterns(tags) + diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst index f6a499561..0d9107be6 100644 --- a/docs/en/get-started/eclipse-setup.rst +++ b/docs/en/get-started/eclipse-setup.rst @@ -7,4 +7,6 @@ ESP-IDF V4.0 has a new CMake-based build system as the default build system. There is a new ESP-IDF Eclipse Plugin that works with the CMake-based build system. Please refer to https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md for further instructions. -If you require Eclipse IDE support for legacy ESP_IDF Make build system, you can follow the :doc:`legacy GNU Make build system Getting Started guide ` which has steps for :doc:`Building and Flashing with Eclipse IDE `. +.. only:: esp32 + + If you require Eclipse IDE support for legacy ESP_IDF Make build system, you can follow the :doc:`legacy GNU Make build system Getting Started guide ` which has steps for :doc:`Building and Flashing with Eclipse IDE `. diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index cb346d606..23f04922a 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -515,7 +515,7 @@ Related Documents eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch - ../get-started-legacy/index + :esp32: ../get-started-legacy/index .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ .. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index ccf983ae9..6593bde3b 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -16,8 +16,9 @@ ESP-IDF requires some prerequisite tools to be installed so you can build firmwa For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. -.. note:: - Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt. +.. only:: esp32 + .. note:: + Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt. .. _get-started-windows-tools-installer: diff --git a/docs/toctree_filter.py b/docs/toctree_filter.py new file mode 100644 index 000000000..be58a8c0f --- /dev/null +++ b/docs/toctree_filter.py @@ -0,0 +1,43 @@ +# Based on https://stackoverflow.com/a/46600038 with some modifications +import re +from sphinx.directives.other import TocTree +from sphinx.util.nodes import explicit_title_re +from sphinx.util import docname_join + +def setup(app): + app.add_directive('toctree', TocTreeFilt, override=True) + + +class TocTreeFilt(TocTree): + """ + Override normal toctree directive to support clauses of the kind + + :filter: Name + + Where the :filter: part becomes selective to only include the document if + one of the provided tags is set, same as the logic used by the "only" directive. + + If no :filter: is supplied, works the same as default Sphinx :toctree: + + Note that excluding via filter doesn't prevent Sphinx from finding these .rst files + when it scan the src/ directory, so it's also necessary to make sure that the files + are covered by the exclude_patterns list in conf.py + """ + RE_PATTERN = re.compile('^\s*:(.+):\s*(.+)$') + + + def run(self): + # Remove all TOC entries that should not be on display + env = self.state.document.settings.env + self.content = [ self.filter_entry(env, e) for e in self.content if e is not None ] + return super(TocTreeFilt, self).run() + + + def filter_entry(self, env, entry): + m = self.RE_PATTERN.match(entry) + if m is not None: + tag_filter, entry = m.groups() + if not env.app.builder.tags.eval_condition(tag_filter): + return None + return entry + diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 0f7c85199..49c89ee99 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -31,3 +31,6 @@ actdiag_fontpath = '../_static/NotoSansSC-Regular.otf' nwdiag_fontpath = '../_static/NotoSansSC-Regular.otf' rackdiag_fontpath = '../_static/NotoSansSC-Regular.otf' packetdiag_fontpath = '../_static/NotoSansSC-Regular.otf' + +update_exclude_patterns(tags) +