Merge branch 'feat/intr_alloc_force_intrno' into 'master'

feat(esp_hw_support): add the possibility to allocate two sources to the same interrupt line

Closes IDF-9552

See merge request espressif/esp-idf!35473

Author: o-marshmallow

components/esp_hw_support/include/esp_intr_alloc.h

@@ -94,7 +94,7 @@ extern "C" {
  *                   the int can be left enabled while the flash cache is disabled.
  *
  * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);
 
@@ -108,7 +108,7 @@ esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);
  * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
  *
  * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_reserve(int intno, int cpu);
 
@@ -131,9 +131,10 @@ esp_err_t esp_intr_reserve(int intno, int cpu);
  * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
  *               choice of interrupts that this routine can choose from. If this value
  *               is 0, it will default to allocating a non-shared interrupt of level
- *               1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
- *               interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
- *               from this function with the interrupt disabled.
+ *               1, 2 or 3. If ESP_INTR_FLAG_SHARED mask is provided, a shared interrupt of
+ *               the given level will be allocated (or level 1 if not specified).
+ *               Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the
+ *               interrupt disabled.
  * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
  *               is requested, because these types of interrupts aren't C-callable.
  * @param arg    Optional argument for passed to the interrupt handler
@@ -143,13 +144,13 @@ esp_err_t esp_intr_reserve(int intno, int cpu);
  *
  * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
  *         ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
 
 
 /**
- * @brief Allocate an interrupt with the given parameters.
+ * @brief Allocate an interrupt with the given parameters, including an interrupt status register.
  *
  *
  * This essentially does the same as esp_intr_alloc, but allows specifying a register and mask
@@ -165,9 +166,10 @@ esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *ar
  * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
  *               choice of interrupts that this routine can choose from. If this value
  *               is 0, it will default to allocating a non-shared interrupt of level
- *               1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
- *               interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
- *               from this function with the interrupt disabled.
+ *               1, 2 or 3. If ESP_INTR_FLAG_SHARED mask is provided, a shared interrupt of
+ *               the given level will be allocated (or level 1 if not specified).
+ *               Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the
+ *               interrupt disabled.
  * @param intrstatusreg The address of an interrupt status register
  * @param intrstatusmask A mask. If a read of address intrstatusreg has any of the bits
  *               that are 1 in the mask set, the ISR will be called. If not, it will be
@@ -181,11 +183,92 @@ esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *ar
  *
  * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
  *         ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
 
 
+/**
+ * @brief Allocate an interrupt with the given parameters that can be bound to an existing interrupt handler.
+ *
+ *
+ * This function does the same as esp_intr_alloc, but allows specifying a previously allocated handler as
+ * the interrupt to share with the given source. This can be very handy to treat two pre-determined interrupt
+ * sources in the same interrupt handler. The interrupt will be allocated on the same core as the given
+ * `shared_handle`. Moreover, make sure to specify the same interrupt level as the one being used by `shared_handle`
+ * to prevent any failure from this function.
+ *
+ * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
+ *               sources, as defined in soc/soc.h, or one of the internal
+ *               ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
+ * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
+ *               choice of interrupts that this routine can choose from. If this value
+ *               is 0, it will default to allocating a non-shared interrupt of level
+ *               1, 2 or 3. If ESP_INTR_FLAG_SHARED mask is provided, a shared interrupt of
+ *               the given level will be allocated (or level 1 if not specified).
+ *               Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the
+ *               interrupt disabled.
+ * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
+ *               is requested, because these types of interrupts aren't C-callable.
+ * @param arg    Optional argument for passed to the interrupt handler
+ * @param shared_handle Previously allocated interrupt to share the CPU interrupt line with. If NULL,
+ *               calling this function equivalent to esp_intr_alloc, else, ESP_INTR_FLAG_SHARED must
+ *               be provided in the flags parameter.
+ * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
+ *               used to request details or free the interrupt. Can be NULL if no handle
+ *               is required.
+ *
+ * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
+ *         ESP_ERR_NOT_FOUND No free interrupt found with the specified flasg or the given level is different
+ *                           from the one assigned to the share_handle parameter.
+ *         ESP_OK on success
+ */
+esp_err_t esp_intr_alloc_bind(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t shared_handle, intr_handle_t *ret_handle);
+
+
+/**
+ * @brief Allocate an interrupt with the given parameters, including an interrupt status register, that can
+ *        be bound to an existing interrupt handler
+ *
+ *
+ * This function does the same as esp_intr_alloc_intrstatus, but allows specifying a previously allocated handler as
+ * the interrupt to share with the given source. This can be very handy to treat two pre-determined interrupt
+ * sources in the same interrupt handler. The interrupt will be allocated on the same core as the given
+ * `shared_handle`. Moreover, make sure to specify the same interrupt level as the one being used by `shared_handle`
+ * to prevent any failure from this function.
+ *
+ * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
+ *               sources, as defined in soc/soc.h, or one of the internal
+ *               ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
+ * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
+ *               choice of interrupts that this routine can choose from. If this value
+ *               is 0, it will default to allocating a non-shared interrupt of level
+ *               1, 2 or 3. If ESP_INTR_FLAG_SHARED mask is provided, a shared interrupt of
+ *               the given level will be allocated (or level 1 if not specified).
+ *               Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the
+ *               interrupt disabled.
+ * @param intrstatusreg The address of an interrupt status register
+ * @param intrstatusmask A mask. If a read of address intrstatusreg has any of the bits
+ *               that are 1 in the mask set, the ISR will be called. If not, it will be
+ *               skipped.
+ * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
+ *               is requested, because these types of interrupts aren't C-callable.
+ * @param arg    Optional argument for passed to the interrupt handler
+ * @param shared_handle Previously allocated interrupt to share the CPU interrupt line with. If NULL,
+ *               calling this function equivalent to esp_intr_alloc, else, ESP_INTR_FLAG_SHARED must
+ *               be provided in the flags parameter.
+ * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
+ *               used to request details or free the interrupt. Can be NULL if no handle
+ *               is required.
+ *
+ * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
+ *         ESP_ERR_NOT_FOUND No free interrupt found with the specified flasg or the given level is different
+ *                           from the one assigned to the share_handle parameter.
+ *         ESP_OK on success
+ */
+esp_err_t esp_intr_alloc_intrstatus_bind(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler,
+                                         void *arg, intr_handle_t shared_handle, intr_handle_t *ret_handle);
+
 /**
  * @brief Disable and free an interrupt.
  *
@@ -202,7 +285,7 @@ esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusre
  *
  * @return ESP_ERR_INVALID_ARG the handle is NULL
  *         ESP_FAIL failed to release this handle
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_free(intr_handle_t handle);
 
@@ -239,7 +322,7 @@ int esp_intr_get_intno(intr_handle_t handle);
  * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
  *
  * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_disable(intr_handle_t handle);
 
@@ -252,7 +335,7 @@ esp_err_t esp_intr_disable(intr_handle_t handle);
  * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
  *
  * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_enable(intr_handle_t handle);
 
@@ -266,7 +349,7 @@ esp_err_t esp_intr_enable(intr_handle_t handle);
  *                   Handlers residing in IRAM can be called when cache is disabled.
  *
  * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
- *         ESP_OK otherwise
+ *         ESP_OK on success
  */
 esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram);
 

components/esp_hw_support/intr_alloc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -72,6 +72,16 @@ struct shared_vector_desc_t {
 #define VECDESC_FL_INIRAM       (1<<1)
 #define VECDESC_FL_SHARED       (1<<2)
 #define VECDESC_FL_NONSHARED    (1<<3)
+#define VECDESC_FL_TYPE_MASK    (0xf)
+
+#if SOC_CPU_HAS_FLEXIBLE_INTC
+/* On targets that have configurable interrupts levels, store the assigned level in the flags */
+#define VECDESC_FL_LEVEL_SHIFT  (8)
+/* Allocate 4 bits in the flag */
+#define VECDESC_FL_LEVEL_MASK   (0xf)
+/* Help to extract the level from flags */
+#define VECDESC_FL_LEVEL(flags) (((flags) >> VECDESC_FL_LEVEL_SHIFT) & VECDESC_FL_LEVEL_MASK)
+#endif
 
 //Pack using bitfields for better memory use
 struct vector_desc_t {
@@ -212,7 +222,7 @@ esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_int_ram)
         portEXIT_CRITICAL(&spinlock);
         return ESP_ERR_NO_MEM;
     }
-    vd->flags = VECDESC_FL_SHARED;
+    vd->flags = (vd->flags & ~VECDESC_FL_TYPE_MASK) | VECDESC_FL_SHARED;
     if (is_int_ram) {
         vd->flags |= VECDESC_FL_INIRAM;
     }
@@ -258,7 +268,17 @@ static bool is_vect_desc_usable(vector_desc_t *vd, int flags, int cpu, int force
         return false;
     }
 
-#ifndef SOC_CPU_HAS_FLEXIBLE_INTC
+#if SOC_CPU_HAS_FLEXIBLE_INTC
+    /* On target that have configurable interrupts levels, check if the interrupt has already
+     * been allocated, and if yes, make sure the levels are compatible. */
+    const int vector_lvl = VECDESC_FL_LEVEL(vd->flags);
+    /* A non-zero value means the level has already been set prior to this allocation, make
+     * sure the current level matches what we need. */
+    if (vector_lvl != 0 && (flags & (1 << vector_lvl)) == 0) {
+        ALCHLOG("....Unusable: incompatible priority");
+        return false;
+    }
+#else
     //Check if the interrupt priority is acceptable
     if (!(flags & (1 << intr_desc.priority))) {
         ALCHLOG("....Unusable: incompatible priority");
@@ -480,8 +500,8 @@ bool esp_intr_ptr_in_isr_region(void* ptr)
 
 
 //We use ESP_EARLY_LOG* here because this can be called before the scheduler is running.
-esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler,
-                                    void *arg, intr_handle_t *ret_handle)
+esp_err_t esp_intr_alloc_intrstatus_bind(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler,
+                                    void *arg, intr_handle_t shared_handle, intr_handle_t *ret_handle)
 {
     intr_handle_data_t *ret=NULL;
     int force = -1;
@@ -509,7 +529,10 @@ esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusre
     if ((flags & ESP_INTR_FLAG_IRAM) && handler && !esp_intr_ptr_in_isr_region(handler)) {
         return ESP_ERR_INVALID_ARG;
     }
-
+    //Shared handler must be passed with share interrupt flag
+    if (shared_handle != NULL && (flags & ESP_INTR_FLAG_SHARED) == 0) {
+        return ESP_ERR_INVALID_ARG;
+    }
     //Default to prio 1 for shared interrupts. Default to prio 1, 2 or 3 for non-shared interrupts.
     if ((flags & ESP_INTR_FLAG_LEVELMASK) == 0) {
         if (flags & ESP_INTR_FLAG_SHARED) {
@@ -549,7 +572,17 @@ esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusre
 
     portENTER_CRITICAL(&spinlock);
     uint32_t cpu = esp_cpu_get_core_id();
-    //See if we can find an interrupt that matches the flags.
+    if (shared_handle != NULL) {
+        /* Sanity check, should not occur */
+        if (shared_handle->vector_desc == NULL) {
+            portEXIT_CRITICAL(&spinlock);
+            return ESP_ERR_INVALID_ARG;
+        }
+        /* If a shared vector was given, force the current interrupt source to same CPU interrupt line */
+        force = shared_handle->vector_desc->intno;
+        /* Allocate the interrupt on the same core as the given handle */
+        cpu = shared_handle->vector_desc->cpu;
+    }
     int intr = get_available_int(flags, cpu, force, source);
     if (intr == -1) {
         //None found. Bail out.
@@ -640,6 +673,7 @@ esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusre
 #if SOC_CPU_HAS_FLEXIBLE_INTC
     //Extract the level from the interrupt passed flags
     int level = esp_intr_flags_to_level(flags);
+    vd->flags |= level << VECDESC_FL_LEVEL_SHIFT;
     esp_cpu_intr_set_priority(intr, level);
 
     if (flags & ESP_INTR_FLAG_EDGE) {
@@ -671,6 +705,13 @@ esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusre
     return ESP_OK;
 }
 
+esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler,
+                                    void *arg, intr_handle_t *ret_handle)
+{
+    return esp_intr_alloc_intrstatus_bind(source, flags, intrstatusreg, intrstatusmask, handler, arg, NULL, ret_handle);
+}
+
+
 esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle)
 {
     /*
@@ -681,6 +722,13 @@ esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *ar
     return esp_intr_alloc_intrstatus(source, flags, 0, 0, handler, arg, ret_handle);
 }
 
+
+esp_err_t esp_intr_alloc_bind(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t shared_handle, intr_handle_t *ret_handle)
+{
+    return esp_intr_alloc_intrstatus_bind(source, flags, 0, 0, handler, arg, shared_handle, ret_handle);
+}
+
+
 esp_err_t IRAM_ATTR esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram)
 {
     if (!handle) {
@@ -790,6 +838,10 @@ static esp_err_t intr_free_for_current_cpu(intr_handle_t handle)
         //we save.(We can also not use the same exit path for empty shared ints anymore if we delete
         //the desc.) For now, just mark it as free.
         handle->vector_desc->flags &= ~(VECDESC_FL_NONSHARED|VECDESC_FL_RESERVED|VECDESC_FL_SHARED);
+#if SOC_CPU_HAS_FLEXIBLE_INTC
+        //Clear the assigned level
+        handle->vector_desc->flags &= ~(VECDESC_FL_LEVEL_MASK << VECDESC_FL_LEVEL_SHIFT);
+#endif
         handle->vector_desc->source = ETS_INTERNAL_UNUSED_INTR_SOURCE;
 
         //Also kill non_iram mask bit.
@@ -802,11 +854,17 @@ static esp_err_t intr_free_for_current_cpu(intr_handle_t handle)
 
 int esp_intr_get_intno(intr_handle_t handle)
 {
+    if (handle == NULL || handle->vector_desc == NULL) {
+        return -1;
+    }
     return handle->vector_desc->intno;
 }
 
 int esp_intr_get_cpu(intr_handle_t handle)
 {
+    if (handle == NULL || handle->vector_desc == NULL) {
+        return -1;
+    }
     return handle->vector_desc->cpu;
 }
 

components/esp_hw_support/test_apps/esp_hw_support_unity_tests/main/CMakeLists.txt

@@ -22,7 +22,7 @@ if(CONFIG_SOC_ETM_SUPPORTED)
 endif()
 
 if(CONFIG_SOC_GPTIMER_SUPPORTED)
-    list(APPEND SRC "test_intr_alloc.c")
+    list(APPEND srcs "test_intr_alloc.c")
 endif()
 
 # In order for the cases defined by `TEST_CASE` to be linked into the final elf,