From e5019c9da01826c75420f5a2bca68f5a02b6c68d Mon Sep 17 00:00:00 2001 From: Linda Date: Mon, 29 Jul 2024 17:05:23 +0800 Subject: [PATCH] docs: update application examples related to system --- docs/en/api-guides/external-ram.rst | 2 ++ docs/en/api-reference/storage/vfs.rst | 6 ++++ docs/en/api-reference/system/app_trace.rst | 7 +++++ docs/en/api-reference/system/efuse.rst | 8 +++++ .../en/api-reference/system/esp_https_ota.rst | 28 +++++------------ .../api-reference/system/misc_system_api.rst | 5 ++++ docs/en/api-reference/system/ota.rst | 8 +++-- docs/zh_CN/api-guides/external-ram.rst | 2 ++ docs/zh_CN/api-reference/storage/vfs.rst | 6 ++++ docs/zh_CN/api-reference/system/app_trace.rst | 7 +++++ docs/zh_CN/api-reference/system/efuse.rst | 8 +++++ .../api-reference/system/esp_https_ota.rst | 30 ++++++------------- .../api-reference/system/misc_system_api.rst | 5 ++++ docs/zh_CN/api-reference/system/ota.rst | 4 +-- 14 files changed, 80 insertions(+), 46 deletions(-) diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 39f2b402b9..2ca608da3e 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -173,6 +173,8 @@ Remaining external RAM can also be added to the capability heap allocator using - The cache will not be disabled during an SPI1 flash operation, thus optimizing the code execution performance during SPI1 flash operations. For ISRs, ISR callbacks and data which might be accessed during this period, you do not need to place them in internal RAM, thus internal RAM usage can be optimized. This feature is useful for high throughput peripheral involved applications to improve the performance during SPI1 flash operations. + :example:`system/xip_from_psram` demonstrates the usage of XiP from PSRAM, optimizing internal RAM usage and avoiding cache disabling during flash operations from user call (e.g., flash erase/read/write operations). + .. only:: esp32p4 .. _external_ram_config_xip: diff --git a/docs/en/api-reference/storage/vfs.rst b/docs/en/api-reference/storage/vfs.rst index 95279c3c0f..e0a3a104b7 100644 --- a/docs/en/api-reference/storage/vfs.rst +++ b/docs/en/api-reference/storage/vfs.rst @@ -192,6 +192,12 @@ Standard I/O streams (``stdin``, ``stdout``, ``stderr``) are mapped to file desc Note that creating an eventfd with ``EFD_SUPPORT_ISR`` will cause interrupts to be temporarily disabled when reading, writing the file and during the beginning and the ending of the ``select()`` when this file is set. +Application Examples +-------------------- + +- :example:`system/eventfd` demonstrates how to use ``eventfd()`` to collect events from tasks and ISRs in a ``select()`` based main loop, using two tasks and a timer ISR (interrupt service routine) callback. + +- :example:`system/select` demonstrates how to use synchronous I/O multiplexing with the ``select()`` function, using UART and socket file descriptors, and configuring both to act as loopbacks to receive messages sent from other tasks. API Reference ------------- diff --git a/docs/en/api-reference/system/app_trace.rst b/docs/en/api-reference/system/app_trace.rst index 05f7dc0e86..427b4a0629 100644 --- a/docs/en/api-reference/system/app_trace.rst +++ b/docs/en/api-reference/system/app_trace.rst @@ -14,6 +14,13 @@ Developers can use this library to send application specific state of execution 2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`. 3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`. +Application Examples +-------------------- + +- :example:`system/app_trace_to_plot` demonstrates how to use the Application Level Tracing Library to send and plot dummy sensor data to a host via JTAG, providing a faster alternative to logging via UART. + +- :example:`system/app_trace_basic` demonstrates how to use the Application Level Tracing Library to log messages to a host via JTAG, providing a faster alternative to UART logs. + API Reference ------------- diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index 6579a6d826..c8f8aaa444 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -566,5 +566,13 @@ Part of the functionality of this tool is also provided directly by ``idf.py`` c .. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst +Application Examples +-------------------- + +- :example:`system/efuse` demonstrates how to use the eFuse API on {IDF_TARGET_NAME}, showing read and write operations with fields from the common and custom eFuse tables, and explaining the use of virtual eFuses for debugging purposes. + +API Reference +------------- + .. include-build-file:: inc/esp_efuse_chip.inc .. include-build-file:: inc/esp_efuse.inc diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst index ace09df14f..623959968d 100644 --- a/docs/en/api-reference/system/esp_https_ota.rst +++ b/docs/en/api-reference/system/esp_https_ota.rst @@ -8,9 +8,6 @@ Overview ``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. It is an abstraction layer over the existing OTA APIs. -Application Example -------------------- - .. code-block:: c esp_err_t do_firmware_upgrade() @@ -56,15 +53,6 @@ Signature Verification For additional security, signature of OTA firmware images can be verified. For more information， please refer to :ref:`secure-ota-updates`. - -Advanced APIs -------------- - -``esp_https_ota`` also provides advanced APIs which can be used if more information and control is needed during the OTA process. - -Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_https_ota`. - - .. _ota_updates_pre-encrypted-firmware: OTA Upgrades with Pre-Encrypted Firmware @@ -94,14 +82,6 @@ This whole workflow is managed by an external component `esp_encrypted_image