diff --git a/components/log/README.rst b/components/log/README.rst index 034c32d79..03ca5f0da 100644 --- a/components/log/README.rst +++ b/components/log/README.rst @@ -8,11 +8,11 @@ Log library has two ways of managing log verbosity: compile time, set via menuco The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity). -At compile time, filtering is done using :ref:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :ref:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor. +At compile time, filtering is done using :envvar:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :envvar:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor. -At run time, all logs below :ref:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. :cpp:func:`esp_log_level_set` function may be used to reduce logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings. +At run time, all logs below :envvar:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. :cpp:func:`esp_log_level_set` function may be used to reduce logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings. -Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :ref:`CONFIG_LOG_DEFAULT_LEVEL`. To increase log level for a specific file at compile time, `LOG_LOCAL_LEVEL` macro can be used (see below for details). +Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :envvar:`CONFIG_LOG_DEFAULT_LEVEL`. To increase log level for a specific file at compile time, `LOG_LOCAL_LEVEL` macro can be used (see below for details). How to use this library ----------------------- diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index ef4cb1f82..807b592d2 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -36,7 +36,7 @@ image header, flashed at offset 0x1000. By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting -:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +:envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. If it is necessary to override the configured flash size at runtime, is is possible to set the ``chip_size`` member of ``g_rom_flashchip`` structure. This diff --git a/components/vfs/README.rst b/components/vfs/README.rst index 36af5c388..e7e50fd67 100644 --- a/components/vfs/README.rst +++ b/components/vfs/README.rst @@ -94,7 +94,7 @@ are the :example:`peripherals/uart_select` and the :example:`system/select` examples. If :cpp:func:`select` is used for socket file descriptors only then one can -enable the :ref:`CONFIG_USE_ONLY_LWIP_SELECT` option which can reduce the code +enable the :envvar:`CONFIG_USE_ONLY_LWIP_SELECT` option which can reduce the code size and improve performance. Paths diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst index 53ff5b295..68f8c74c4 100644 --- a/docs/en/api-guides/app_trace.rst +++ b/docs/en/api-guides/app_trace.rst @@ -30,7 +30,7 @@ The library supports two modes of operation: **Post-mortem mode**. This is the default mode. The mode does not need interaction from the host side. In this mode tracing module does not check whether host has read all the data from *HW UP BUFFER* buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing program's behaviour just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface. -**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_ESP32_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. +**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :envvar:`CONFIG_ESP32_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. Configuration Options and Dependencies @@ -47,8 +47,8 @@ Using of this feature depends on two components: There are two additional menuconfig options not mentioned above: -1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_THRESH`). This option is necessary due to the nature of working over JTAG. In that mode trace data are exposed to the host in 16KB blocks. In post-mortem mode when one block is filled it is exposed to the host and the previous one becomes unavailable. In other words trace data are overwritten in 16KB granularity. On panic the latest data from the current input block are exposed to host and host can read them for post-analysis. It can happen that system panic occurs when there are very small amount of data which are not exposed to the host yet. In this case the previous 16KB of collected data will be lost and host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of panic. For example user can decide that it needs not less then 512 bytes of the recent trace data, so if there is less then 512 bytes of pending data at the moment of panic they will not be flushed and will not overwrite previous 16KB. The option is only meaningful in post-mortem mode and when working over JTAG. -2. *Timeout for flushing last trace data to host on panic* (:ref:`CONFIG_ESP32_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and controls the maximum time tracing module will wait for the host to read the last data in case of panic. +1. *Threshold for flushing last trace data to host on panic* (:envvar:`CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_THRESH`). This option is necessary due to the nature of working over JTAG. In that mode trace data are exposed to the host in 16KB blocks. In post-mortem mode when one block is filled it is exposed to the host and the previous one becomes unavailable. In other words trace data are overwritten in 16KB granularity. On panic the latest data from the current input block are exposed to host and host can read them for post-analysis. It can happen that system panic occurs when there are very small amount of data which are not exposed to the host yet. In this case the previous 16KB of collected data will be lost and host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of panic. For example user can decide that it needs not less then 512 bytes of the recent trace data, so if there is less then 512 bytes of pending data at the moment of panic they will not be flushed and will not overwrite previous 16KB. The option is only meaningful in post-mortem mode and when working over JTAG. +2. *Timeout for flushing last trace data to host on panic* (:envvar:`CONFIG_ESP32_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and controls the maximum time tracing module will wait for the host to read the last data in case of panic. How to use this library @@ -323,9 +323,9 @@ Another useful IDF feature built on top of application tracing library is the sy How To Use It """"""""""""" -Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:ref:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu: +Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:envvar:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu: -1. *ESP32 timer to use as SystemView timestamp source* (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40Mhz is used, so timestamp granularity is 25 ns. +1. *ESP32 timer to use as SystemView timestamp source* (:envvar:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40Mhz is used, so timestamp granularity is 25 ns. 2. Individually enabled or disabled collection of SystemView events (``CONFIG_SYSVIEW_EVT_XXX``): - Trace Buffer Overflow Event diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 6e5efbcc0..0c04a646d 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -13,22 +13,22 @@ FACTORY reset --------------------------- The user can write a basic working firmware and load it into the factory partition. Next, update the firmware via OTA (over the air). The updated firmware will be loaded into an OTA app partition slot and the OTA data partition is updated to boot from this partition. -If you want to be able to roll back to the factory firmware and clear the settings, then you need to set :ref:`CONFIG_BOOTLOADER_FACTORY_RESET`. +If you want to be able to roll back to the factory firmware and clear the settings, then you need to set :envvar:`CONFIG_BOOTLOADER_FACTORY_RESET`. The factory reset mechanism allows to reset the device to factory settings: - Clear one or more data partitions. - Boot from "factory" partition. -:ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` allows customers to select which data partitions will be erased when the factory reset is executed. +:envvar:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` allows customers to select which data partitions will be erased when the factory reset is executed. Can specify the names of partitions through comma-delimited with optional spaces for readability. (Like this: "nvs, phy_init, nvs_custom, ..."). Make sure that the name specified in the partition table and here are the same. Partitions of type "app" cannot be specified here. -:ref:`CONFIG_BOOTLOADER_OTA_DATA_ERASE` - the device will boot from "factory" partition after a factory reset. The OTA data partition will be cleared. +:envvar:`CONFIG_BOOTLOADER_OTA_DATA_ERASE` - the device will boot from "factory" partition after a factory reset. The OTA data partition will be cleared. -:ref:`CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET`- number of the GPIO input for factory reset uses to trigger a factory reset, this GPIO must be pulled low on reset to trigger this. +:envvar:`CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET`- number of the GPIO input for factory reset uses to trigger a factory reset, this GPIO must be pulled low on reset to trigger this. -:ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO`- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed. +:envvar:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO`- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed. Partition table.:: @@ -45,12 +45,12 @@ Partition table.:: Boot from TEST firmware ------------------------ The user can write a special firmware for testing in production, and run it as needed. The partition table also needs a dedicated partition for this testing firmware (See `partition table`). -To trigger a test app you need to set :ref:`CONFIG_BOOTLOADER_APP_TEST`. +To trigger a test app you need to set :envvar:`CONFIG_BOOTLOADER_APP_TEST`. -:ref:`CONFIG_BOOTLOADER_NUM_PIN_APP_TEST` - number of the GPIO input to boot TEST partition. The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset. +:envvar:`CONFIG_BOOTLOADER_NUM_PIN_APP_TEST` - number of the GPIO input to boot TEST partition. The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset. After the GPIO input is deactivated and the device reboots, the old application will boot (factory or any OTA slot). -:ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO` - this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed. +:envvar:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO` - this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed. Customer bootloader --------------------- diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 52704365d..15438072b 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -65,7 +65,7 @@ The use of external RAM has a few restrictions: execution of code afterwards slower. * External RAM cannot be used as task stack memory; because of this, xTaskCreate and similar functions will always allocate internal memory for stack and task TCBs and xTaskCreateStatic-type functions 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 + on code in ROM in any way, directly or indirectly, the menuconfig option :envvar:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing task stack in external RAM. Using this is not advised, however. @@ -91,7 +91,7 @@ The bugs in this silicon revision introduce a hazard when certain sequences of m To work around this, the gcc compiler to compile ESP-IDF has been expanded with a flag: ``-mfix-esp32-psram-cache-issue``. With this flag passed to gcc on the command line, the compiler works around these sequences and only outputs code that can safely be executed. -In ESP-IDF, this flag is enabled when you select :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. ESP-IDF also takes other measures to make +In ESP-IDF, this flag is enabled when you select :envvar:`CONFIG_SPIRAM_CACHE_WORKAROUND`. ESP-IDF also takes other measures to make sure no combination of PSRAM access plus the offending instruction sets are used: it links to a version of Newlib recompiled with the gcc flag, doesn't use some ROM functions and allocates static memory for the WiFi stack. diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index 40665d9c5..c2f72f5f6 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -89,7 +89,7 @@ Static Alocation ^^^^^^^^^^^^^^^^^ This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The -:ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` option must be enabled in `menuconfig` +:envvar:`CONFIG_SUPPORT_STATIC_ALLOCATION` option must be enabled in `menuconfig` in order for static allocation functions to be available. Once enabled, the following functions can be called... @@ -462,7 +462,7 @@ called for that TLSP during task deletion. If a deletion callback is `NULL`, users should manually free the memory pointed to by the associated TLSP before task deletion in order to avoid memory leak. -:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used +:envvar:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used to configure the number TLSP and Deletion Callbacks a TCB will have. For more details see :doc:`FreeRTOS API reference<../api-reference/system/freertos>`. @@ -478,21 +478,21 @@ The ESP-IDF FreeRTOS can be configured using ``make menuconfig`` under ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` -:ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only +:envvar:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on **PRO_CPU**. Note that this is **not equivalent to running vanilla FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such as :component_file:`esp32/cpu_start.c`. For more details regarding the effects of running ESP-IDF FreeRTOS on a single core, search for occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. -:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the +:envvar:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the number of Thread Local Storage Pointers each task will have in ESP-IDF FreeRTOS. -:ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported +:envvar:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS -:ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in +:envvar:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in particular functions in ESP-IDF FreeRTOS which have not been fully tested in an SMP context. 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 bc81dbd6f..e35fdb7b0 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -9,7 +9,7 @@ This section provides collection of all tips and quirks referred to from various Breakpoints and watchpoints available ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ESP32 supports 2 hardware breakpoints. It also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description. +The ESP32 supports 2 hardware breakpoints. It also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :envvar:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description. .. _jtag-debugging-tip-where-breakpoints: @@ -35,8 +35,8 @@ 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. -* :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. +* :envvar:`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. +* :envvar:`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:`make menuconfig ` menu for more details on setting compile-time options. diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 2893dbcaa..6363f58f8 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -107,7 +107,7 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space. - - To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. + - To load PHY data from this partition, run ``make menuconfig`` and enable :envvar:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. - NVS is used to store per-device PHY calibration data (different to initialisation data). @@ -153,7 +153,7 @@ MD5 checksum The binary format of the partition table contains an MD5 checksum computed based on the partition table. This checksum is used for checking the integrity of the partition table during the boot. -The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :ref:`CONFIG_PARTITION_TABLE_MD5` option. This is useful for example when one uses a legacy bootloader which cannot process MD5 checksums and the boot fails with the error message ``invalid magic number 0xebeb``. +The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :envvar:`CONFIG_PARTITION_TABLE_MD5` option. This is useful for example when one uses a legacy bootloader which cannot process MD5 checksums and the boot fails with the error message ``invalid magic number 0xebeb``. Flashing the partition table ---------------------------- diff --git a/docs/en/api-reference/storage/spi_flash.rst b/docs/en/api-reference/storage/spi_flash.rst index 1dbb92bdd..07f3a3e9b 100644 --- a/docs/en/api-reference/storage/spi_flash.rst +++ b/docs/en/api-reference/storage/spi_flash.rst @@ -40,7 +40,7 @@ CPU A as well and returns control to the calling code. Additionally, all API functions are protected with a mutex (s_flash_op_mutex). -In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), we simply +In a single core environment (:envvar:`CONFIG_FREERTOS_UNICORE` enabled), we simply disable both caches, no inter-CPU communication takes place. API Reference - SPI Flash diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 57d25e9a7..24e47a390 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -374,8 +374,8 @@ defined Idle Hook and Tick Hook on every iteration of the Idle Task and Tick Interrupt respectively. Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS. -To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS`, -:ref:`CONFIG_FREERTOS_LEGACY_IDLE_HOOK`, and :ref:`CONFIG_FREERTOS_LEGACY_TICK_HOOK` +To enable legacy hooks, :envvar:`CONFIG_FREERTOS_LEGACY_HOOKS`, +:envvar:`CONFIG_FREERTOS_LEGACY_IDLE_HOOK`, and :envvar:`CONFIG_FREERTOS_LEGACY_TICK_HOOK` should all be enabled in ``make menuconfig``. Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()`` diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index 72052b3b3..7769d1cf6 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -62,7 +62,7 @@ Configuration Temporarily increasing the heap corruption detection level can give more detailed information about heap corruption errors. -In ``make menuconfig``, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: +In ``make menuconfig``, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :envvar:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: Basic (no poisoning) ++++++++++++++++++++ @@ -140,7 +140,7 @@ If you suspect a memory leak, the first step is to figure out which part of the Once you've identified the code which you think is leaking: -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` and set :ref:`CONFIG_HEAP_TRACING`. +- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` and set :envvar:`CONFIG_HEAP_TRACING`. - Call the function :cpp:func:`heap_trace_init_standalone` early in the program, to register a buffer which can be used to record the memory trace. - Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. - Call the function :cpp:func:`heap_trace_stop` to stop the trace once the suspect piece of code has finished executing. diff --git a/docs/en/api-reference/system/ipc.rst b/docs/en/api-reference/system/ipc.rst index 37d416145..a6a1106a1 100644 --- a/docs/en/api-reference/system/ipc.rst +++ b/docs/en/api-reference/system/ipc.rst @@ -29,7 +29,7 @@ until the IPC Task has completed execution of the given function. Functions executed by IPCs must be functions of type `void func(void *arg)`. To run more complex functions which require a larger stack, the IPC tasks' stack size can be configured by modifying -:ref:`CONFIG_IPC_TASK_STACK_SIZE` in `menuconfig`. The IPC API is protected by a +:envvar:`CONFIG_IPC_TASK_STACK_SIZE` in `menuconfig`. The IPC API is protected by a mutex hence simultaneous IPC calls are not possible. Care should taken to avoid deadlock when writing functions to be executed by diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index 9ad1e16a9..80fcda64b 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -16,15 +16,15 @@ Naturally, requesting higher APB or CPU frequency or disabling light sleep cause Configuration ------------- -Power management can be enabled at compile time, using :ref:`CONFIG_PM_ENABLE` option. +Power management can be enabled at compile time, using :envvar:`CONFIG_PM_ENABLE` option. Enabling power management features comes at the cost of increased interrupt latency. Extra latency depends on a number of factors, among which are CPU frequency, single/dual core mode, whether frequency switch needs to be performed or not. Minimal extra latency is 0.2us (when CPU frequency is 240MHz, and frequency scaling is not enabled), maximum extra latency is 40us (when frequency scaling is enabled, and a switch from 40MHz to 80MHz is performed on interrupt entry). -Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in the application by calling :cpp:func:`esp_pm_configure` function. Its argument is a structure defining frequency scaling settings (for ESP32, minimum and maximum CPU frequencies). Alternatively, :ref:`CONFIG_PM_DFS_INIT_AUTO` option can be enabled in menuconfig. If enabled, maximal CPU frequency is determined by :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and minimal CPU frequency is set to the XTAL frequency. +Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in the application by calling :cpp:func:`esp_pm_configure` function. Its argument is a structure defining frequency scaling settings (for ESP32, minimum and maximum CPU frequencies). Alternatively, :envvar:`CONFIG_PM_DFS_INIT_AUTO` option can be enabled in menuconfig. If enabled, maximal CPU frequency is determined by :envvar:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and minimal CPU frequency is set to the XTAL frequency. .. note:: - Automatic light sleep is based on FreeRTOS Tickless Idle functionality. :cpp:func:`esp_pm_configure` will return an `ESP_ERR_NOT_SUPPORTED` error if :ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE` option is not enabled in menuconfig, but automatic light sleep is requested. + Automatic light sleep is based on FreeRTOS Tickless Idle functionality. :cpp:func:`esp_pm_configure` will return an `ESP_ERR_NOT_SUPPORTED` error if :envvar:`CONFIG_FREERTOS_USE_TICKLESS_IDLE` option is not enabled in menuconfig, but automatic light sleep is requested. .. note:: @@ -54,7 +54,7 @@ Power Management Algorithm for the ESP32 When dynamic frequency scaling is enabled, CPU frequency will be switched as follows: -- If maximal CPU frequency (set using :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`) is 240 MHz: +- If maximal CPU frequency (set using :cpp:func:`esp_pm_configure` or :envvar:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`) is 240 MHz: 1. When ``ESP_PM_CPU_FREQ_MAX`` or ``ESP_PM_APB_FREQ_MAX`` locks are acquired, CPU frequency will be 240 MHz, and APB frequency will be 80 MHz. diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index adfa49693..e790a5df4 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -61,10 +61,10 @@ longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed form the TWDT, the TWDT can be deinitialized by calling :cpp:func:`esp_task_wdt_deinit()`. -By default :ref:`CONFIG_TASK_WDT` in ``make menuconfig`` will be enabled causing +By default :envvar:`CONFIG_TASK_WDT` in ``make menuconfig`` will be enabled causing the TWDT to be initialized automatically during startup. Likewise -:ref:`CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU0` and -:ref:`CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing +:envvar:`CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU0` and +:envvar:`CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing the two Idle Tasks to be subscribed to the TWDT during startup. JTAG and watchdogs diff --git a/docs/en/get-started/idf-monitor.rst b/docs/en/get-started/idf-monitor.rst index 09291a3d3..600bec970 100644 --- a/docs/en/get-started/idf-monitor.rst +++ b/docs/en/get-started/idf-monitor.rst @@ -67,7 +67,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required. -To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. +To enable the gdbstub, run ``make menuconfig`` and set :envvar:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.) diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 9e33e6349..0cbbe2c28 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -286,7 +286,7 @@ To exit the monitor use shortcut ``Ctrl+]``. e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. + or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :envvar:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application. diff --git a/docs/gen-kconfig-doc.py b/docs/gen-kconfig-doc.py index a14164119..7e552b5c3 100755 --- a/docs/gen-kconfig-doc.py +++ b/docs/gen-kconfig-doc.py @@ -8,7 +8,7 @@ # as ReST markup. # For each option in Kconfig file (e.g. 'FOO'), CONFIG_FOO link target is # generated, allowing options to be referenced in other documents -# (using :ref:`CONFIG_FOO`) +# (using :envvar:`CONFIG_FOO`) # # This script uses kconfiglib library to do all the work of parsing Kconfig # files: https://github.com/ulfalizer/Kconfiglib @@ -42,10 +42,12 @@ INITIAL_HEADING_LEVEL = 2 MAX_HEADING_LEVEL = 5 OPTION_HEADING_LEVEL = 6 - -def print_menu_contents(title, items, heading_level, breadcrumbs): - if title: - print_section_heading(title, heading_level) +def print_menu_contents(title, items, heading_level, breadcrumbs, genindex): + if not genindex: + if title: + print_section_heading(title, heading_level) + if heading_level == INITIAL_HEADING_LEVEL+1: + print_menu_contents(title, items, heading_level, breadcrumbs, True) for entry in items: if entry.is_menu(): if len(breadcrumbs) > 0: @@ -55,7 +57,9 @@ def print_menu_contents(title, items, heading_level, breadcrumbs): print_menu_contents(entry.get_title(), entry.get_items(), min(heading_level + 1, MAX_HEADING_LEVEL), - new_breadcrumbs) + new_breadcrumbs, genindex) + elif genindex: + print_item(entry, breadcrumbs) elif entry.is_choice(): print_choice(entry, breadcrumbs) else: @@ -71,7 +75,7 @@ def print_menu_contents(title, items, heading_level, breadcrumbs): def print_choice(choice, breadcrumbs): print_option(choice, breadcrumbs) print - print '%sAvailable options:' % INDENT + print '%sAvailable options' % INDENT for opt in choice.get_symbols(): # Format available options as a list print '%s- %s' % (INDENT * 2, opt.name) @@ -82,25 +86,28 @@ def print_section_heading(title, heading_level): print def print_option(opt, breadcrumbs): - # add link target so we can use :ref:`CONFIG_FOO` - print '.. _CONFIG_%s:' % opt.name + # add link target so we can use :envvar:`CONFIG_FOO` + print '.. envvar:: CONFIG_%s' % opt.name print - print_section_heading(opt.name, OPTION_HEADING_LEVEL) if len(opt.prompts) > 0: print '%s%s' % (INDENT, opt.prompts[0][0]) print - print '%s:emphasis:`Found in: %s`' % (INDENT, breadcrumbs) - print if opt.get_help() is not None: # Help text normally contains newlines, but spaces at the beginning of # each line are stripped by kconfiglib. We need to re-indent the text # to produce valid ReST. print '%s%s' % (INDENT, opt.get_help().replace('\n', '\n%s' % INDENT)) + print '%sFound in\n%s' % (INDENT, INDENT * 2 + breadcrumbs) + print + +def print_item(opt, breadcrumbs): + print '- :envvar:`CONFIG_%s`' % opt.name + print def process_kconfig_file(kconfig_file, heading_level, breadcrumbs): if os.path.exists(kconfig_file): cfg = kconfiglib.Config(kconfig_file, print_warnings=True) - print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs) + print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs, False) def print_all_components(): heading_level = INITIAL_HEADING_LEVEL diff --git a/docs/zh_CN/get-started/idf-monitor.rst b/docs/zh_CN/get-started/idf-monitor.rst index a5b30e2d0..5d3299d50 100644 --- a/docs/zh_CN/get-started/idf-monitor.rst +++ b/docs/zh_CN/get-started/idf-monitor.rst @@ -65,7 +65,7 @@ IDF Monitor 为转储补充如下信息:: 您可以选择配置 panic 处理函数，使其运行串行的 "gdb stub"。该程序可以与 gdb 调试器通信，提供内存，变量，栈帧读取的功能。虽然这不像 JTAG 调试那样通用，但您不需要使用特殊硬件。 -要启用 gdbstub，运行 ``make menuconfig`` 并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 +要启用 gdbstub，运行 ``make menuconfig`` 并将 :envvar:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 如果启用此选项并且 IDF Monitor 发现 gdbstub 已加载，它将自动暂停串口监控并使用正确的参数运行 GDB。GDB 退出后，电路板将通过 RTS 串行线路复位（如果已连接）。 diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 8831d86fd..ba7aa5a7b 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -279,7 +279,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - 或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器，回到 :ref:`配置 `，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编译和烧写 `。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。 + 或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器，回到 :ref:`配置 `，将 :envvar:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编译和烧写 `。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。 要一次性执行 ``make flash`` 和 ``make monitor``，输入 ``make flash monitor``。参考文档 :doc:`IDF Monitor ` 里的快捷键和更多内容。