Merge branch 'doc/async_memcpy_code_sample' into 'master'

docs: async_memcpy: use real function names in the example code

See merge request espressif/esp-idf!20469

docs/en/api-guides/bootloader.rst

@@ -14,7 +14,7 @@ The ESP-IDF Software Bootloader performs the following functions:
 
 Bootloader is located at the address {IDF_TARGET_BOOTLOADER_OFFSET} in the flash.
 
-For a full description of the startup process including the the ESP-IDF bootloader, see :doc:`startup`.
+For a full description of the startup process including the ESP-IDF bootloader, see :doc:`startup`.
 
 .. _bootloader-compatibility:
 

docs/en/api-guides/esp-wifi-mesh.rst

@@ -570,7 +570,7 @@ An ESP-WIFI-MESH network channel switch can be triggered by either the router or
 
 Root Node Triggered
 """""""""""""""""""
-**A root node triggered channel switch can only occur when the ESP-WIFI-MESH network is not connected to a router**. By calling :cpp:func:`esp_mesh_switch_channel`, the root node will set an initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is then received by second layer nodes, and forwarded downstream in the their own beacon frames.
+**A root node triggered channel switch can only occur when the ESP-WIFI-MESH network is not connected to a router**. By calling :cpp:func:`esp_mesh_switch_channel`, the root node will set an initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is then received by second layer nodes, and forwarded downstream in their own beacon frames.
 
 Router Triggered
 """"""""""""""""

docs/en/api-guides/wifi.rst

@@ -508,7 +508,7 @@ The scan type and other per-scan attributes are configured by :cpp:func:`esp_wif
        - min=0, max>0: scan dwells on each channel for ``max`` ms.
        - min>0, max>0: the minimum time the scan dwells on each channel is ``min`` ms. If no AP is found during this time frame, the scan switches to the next channel. Otherwise, the scan dwells on the channel for ``max`` ms.
 
-       If you want to improve the performance of the the scan, you can try to modify these two parameters.
+       If you want to improve the performance of the scan, you can try to modify these two parameters.
 
 
 There are also some global scan attributes which are configured by API :cpp:func:`esp_wifi_set_config()`, refer to `Station Basic Configuration`_

docs/en/api-reference/peripherals/mcpwm.rst

@@ -806,7 +806,7 @@ The MCPWM capture channel can inform the user when there's a valid edge detected
 
 - :cpp:member:`mcpwm_capture_event_callbacks_t::on_cap` sets callback function for the capture channel when a valid edge is detected.
 
-The callback function will provide event specific data of type :cpp:type:`mcpwm_capture_event_data_t`, so that you can get the the edge of the capture signal in :cpp:member:`mcpwm_capture_event_data_t::cap_edge` and the count value of that moment in :cpp:member:`mcpwm_capture_event_data_t::cap_value`.
+The callback function will provide event specific data of type :cpp:type:`mcpwm_capture_event_data_t`, so that you can get the edge of the capture signal in :cpp:member:`mcpwm_capture_event_data_t::cap_edge` and the count value of that moment in :cpp:member:`mcpwm_capture_event_data_t::cap_value`.
 
 The callback function is called within the ISR context, so is should **not** attempt to block (e.g., make sure that only FreeRTOS APIs with ``ISR`` suffix is called within the function).
 

docs/en/api-reference/peripherals/pcnt.rst

@@ -173,7 +173,7 @@ The PCNT unit features filters to ignore possible short glitches in the signals.
 
 You can enable the glitch filter for PCNT unit by calling :cpp:func:`pcnt_unit_set_glitch_filter` with the filter configuration provided above. Particularly, you can disable the glitch filter later by calling :cpp:func:`pcnt_unit_set_glitch_filter` with a `NULL` filter configuration.
 
-This function should be called when the the unit is in the init state. Otherwise, it will return :c:macro:`ESP_ERR_INVALID_STATE` error.
+This function should be called when the unit is in the init state. Otherwise, it will return :c:macro:`ESP_ERR_INVALID_STATE` error.
 
 .. note::
 

docs/en/api-reference/peripherals/twai.rst

@@ -329,7 +329,7 @@ Message Fields and Flags
 
 The TWAI driver distinguishes different types of messages by using the various bit field members of the :cpp:type:`twai_message_t` structure. These bit field members determine whether a message is in standard or extended format, a remote frame, and the type of transmission to use when transmitting such a message.
 
-These bit field members can also be toggled using the the `flags` member of :cpp:type:`twai_message_t` and the following message flags:
+These bit field members can also be toggled using the `flags` member of :cpp:type:`twai_message_t` and the following message flags:
 
 .. list-table::
     :widths: 30 70

docs/en/api-reference/storage/spi_flash_override_driver.rst

@@ -32,7 +32,7 @@ Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver Lis
 
       1. Please check whether your flash chip have the capabilities listed in `spi_flash_caps_t` by checking the flash datasheet.
       2. Write a function named `spi_flash_chip_***(vendor)_get_caps`. Take the example below as a reference. (if the flash support `suspend` and `read unique id`).
-      3. Points the the pointer `get_chip_caps` (in `spi_flash_chip_t`) to the function mentioned above.
+      3. Points the pointer `get_chip_caps` (in `spi_flash_chip_t`) to the function mentioned above.
 
       .. code-block:: c
 

docs/en/api-reference/system/async_memcpy.rst

@@ -44,29 +44,30 @@ Send memory copy request
 
 :cpp:func:`esp_async_memcpy` is the API to send memory copy request to DMA engine. It must be called after driver is installed successfully. This API is thread safe, so it can be called from different tasks.
 
-Different from the libc version of `memcpy`, user should also pass a callback to :cpp:func:`esp_async_memcpy`, if it's necessary to be notified when the memory copy is done. The callback is executed in the ISR context, make sure you won't violate the the restriction applied to ISR handler.
+Different from the libc version of ``memcpy``, user should also pass a callback to :cpp:func:`esp_async_memcpy`, if it's necessary to be notified when the memory copy is done. The callback is executed in the ISR context, make sure you won't violate the restriction applied to ISR handler.
 
-Besides that, the callback function should reside in IRAM space by applying `IRAM_ATTR` attribute. The prototype of the callback function is :cpp:type:`async_memcpy_isr_cb_t`, please note that, the callback function should return true if it wakes up a high priority task by some API like :cpp:func:`xSemaphoreGiveFromISR`.
+Besides that, the callback function should reside in IRAM space by applying ``IRAM_ATTR`` attribute. The prototype of the callback function is :cpp:type:`async_memcpy_isr_cb_t`, please note that, the callback function should return true if it wakes up a high priority task by some API like :cpp:func:`xSemaphoreGiveFromISR`.
 
 .. highlight:: c
 
 ::
 
-    Semphr_Handle_t semphr; //already initialized in somewhere
-
     // Callback implementation, running in ISR context
     static IRAM_ATTR bool my_async_memcpy_cb(async_memcpy_t mcp_hdl, async_memcpy_event_t *event, void *cb_args)
     {
         SemaphoreHandle_t sem = (SemaphoreHandle_t)cb_args;
         BaseType_t high_task_wakeup = pdFALSE;
-        SemphrGiveInISR(semphr, &high_task_wakeup); // high_task_wakeup set to pdTRUE if some high priority task unblocked
+        xSemaphoreGiveFromISR(semphr, &high_task_wakeup); // high_task_wakeup set to pdTRUE if some high priority task unblocked
         return high_task_wakeup == pdTRUE;
     }
 
+    // Create a semaphore used to report the completion of async memcpy
+    SemaphoreHandle_t semphr = xSemaphoreCreateBinary();
+
     // Called from user's context
     ESP_ERROR_CHECK(esp_async_memcpy(driver_handle, to, from, copy_len, my_async_memcpy_cb, my_semaphore));
-    //Do something else here
-    SemphrTake(my_semaphore, ...); //wait until the buffer copy is done
+    // Do something else here
+    xSemaphoreTake(my_semaphore, portMAX_DELAY); // Wait until the buffer copy is done
 
 Uninstall driver (optional)
 ---------------------------

docs/en/api-reference/system/ulp_instruction_set.rst

@@ -1225,7 +1225,7 @@ The detailed description of all instructions is presented below:
 
 .. only:: esp32s2 or esp32s3
 
-  This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the the register, as seen from the ULP, can be calculated from the address of the same register on the PeriBUS1 as follows::
+  This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the register, as seen from the ULP, can be calculated from the address of the same register on the PeriBUS1 as follows::
 
     addr_ulp = (addr_peribus1 - DR_REG_RTCCNTL_BASE) / 4
 

docs/en/api-reference/system/ulp_macros.rst

@@ -28,7 +28,7 @@ The ``program`` array is an array of ``ulp_insn_t``, i.e. ULP coprocessor instru
 
 To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label.
 
-Implementation note: these ``M_`` preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the the extra ``ulp_insn_t`` token which contains the label numer.
+Implementation note: these ``M_`` preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the extra ``ulp_insn_t`` token which contains the label numer.
 
 Here is an example of using labels and branches::
 

docs/en/migration-guides/release-5.x/peripherals.rst

@@ -119,7 +119,7 @@ Timer Group Driver
 
 Timer Group driver has been redesigned into :doc:`GPTimer <../../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer. 
 
-Although it's recommended to use the the new driver APIs, the legacy driver is still available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will trigger the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
+Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will trigger the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
 
 .. code-block:: text