Merge branch 'docs/add_application_examples_system_component' into 'master'

docs: add or update application examples of system component See merge request espressif/esp-idf!32004
2024-07-29 17:20:17 +08:00
parent d839ea6805 0af1256a12
commit 9e1d02a3ef
27 changed files with 161 additions and 65 deletions
@@ -186,13 +186,16 @@ Linenoise 库不需要显式地初始化，但是在调用行编辑函数之前

    同样，如果 REPL 环境是构建在 USB_SERIAL_JTAG 设备基础上，你只需要先调用 :cpp:func:`esp_console_new_repl_usb_serial_jtag` 函数进行初始化，然后再照常调用其它函数。

-应用程序示例
+应用示例
 ------------

-:example:`system/console` 目录下提供了 ``console`` 组件的示例应用程序，展示了具体的使用方法。该示例介绍了如何初始化 UART 和 VFS 的功能，设置 linenoise 库，从 UART 中读取命令并加以处理，然后将历史命令存储到 flash 中。更多信息，请参阅示例代码目录中的 README.md 文件。
+- :example:`system/console/basic` 演示了如何使用控制台组件的 REPL（读-评估-打印循环）API 在 {IDF_TARGET_NAME} 上创建一个交互式 Shell，该 Shell 可以通过串行接口控制，支持 UART 和 USB 接口，并可以作为需要命令行接口的应用程序的基础。

-此外，ESP-IDF 还提供了众多基于 ``console`` 组件的示例程序，它们可以辅助应用程序的开发。例如，:example:`peripherals/i2c/i2c_tools`，:example:`wifi/iperf` 等等。
+- :example:`system/console/advanced` 演示了如何使用控制台组件在 {IDF_TARGET_NAME} 上创建一个交互式 Shell，该 Shell 可以通过串行端口控制，为需要命令行接口的应用程序提供基础。

+.. only:: esp32s3
+
+    - :example:`system/console/advanced_usb_cdc` 演示了如何通过 {IDF_TARGET_NAME} 的 USB_OTG 外设创建并与具有命令行接口的交互式 Shell 进行交互。

 API 参考
 --------
@@ -215,11 +215,9 @@
 应用示例
 -------------------

-使用 ``esp_event`` 库的示例存放在 :example:`system/esp_event` 中，涵盖事件声明、循环创建、处理程序注册和注销以及事件发布。
+- :example:`system/esp_event/default_event_loop` 演示了如何使用 {IDF_TARGET_NAME} 的默认事件循环系统来发布和处理事件，包括声明和定义事件、创建默认事件循环、将事件发布到循环中，以及注册/注销事件处理程序。

-其他使用 ``esp_event`` 库的示例:
-
-    * :example:`NMEA Parser <peripherals/uart/nmea0183_parser>`，该示例将解码从 GPS 接收到的语句。
+- :example:`system/esp_event/user_event_loops` 演示了如何在 {IDF_TARGET_NAME} 上创建和使用用户事件循环，包括创建和运行事件循环、注册和注销处理程序、以及发布事件，能够处理超出默认事件循环的不同示例。

 API 参考
 -------------
@@ -140,3 +140,10 @@ FreeRTOS 堆

    - 使用一个 ``...CreateWithCaps()`` API，如 :cpp:func:`xTaskCreateWithCaps` 和 :cpp:func:`xQueueCreateWithCaps` 来分配任务或对象（参见 :ref:`freertos-idf-additional-api` 获取更多详细信息）。
    - 使用 :cpp:func:`heap_caps_malloc` 为这些对象手动分配外部内存，然后使用 FreeRTOS 的一个 ``...CreateStatic()`` 函数从分配的内存中创建对象。
+
+应用示例
+--------------------
+
+- :example:`system/freertos/basic_freertos_smp_usage` 演示了如何在 {IDF_TARGET_NAME} 的 SMP 架构中使用基本的 FreeRTOS API 进行任务创建、通信、同步和批处理。
+
+- :example:`system/freertos/real_time_stats` 演示了如何使用 FreeRTOS 的 vTaskGetRunTimeStats() 函数来获取任务在指定时间段内的 CPU 使用统计信息，而不是整个 FreeRTOS 运行时间的统计信息。
@@ -510,6 +510,11 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 <heap-information>`、:ref:`

 要区分“真实”和“误报”的内存泄漏，可以在堆内存跟踪运行时多次调用可疑代码，并在堆内存跟踪输出中查找重复出现的内存分配情况。

+应用示例
+--------------------
+
+- :example:`system/heap_task_tracking` 演示了如何使用堆任务跟踪功能跟踪分配给每个任务的堆内存。
+
 API 参考 - 堆内存跟踪
 ----------------------------

@@ -17,11 +17,10 @@ ESP32 仍可使用大于等于 4 MiB 大小的 SPI RAM 芯片。不过，这些

 Himem API 可以看作是存储体切换方案的一个抽象。具体而言，该 API 允许声明一个或多个地址空间存储体（在 API 中称为“regions”），以及一个或多个需映射到此范围的内存存储体。

-示例
-------
-
-ESP-IDF 中提供了对大内存范围进行简单内存测试的示例，请前往 :example:`system/himem` 查看。
+应用示例
+--------------------

+- :example:`system/himem` 演示了如何在 {IDF_TARGET_NAME} 上使用 Himem API 对 8 MiB PSRAM 芯片的上部 4 MiB 进行内存测试，展示了如何分配地址空间、分配物理内存，并在分配的地址空间中切换内存。

 API 参考
 -------------
@@ -146,6 +146,17 @@ IPC 功能提供了下列 API，以在高优先级中断的上下文中执行回
    :CONFIG_IDF_TARGET_ARCH_XTENSA: - :cpp:func:`esp_ipc_isr_stall_other_cpu`：暂停目标内核。调用内核禁用 3 级及以下级别的中断，而目标内核将在 5 级及以下的中断被禁用的情况下进入忙等待。在调用 :cpp:func:`esp_ipc_isr_release_other_cpu` 前，目标内核会保持忙等待。
    - :cpp:func:`esp_ipc_isr_release_other_cpu`：恢复目标内核。

+应用示例
+--------------------
+
+.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
+
+    - :example:`system/ipc/ipc_isr/xtensa` 演示了如何在高优先级中断的上下文中使用 IPC ISR 功能运行 IPC，允许用户快速获取另一个 CPU 的状态，包括两个汇编回调函数，这些回调函数返回另一个核心的 PS 寄存器并在执行基于输入参数的任务时保存/恢复寄存器。
+
+.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
+
+    - :example:`system/ipc/ipc_isr/riscv` 演示了如何在 {IDF_TARGET_NAME} 上使用 IPC ISR 功能在高优先级中断的上下文中运行 IPC，包括如何快速获取另一个 CPU 的状态以及如何从回调函数返回多个值。
+
 API 参考
 -------------

@@ -8,7 +8,7 @@
 应用示例
 -------------------

-在目录 ``examples/system/perfmon`` 下提供了一个结合性能监视器的示例。此示例初始化并执行了性能监视器，同时打印了统计信息。
+- :example:`system/perfmon` 演示了如何使用 `perfmon` API 来监控和分析函数性能。

 高级 API 参考
 ------------------------
@@ -195,13 +195,12 @@ ESP-IDF 扩展

 此配置的作用范围是调用线程或 FreeRTOS 任务，这意味着 :cpp:func:`esp_pthread_set_cfg` 可以在不同的线程或任务中独立调用。如果在当前配置中设置了 ``inherit_cfg`` 标志，那么当一个线程递归调用 ``pthread_create()`` 时，任何新创建的线程都会继承该线程的配置，否则新线程将采用默认配置。

-示例
--------
+应用示例
+-------------------

 - :example:`system/pthread` 演示了如何使用 pthread API 创建线程。
 - :example:`cxx/pthread` 演示了如何通过线程使用 C++ 标准库函数。

-
 API 参考
 -------------

@@ -224,11 +224,18 @@ ULP LP-Core 中断
 应用示例
 --------

-* 在示例 :example:`system/ulp/lp_core/gpio` 中，ULP LP-Core 协处理器在主 CPU 深度睡眠时轮询 GPIO。
-* 在示例 :example:`system/ulp/lp_core/lp_i2c` 中，ULP LP-Core 协处理器在主 CPU 深度睡眠时读取外部 I2C 环境光传感器 (BH1750)，并在达到阈值时唤醒主 CPU。
-* 在示例 :example:`system/ulp/lp_core/lp_uart/lp_uart_echo` 中，低功耗内核上运行的 LP UART 驱动程序读取并回显写入串行控制台的数据。
+* :example:`system/ulp/lp_core/gpio` 展示了 ULP LP-Core 协处理器在主 CPU 深度睡眠时轮询 GPIO。
+
+.. only:: esp32c6
+
+    * :example:`system/ulp/lp_core/lp_i2c` 展示了 ULP LP-Core 协处理器在主 CPU 深度睡眠时读取外部 I2C 环境光传感器 (BH1750)，并在达到阈值时唤醒主 CPU。
+
+* :example:`system/ulp/lp_core/lp_uart/lp_uart_echo` 展示了低功耗内核上运行的 LP UART 驱动程序如何读取并回显写入串行控制台的数据。
+
 * :example:`system/ulp/lp_core/lp_uart/lp_uart_print` 展示了如何在低功耗内核上使用串口打印功能。
+
 * :example:`system/ulp/lp_core/interrupt` 展示了如何在 LP 内核上注册中断处理程序，接收由主 CPU 触发的中断。
+
 * :example:`system/ulp/lp_core/gpio_intr_pulse_counter` 展示了如何在主 CPU 处于 Deep-sleep 模式时，使用 GPIO 中断为脉冲计数。

 API 参考
@@ -243,11 +243,23 @@ ULP RISC-V 的中断处理尚在开发中，还不支持针对内部中断源的
 应用示例
 --------------------

-* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器轮询 GPIO：:example:`system/ulp/ulp_riscv/gpio`。
-* ULP RISC-V 协处理器使用 bit-banged UART 驱动程序打印：:example:`system/ulp/ulp_riscv/uart_print`.
-* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部温度传感器：:example:`system/ulp/ulp_riscv/ds18b20_onewire`。
-* 主 CPU 处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部 I2C 温度和湿度传感器 (BMP180)，达到阈值时唤醒主 CPU：:example:`system/ulp/ulp_riscv/i2c`.
-* 使用 ULP RISC-V 协处理器处理软件中断和 RTC IO 中断：:example:`system/ulp/ulp_riscv/interrupts`.
+* :example:`system/ulp/ulp_riscv/gpio` 演示了如何通过 ULP-RISC-V 协处理器监控 GPIO 引脚，并在其状态发生变化时唤醒主 CPU。
+
+* :example:`system/ulp/ulp_riscv/uart_print` 演示了如何在开发板上使用 ULP-RISC-V 协处理器通过 bitbang 实现 UART 发射，即使在主 CPU 处于深度睡眠状态时也能直接从 ULP-RISC-V 协处理器输出日志。
+
+.. only:: esp32s2
+
+    * :example:`system/ulp/ulp_riscv/ds18b20_onewire` 演示了如何使用 ULP-RISC-V 协处理器通过 1-Wire 协议读取 DS18B20 传感器的温度，并在温度超过阈值时唤醒主 CPU。
+
+* :example:`system/ulp/ulp_riscv/i2c` 演示了如何在深度睡眠模式下使用 ULP RISC-V 协处理器的 RTC I2C 外设定期测量 BMP180 传感器的温度和压力值，并在这些值超过阈值时唤醒主 CPU。
+
+* :example:`system/ulp/ulp_riscv/interrupts` 演示了 ULP-RISC-V 协处理器如何注册和处理软件中断和 RTC IO 触发的中断，记录软件中断的计数，并在达到某个阈值后或按下按钮时唤醒主 CPU。
+
+* :example:`system/ulp/ulp_riscv/adc` 演示了如何使用 ULP-RISC-V 协处理器定期测量输入电压，并在电压超过设定阈值时唤醒系统。
+
+* :example:`system/ulp/ulp_riscv/gpio_interrupt` 演示了如何使用 ULP-RISC-V 协处理器以通过 RTC IO 中断从深度睡眠中唤醒，使用 GPIO0 作为输入信号，并配置和运行协处理器，将芯片置于深度睡眠模式，直到唤醒源引脚被拉低。
+
+* :example:`system/ulp/ulp_riscv/touch` 演示了如何使用 ULP RISC-V 协处理器定期扫描和读取触摸传感器，并在触摸传感器被激活时唤醒主 CPU。

 API 参考
 -------------
@@ -176,8 +176,11 @@ ULP FSM 协处理器代码由汇编语言编写，使用 `binutils-esp32ulp 工
 应用示例
 --------------------

-* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器对 IO 脉冲进行计数：:example:`system/ulp/ulp_fsm/ulp`。
-* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器轮询 ADC：:example:`system/ulp/ulp_fsm/ulp_adc`。
+* :example:`system/ulp/ulp_fsm/ulp` 展示了主处理器运行其他代码或处于 Deep-sleep 状态时，使用 ULP FSM 协处理器对 IO 脉冲进行计数，脉冲计数会在唤醒时保存到 NVS 中。
+
+.. only:: esp32 or esp32s3
+
+    * :example:`system/ulp/ulp_fsm/ulp_adc` 展示了主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器测量特定 ADC 通道上的输入电压，将其与设定的阈值进行比较，电压超出阈值时唤醒系统。

 API 参考
 -------------
@@ -174,13 +174,12 @@ JTAG & 看门狗

 在使用 OpenOCD 进行调试时，CPU 会在每次达到断点时停止运行。然而，如果遇到断点后看门狗定时器继续运行，就会最终触发复位，为调试代码带来巨大的困难。因此， OpenOCD 会在每个断点处禁用中断和任务的看门狗的硬件定时器。此外，在离开断点时，OpenOCD 也不会重新启用定时器，也就是说，中断看门狗和任务看门狗实际上被禁用。当 {IDF_TARGET_NAME} 通过 JTAG 连接到 OpenOCD 时，看门狗不会打印任何警告或出现严重错误。

+应用示例
+--------------------
+
+- :example:`system/task_watchdog` 演示了如何初始化、订阅和取消订阅任务看门狗的任务和用户，以及任务和用户如何重置任务看门狗。

 API 参考
 -------------

-任务看门狗
-^^^^^^^^^^^^^
-
-在 ESP-IDF 中使用任务看门狗的完整示例：:example:`system/task_watchdog`
-
 .. include-build-file:: inc/esp_task_wdt.inc