dedic_gpio: mention the overhead of using driver API

docs/docs_not_updated/esp32c2.txt

@@ -91,7 +91,6 @@ api-reference/peripherals/secure_element
 api-reference/peripherals/temp_sensor
 api-reference/peripherals/spi_slave_hd
 api-reference/peripherals/i2c
-api-reference/peripherals/dedic_gpio
 api-reference/peripherals/index
 api-reference/kconfig
 api-reference/network/esp_openthread

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

@@ -72,20 +72,47 @@ GPIO Bundle Operations
    * - Read the value that output from bundle
      - :cpp:func:`dedic_gpio_bundle_read_in`
 
+.. note::
+    Using the above functions might not get a high GPIO flip speed because of the overhead of function calls and the bit operations involved inside. Users can try `Manipulate GPIOs by Assembly Code  <#manipulate-gpios-by-writing-assembly-code>`__ instead to reduce the overhead but should take care of the thread safety by themselves.
+
+Manipulate GPIOs by Writing Assembly Code
+------------------------------------------
+
+For advanced users, they can always manipulate the GPIOs by writing assembly code or invoking CPU Low Level APIs. The usual procedure could be:
+
+1. Allocate a GPIO bundle: :cpp:func:`dedic_gpio_new_bundle`
+2. Query the mask occupied by that bundle: :cpp:func:`dedic_gpio_get_out_mask` or/and :cpp:func:`dedic_gpio_get_in_mask`
+3. Call CPU LL apis (e.g. `cpu_ll_write_dedic_gpio_mask`) or write assembly code with that mask
+4. The fasted way of toggling IO is to use the dedicated "set/clear" instructions:
+
+    .. only:: esp32s2 or esp32s3
+
+        - Set bits of GPIO: ``set_bit_gpio_out imm[7:0]``
+        - Clear bits of GPIO: ``clr_bit_gpio_out imm[7:0]``
+        - Note: Immediate value width depends on the number of dedicated GPIO channels
+
+    .. only:: esp32c2 or esp32c3
+
+        - Set bits of GPIO: ``csrrsi rd, csr, imm[4:0]``
+        - Clear bits of GPIO: ``csrrci rd, csr, imm[4:0]``
+        - Note: Can only control the lowest 4 GPIO channels
+
 .. only:: esp32s2
 
-    .. note::
+    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
-        The functions above just wrap the customized instructions defined for {IDF_TARGET_NAME}, for the details of those instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__].
 
 .. only:: esp32s3
 
-    .. note::
+    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *Processor Instruction Extensions (PIE) (to be added later)* [`PDF <{IDF_TARGET_TRM_EN_URL}#pie>`__].
-        The functions above just wrap the customized instructions defined for {IDF_TARGET_NAME}, for the details of those instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *Processor Instruction Extensions (PIE) (to be added later)* [`PDF <{IDF_TARGET_TRM_EN_URL}#pie>`__].
 
 .. only:: esp32c2 or esp32c3
 
-    .. note::
+    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *ESP-RISC-V CPU* [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__].
-        The functions above just wrap the customized instructions defined for {IDF_TARGET_NAME}, for the details of those instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *ESP-RISC-V CPU* [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__].
+
+Some of the dedicated CPU instructions are also wrapped inside `soc/cpu_ll.h` as helper inline functions.
+
+.. note::
+    Writing assembly code in application could make your code hard to port between targets, because those customized instructions are not guaranteed to remain the same format on different targets.
 
 .. only:: SOC_DEDIC_GPIO_HAS_INTERRUPT
 
@@ -115,47 +142,7 @@ GPIO Bundle Operations
         // wait for done semaphore
         xSemaphoreTake(sem, portMAX_DELAY);
 
-
+.. only:: SOC_DEDIC_GPIO_HAS_INTERRUPT
-Manipulate GPIOs by Writing Assembly Code
-------------------------------------------
-
-For advanced users, they can always manipulate the GPIOs by writing assembly code or invoking CPU Low Level APIs. The usual procedure could be:
-
-1. Allocate a GPIO bundle: :cpp:func:`dedic_gpio_new_bundle`
-2. Query the mask occupied by that bundle: :cpp:func:`dedic_gpio_get_out_mask` or/and :cpp:func:`dedic_gpio_get_in_mask`
-3. Call CPU LL apis (e.g. `cpu_ll_write_dedic_gpio_mask`) or write assembly code with that mask
-4. The fasted way of toggling IO is to use the dedicated "set/clear" instructions:
-
-    .. only:: esp32s2 or esp32s3
-
-        - Set bits of GPIO: ``set_bit_gpio_out imm[7:0]``
-        - Clear bits of GPIO: ``clr_bit_gpio_out imm[7:0]``
-        - Note: Immediate value width depends on the number of dedicated GPIO channels
-
-    .. only:: esp32c2 or esp32c3
-
-        - Set bits of GPIO: ``csrrsi rd, csr, imm[4:0]``
-        - Clear bits of GPIO: ``csrrci rd, csr, imm[4:0]``
-        - Note: Can only control the lowest 4 GPIO channels
-
-.. only:: esp32s2
-
-    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *IO MUX and GPIO Matrix (GPIO, IO_MUX)* [`PDF <{IDF_TARGET_TRM_EN_URL}#iomuxgpio>`__]. 
-
-.. only:: esp32s3
-
-    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *Processor Instruction Extensions (PIE) (to be added later)* [`PDF <{IDF_TARGET_TRM_EN_URL}#pie>`__]. 
-
-.. only:: esp32c2 or esp32c3
-
-    For details of supported dedicated GPIO instructions, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > *ESP-RISC-V CPU* [`PDF <{IDF_TARGET_TRM_EN_URL}#riscvcpu>`__].
-
-The supported dedicated CPU instructions are also wrapped inside `soc/cpu_ll.h` as helper inline functions.
-
-.. note::
-    Writing assembly code in application could make your code hard to port between targets, because those customized instructions are not guaranteed to remain the same format on different targets.
-
-.. only:: esp32s2
 
     Application Example
     -------------------