Merge branch 'bugfix/fix_gpio_etm_multi_task_v5.3' into 'release/v5.3'

fix(gpio_etm): allow one GPIO binds to multiple ETM tasks (v5.3)

See merge request espressif/esp-idf!30455

Author: suda-morris

components/esp_driver_gpio/include/driver/gpio_etm.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,38 +13,49 @@
 extern "C" {
 #endif
 
+#define GPIO_ETM_EVENT_EDGE_TYPES   3   /*!< GPIO ETM edge events are POS/NEG/ANY */
+#define GPIO_ETM_TASK_ACTION_TYPES  3   /*!< GPIO ETM action tasks are SET/CLEAR/TOGGLE */
+
 /**
  * @brief GPIO edges that can be used as ETM event
  */
 typedef enum {
-    GPIO_ETM_EVENT_EDGE_POS, /*!< A rising edge on the GPIO will generate an ETM event signal */
-    GPIO_ETM_EVENT_EDGE_NEG, /*!< A falling edge on the GPIO will generate an ETM event signal */
-    GPIO_ETM_EVENT_EDGE_ANY, /*!< Any edge on the GPIO can generate an ETM event signal */
+    GPIO_ETM_EVENT_EDGE_POS = 1,    /*!< A rising edge on the GPIO will generate an ETM event signal */
+    GPIO_ETM_EVENT_EDGE_NEG,        /*!< A falling edge on the GPIO will generate an ETM event signal */
+    GPIO_ETM_EVENT_EDGE_ANY,        /*!< Any edge on the GPIO can generate an ETM event signal */
 } gpio_etm_event_edge_t;
 
 /**
  * @brief GPIO ETM event configuration
+ *
+ * If more than one kind of ETM edge event want to be triggered on the same GPIO pin, you can configure them together.
+ * It helps to save GPIO ETM event channel resources for other GPIOs.
  */
 typedef struct {
-    gpio_etm_event_edge_t edge; /*!< Which kind of edge can trigger the ETM event module */
+    union {
+        gpio_etm_event_edge_t edge;                                 /*!< Which kind of edge can trigger the ETM event module */
+        gpio_etm_event_edge_t edges[GPIO_ETM_EVENT_EDGE_TYPES];     /*!< Array of kinds of edges to trigger the ETM event module on the same GPIO */
+    };
 } gpio_etm_event_config_t;
 
 /**
  * @brief Create an ETM event object for the GPIO peripheral
  *
  * @note The created ETM event object can be deleted later by calling `esp_etm_del_event`
  * @note The newly created ETM event object is not bind to any GPIO, you need to call `gpio_etm_event_bind_gpio` to bind the wanted GPIO
+ * @note Every success call to this function will acquire a free GPIO ETM event channel
  *
  * @param[in] config GPIO ETM event configuration
  * @param[out] ret_event Returned ETM event handle
+ * @param[out] ...  Other returned ETM event handles if any (the order of the returned event handles is aligned with the array order in field `edges` in `gpio_etm_event_config_t`)
  * @return
  *      - ESP_OK: Create ETM event successfully
  *      - ESP_ERR_INVALID_ARG: Create ETM event failed because of invalid argument
  *      - ESP_ERR_NO_MEM: Create ETM event failed because of out of memory
  *      - ESP_ERR_NOT_FOUND: Create ETM event failed because all events are used up and no more free one
  *      - ESP_FAIL: Create ETM event failed because of other reasons
  */
-esp_err_t gpio_new_etm_event(const gpio_etm_event_config_t *config, esp_etm_event_handle_t *ret_event);
+esp_err_t gpio_new_etm_event(const gpio_etm_event_config_t *config, esp_etm_event_handle_t *ret_event, ...);
 
 /**
  * @brief Bind the GPIO with the ETM event
@@ -65,16 +76,21 @@ esp_err_t gpio_etm_event_bind_gpio(esp_etm_event_handle_t event, int gpio_num);
  * @brief GPIO actions that can be taken by the ETM task
  */
 typedef enum {
-    GPIO_ETM_TASK_ACTION_SET, /*!< Set the GPIO level to high */
-    GPIO_ETM_TASK_ACTION_CLR, /*!< Clear the GPIO level to low */
-    GPIO_ETM_TASK_ACTION_TOG, /*!< Toggle the GPIO level */
+    GPIO_ETM_TASK_ACTION_SET = 1,   /*!< Set the GPIO level to high */
+    GPIO_ETM_TASK_ACTION_CLR,       /*!< Clear the GPIO level to low */
+    GPIO_ETM_TASK_ACTION_TOG,       /*!< Toggle the GPIO level */
 } gpio_etm_task_action_t;
 
 /**
  * @brief GPIO ETM task configuration
+ *
+ * If multiple actions wants to be added to the same GPIO pin, you have to configure all the GPIO ETM tasks together.
  */
 typedef struct {
-    gpio_etm_task_action_t action; /*!< Which action to take by the ETM task module */
+    union {
+        gpio_etm_task_action_t action;                                  /*!< Action to take by the ETM task module */
+        gpio_etm_task_action_t actions[GPIO_ETM_TASK_ACTION_TYPES];     /*!< Array of actions to take by the ETM task module on the same GPIO */
+    };
 } gpio_etm_task_config_t;
 
 /**
@@ -83,17 +99,19 @@ typedef struct {
  * @note The created ETM task object can be deleted later by calling `esp_etm_del_task`
  * @note The GPIO ETM task works like a container, a newly created ETM task object doesn't have GPIO members to be managed.
  *       You need to call `gpio_etm_task_add_gpio` to put one or more GPIOs to the container.
+ * @note Every success call to this function will acquire a free GPIO ETM task channel
  *
  * @param[in] config GPIO ETM task configuration
  * @param[out] ret_task Returned ETM task handle
+ * @param[out] ...  Other returned ETM task handles if any (the order of the returned task handles is aligned with the array order in field `actions` in `gpio_etm_task_config_t`)
  * @return
  *      - ESP_OK: Create ETM task successfully
  *      - ESP_ERR_INVALID_ARG: Create ETM task failed because of invalid argument
  *      - ESP_ERR_NO_MEM: Create ETM task failed because of out of memory
  *      - ESP_ERR_NOT_FOUND: Create ETM task failed because all tasks are used up and no more free one
  *      - ESP_FAIL: Create ETM task failed because of other reasons
  */
-esp_err_t gpio_new_etm_task(const gpio_etm_task_config_t *config, esp_etm_task_handle_t *ret_task);
+esp_err_t gpio_new_etm_task(const gpio_etm_task_config_t *config, esp_etm_task_handle_t *ret_task, ...);
 
 /**
  * @brief Add GPIO to the ETM task.