alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/update_chip_independent_api_ref_for_c6_and_h2' into 'master'

Browse Source 
docs: Updated chip independednt api-reference chapters for c6 and h2

Closes IDF-5918

See merge request espressif/esp-idf!22138
This commit is contained in:
Sudeep Mohanty 2023-02-04 06:31:06 +08:00
commit 6777230951
13 changed files with 50 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/docs_not_updated/esp32c6.txt
View File

@ -64,41 +64,26 @@ api-reference/network/esp_wifi
api-reference/network/index
api-reference/system
api-reference/system/sleep_modes
api-reference/system/ota
api-reference/system/app_trace
api-reference/system/ulp_macros
api-reference/system/perfmon
api-reference/system/ulp
api-reference/system/esp_function_with_shared_stack
api-reference/system/efuse
api-reference/system/ulp_instruction_set
api-reference/system/async_memcpy
api-reference/system/random
api-reference/system/esp_timer
api-reference/system/esp_event
api-reference/system/freertos
api-reference/system/system_time
api-reference/system/log
api-reference/system/soc_caps
api-reference/system/internal-unstable
api-reference/system/app_image_format
api-reference/system/freertos_additions
api-reference/system/himem
api-reference/system/power_management
api-reference/system/mem_alloc
api-reference/system/misc_system_api
api-reference/system/inc
api-reference/system/inc/show-efuse-table_ESP32-C6
api-reference/system/inc/power_management_esp32s2_and_later
api-reference/system/inc/espefuse_summary_ESP32-C6
api-reference/system/heap_debug
api-reference/system/ipc
api-reference/system/esp_https_ota
api-reference/system/ulp-risc-v
api-reference/system/esp_err
api-reference/system/console
api-reference/system/index
api-reference/system/pthread
api-reference/bluetooth
api-reference/bluetooth/esp_spp
api-reference/bluetooth/esp_l2cap_bt

13
docs/docs_not_updated/esp32h2.txt
View File

@ -115,43 +115,30 @@ api-reference/network/esp_wifi
api-reference/network/index
api-reference/network/esp_netif
api-reference/system/sleep_modes
api-reference/system/ota
api-reference/system/app_trace
api-reference/system/ulp_macros
api-reference/system/perfmon
api-reference/system/ulp
api-reference/system/esp_function_with_shared_stack
api-reference/system/efuse
api-reference/system/chip_revision
api-reference/system/ulp_instruction_set
api-reference/system/random
api-reference/system/esp_timer
api-reference/system/esp_event
api-reference/system/freertos
api-reference/system/system_time
api-reference/system/log
api-reference/system/soc_caps
api-reference/system/internal-unstable
api-reference/system/app_image_format
api-reference/system/freertos_additions
api-reference/system/himem
api-reference/system/power_management
api-reference/system/mem_alloc
api-reference/system/wdts
api-reference/system/misc_system_api
api-reference/system/inc/power_management_esp32
api-reference/system/inc/espefuse_summary_ESP32-H2
api-reference/system/inc/revisions_ESP32-H2
api-reference/system/inc/show-efuse-table_ESP32-H2
api-reference/system/inc/power_management_esp32s2_and_later
api-reference/system/heap_debug
api-reference/system/ipc
api-reference/system/esp_https_ota
api-reference/system/ulp-risc-v
api-reference/system/esp_err
api-reference/system/console
api-reference/system/index
api-reference/system/pthread
api-reference/bluetooth/esp_spp
api-reference/bluetooth/esp_l2cap_bt
api-reference/bluetooth/esp_hidd

10
docs/en/api-reference/system/app_image_format.rst
View File

@ -25,6 +25,7 @@ To get the list of your image segments, please run the following command:
Image version: 1
Entry point: 40080ea4
13 segments
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
@ -38,7 +39,8 @@ To get the list of your image segments, please run the following command:
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
Checksum: e8 (valid)Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
Checksum: e8 (valid)
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
You can also see the information on segments in the ESP-IDF logs while your application is booting:
@ -67,7 +69,7 @@ You can also see the information on segments in the ESP-IDF logs while your appl
For more details on the type of memory segments and their address ranges, see *{IDF_TARGET_NAME} Technical Reference Manual* > *System and Memory* > *Internal Memory* [`PDF <{IDF_TARGET_TRM_EN_URL}#sysmem>`__].
3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.
4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from the first byte and up to this field. The length of this field is 32 bytes.
4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of the SHA256 hash is calculated on the range from the first byte and up to this field. The length of this field is 32 bytes.
5. If the option :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` is set to ECDSA then the application image will have an additional 68 bytes for an ECDSA signature, which includes:
* version word (4 bytes),
@ -88,11 +90,11 @@ The ``DROM`` segment of the application binary starts with the :cpp:type:`esp_ap
* ``project_name`` is filled from ``PROJECT_NAME``. ``*``
* ``time`` and ``date`` - compile time and date.
* ``idf_ver`` - version of ESP-IDF. ``*``
* ``app_elf_sha256`` - contains sha256 for the application ELF file.
* ``app_elf_sha256`` - contains sha256 hash for the application ELF file.
``*`` - The maximum length is 32 characters, including null-termination character. For example, if the length of ``PROJECT_NAME`` exceeds 31 characters, the excess characters will be disregarded.
This structure is useful for identification of images uploaded OTA because it has a fixed offset = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`). As soon as a device receives the first fragment containing this structure, it has all the information to determine whether the update should be continued or not.
This structure is useful for identification of images uploaded via Over-the-Air (OTA) updates because it has a fixed offset = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`). As soon as a device receives the first fragment containing this structure, it has all the information to determine whether the update should be continued with or not.
To obtain the :cpp:type:`esp_app_desc_t` structure for the currently running application, use :cpp:func:`esp_app_get_description`.

2
docs/en/api-reference/system/app_trace.rst
View File

@ -5,7 +5,7 @@ Overview
--------
IDF provides a useful feature for program behavior analysis called **Application Level Tracing**. The feature can be enabled in menuconfig and allows transfer of arbitrary data between the host and {IDF_TARGET_NAME} via JTAG interface with minimal overhead on program execution.
Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
Developers can use this library to send application specific state of execution to the host and receive commands or other type of information in the opposite direction at runtime. The main use cases of this library are:
1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`
2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`

24
docs/en/api-reference/system/console.rst
View File

@ -2,7 +2,7 @@ Console
=======
:link_to_translation:`zh_CN:[中文]`
ESP-IDF provides ``console`` component, which includes building blocks needed to develop an interactive console over serial port. This component includes following facilities:
ESP-IDF provides ``console`` component, which includes building blocks needed to develop an interactive console over serial port. This component includes the following features:
- Line editing, provided by `linenoise`_ library. This includes handling of backspace and arrow keys, scrolling through command history, command auto-completion, and argument hints.
- Splitting of command line into arguments.
@ -12,12 +12,12 @@ ESP-IDF provides ``console`` component, which includes building blocks needed to
.. note::
These facilities can be used together or independently. For example, it is possible to use line editing and command registration features, but use ``getopt`` or custom code for argument parsing, instead of `argtable3`_. Likewise, it is possible to use simpler means of command input (such as ``fgets``) together with the rest of the means for command splitting and argument parsing.
These features can be used together or independently. For example, it is possible to use line editing and command registration features, but use ``getopt`` or custom code for argument parsing, instead of `argtable3`_. Likewise, it is possible to use simpler means of command input (such as ``fgets``) together with the rest of the means for command splitting and argument parsing.
Line editing
------------
Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key.
Line editing feature lets users compose commands by typing them, erasing symbols using the 'backspace' key, navigating within the command using the left/right keys, navigating to previously typed commands using the up/down keys, and performing autocompletion using the 'tab' key.
.. note::
@ -36,7 +36,7 @@ Linenoise library does not need explicit initialization. However, some configura
:cpp:func:`linenoiseSetMultiLine`
Switch between single line and multi line editing modes. In single line mode, if the length of the command exceeds the width of the terminal, the command text is scrolled within the line to show the end of the text. In this case the beginning of the text is hidden. Single line needs less data to be sent to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side, editing commands and copying command text from terminal in single line mode is harder. Default is single line mode.
Switch between single line and multi line editing modes. In single line mode, if the length of the command exceeds the width of the terminal, the command text is scrolled within the line to show the end of the text. In this case the beginning of the text is hidden. Single line mode needs less data to be sent to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side, editing commands and copying command text from terminal in single line mode is harder. Default is single line mode.
:cpp:func:`linenoiseAllowEmpty`
@ -44,7 +44,7 @@ Linenoise library does not need explicit initialization. However, some configura
:cpp:func:`linenoiseSetMaxLineLen`
Set maximum length of the line for linenoise library. Default length is 4096. If you need optimize RAM memory usage, you can do it by this function by setting a value less than default 4 KB.
Set maximum length of the line for linenoise library. Default length is 4096. The default value can be updated to optimize RAM memory usage.
Main loop
@ -52,7 +52,7 @@ Main loop
:cpp:func:`linenoise`
In most cases, console applications have some form of read/eval loop. :cpp:func:`linenoise` is the single function which handles user's key presses and returns completed line once 'enter' key is pressed. As such, it handles the 'read' part of the loop.
In most cases, console applications have some form of read/eval loop. :cpp:func:`linenoise` is the single function which handles user's key presses and returns the completed line once the 'enter' key is pressed. As such, it handles the 'read' part of the loop.
:cpp:func:`linenoiseFree`
@ -64,7 +64,7 @@ Hints and completions
:cpp:func:`linenoiseSetCompletionCallback`
When user presses 'tab' key, linenoise library invokes completion callback. The callback should inspect the contents of the command typed so far and provide a list of possible completions using calls to :cpp:func:`linenoiseAddCompletion` function. :cpp:func:`linenoiseSetCompletionCallback` function should be called to register this completion callback, if completion feature is desired.
When the user presses the 'tab' key, linenoise library invokes the completion callback. The callback should inspect the contents of the command typed so far and provide a list of possible completions using calls to :cpp:func:`linenoiseAddCompletion` function. :cpp:func:`linenoiseSetCompletionCallback` function should be called to register this completion callback, if completion feature is desired.
``console`` component provides a ready made function to provide completions for registered commands, :cpp:func:`esp_console_get_completion` (see below).
@ -74,11 +74,11 @@ Hints and completions
:cpp:func:`linenoiseSetHintsCallback`
Whenever user input changes, linenoise invokes hints callback. This callback can inspect the command line typed so far, and provide a string with hints (which can include list of command arguments, for example). The library then displays the hint text on the same line where editing happens, possibly with a different color.
Whenever user input changes, linenoise invokes the hints callback. This callback can inspect the command line typed so far, and provide a string with hints (which can include list of command arguments, for example). The library then displays the hint text on the same line where editing happens, possibly with a different color.
:cpp:func:`linenoiseSetFreeHintsCallback`
If hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the function which performs such cleanup should be registered via :cpp:func:`linenoiseSetFreeHintsCallback`.
If the hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the function which performs such cleanup should be registered via :cpp:func:`linenoiseSetFreeHintsCallback`.
History
@ -86,7 +86,7 @@ History
:cpp:func:`linenoiseHistorySetMaxLen`
This function sets the number of most recently typed commands to be kept in memory. Users can navigate the history using up/down arrows.
This function sets the number of most recently typed commands to be kept in memory. Users can navigate the history using the up/down arrows keys.
:cpp:func:`linenoiseHistoryAdd`
@ -174,14 +174,14 @@ After that, you can register your own commands with :cpp:func:`esp_console_cmd_r
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
Likewise, if your REPL environment is based on USB_SERIAL_JTAG device, you only need to call :cpp:func:`esp_console_new_repl_usb_serial_jtag` at first step. And call other functions as usual.
Likewise, if your REPL environment is based on USB_SERIAL_JTAG device, you only need to call :cpp:func:`esp_console_new_repl_usb_serial_jtag` at first step. Then call other functions as usual.
Application Example
-------------------
Example application illustrating usage of the ``console`` component is available in :example:`system/console` directory. This example shows how to initialize UART and VFS functions, set up linenoise library, read and handle commands from UART, and store command history in Flash. See README.md in the example directory for more details.
Besides that, ESP-IDF contains several useful examples which based on `console` component and can be treated as "tools" when developing applications. For example, :example:`peripherals/i2c/i2c_tools`, :example:`wifi/iperf`.
Besides that, ESP-IDF contains several useful examples which are based on the `console` component and can be treated as "tools" when developing applications. For example, :example:`peripherals/i2c/i2c_tools`, :example:`wifi/iperf`.
API Reference

6
docs/en/api-reference/system/esp_event.rst
View File

@ -22,7 +22,7 @@ These two appear prominently in the event loop library APIs.
Using this library roughly entails the following flow:
1. A user defines a function that should run when an event is posted to a loop. This function is referred to as the event handler. It should have the same signature as :cpp:type:`esp_event_handler_t`.
1. A user defines a function that should run when an event is posted to a loop. This function is referred to as the event handler. It should have the same signature as :cpp:type:`esp_event_handler_t`.
2. An event loop is created using :cpp:func:`esp_event_loop_create`, which outputs a handle to the loop of type :cpp:type:`esp_event_loop_handle_t`. Event loops created using this API are referred to as user event loops. There is, however, a special type of event loop called the default event loop which are discussed :ref:`here <esp-event-default-loops>`.
3. Components register event handlers to the loop using :cpp:func:`esp_event_handler_register_with`. Handlers can be registered with multiple loops, more on that :ref:`here <esp-event-handler-registration>`.
4. Event sources post an event to the loop using :cpp:func:`esp_event_post_to`.
@ -105,8 +105,8 @@ Event base definition:
.. note::
In IDF, the base identifiers for system events are uppercase and are postfixed with ``_EVENT``. For example, the base for Wi-Fi events is declared and defined
as ``WIFI_EVENT``, the ethernet event base ``ETHERNET_EVENT``, and so on. The purpose is to have event bases look like constants (although
they are global variables considering the defintions of macros ``ESP_EVENT_DECLARE_BASE`` and ``ESP_EVENT_DEFINE_BASE``).
as ``WIFI_EVENT``, the Ethernet event base ``ETHERNET_EVENT``, and so on. The purpose is to have event bases look like constants (although
they are global variables considering the definitions of macros ``ESP_EVENT_DECLARE_BASE`` and ``ESP_EVENT_DEFINE_BASE``).
For event ID's, declaring them as enumerations is recommended. Once again, for visibility, these are typically placed in public header files.

2
docs/en/api-reference/system/esp_function_with_shared_stack.rst
View File

@ -12,7 +12,7 @@ Usage
:cpp:func:`esp_execute_shared_stack_function` takes four arguments:
- a mutex object allocated by the caller, which is used to protect if the same function shares its allocated stack
- a pointer to the top of stack used for that fuction
- a pointer to the top of stack used for that function
- the size of stack in bytes
- a pointer to the shared stack function

10
docs/en/api-reference/system/esp_timer.rst
View File

@ -3,7 +3,7 @@ High Resolution Timer (ESP Timer)
{IDF_TARGET_HR_TIMER:default = "SYSTIMER", esp32 = "LAC timer"}
{IDF_TARGET_HR_TIMER_Resolution:default = "Not updated", esp32 = "64", esp32s2 = "64", esp32c3 = "52", esp32s3 = "52", esp32c2 = "52"}
{IDF_TARGET_HR_TIMER_Resolution:default = "Not updated", esp32 = "64", esp32s2 = "64", esp32c3 = "52", esp32s3 = "52", esp32c2 = "52", esp32c6 = "52"}
Overview
@ -68,9 +68,9 @@ The context switch will be done after all ISR dispatch timers have been processe
The esp_timer is constructed based on a hardware timer called *systimer*, which is able to generate the alarm event and interact with the :doc:`ETM </api-reference/peripherals/etm>` module. You can call :cpp:func:`esp_timer_new_etm_alarm_event` to get the corresponding ETM event handle.
For how to connect the event to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
To know more about how to connect the event to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
esp_timer during the light sleep
esp_timer during light sleep
--------------------------------
During light sleep, the esp_timer counter stops and no callback functions are called.
@ -86,7 +86,7 @@ you can use the `skip_unhandled_events` option during :cpp:func:`esp_timer_creat
When the `skip_unhandled_events` is true, if a periodic timer expires one or more times during light sleep
then only one callback is called on wake.
Using the `skip_unhandled_events` option with `automatic light sleep` (see :doc:`Power Management APIs <power_management>`) helps to reduce the consumption of the system when it is in light sleep. The duration of light sleep is also determined by esp_timers. Timers with `skip_unhandled_events` option will not wake up the system.
Using the `skip_unhandled_events` option with `automatic light sleep` (see :doc:`Power Management APIs <power_management>`) helps to reduce the power consumption of the system when it is in light sleep. The duration of light sleep is also determined by esp_timers. Timers with `skip_unhandled_events` option will not wake up the system.
Handling callbacks
------------------
@ -94,7 +94,7 @@ Handling callbacks
esp_timer is designed to achieve a high-resolution low latency timer and the ability to handle delayed events.
If the timer is late then the callback will be called as soon as possible, it will not be lost.
In the worst case, when the timer has not been processed for more than one period (for periodic timers),
in this case the callbacks will be called one after the other without waiting for the set period.
the callbacks will be called one after the other without waiting for the set period.
This can be bad for some applications, and the `skip_unhandled_events` option was introduced to eliminate this behavior.
If `skip_unhandled_events` is set then a periodic timer that has expired multiple times without being able to call
the callback will still result in only one callback event once processing is possible.

12
docs/en/api-reference/system/freertos.rst
View File

@ -19,7 +19,7 @@ Vanilla FreeRTOS allows ports and applications to configure the kernel by adding
ESP-IDF FreeRTOS can be configured in the project configuration menu (``idf.py menuconfig``) under ``Component Config/FreeRTOS``. The following section highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF FreeRTOS configurations, see :doc:`/api-reference/kconfig`
- :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on CPU0. Note that this is **not equivalent to running Vanilla FreeRTOS**. Futhermore, this option may affect behavior of components other than :component:`freertos`. For more details regarding the effects of running ESP-IDF FreeRTOS on a single core, refer to :ref:`freertos-smp-single-core`. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
- :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF 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 ESP-IDF FreeRTOS on a single core, refer to :ref:`freertos-smp-single-core`. Alternatively, users can also search for occurrences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.
- :ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions within a wrapper function. In the case that a task function mistakenly returns (i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the wrapper function. The wrapper function will then log an error and abort the application, as illustrated below::
@ -66,7 +66,7 @@ The ``main`` task is one of multiple tasks that are automatically spawned by ESP
* - IPC Tasks (``ipcx``)
- CPU0 and CPU1
- 24
- IPC tasks created for (and pinned to ) each CPU. IPC tasks are used to implement the IPC feature. See :doc:`/api-reference/system/ipc` for more details.
- IPC tasks created for (and pinned to) each CPU. IPC tasks are used to implement the Inter-processor Call (IPC) feature. See :doc:`/api-reference/system/ipc` for more details.
.. only:: CONFIG_FREERTOS_UNICORE
@ -82,10 +82,10 @@ The ``main`` task is one of multiple tasks that are automatically spawned by ESP
- CPU0
- 1
- Task that simply calls ``app_main``. This task will self delete when ``app_main`` returns
* - Idle Tasks (``IDLEx``)
- CPU0 and CPU1
* - Idle Tasks (``IDLE``)
- CPU0
- 0
- Idle task created for (and pinned to) each CPU
- Idle task created for CPU0
.. note::
@ -111,7 +111,6 @@ Timer API
.. include-build-file:: inc/timers.inc
Event Group API
---------------
@ -122,7 +121,6 @@ Stream Buffer API
.. include-build-file:: inc/stream_buffer.inc
Message Buffer API
------------------

8
docs/en/api-reference/system/freertos_additions.rst
View File

@ -13,7 +13,7 @@ This document describes these supplemental features added to ESP-IDF. This docum
Overview
--------
ESP-IDF FreeRTOS is modified version of based on the Xtensa port of FreeRTOS v10.4.3 with significant modifications for SMP compatibility (see :doc:`ESP-IDF FreeRTOS SMP Changes<../../api-guides/freertos-smp>`). However, various new features specific to ESP-IDF FreeRTOS have been added. The features are as follows:
ESP-IDF adds various new features to supplement the capabilities of ESP-IDF FreeRTOS as follows:
- **Ring buffers**: Ring buffers provide a FIFO buffer that can accept entries of arbitrary lengths.
- **ESP-IDF Tick and Idle Hooks**: ESP-IDF provides multiple custom tick interrupt hooks and idle task hooks that are more numerous and more flexible when compared to FreeRTOS tick and idle hooks.
@ -26,7 +26,7 @@ ESP-IDF FreeRTOS is modified version of based on the Xtensa port of FreeRTOS v10
Ring Buffers
------------
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for storing items. The ring buffer provides API to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. The ring buffers are split into the three following types:
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for storing items. The ring buffer provides APIs to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. The ring buffers are split into the three following types:
**No-Split buffers** will guarantee that an item is stored in contiguous memory and will not attempt to split an item under any circumstances. Use No-Split buffers when items must occupy contiguous memory. *Only this buffer type allows you to get the data item address and write to the item by yourself.* Refer the documentation of the functions :cpp:func:`xRingbufferSendAcquire` and :cpp:func:`xRingbufferSendComplete` for more details.
@ -398,7 +398,7 @@ Therefore, ESP-IDF tick and idle hooks are provided to supplement the features o
- Multiple hooks can be registered (with a maximum of 8 hooks of each type per CPU)
- On multi-core targets, the hooks can be asymmetric, meaning different hooks can be registered to each CPU
ESP-IDF hooks can be registered and deregistered using the following API:
ESP-IDF hooks can be registered and deregistered using the following APIs:
- For tick hooks:
@ -425,7 +425,7 @@ Vanilla FreeRTOS provides a Thread Local Storage Pointers (TLSP) feature. These
- get a task's TLSPs by calling :cpp:func:`pvTaskGetThreadLocalStoragePointer` during the task's lifetime.
- free the memory pointed to by the TLSPs before the task is deleted.
However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESP-IDF FreeRTOS provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks are called automatically when a task is deleted, thus allows the TLSP memory to be cleaned up without needing to add the cleanup logic explicitly to the code of every task.
However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESP-IDF FreeRTOS provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks are called automatically when a task is deleted, thus allowing the TLSP memory to be cleaned up without needing to add the cleanup logic explicitly to the code of every task.
The TLSP deletion callbacks are set in a similar fashion to the TLSPs themselves.

2
docs/en/api-reference/system/mem_alloc.rst
View File

@ -34,7 +34,7 @@ DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and wr
When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls cpp:func:`heap_caps_malloc_default(size)`. This will allocate memory with capability ``MALLOC_CAP_DEFAULT``, which is byte-addressable.
Because malloc uses the capabilities-based allocation system, memory allocated using :cpp:func:`heap_caps_malloc` can be freed by calling
Because ``malloc()`` uses the capabilities-based allocation system, memory allocated using :cpp:func:`heap_caps_malloc` can be freed by calling
the standard ``free()`` function.
Available Heap

6
docs/en/api-reference/system/misc_system_api.rst
View File

@ -3,12 +3,12 @@ Miscellaneous System APIs
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"}
{IDF_TARGET_CPU_RESET_DES: default="both CPUs are reset", esp32c3="the CPU is reset", esp32c2="the CPU is reset"}
{IDF_TARGET_CPU_RESET_DES: default="the CPU is reset", esp32="both CPUs are reset", esp32s3="both CPUs are reset"}
Software Reset
--------------
To perform software reset of the chip, the :cpp:func:`esp_restart` function is provided. When the function is called, execution of the program stops, {IDF_TARGET_CPU_RESET_DES}, and the application is loaded by the bootloader and starts execution again.
To perform software reset of the chip, the :cpp:func:`esp_restart` function is provided. When the function is called, execution of the program stops, {IDF_TARGET_CPU_RESET_DES}, the application is loaded by the bootloader and starts execution again.
Additionally, the :cpp:func:`esp_register_shutdown_handler` function can register a routine that will be automatically called before a restart (that is triggered by :cpp:func:`esp_restart`) occurs. This is similar to the functionality of ``atexit`` POSIX function.
@ -23,7 +23,7 @@ Heap Memory
Two heap-memory-related functions are provided:
* :cpp:func:`esp_get_free_heap_size` returns the current size of free heap memory.
* :cpp:func:`esp_get_minimum_free_heap_size` returns the minimum size of free heap memory that has ever been available (i.e., the smallest size of free heap memory in the applications lifetime).
* :cpp:func:`esp_get_minimum_free_heap_size` returns the minimum size of free heap memory that has ever been available (i.e., the smallest size of free heap memory in the application's lifetime).
Note that ESP-IDF supports multiple heaps with different capabilities. The functions mentioned in this section return the size of heap memory that can be allocated using the ``malloc`` family of functions. For further information about heap memory, see :doc:`Heap Memory Allocation <mem_alloc>`.

16
docs/en/api-reference/system/system_time.rst
View File

@ -2,11 +2,11 @@ System Time
===========
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz"}
{IDF_TARGET_INT_OSC_FRE:default="Not updated", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz"}
{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz"}
{IDF_TARGET_INT_OSC_FRE:default="Not updated", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"}
{IDF_TARGET_INT_OSC_FRE_DIVIDED:default="Not updated", esp32="~33 kHz", esp32s2="~33 kHz", esp32s3="~68 kHz", esp32c3="~68 kHz", esp32c2="~68 kHz"}
{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N"}
{IDF_TARGET_EXT_OSC_PIN:default="Not updated", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0"}
{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N", esp32c6="XTAL_32K_P and XTAL_32K_N"}
{IDF_TARGET_EXT_OSC_PIN:default="Not updated", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"}
{IDF_TARGET_HARDWARE_DESIGN_URL:default="Not updated",esp32="`ESP32 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf#page=11>`_", esp32s2="`ESP32-S2 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_en.pdf#page=10>`_", esp32s3="`ESP32-S3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_en.pdf#page=11>`_", esp32c3="`ESP32-C3 Hardware Design Guidelines <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_en.pdf#page=9>`_"}
@ -44,13 +44,15 @@ The RTC timer has the following clock sources:
- ``External 32 kHz oscillator at {IDF_TARGET_EXT_OSC_PIN} pin``: Allows using 32 kHz clock generated by an external circuit. The external clock signal must be connected to the {IDF_TARGET_EXT_OSC_PIN} pin. The amplitude should be less than 1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the range of 0.1 < Vcm < 0.5xVamp, where Vamp stands for signal amplitude. In this case, the {IDF_TARGET_EXT_OSC_PIN} pin cannot be used as a GPIO pin.
- ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components.
:not esp32c6: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components.
:esp32c6: - ``Internal 32 kHz RC oscillator``
The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_RTC_CLK_SRC` in project configuration.
.. Need to add esp32c2 hardware design guideline link after it is publsihed.
.. Need to add esp32c2 and esp32c6 hardware design guideline link after it is publsihed.
.. only:: not esp32c2
.. only:: not esp32c2 and not esp32c6
More details about the wiring requirements for the external crystal or external oscillator, please refer to {IDF_TARGET_HARDWARE_DESIGN_URL}.