add interrupt support for Linux utility drivers

Also improved exception messages in a few drivers.

docs/API/arduino_wrappers.rst

@@ -44,3 +44,11 @@ Arduino GPIOClass
 This is library-specific API wrapping the Arduino GPIO interface.
 
 .. cpp-apigen-group:: arduino-gpio
+
+
+Arduino Interrupts
+------------------
+
+This is library-specific API wrapping the Arduino interrupt functionality.
+
+.. cpp-apigen-group:: arduino-irq

src/utility/CMakeLists.txt

@@ -4,11 +4,13 @@ set(CIRQUE_PINNACLE_UTILITY_HEADERS
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/spi.h
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/i2c.h
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/time_keeping.h
+ ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/interrupt.h
 )
 set(PINNACLE_UTILITY_IMPLEMENTATION_FILES
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/spi.cpp
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/i2c.cpp
  ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/time_keeping.cpp
+ ${CMAKE_CURRENT_LIST_DIR}/${PINNACLE_DRIVER}/interrupt.cpp
 )
 if("${PINNACLE_DRIVER}" STREQUAL "bcm2xxx") # use bcm2835 lib
  install(FILES

src/utility/bcm2xxx/i2c.h

@@ -16,8 +16,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef CIRQUEPINNACLE_UTILITY_TEMPLATE_I2C_H_
-#define CIRQUEPINNACLE_UTILITY_TEMPLATE_I2C_H_
+#ifndef CIRQUEPINNACLE_UTILITY_BCM2XXX_I2C_H_
+#define CIRQUEPINNACLE_UTILITY_BCM2XXX_I2C_H_
 #ifndef ARDUINO
 
  #include <cstdint>

src/utility/bcm2xxx/interrupt.cpp

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2023 Brendan Doherty (2bndy5)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef ARDUINO
+ #include <pthread.h>
+ #include <map>
+ #include "bcm2835.h"
+ #include "interrupt.h"
+
+ #ifdef __cplusplus
+extern "C" {
+ #endif
+
+namespace cirque_pinnacle_arduino_wrappers {
+
+ static pthread_mutex_t irq_mutex = PTHREAD_MUTEX_INITIALIZER;
+ std::map<pinnacle_gpio_t, IrqPinCache> irqCache;
+
+ void* poll_irq(void* arg)
+ {
+ IrqPinCache* pinCache = (IrqPinCache*)(arg);
+
+ for (;;) {
+ int ret = bcm2835_gpio_eds(pinCache->pin);
+ if (ret > 0) {
+ bcm2835_gpio_set_eds(pinCache->pin);
+ pinCache->function();
+ }
+ pthread_testcancel();
+ }
+ return NULL;
+ }
+
+ int attachInterrupt(pinnacle_gpio_t pin, int mode, void (*function)(void))
+ {
+ // ensure pin is not already being used in a separate thread
+ detachInterrupt(pin);
+
+ // create a request object to configure the specified pin
+ switch (mode) {
+ case CHANGE:
+ bcm2835_gpio_ren(pin);
+ bcm2835_gpio_fen(pin);
+ break;
+ case RISING:
+ bcm2835_gpio_ren(pin);
+ break;
+ case FALLING:
+ bcm2835_gpio_fen(pin);
+ break;
+ default:
+ // bad user input!
+ return 0; // stop here
+ }
+
+ // cache details
+ IrqPinCache irqPinCache;
+ irqPinCache.pin = pin;
+ irqPinCache.function = function;
+ std::pair<std::map<pinnacle_gpio_t, IrqPinCache>::iterator, bool> indexPair = irqCache.insert(std::pair<pinnacle_gpio_t, IrqPinCache>(pin, irqPinCache));
+
+ if (!indexPair.second) {
+ // this should not be reached, but indexPair.first needs to be the inserted map element
+ throw IRQException("[attachInterrupt] Could not cache the IRQ pin with function pointer");
+ return 0;
+ }
+
+ // create and start thread
+ pthread_mutex_lock(&irq_mutex);
+ pthread_create(&indexPair.first->second.id, nullptr, poll_irq, &indexPair.first->second);
+ pthread_mutex_unlock(&irq_mutex);
+
+ return 1;
+ }
+
+ int detachInterrupt(pinnacle_gpio_t pin)
+ {
+ std::map<pinnacle_gpio_t, IrqPinCache>::iterator cachedPin = irqCache.find(pin);
+ if (cachedPin == irqCache.end()) {
+ return 0; // pin not in cache; just exit
+ }
+ pthread_cancel(cachedPin->second.id); // send cancel request
+ pthread_join(cachedPin->second.id, NULL); // wait till thread terminates
+ bcm2835_gpio_clr_ren(cachedPin->second.pin);
+ bcm2835_gpio_clr_fen(cachedPin->second.pin);
+ bcm2835_gpio_set_eds(cachedPin->second.pin);
+ irqCache.erase(cachedPin);
+ return 1;
+ }
+
+} // namespace cirque_pinnacle_arduino_wrappers
+
+ #ifdef __cplusplus
+}
+ #endif
+
+#endif // !defined(ARDUINO)

src/utility/bcm2xxx/interrupt.h

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2023 Brendan Doherty (2bndy5)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef CIRQUEPINNACLE_UTILITY_BCM2XXX_INTERRUPT_H_
+#define CIRQUEPINNACLE_UTILITY_BCM2XXX_INTERRUPT_H_
+#ifndef ARDUINO
+
+ #include <pthread.h> // pthread_t
+ #include <stdexcept> // std::exception, std::string
+ #include "gpio.h" // pinnacle_gpio_t
+
+ #ifdef __cplusplus
+extern "C" {
+ #endif
+
+namespace cirque_pinnacle_arduino_wrappers {
+
+ enum Edge
+ {
+ FALLING,
+ RISING,
+ CHANGE,
+ };
+
+ /** Specific exception for IRQ errors */
+ class IRQException : public std::runtime_error
+ {
+ public:
+ explicit IRQException(const std::string& msg)
+ : std::runtime_error(msg)
+ {
+ }
+ };
+
+ /** Details related to a certain pin's ISR. */
+ struct IrqPinCache
+ {
+ /// The pin request's file descriptor
+ int pin = 0;
+
+ /// The posix thread ID.
+ pthread_t id = 0;
+
+ /// The user-designated ISR function (used as a callback)
+ void (*function)(void) = nullptr;
+ };
+
+ /**
+ * Take the details and create an interrupt handler that will
+ * callback to the user-supplied function.
+ */
+ int attachInterrupt(pinnacle_gpio_t pin, int mode, void (*function)(void));
+
+ /**
+ * Will cancel the interrupt thread, close the filehandle and release the pin.
+ */
+ int detachInterrupt(pinnacle_gpio_t pin);
+
+} // namespace cirque_pinnacle_arduino_wrappers
+
+ #ifdef __cplusplus
+}
+ #endif
+
+#endif // !defined(ARDUINO)
+#endif // CIRQUEPINNACLE_UTILITY_BCM2XXX_INTERRUPT_H_

src/utility/bcm2xxx/spi.h

@@ -16,8 +16,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef CIRQUEPINNACLE_UTILITY_RPI_SPI_H_
-#define CIRQUEPINNACLE_UTILITY_RPI_SPI_H_
+#ifndef CIRQUEPINNACLE_UTILITY_BCM2XXX_SPI_H_
+#define CIRQUEPINNACLE_UTILITY_BCM2XXX_SPI_H_
 #ifndef ARDUINO
 
  #include <stdio.h>

src/utility/includes.h.in

@@ -23,6 +23,7 @@
 #include "@PINNACLE_DRIVER@/spi.h"
 #include "@PINNACLE_DRIVER@/i2c.h"
 #include "@PINNACLE_DRIVER@/time_keeping.h"
+#include "@PINNACLE_DRIVER@/interrupt.h"
 
 // clang-format off
 // A macro to help execute driver specific code