POSSIBLY BREAKING change to uPort layer: add GPIO interrupt support. (#1189)

* POSSIBLY BREAKING change to uPort layer: add GPIO interrupt support.

The GPIO portion of the port layer is updated to include GPIO interrupt support.  Specifically, three new fields are added to the uPortGpioConfig_t structure that is passed to uPortGpioConfig(), allowing an interrupt callback and either edge or level (where supported) triggering to be configured.  This is required for up-coming support of use of the Data Ready pin when reading from a GNSS device.

This change is backwards compatible with existing ports in that there is also a uPortGpioInterruptSupported() function with a WEAK implementation that returns false; the ubxlib code will not attempt to use GPIO interrupts on platforms where uPortGpioInterruptSupported() returns false.  Note that interrupts are not implemented for Windows and Linux (including Zephyr on Linux), since interrupts are not accessible on these platforms.

The POSSIBLY BREAKING part of the change is that, if anyone has used uPortGpioConfig() in their application and passed into it a uPortGpioConfig_t structure that has NOT been assigned to U_PORT_GPIO_CONFIG_DEFAULT, the three new fields will be left floating and anything may happen.  Please make sure that, if you have used uPortGpioConfig() in your application code, you have assigned your uPortGpioConfig_t to U_PORT_GPIO_CONFIG_DEFAULT on creation; all of the ubxlib code does this.

Author: RobMeades

port/api/u_port_gpio.h

@@ -108,6 +108,41 @@ typedef struct {
                         last pin on GPIO chip 0 were pin 15 then the
                         first pin on GPIO chip 1 would likely be pin 16,
                         it could not be pin 0 again. */
+    void (*pInterrupt)(void); /**< if non-NULL and interrupts are supported
+                                   by the platform then the pin will be
+                                   configured as an interrupt; NULL is the
+                                   default. If you have your own port you
+                                   only need to implement interrupt functionality
+                                   if you wish to use the "data ready" feature
+                                   of the GNSS interface, enabling this MCU to
+                                   sleep while waiting for a response from
+                                   a GNSS device; GPIO interrupts are otherwise
+                                   not used within ubxlib.  Note also that
+                                   some platforms may require additional
+                                   compile-time configuration for this to work,
+                                   e.g. for STM32Cube it is necessary to make
+                                   the correct HW interrupts available to
+                                   this code, search for
+                                   U_CFG_HW_EXTI_ to find out more; also,
+                                   platforms may apply additional restrictions,
+                                   e.g. an interrupt pin may not be able to
+                                   be set as input/output (this is the case
+                                   with ESP32), perhaps only certain pins
+                                   can be set as interrupts, etc. */
+    bool interruptActiveLow; /**< if true then the pin is assumed
+                                  to be an active-low interrupt, else
+                                  (the default) if is assumed to be an
+                                  active-high interrupt; ignored if
+                                  pInterrupt is NULL or interrupts are
+                                  not supported by the platform. */
+    bool interruptLevel;  /**< if true then the pin will be configured
+                               as a level-triggered interrupt, else
+                               it will be configured as an edge-triggered
+                               interrupt (the default); ignored if
+                               pInterrupt is NULL or interrupts are not
+                               supported by the platform, not all platforms
+                               support level-triggered interrupts (e.g.
+                               STM32F4 does not). */
 } uPortGpioConfig_t;
 
 /** Default values for the above.
@@ -117,7 +152,8 @@ typedef struct {
                                    U_PORT_GPIO_PULL_MODE_NONE,          \
                                    U_PORT_GPIO_DRIVE_MODE_NORMAL,       \
                                    U_PORT_GPIO_DRIVE_CAPABILITY_STRONG, \
-                                   -1}
+                                   -1,                                  \
+                                   NULL, false, false}
 
 /** Compilers won't generally allow myConfig = #U_PORT_GPIO_CONFIG_DEFAULT;
  * to be done anywhere other than where myConfig is declared.  This macro
@@ -128,7 +164,10 @@ typedef struct {
                                          (pConfig)->pullMode = U_PORT_GPIO_PULL_MODE_NONE;                 \
                                          (pConfig)->driveMode = U_PORT_GPIO_DRIVE_MODE_NORMAL;             \
                                          (pConfig)->driveCapability = U_PORT_GPIO_DRIVE_CAPABILITY_STRONG; \
-                                         (pConfig)->index = -1
+                                         (pConfig)->index = -1;                                            \
+                                         (pConfig)->pInterrupt = NULL;                                     \
+                                         (pConfig)->interruptActiveLow = false;                            \
+                                         (pConfig)->interruptLevel = false;
 
 /* ----------------------------------------------------------------
  * FUNCTIONS
@@ -168,6 +207,13 @@ int32_t uPortGpioSet(int32_t pin, int32_t level);
  */
 int32_t uPortGpioGet(int32_t pin);
 
+/** Should return true if interrupts are supported; where not
+ * supported a weak implementation will return false.
+ *
+ * @return true if interrupts are supported, else false.
+ */
+bool uPortGpioInterruptSupported();
+
 #ifdef __cplusplus
 }
 #endif

port/platform/common/automation/DATABASE.md

@@ -50,7 +50,7 @@ The table below defines the instances of test hardware available on the `ubxlib`
 | 13.1.0| Nordic DK board (NRF52840) + EVK           |  NRF52840   | nrf52840dk_nrf52840 | Zephyr |       | M10                              | port at_client ubx_protocol gnss spartn     | gnss          | U_CFG_APP_GNSS_I2C=1 U_CFG_TEST_PIN_GNSS_RESET_N=29 U_CFG_TEST_UART_B=0 U_DEBUG_UTILS_DUMP_THREADS |
 | 13.1.1| Nordic DK board (NRF52840) + EVK           |  NRF52840   | nrf52840dk_nrf52840 | Zephyr |       |                                  | port at_client ubx_protocol spartn          | short_range   | U_CFG_TEST_UART_B=0 U_DEBUG_UTILS_DUMP_THREADS |
 | 13.1.2| Nordic DK board (NRF52840) + EVK, DT cfg   |  NRF52840   | ubx_evkninab3_nrf52840 | Zephyr |    |                                  | port                                        |               | U_CFG_APP_FILTER=zephyrPort. U_CFG_PPP_ENABLE U_CFG_TEST_UART_A=-1 U_CFG_TEST_PIN_A=-1 U_CFG_TEST_PIN_B=-1 U_CFG_TEST_PIN_C=-1 |
-| 14    | STM32F407 Discovery + EVK, Cat M1          |   STM32F4   |             | STM32Cube |            | LEXI_R422 M9                     | port device network sock security cell mqtt_client http_client gnss location || CMSIS_V2 U_CELL_CFG_TEST_CELL_DISABLE_MNO_PROFILE U_CFG_TEST_CELL_PWR_DISABLE U_CFG_TEST_GNSS_ASSIST_NOW U_GNSS_MGA_TEST_HAS_FLASH U_LOCATION_TEST_DISABLE U_CFG_1V8_SIM_WORKAROUND HSE_VALUE=8000000U U_CFG_APP_GNSS_SPI=2 U_CFG_APP_PIN_GNSS_SPI_MOSI=0x1F U_CFG_APP_PIN_GNSS_SPI_MISO=0x1E U_CFG_APP_PIN_GNSS_SPI_CLK=0x1D U_CFG_APP_PIN_GNSS_SPI_SELECT=0x1C U_CFG_TEST_PIN_GNSS_RESET_N=0x40 U_CFG_TEST_PIN_C=0x3F U_CFG_APP_GNSS_UART=-1 U_CFG_APP_PIN_GNSS_ENABLE_POWER=-1 U_CFG_TEST_UART_A=-1 U_CFG_APP_PIN_C030_ENABLE_3V3=-1 U_CFG_APP_PIN_CELL_RESET=-1 U_CFG_APP_CELL_UART=3 U_CFG_APP_PIN_CELL_TXD=0x38 U_CFG_APP_PIN_CELL_RXD=0x39 U_CFG_APP_PIN_CELL_RTS=-1 U_CFG_APP_PIN_CELL_CTS=-1 U_DEBUG_UTILS_DUMP_THREADS |
+| 14    | STM32F407 Discovery + EVK, Cat M1          |   STM32F4   |             | STM32Cube |            | LEXI_R422 M9                     | port device network sock security cell mqtt_client http_client gnss location || CMSIS_V2 U_CELL_CFG_TEST_CELL_DISABLE_MNO_PROFILE U_CFG_TEST_CELL_PWR_DISABLE U_CFG_TEST_GNSS_ASSIST_NOW U_GNSS_MGA_TEST_HAS_FLASH U_LOCATION_TEST_DISABLE U_CFG_1V8_SIM_WORKAROUND HSE_VALUE=8000000U U_CFG_APP_GNSS_SPI=2 U_CFG_APP_PIN_GNSS_SPI_MOSI=0x1F U_CFG_APP_PIN_GNSS_SPI_MISO=0x1E U_CFG_APP_PIN_GNSS_SPI_CLK=0x1D U_CFG_APP_PIN_GNSS_SPI_SELECT=0x1C U_CFG_TEST_PIN_GNSS_RESET_N=0x40 U_CFG_TEST_PIN_C=0x3F U_CFG_APP_GNSS_UART=-1 U_CFG_APP_PIN_GNSS_ENABLE_POWER=-1 U_CFG_HW_EXTI_8_AVAILABLE=1 U_CFG_HW_EXTI_15_AVAILABLE=1 U_CFG_TEST_UART_A=-1 U_CFG_APP_PIN_C030_ENABLE_3V3=-1 U_CFG_APP_PIN_CELL_RESET=-1 U_CFG_APP_CELL_UART=3 U_CFG_APP_PIN_CELL_TXD=0x38 U_CFG_APP_PIN_CELL_RXD=0x39 U_CFG_APP_PIN_CELL_RTS=-1 U_CFG_APP_PIN_CELL_CTS=-1 U_DEBUG_UTILS_DUMP_THREADS |
 | 15.1  | Nordic DK board (NRF52840) + EVK           |  NRF52840   | nrf52840dk_nrf52840 | Zephyr |       | M9                               | port device network ble short_range gnss    |               | U_CFG_TEST_UART_A=-1 U_CFG_APP_GNSS_SPI=3 U_CFG_APP_PIN_GNSS_SPI_SELECT=29 U_CFG_TEST_PIN_GNSS_RESET_N=37 U_GNSS_MGA_TEST_HAS_FLASH U_BLE_TEST_CFG_REMOTE_SPS_CENTRAL=2462ABB6CC42p U_DEBUG_UTILS_DUMP_THREADS |
 | 16    | STM32F407 Discovery                        |   STM32F4   |             | STM32Cube |            | M10                              | port ubx_protocol gnss spartn geofence      | gnss          | U_CFG_GEOFENCE HSE_VALUE=8000000U U_PORT_TEST_DISABLE_I2C U_GNSS_MGA_TEST_DISABLE_DATABASE U_CFG_APP_GNSS_I2C=1 U_CFG_TEST_PIN_GNSS_RESET_N=0x40 U_CFG_APP_GNSS_UART=-1 U_CFG_APP_PIN_GNSS_ENABLE_POWER=-1 U_CFG_TEST_PIN_A=-1 U_CFG_TEST_PIN_B=-1 U_CFG_TEST_PIN_C=-1 U_CFG_TEST_UART_A=-1 U_CFG_APP_PIN_C030_ENABLE_3V3=-1 U_CFG_APP_PIN_CELL_RESET=-1 U_DEBUG_UTILS_DUMP_THREADS |
 | 17.1.0| Nordic NRF5340 DK board                    |   NRF5340   | nrf5340dk_nrf5340_cpuapp | Zephyr  | | M9                               | port device network ble short_range lib_common ubx_protocol gnss spartn || U_CFG_APP_GNSS_SPI=2 U_CFG_APP_SPI_MAX_SEGMENT_SIZE=32 U_CFG_APP_PIN_GNSS_SPI_SELECT=46 U_CFG_TEST_PIN_GNSS_RESET_N=37 U_GNSS_MGA_TEST_HAS_FLASH U_CFG_BLE_MODULE_INTERNAL U_BLE_TEST_CFG_REMOTE_SPS_CENTRAL=2462ABB6CC42p U_BLE_TEST_CFG_REMOTE_SPS_PERIPHERAL=2462ABB6EAC6p U_CFG_APP_SHORT_RANGE_ROLE=1 U_DEBUG_UTILS_DUMP_THREADS |

port/platform/esp-idf/src/u_port_gpio.c

@@ -36,6 +36,12 @@
  * COMPILE-TIME MACROS
  * -------------------------------------------------------------- */
 
+#ifndef U_PORT_GPIO_ESPIDF_INTERRUPT_FLAGS
+/** The type of interrupt handler to use: low or medium should be fine.
+ */
+# define U_PORT_GPIO_ESPIDF_INTERRUPT_FLAGS ESP_INTR_FLAG_LOWMED
+#endif
+
 /* ----------------------------------------------------------------
  * TYPES
  * -------------------------------------------------------------- */
@@ -44,10 +50,22 @@
  * VARIABLES
  * -------------------------------------------------------------- */
 
+/** Keep track of whether we installed the ISR service (otherwise
+ * ESP-IDF prints error messages when we blindly call
+ * gpio_isr_handler_remove().
+ */
+static bool gIsrServiceInstalled = false;
+
 /* ----------------------------------------------------------------
  * STATIC FUNCTIONS
  * -------------------------------------------------------------- */
 
+// ISR handler function; just calls pArg.
+static void isrHandler(void *pArg)
+{
+    ((void (*)()) pArg)();
+}
+
 /* ----------------------------------------------------------------
  * PUBLIC FUNCTIONS
  * -------------------------------------------------------------- */
@@ -58,10 +76,24 @@ int32_t uPortGpioConfig(uPortGpioConfig_t *pConfig)
     uErrorCode_t errorCode = U_ERROR_COMMON_INVALID_PARAMETER;
     bool badConfig = false;
     gpio_config_t config;
+    esp_err_t espErr;
 
     if (pConfig != NULL) {
-        // Set the things that won't change
+        // Set interrupt type
         config.intr_type = GPIO_INTR_DISABLE;
+        if (pConfig->pInterrupt != NULL) {
+            if (pConfig->interruptLevel) {
+                config.intr_type = GPIO_INTR_HIGH_LEVEL;
+                if (pConfig->interruptActiveLow) {
+                    config.intr_type = GPIO_INTR_LOW_LEVEL;
+                }
+            } else {
+                config.intr_type = GPIO_INTR_POSEDGE;
+                if (pConfig->interruptActiveLow) {
+                    config.intr_type = GPIO_INTR_NEGEDGE;
+                }
+            }
+        }
 
         // Set the direction and drive mode
         switch (pConfig->direction) {
@@ -124,6 +156,32 @@ int32_t uPortGpioConfig(uPortGpioConfig_t *pConfig)
                     // It's not an output pin so we're done
                     errorCode = U_ERROR_COMMON_SUCCESS;
                 }
+                if (errorCode == U_ERROR_COMMON_SUCCESS) {
+                    if (pConfig->pInterrupt != NULL) {
+                        // Set up the interrupt
+                        errorCode = U_ERROR_COMMON_PLATFORM;
+                        espErr = ESP_OK;
+                        if (!gIsrServiceInstalled) {
+                            espErr = gpio_install_isr_service(U_PORT_GPIO_ESPIDF_INTERRUPT_FLAGS);
+                        }
+                        // Note: ESP_ERR_INVALID_STATE means that the service is already
+                        // installed (might have been done by the application for other reasons)
+                        if ((espErr == ESP_OK) || (espErr == ESP_ERR_INVALID_STATE)) {
+                            gIsrServiceInstalled = true;
+                            if (gpio_isr_handler_add((gpio_num_t) pConfig->pin,
+                                                     isrHandler,
+                                                     pConfig->pInterrupt) == ESP_OK) {
+                                errorCode = U_ERROR_COMMON_SUCCESS;
+                            }
+                        }
+                    } else {
+                        if (gIsrServiceInstalled) {
+                            // If an interrupt is NOT requested then, in case it had been
+                            // previously, blindly call the "remove" function
+                            gpio_isr_handler_remove((gpio_num_t) pConfig->pin);
+                        }
+                    }
+                }
             }
         }
     }
@@ -156,4 +214,10 @@ int32_t uPortGpioGet(int32_t pin)
     return gpio_get_level((gpio_num_t) pin);
 }
 
+// Interrupt support.
+bool uPortGpioInterruptSupported()
+{
+    return true;
+}
+
 // End of file

port/platform/linux/src/u_port_gpio.c

@@ -146,7 +146,9 @@ U_WEAK int32_t uPortGpioConfig(uPortGpioConfig_t *pConfig)
     if ((pConfig != NULL) &&
         (pConfig->pin >= 0) && (pConfig->pin < sizeof(gPinIndex) / sizeof(gPinIndex[0])) &&
         // Needs to be a signed compare or an index of -1 fails the test below
-        (pConfig->index < (int32_t) (sizeof(gpGpioChip) / sizeof(gpGpioChip[0])))) {
+        (pConfig->index < (int32_t) (sizeof(gpGpioChip) / sizeof(gpGpioChip[0]))) &&
+        // Interrupts not supported
+        (pConfig->pInterrupt == NULL)) {
         index = pConfig->index;
         if (index < 0) {
             index = U_PORT_GPIO_CHIP_INDEX_DEFAULT;

port/platform/stm32cube/mcu/stm32f4/cfg/u_cfg_hw_platform_specific.h

@@ -28,6 +28,7 @@
  * Some of the values may be configured for your hardware,
  * others are fixed inside the STM32F4 chip; each section describes
  * which is the case.
+ *
  * Note that "UART" is used throughout this code, rather than
  * switching between "UART" and "USART" and having to
  * remember which number UART/USART is which.
@@ -271,6 +272,123 @@
  */
 #define U_CFG_HW_UART8_DMA_CHANNEL             5
 
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS FOR STM32F4: EXTI (INTERRUPTS NEED FOR GPIO)
+ * -------------------------------------------------------------- */
+
+/** In order to support use of a GPIO line as an interrupt, the
+ * relevant interrupt function needs to be made available to ubxlib.
+ * For STM32F4 there are 16 interrupts available where EXTI 0 serves
+ * pin 0 on any of the GPIO ports (A to I), EXTI 1 serves pin 1 on
+ * any of the GPIO ports, etc, up to EXTI 15 serving pins 15.
+ *
+ * The only usage of GPIO interrupts by ubxlib is if a Data Ready
+ * pin is to be used with a GNSS device; one EXTI interrupt is
+ * required for each GNSS device where this is the case.
+ *
+ * So if, for instance, you want to use pin B5 as your Data Ready
+ * pin, you would need to make sure that U_CFG_HW_EXTI_5_AVAILABLE,
+ * the EXTI for GPIO pin 5, was set to 1; the uPortGpio driver
+ * here will then set the relevant SYSCFG_EXTI register to indicate
+ * that EXTI5 is to monitor port B: hence pin B5, et voila.
+ */
+
+#ifndef U_CFG_HW_EXTI_0_AVAILABLE
+/** Whether EXTI 0 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_0_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_1_AVAILABLE
+/** Whether EXTI 1 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_1_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_2_AVAILABLE
+/** Whether EXTI 2 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_2_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_3_AVAILABLE
+/** Whether EXTI 3 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_3_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_4_AVAILABLE
+/** Whether EXTI 4 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_4_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_5_AVAILABLE
+/** Whether EXTI 5 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_5_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_6_AVAILABLE
+/** Whether EXTI 6 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_6_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_7_AVAILABLE
+/** Whether EXTI 7 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_7_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_8_AVAILABLE
+/** Whether EXTI 8 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_8_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_9_AVAILABLE
+/** Whether EXTI 9 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_9_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_10_AVAILABLE
+/** Whether EXTI 10 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_10_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_11_AVAILABLE
+/** Whether EXTI 11 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_11_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_12_AVAILABLE
+/** Whether EXTI 12 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_12_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_13_AVAILABLE
+/** Whether EXTI 13 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_13_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_14_AVAILABLE
+/** Whether EXTI 14 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_14_AVAILABLE  0
+#endif
+
+#ifndef U_CFG_HW_EXTI_15_AVAILABLE
+/** Whether EXTI 15 is available to ubxlib.
+ */
+# define U_CFG_HW_EXTI_15_AVAILABLE  0
+#endif
+
 #endif // _U_CFG_HW_PLATFORM_SPECIFIC_H_
 
 // End of file