From 3c8cccc73bfd156ec5f2046a9ee9a7467e2d4120 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Thu, 7 Dec 2023 17:59:44 +0800 Subject: [PATCH] change(docs): Update multicore tags to SOC_HP_CPU_HAS_MULTIPLE_CORES Previously, documentation sections that were only meant for multicore ESP targets would use tags that depend on CONFIG_FREERTOS_UNICORE. This is not ideal as project configuration can be changed by the user. This commit updates those tags to use SOC_HP_CPU_HAS_MULTIPLE_CORES which is always defined in multicore targets regardless of project configuration. --- docs/en/api-guides/app_trace.rst | 4 ++-- docs/en/api-guides/performance/speed.rst | 12 ++++++------ docs/en/api-guides/startup.rst | 16 ++++++++-------- .../spi_flash/spi_flash_concurrency.rst | 4 ++-- docs/en/api-reference/system/freertos.rst | 2 +- docs/en/api-reference/system/index.rst | 2 +- docs/en/api-reference/system/intr_alloc.rst | 2 +- docs/en/api-reference/system/pthread.rst | 2 +- docs/en/api-reference/system/wdts.rst | 2 +- docs/zh_CN/api-guides/app_trace.rst | 4 ++-- docs/zh_CN/api-guides/performance/speed.rst | 12 ++++++------ docs/zh_CN/api-guides/startup.rst | 16 ++++++++-------- .../spi_flash/spi_flash_concurrency.rst | 4 ++-- docs/zh_CN/api-reference/system/freertos.rst | 2 +- docs/zh_CN/api-reference/system/intr_alloc.rst | 2 +- docs/zh_CN/api-reference/system/pthread.rst | 2 +- docs/zh_CN/api-reference/system/wdts.rst | 2 +- 17 files changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst index 90ee9efd4f0..1507f0d8d73 100644 --- a/docs/en/api-guides/app_trace.rst +++ b/docs/en/api-guides/app_trace.rst @@ -420,7 +420,7 @@ Data Visualization After trace data are collected, users can use a special tool to visualize the results and inspect behavior of the program. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES Unfortunately, SystemView does not support tracing from multiple cores. So when tracing from {IDF_TARGET_NAME} with JTAG interfaces in the dual-core mode, two files are generated: one for PRO CPU and another for APP CPU. Users can load each file into separate instances of the tool. For tracing over UART, users can select ``Component config`` > ``Application Level Tracing`` > ``FreeRTOS SystemView Tracing`` in menuconfig Pro or App to choose which CPU has to be traced. @@ -432,7 +432,7 @@ Good instructions on how to install, configure, and visualize data in Impulse fr ESP-IDF uses its own mapping for SystemView FreeRTOS events IDs, so users need to replace the original file mapping ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` with ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``. Also, contents of that ESP-IDF-specific file should be used when configuring SystemView serializer using the above link. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES Configure Impulse for Dual Core Traces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/en/api-guides/performance/speed.rst b/docs/en/api-guides/performance/speed.rst index 23eed563dee..03c067c2481 100644 --- a/docs/en/api-guides/performance/speed.rst +++ b/docs/en/api-guides/performance/speed.rst @@ -54,7 +54,7 @@ Executing the target multiple times can help average out factors, e.g., RTOS con - It is also possible to use the standard Unix ``gettimeofday()`` and ``utime()`` functions, although the overhead is slightly higher. - Otherwise, including ``hal/cpu_hal.h`` and calling the HAL function ``cpu_hal_get_cycle_count()`` returns the number of CPU cycles executed. This function has lower overhead than the others, which is good for measuring very short execution times with high precision. - .. only:: not CONFIG_FREERTOS_UNICORE + .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES The CPU cycles are counted per-core, so only use this method from an interrupt handler, or a task that is pinned to a single core. @@ -159,7 +159,7 @@ Common priorities are: .. Note: the following two lists should be kept the same, but the second list also shows CPU affinities -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES .. list:: @@ -176,7 +176,7 @@ Common priorities are: - If using the :doc:`/api-reference/protocols/mqtt` component, it creates a task with default priority 5 (:ref:`configurable`), depending on :ref:`CONFIG_MQTT_USE_CUSTOM_CONFIG`, and also configurable at runtime by ``task_prio`` field in the :cpp:class:`esp_mqtt_client_config_t`) - To see what is the task priority for ``mDNS`` service, please check `Performance Optimization `__. -.. only :: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES .. list:: @@ -204,11 +204,11 @@ Common priorities are: Choosing Task Priorities of the Application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES In general, it is not recommended to set task priorities higher than the built-in {IDF_TARGET_RF_TYPE} operations as starving them of CPU may make the system unstable. For very short timing-critical operations that do not use the network, use an ISR or a very restricted task (with very short bursts of runtime only) at the highest priority (24). Choosing priority 19 allows lower-layer {IDF_TARGET_RF_TYPE} functionality to run without delays, but still preempts the lwIP TCP/IP stack and other less time-critical internal functionality - this is the best option for time-critical tasks that do not perform network operations. Any task that does TCP/IP network operations should run at a lower priority than the lwIP TCP/IP task (18) to avoid priority-inversion issues. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES With a few exceptions, most importantly the lwIP TCP/IP task, in the default configuration most built-in tasks are pinned to Core 0. This makes it quite easy for the application to place high priority tasks on Core 1. Using priority 19 or higher guarantees that an application task can run on Core 1 without being preempted by any built-in task. To further isolate the tasks running on each CPU, configure the :ref:`lwIP task ` to only run on Core 0 instead of either core, which may reduce total TCP/IP throughput depending on what other tasks are running. @@ -234,7 +234,7 @@ To obtain the best performance for a particular interrupt handler: .. list:: - Assign more important interrupts a higher priority using a flag such as ``ESP_INTR_FLAG_LEVEL2`` or ``ESP_INTR_FLAG_LEVEL3`` when calling :cpp:func:`esp_intr_alloc`. - :not CONFIG_FREERTOS_UNICORE: - Assign the interrupt on a CPU where built-in {IDF_TARGET_RF_TYPE} tasks are not configured to run, which means assigning the interrupt on Core 1 by default, see :ref:`built-in-task-priorities`. Interrupts are assigned on the same CPU where the :cpp:func:`esp_intr_alloc` function call is made. + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - Assign the interrupt on a CPU where built-in {IDF_TARGET_RF_TYPE} tasks are not configured to run, which means assigning the interrupt on Core 1 by default, see :ref:`built-in-task-priorities`. Interrupts are assigned on the same CPU where the :cpp:func:`esp_intr_alloc` function call is made. - If you are sure the entire interrupt handler can run from IRAM (see :ref:`iram-safe-interrupt-handlers`) then set the ``ESP_INTR_FLAG_IRAM`` flag when calling :cpp:func:`esp_intr_alloc` to assign the interrupt. This prevents it being temporarily disabled if the application firmware writes to the internal SPI flash. - Even if the interrupt handler is not IRAM-safe, if it is going to be executed frequently then consider moving the handler function to IRAM anyhow. This minimizes the chance of a flash cache miss when the interrupt code is executed (see :ref:`speed-targeted-optimizations`). It is possible to do this without adding the ``ESP_INTR_FLAG_IRAM`` flag to mark the interrupt as IRAM-safe, if only part of the handler is guaranteed to be in IRAM. diff --git a/docs/en/api-guides/startup.rst b/docs/en/api-guides/startup.rst index d402bb770a6..db0903e19de 100644 --- a/docs/en/api-guides/startup.rst +++ b/docs/en/api-guides/startup.rst @@ -22,11 +22,11 @@ This process is explained in detail in the following sections. First Stage Bootloader ^^^^^^^^^^^^^^^^^^^^^^ -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located in the mask ROM of the {IDF_TARGET_NAME} chip and cannot be modified. -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES After SoC reset, the CPU will start running immediately to perform initialization. The reset vector code is located in the mask ROM of the {IDF_TARGET_NAME} chip and cannot be modified. @@ -76,7 +76,7 @@ For the selected partition, second stage bootloader reads the binary image from - For segments with load addresses in internal :ref:`iram` or :ref:`dram`, the contents are copied from flash to the load address. - For segments which have load addresses in :ref:`drom` or :ref:`irom` regions, the flash MMU is configured to provide the correct mapping from the flash to the load address. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application. @@ -114,13 +114,13 @@ This port-layer initialization function initializes the basic C Runtime Environm - Set the CPU clocks to the frequencies configured for the project. :CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - Initialize memory protection if configured. :esp32: - Reconfigure the main SPI flash based on the app header settings (necessary for compatibility with bootloader versions before ESP-IDF V4.0, see :ref:`bootloader-compatibility`). - :not CONFIG_FREERTOS_UNICORE: - If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside the similar "port layer" initialization function ``call_start_cpu1``). + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside the similar "port layer" initialization function ``call_start_cpu1``). -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES Once ``call_start_cpu0`` completes running, it calls the "system layer" initialization function ``start_cpu0`` found in :idf_file:`components/esp_system/startup.c`. Other cores will also complete port-layer initialization and call ``start_other_cores`` found in the same file. -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES Once ``call_start_cpu0`` completes running, it calls the "system layer" initialization function ``start_cpu0`` found in :idf_file:`components/esp_system/startup.c`. @@ -156,13 +156,13 @@ After doing some more initialization tasks (that require the scheduler to have s The main task that runs ``app_main`` has a fixed RTOS priority (one higher than the minimum) and a :ref:`configurable stack size `. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES The main task core affinity is also configurable: :ref:`CONFIG_ESP_MAIN_TASK_AFFINITY`. Unlike normal FreeRTOS tasks (or embedded C ``main`` functions), the ``app_main`` task is allowed to return. If this happens, The task is cleaned up and the system will continue running with other RTOS tasks scheduled normally. Therefore, it is possible to implement ``app_main`` as either a function that creates other application tasks and then returns, or as a main application task itself. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES Second Core Startup ------------------- diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst index 2d6a22451fa..897f4f552c4 100644 --- a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst +++ b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst @@ -42,11 +42,11 @@ Under this condition, all CPUs should always execute code and access data from i When :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA` are both enabled, these APIs will not disable the caches. -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES The way that these APIs disable the caches suspends all the other tasks. Besides, all non-IRAM-safe interrupts will be disabled. The other core will be polling in a busy loop. These will be restored until the Flash operation completes. -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES The way that these APIs disable the caches also disables non-IRAM-safe interrupts. These will be restored until the Flash operation completes. diff --git a/docs/en/api-reference/system/freertos.rst b/docs/en/api-reference/system/freertos.rst index ca1b1fcdc55..db18a581316 100644 --- a/docs/en/api-reference/system/freertos.rst +++ b/docs/en/api-reference/system/freertos.rst @@ -51,7 +51,7 @@ For the full list of user configurable kernel options, see :doc:`/api-reference/ - :ref:`CONFIG_FREERTOS_UNICORE` runs FreeRTOS only on CPU0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Furthermore, this option may affect behavior of components other than :component:`freertos`. For more details regarding the effects of running FreeRTOS on a single core, refer to :ref:`freertos-smp-single-core` (if using ESP-IDF FreeRTOS) or the official Amazon SMP FreeRTOS documentation. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES .. note:: As {IDF_TARGET_NAME} is a single core SoC, the :ref:`CONFIG_FREERTOS_UNICORE` configuration is always set. diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index 3f284fcf092..9b288356d09 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -25,7 +25,7 @@ System API heap_debug esp_timer internal-unstable - :not CONFIG_FREERTOS_UNICORE: ipc + :SOC_HP_CPU_HAS_MULTIPLE_CORES: ipc intr_alloc log misc_system_api diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index 06b7bc456df..62329d945db 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -143,7 +143,7 @@ If you have confirmed that the application is indeed running out of interrupts, .. list:: - :not CONFIG_FREERTOS_UNICORE: - On multi-core SoCs, try initializing some of the peripheral drivers from a task pinned to the second core. Interrupts are typically allocated on the same core where the peripheral driver initialization function runs. Therefore by running the initialization function on the second core, more interrupt inputs can be used. + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - On multi-core SoCs, try initializing some of the peripheral drivers from a task pinned to the second core. Interrupts are typically allocated on the same core where the peripheral driver initialization function runs. Therefore by running the initialization function on the second core, more interrupt inputs can be used. - Determine the interrupts which can tolerate higher latency, and allocate them using ``ESP_INTR_FLAG_SHARED`` flag (optionally ORed with ``ESP_INTR_FLAG_LOWMED``). Using this flag for two or more peripherals will let them use a single interrupt input, and therefore save interrupt inputs for other peripherals. See :ref:`intr-alloc-shared-interrupts` above. :not SOC_CPU_HAS_FLEXIBLE_INTC: - Some peripheral driver may default to allocating interrupts with ``ESP_INTR_FLAG_LEVEL1`` flag, so priority 2 and 3 interrupts do not get used by default. If :cpp:func:`esp_intr_dump` shows that some priority 2 or 3 interrupts are available, try changing the interrupt allocation flags when initializing the driver to ``ESP_INTR_FLAG_LEVEL2`` or ``ESP_INTR_FLAG_LEVEL3``. - Check if some of the peripheral drivers do not need to be used all the time, and initialize or deinitialize them on demand. This can reduce the number of simultaneously allocated interrupts. diff --git a/docs/en/api-reference/system/pthread.rst b/docs/en/api-reference/system/pthread.rst index 783a66548a1..ec79ca8d62b 100644 --- a/docs/en/api-reference/system/pthread.rst +++ b/docs/en/api-reference/system/pthread.rst @@ -189,7 +189,7 @@ The API :cpp:func:`esp_pthread_set_cfg` defined in the ``esp_pthreads.h`` header .. list:: - Default stack size of new threads, if not specified when calling ``pthread_create()`` (overrides :ref:`CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT`). - RTOS priority of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_PRIO_DEFAULT`). - :not CONFIG_FREERTOS_UNICORE: - Core affinity / core pinning of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`). + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - Core affinity / core pinning of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`). - FreeRTOS task name for new threads (overrides :ref:`CONFIG_PTHREAD_TASK_NAME_DEFAULT`) This configuration is scoped to the calling thread (or FreeRTOS task), meaning that :cpp:func:`esp_pthread_set_cfg` can be called independently in different threads or tasks. If the ``inherit_cfg`` flag is set in the current configuration then any new thread created will inherit the creator's configuration (if that thread calls ``pthread_create()`` recursively), otherwise the new thread will have the default configuration. diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 7f73aaf085c..f1525362b33 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -113,7 +113,7 @@ The following config options control TWDT configuration. They are all enabled by - :ref:`CONFIG_ESP_TASK_WDT_EN` - enables TWDT feature. If this option is disabled, TWDT cannot be used, even if initialized at runtime. - :ref:`CONFIG_ESP_TASK_WDT_INIT` - the TWDT is initialized automatically during startup. If this option is disabled, it is still possible to initialize the Task WDT at runtime by calling :cpp:func:`esp_task_wdt_init`. - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - {IDF_TARGET_IDLE_TASK} is subscribed to the TWDT during startup. If this option is disabled, it is still possible to subscribe the idle task by calling :cpp:func:`esp_task_wdt_init` again. - :not CONFIG_FREERTOS_UNICORE: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 Idle task is subscribed to the TWDT during startup. + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 Idle task is subscribed to the TWDT during startup. .. note:: diff --git a/docs/zh_CN/api-guides/app_trace.rst b/docs/zh_CN/api-guides/app_trace.rst index 13012578ee7..1e00241e921 100644 --- a/docs/zh_CN/api-guides/app_trace.rst +++ b/docs/zh_CN/api-guides/app_trace.rst @@ -420,7 +420,7 @@ Start 子命令语法： 收集到跟踪数据后，用户可以使用特殊的工具对结果进行可视化并分析程序行为。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 遗憾的是，SystemView 不支持从多个核心进行跟踪。所以当使用 JTAG 追踪双核模式下的 {IDF_TARGET_NAME} 时会生成两个文件：一个用于 PRO CPU，另一个用于 APP CPU。用户可以将每个文件加载到工具中单独分析。使用 UART 进行追踪时，用户可以在 menuconfig Pro 或 App 中点击 ``Component config`` > ``Application Level Tracing`` > ``FreeRTOS SystemView Tracing`` 并选择要追踪的 CPU。 @@ -432,7 +432,7 @@ Start 子命令语法： ESP-IDF 使用自己的 SystemView FreeRTOS 事件 ID 映射，因此用户需要将 ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` 替换成 ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``。在使用上述链接配置 SystemView 序列化程序时，也应该使用该特定文件的内容。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 配置 Impulse 实现双核跟踪 ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/api-guides/performance/speed.rst b/docs/zh_CN/api-guides/performance/speed.rst index 3e4792d6e3e..8db36c737fb 100644 --- a/docs/zh_CN/api-guides/performance/speed.rst +++ b/docs/zh_CN/api-guides/performance/speed.rst @@ -54,7 +54,7 @@ - 也可以使用标准 Unix 函数 ``gettimeofday()`` 和 ``utime()`` 来进行计时测量，尽管其开销略高一些。 - 此外，代码中包含 ``hal/cpu_hal.h`` 头文件，并调用 HAL 函数 ``cpu_hal_get_cycle_count()`` 可以返回已执行的 CPU 循环数。该函数开销较低，适用于高精度测量执行时间极短的代码。 - .. only:: not CONFIG_FREERTOS_UNICORE + .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES CPU 周期是各核心独立计数的，因此本方法仅适用于测量中断处理程序或固定在单个核心上的任务。 @@ -159,7 +159,7 @@ ESP-IDF 启动的系统任务预设了固定优先级。启动时，一些任务 .. Note: 以下两个列表应保持一致，但第二个列表还展示了 CPU 亲和性。 -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES .. list:: @@ -176,7 +176,7 @@ ESP-IDF 启动的系统任务预设了固定优先级。启动时，一些任务 - 如果使用 :doc:`/api-reference/protocols/mqtt` 组件，它会创建优先级默认为 5 的任务（ :ref:`可配置 ` ），可通过 :ref:`CONFIG_MQTT_USE_CUSTOM_CONFIG` 调整，也可以在运行时通过 :cpp:class:`esp_mqtt_client_config_t` 结构体中的 ``task_prio`` 字段调整。 - 关于 ``mDNS`` 服务的任务优先级，参见 `性能优化 `__ 。 -.. only :: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES .. list:: @@ -204,11 +204,11 @@ ESP-IDF 启动的系统任务预设了固定优先级。启动时，一些任务 设定应用程序任务优先级 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES 由于 {IDF_TARGET_RF_TYPE} 操作饥饿可能导致系统不稳定，通常不建议让特定任务的优先级高于 {IDF_TARGET_RF_TYPE} 操作的内置优先级。对于非常短且无需网络的实时操作，可以使用中断服务程序或极受限的任务（仅运行极短时间）并设置为最高优先级 (24)。将特定任务优先级设为 19 不会妨碍较低层级的 {IDF_TARGET_RF_TYPE} 功能无延迟运行，但仍然会抢占 lwIP TCP/IP 堆栈以及其他非实时内部功能，这对于不执行网络操作的实时任务而言是最佳选项。lwIP TCP/IP 任务优先级 (18) 应高于所有执行 TCP/IP 网络操作的任务，以保证任务正常执行。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 默认配置下，除了个别例外，尤其是 lwIP TCP/IP 任务，大多数内置任务都固定在核心 0 上执行。因此，应用程序可以方便地将高优先级任务放置在核心 1 上执行。优先级大于等于 19 的应用程序任务在核心 1 上运行时可以确保不会被任何内置任务抢占。为了进一步隔离各个 CPU 上运行的任务，配置 :ref:`lwIP 任务 ` ，可以使 lwIP 任务仅在核心 0 上运行，而非上述任一核心，这可能会根据其他任务的运行情况减少总 TCP/IP 吞吐量。 @@ -234,7 +234,7 @@ ESP-IDF 支持动态 :doc:`/api-reference/system/intr_alloc` 和中断抢占。 .. list:: - 调用 :cpp:func:`esp_intr_alloc` 时使用 ``ESP_INTR_FLAG_LEVEL2`` 或 ``ESP_INTR_FLAG_LEVEL3`` 等标志，可以为更重要的中断设定更高优先级。 - :not CONFIG_FREERTOS_UNICORE: - 将中断分配到不运行内置 {IDF_TARGET_RF_TYPE} 任务的 CPU 上执行，即默认情况下，将中断分配到核心 1 上执行，参见 :ref:`built-in-task-priorities` 。调用 :cpp:func:`esp_intr_alloc` 函数即可将中断分配到函数所在 CPU。 + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 将中断分配到不运行内置 {IDF_TARGET_RF_TYPE} 任务的 CPU 上执行，即默认情况下，将中断分配到核心 1 上执行，参见 :ref:`built-in-task-priorities` 。调用 :cpp:func:`esp_intr_alloc` 函数即可将中断分配到函数所在 CPU。 - 如果确定整个中断处理程序可以在 IRAM 中运行（参见 :ref:`iram-safe-interrupt-handlers` ），那么在调用 :cpp:func:`esp_intr_alloc` 分配中断时，请设置 ``ESP_INTR_FLAG_IRAM`` 标志，这样可以防止在应用程序固件写入内置 SPI flash 时临时禁用中断。 - 即使是非 IRAM 安全的中断处理程序，如果需要频繁执行，可以考虑将处理程序的函数移到 IRAM 中，从而尽可能规避执行中断代码时发生 flash 缓存缺失的可能性（参见 :ref:`speed-targeted-optimizations` ）。如果可以确保只有部分处理程序位于 IRAM 中，则无需添加 ``ESP_INTR_FLAG_IRAM`` 标志将程序标记为 IRAM 安全。 diff --git a/docs/zh_CN/api-guides/startup.rst b/docs/zh_CN/api-guides/startup.rst index 155b3c6b4ea..54e58bc3b8a 100644 --- a/docs/zh_CN/api-guides/startup.rst +++ b/docs/zh_CN/api-guides/startup.rst @@ -22,11 +22,11 @@ 一级引导程序 ~~~~~~~~~~~~ -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES SoC 复位后，PRO CPU 会立即开始运行，执行复位向量代码，而 APP CPU 仍然保持复位状态。在启动过程中，PRO CPU 会执行所有的初始化操作。APP CPU 的复位状态会在应用程序启动代码的 ``call_start_cpu0`` 函数中失效。复位向量代码位于 {IDF_TARGET_NAME} 芯片掩膜 ROM 处，且不能被修改。 -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES SoC 复位后，CPU 会立即开始运行，执行所有的初始化操作。复位向量代码位于 {IDF_TARGET_NAME} 芯片掩膜 ROM 处，且不能被修改。 @@ -76,7 +76,7 @@ - 对于在内部 :ref:`iram` 或 :ref:`dram` 中具有加载地址的段，将把数据从 flash 复制到它们的加载地址处。 - 对于一些加载地址位于 :ref:`drom` 或 :ref:`irom` 区域的段，通过配置 flash MMU，可为从 flash 到加载地址提供正确的映射。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 请注意，二级引导程序同时为 PRO CPU 和 APP CPU 配置 flash MMU，但仅使能 PRO CPU 的 flash MMU。原因是二级引导程序代码已加载到 APP CPU 的高速缓存使用的内存区域中。因此使能 APP CPU 高速缓存的任务就交给了应用程序。 @@ -114,13 +114,13 @@ ESP-IDF 应用程序的入口是 :idf_file:`components/esp_system/port/cpu_start - 将 CPU 时钟设置为项目配置的频率。 :CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - 如果配置了内存保护，则初始化内存保护。 :esp32: - 根据应用程序头部设置重新配置主 SPI flash，这是为了与 ESP-IDF V4.0 之前的引导程序版本兼容，请参考 :ref:`bootloader-compatibility`。 - :not CONFIG_FREERTOS_UNICORE: - 如果应用程序被配置为在多个内核上运行，则启动另一个内核并等待其初始化（在类似的“端口层”初始化函数 ``call_start_cpu1`` 内）。 + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 如果应用程序被配置为在多个内核上运行，则启动另一个内核并等待其初始化（在类似的“端口层”初始化函数 ``call_start_cpu1`` 内）。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES ``call_start_cpu0`` 完成运行后，将调用在 :idf_file:`components/esp_system/startup.c` 中找到的“系统层”初始化函数 ``start_cpu0``。其他内核也将完成端口层的初始化，并调用同一文件中的 ``start_other_cores``。 -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES ``call_start_cpu0`` 完成运行后，将调用在 :idf_file:`components/esp_system/startup.c` 中找到的“系统层”初始化函数 ``start_cpu0``。 @@ -156,13 +156,13 @@ ESP-IDF 应用程序的入口是 :idf_file:`components/esp_system/port/cpu_start 运行 ``app_main`` 的主任务有一个固定的 RTOS 优先级（比最小值高）和一个 :ref:`可配置的堆栈大小`。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 主任务的内核亲和性也是可以配置的，请参考 :ref:`CONFIG_ESP_MAIN_TASK_AFFINITY`。 与普通的 FreeRTOS 任务（或嵌入式 C 的 ``main`` 函数）不同，``app_main`` 任务可以返回。如果``app_main`` 函数返回，那么主任务将会被删除。系统将继续运行其他的 RTOS 任务。因此可以将 ``app_main`` 实现为一个创建其他应用任务然后返回的函数，或主应用任务本身。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES APP CPU 的内核启动流程 ------------------------------------ diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst index 3177abff4a5..bdbb9f4d7e8 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst @@ -42,11 +42,11 @@ SPI1 flash 并发约束 同时启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 选项后，不会禁用 cache。 -.. only:: not CONFIG_FREERTOS_UNICORE +.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES 为避免意外读取 flash cache，一个 CPU 在启动 flash 写入或擦除操作时，另一个 CPU 将阻塞。在 flash 操作完成前，会禁用所有在 CPU 上非 IRAM 安全的中断。 -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES 为避免意外读取 flash cache，在 flash 操作完成前，所有 CPU 上，会禁用所有在 CPU 上非 IRAM 安全的中断。 diff --git a/docs/zh_CN/api-reference/system/freertos.rst b/docs/zh_CN/api-reference/system/freertos.rst index a2d88e48373..f6663e23758 100644 --- a/docs/zh_CN/api-reference/system/freertos.rst +++ b/docs/zh_CN/api-reference/system/freertos.rst @@ -51,7 +51,7 @@ ESP-IDF FreeRTOS - :ref:`CONFIG_FREERTOS_UNICORE`：仅在 CPU0 上运行 FreeRTOS。注意，这 **不等同于运行原生 FreeRTOS。** 另外，此选项还可能影响除 :component:`freertos` 外其他组件的行为。关于在单核上运行 FreeRTOS 的更多内容，请参考 :ref:`freertos-smp-single-core` （使用 ESP-IDF FreeRTOS 时）或参考 Amazon SMP FreeRTOS 的官方文档，还可以在 ESP-IDF 组件中搜索 ``CONFIG_FREERTOS_UNICORE``。 -.. only:: CONFIG_FREERTOS_UNICORE +.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES .. note:: 由于 {IDF_TARGET_NAME} 是一个单核 SoC，所以总是会启用 :ref:`CONFIG_FREERTOS_UNICORE` 配置。 diff --git a/docs/zh_CN/api-reference/system/intr_alloc.rst b/docs/zh_CN/api-reference/system/intr_alloc.rst index f795107ac73..1ac547249b9 100644 --- a/docs/zh_CN/api-reference/system/intr_alloc.rst +++ b/docs/zh_CN/api-reference/system/intr_alloc.rst @@ -143,7 +143,7 @@ CPU 中断在大多数 Espressif SoC 上都是有限的资源。因此，一个 .. list:: - :not CONFIG_FREERTOS_UNICORE: - 在多核 SoC 上，尝试通过固定在第二个核的任务来初始化某些外设驱动程序。中断通常分配在运行外设驱动程序初始化函数的同一个内核上，因此，通过在第二个内核上运行初始化函数，就可以使用更多的中断输入。 + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 在多核 SoC 上，尝试通过固定在第二个核的任务来初始化某些外设驱动程序。中断通常分配在运行外设驱动程序初始化函数的同一个内核上，因此，通过在第二个内核上运行初始化函数，就可以使用更多的中断输入。 - 找到可接受更高延迟的中断，并用 ``ESP_INTR_FLAG_SHARED`` flag （或与 ``ESP_INTR_FLAG_LOWMED`` 进行 OR 运算）分配这些中断。对两个或更多外设使用此 flag 能让它们使用单个中断输入，从而为其他外设节约中断输入。参见 :ref:`intr-alloc-shared-interrupts`。 :not SOC_CPU_HAS_FLEXIBLE_INTC: - 一些外设驱动程序可能默认使用 ``ESP_INTR_FLAG_LEVEL1`` flag 来分配中断，因此默认情况下不会使用优先级为 2 或 3 的中断。如果 :cpp:func:`esp_intr_dump` 显示某些优先级为 2 或 3 的中断可用，尝试在初始化驱动程序时将中断分配 flag 改为 ``ESP_INTR_FLAG_LEVEL2`` 或 ``ESP_INTR_FLAG_LEVEL3``。 - 检查是否有些外设驱动程序不需要一直启用，并按需将其初始化或取消初始化。这样可以减少同时分配的中断数量。 diff --git a/docs/zh_CN/api-reference/system/pthread.rst b/docs/zh_CN/api-reference/system/pthread.rst index 8a5f5e6bad2..ad23de102ef 100644 --- a/docs/zh_CN/api-reference/system/pthread.rst +++ b/docs/zh_CN/api-reference/system/pthread.rst @@ -189,7 +189,7 @@ ESP-IDF 扩展 .. list:: - 如果调用 ``pthread_create()`` 时未指定默认堆栈大小，可设置新线程的默认堆栈大小（覆盖 :ref:`CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT`）。 - 新线程的 RTOS 优先级（覆盖 :ref:`CONFIG_PTHREAD_TASK_PRIO_DEFAULT`）。 - :not CONFIG_FREERTOS_UNICORE: - 新线程的内核亲和性/内核固定（覆盖 :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`）。 + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 新线程的内核亲和性/内核固定（覆盖 :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`）。 - 新线程的 FreeRTOS 任务名称（覆盖 :ref:`CONFIG_PTHREAD_TASK_NAME_DEFAULT`） 此配置的作用范围是调用线程或 FreeRTOS 任务，这意味着 :cpp:func:`esp_pthread_set_cfg` 可以在不同的线程或任务中独立调用。如果在当前配置中设置了 ``inherit_cfg`` 标志，那么当一个线程递归调用 ``pthread_create()`` 时，任何新创建的线程都会继承该线程的配置，否则新线程将采用默认配置。 diff --git a/docs/zh_CN/api-reference/system/wdts.rst b/docs/zh_CN/api-reference/system/wdts.rst index bb582b962b0..df6f18c0cb9 100644 --- a/docs/zh_CN/api-reference/system/wdts.rst +++ b/docs/zh_CN/api-reference/system/wdts.rst @@ -113,7 +113,7 @@ TWDT 的默认超时时间可以通过 :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` 配 - :ref:`CONFIG_ESP_TASK_WDT_EN` - 启用 TWDT 功能。如果禁用此选项， TWDT 即使运行时已初始化也无法使用。 - :ref:`CONFIG_ESP_TASK_WDT_INIT` - TWDT 在启动期间自动初始化。禁用此选项时，仍可以调用 :cpp:func:`esp_task_wdt_init` 在运行时初始化 TWDT。 - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` - {IDF_TARGET_IDLE_TASK}在启动时订阅了 TWDT。如果此选项被禁用，仍可以调用 :cpp:func:`esp_task_wdt_init` 再次订阅。 - :not CONFIG_FREERTOS_UNICORE: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 空闲任务在启动时订阅了 TWDT。 + :SOC_HP_CPU_HAS_MULTIPLE_CORES: - :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` - CPU1 空闲任务在启动时订阅了 TWDT。 .. note::