mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-10 04:43:33 +00:00
docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs
This commit is contained in:
Angus Gratton
committed by
Angus Gratton
Angus Gratton
parent
37d5e2fba6
commit
9399f04da0
@@ -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 <build-system-legacy>`, 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 <build-system-legacy>`, which was the default before ESP-IDF V4.0.
|
||||
|
||||
|
||||
Overview
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 <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 <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
|
||||
|
||||
24
docs/en/api-guides/inc/external-ram-esp32-notes.inc
Normal file
24
docs/en/api-guides/inc/external-ram-esp32-notes.inc
Normal file
@@ -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
|
||||
@@ -6,14 +6,14 @@ API Guides
|
||||
:maxdepth: 1
|
||||
|
||||
Application Level Tracing <app_trace>
|
||||
BluFi <blufi>
|
||||
:esp32: BluFi <blufi>
|
||||
Bootloader <bootloader>
|
||||
Build System <build-system>
|
||||
Build System (Legacy GNU Make) <build-system-legacy>
|
||||
:esp32: Build System (Legacy GNU Make) <build-system-legacy>
|
||||
Console Component <console>
|
||||
Deep Sleep Wake Stubs <deep-sleep-stub>
|
||||
Error Handling <error-handling>
|
||||
ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
|
||||
:esp32: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
|
||||
ESP-MESH (Wi-Fi) <mesh>
|
||||
ESP32 Core Dump <core_dump>
|
||||
Event Handling <event-handling>
|
||||
@@ -33,7 +33,7 @@ API Guides
|
||||
Thread Local Storage <thread-local-storage>
|
||||
Tools <tools/index>
|
||||
ULP Coprocessor <ulp>
|
||||
ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
|
||||
Unit Testing (Legacy GNU Make) <unit-tests-legacy>
|
||||
:esp32: ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
|
||||
Unit Testing <unit-tests>
|
||||
:esp32: Unit Testing (Legacy GNU Make) <unit-tests-legacy>
|
||||
WiFi Driver <wifi>
|
||||
|
||||
@@ -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 <get-started-configure>` menu for more details on setting compile-time options.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
-----------------------
|
||||
|
||||
Reference in New Issue
Block a user