From 12f4ea94aac377306613904cb3f80eb0fe1b30d3 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 3 Oct 2022 17:59:34 +0200 Subject: [PATCH 1/2] docs: async_memcpy: use real function names in the example code --- docs/en/api-reference/system/async_memcpy.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/en/api-reference/system/async_memcpy.rst b/docs/en/api-reference/system/async_memcpy.rst index c04592db6e..3e3b343b7e 100644 --- a/docs/en/api-reference/system/async_memcpy.rst +++ b/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 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) --------------------------- From 8048d596a27cb7b74005e24ec971eae0c0a751fb Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Wed, 5 Oct 2022 11:57:52 +0200 Subject: [PATCH 2/2] docs: remove duplicate "the" articles --- docs/en/api-guides/bootloader.rst | 2 +- docs/en/api-guides/esp-wifi-mesh.rst | 2 +- docs/en/api-guides/wifi.rst | 2 +- docs/en/api-reference/peripherals/mcpwm.rst | 2 +- docs/en/api-reference/peripherals/pcnt.rst | 2 +- docs/en/api-reference/peripherals/twai.rst | 2 +- docs/en/api-reference/storage/spi_flash_override_driver.rst | 2 +- docs/en/api-reference/system/async_memcpy.rst | 2 +- docs/en/api-reference/system/ulp_instruction_set.rst | 2 +- docs/en/api-reference/system/ulp_macros.rst | 2 +- docs/en/migration-guides/release-5.x/peripherals.rst | 2 +- 11 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index ede6b483ed..2715e5d6d7 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/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: diff --git a/docs/en/api-guides/esp-wifi-mesh.rst b/docs/en/api-guides/esp-wifi-mesh.rst index 81e7599c1a..03284305a8 100644 --- a/docs/en/api-guides/esp-wifi-mesh.rst +++ b/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 """""""""""""""" diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 989403df1c..861a9b9e52 100644 --- a/docs/en/api-guides/wifi.rst +++ b/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`_ diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index 44f84c4f40..017d934ac1 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/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). diff --git a/docs/en/api-reference/peripherals/pcnt.rst b/docs/en/api-reference/peripherals/pcnt.rst index accee48fb6..1892b5ed61 100644 --- a/docs/en/api-reference/peripherals/pcnt.rst +++ b/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:: diff --git a/docs/en/api-reference/peripherals/twai.rst b/docs/en/api-reference/peripherals/twai.rst index 2667b27058..3988210c06 100644 --- a/docs/en/api-reference/peripherals/twai.rst +++ b/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 diff --git a/docs/en/api-reference/storage/spi_flash_override_driver.rst b/docs/en/api-reference/storage/spi_flash_override_driver.rst index 8f3e7a84b2..c1da0dbc23 100644 --- a/docs/en/api-reference/storage/spi_flash_override_driver.rst +++ b/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 diff --git a/docs/en/api-reference/system/async_memcpy.rst b/docs/en/api-reference/system/async_memcpy.rst index 3e3b343b7e..d5a4813571 100644 --- a/docs/en/api-reference/system/async_memcpy.rst +++ b/docs/en/api-reference/system/async_memcpy.rst @@ -44,7 +44,7 @@ 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`. diff --git a/docs/en/api-reference/system/ulp_instruction_set.rst b/docs/en/api-reference/system/ulp_instruction_set.rst index 5b0be07f77..abe268a9f3 100644 --- a/docs/en/api-reference/system/ulp_instruction_set.rst +++ b/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 diff --git a/docs/en/api-reference/system/ulp_macros.rst b/docs/en/api-reference/system/ulp_macros.rst index 22a5b5eb2b..150f2a2921 100644 --- a/docs/en/api-reference/system/ulp_macros.rst +++ b/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:: diff --git a/docs/en/migration-guides/release-5.x/peripherals.rst b/docs/en/migration-guides/release-5.x/peripherals.rst index 495649109b..f421466359 100644 --- a/docs/en/migration-guides/release-5.x/peripherals.rst +++ b/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