feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

dedic_gpio: mention the overhead of using driver API

Browse Source
This commit is contained in:
morris
2022-05-05 14:46:29 +08:00
parent 3a5fdfe35a
commit 407b693646
2 changed files with 34 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docs_not_updated/esp32c2.txt
View File

@@ -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

77
docs/en/api-reference/peripherals/dedic_gpio.rst
View File

@@ -72,49 +72,8 @@ GPIO Bundle Operations
* - Read the value that output from bundle
- :cpp:func:`dedic_gpio_bundle_read_in`
.. only:: esp32s2
.. note::
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::
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::
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>`__].
.. only:: SOC_DEDIC_GPIO_HAS_INTERRUPT
Interrupt Handling
------------------
Dedicated GPIO can also trigger interrupt on specific input event. All supported events are defined in :cpp:type:`dedic_gpio_intr_type_t`.
One can enable and register interrupt callback by calling :cpp:func:`dedic_gpio_bundle_set_interrupt_and_callback`. The prototype of the callback function is defined in :cpp:type:`dedic_gpio_isr_callback_t`. Keep in mind, the callback should return true if there's some high priority task woken up.
.. highlight:: c
::
// user defined ISR callback
IRAM_ATTR bool dedic_gpio_isr_callback(dedic_gpio_bundle_handle_t bundle, uint32_t index, void *args)
{
SemaphoreHandle_t sem = (SemaphoreHandle_t)args;
BaseType_t high_task_wakeup = pdFALSE;
xSemaphoreGiveFromISR(sem, &high_task_wakeup);
return high_task_wakeup == pdTRUE;
}
// enable positive edge interrupt on the second GPIO in the bundle (i.e. index 1)
ESP_ERROR_CHECK(dedic_gpio_bundle_set_interrupt_and_callback(bundle, BIT(1), DEDIC_GPIO_INTR_POS_EDGE, dedic_gpio_isr_callback, sem));
// wait for done semaphore
xSemaphoreTake(sem, portMAX_DELAY);
.. 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
------------------------------------------
@@ -150,12 +109,40 @@ For advanced users, they can always manipulate the GPIOs by writing assembly cod
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.
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:: esp32s2
.. only:: SOC_DEDIC_GPIO_HAS_INTERRUPT
Interrupt Handling
------------------
Dedicated GPIO can also trigger interrupt on specific input event. All supported events are defined in :cpp:type:`dedic_gpio_intr_type_t`.
One can enable and register interrupt callback by calling :cpp:func:`dedic_gpio_bundle_set_interrupt_and_callback`. The prototype of the callback function is defined in :cpp:type:`dedic_gpio_isr_callback_t`. Keep in mind, the callback should return true if there's some high priority task woken up.
.. highlight:: c
::
// user defined ISR callback
IRAM_ATTR bool dedic_gpio_isr_callback(dedic_gpio_bundle_handle_t bundle, uint32_t index, void *args)
{
SemaphoreHandle_t sem = (SemaphoreHandle_t)args;
BaseType_t high_task_wakeup = pdFALSE;
xSemaphoreGiveFromISR(sem, &high_task_wakeup);
return high_task_wakeup == pdTRUE;
}
// enable positive edge interrupt on the second GPIO in the bundle (i.e. index 1)
ESP_ERROR_CHECK(dedic_gpio_bundle_set_interrupt_and_callback(bundle, BIT(1), DEDIC_GPIO_INTR_POS_EDGE, dedic_gpio_isr_callback, sem));
// wait for done semaphore
xSemaphoreTake(sem, portMAX_DELAY);
.. only:: SOC_DEDIC_GPIO_HAS_INTERRUPT
Application Example
-------------------