Merge branch 'rp2040-interrupts' into main

README.md

@@ -2,7 +2,7 @@
 
 The **uClock BPM Generator library** is designed to implement precise and reliable BPM clock tick calls using the microcontroller's timer hardware interruption. It is designed to be multi-architecture, portable, and easy to use within the Opensource community universe. 
 
-We have chosen PlatformIO and Arduino as our official deployment platforms. The library has been supported and tested on general **AVR boards (ATmega168/328, ATmega16u4/32u4, and ATmega2560)** as well as **ARM boards (Teensy, STM32XX, and Seedstudio XIAO M0)**.
+We have chosen PlatformIO and Arduino as our official deployment platforms. The library has been supported and tested on general **AVR boards (ATmega168/328, ATmega16u4/32u4, and ATmega2560)** as well as **ARM boards (Teensy, STM32XX, and Seedstudio XIAO M0)**.  It has experimental support for **RP2040 boards (Raspberry Pico, Seeed XIAO RP2040)** (see notes).
 
 The absence of real-time features necessary for creating professional-level embedded devices for music and video on Opensource community-based platforms like Arduino led to the development of uClock. By leveraging the use of timer hardware interruptions, the library can schedule and manage real-time-like processing with safe shared resource access through its API.
 
@@ -373,3 +373,12 @@ void loop()
   //processYourPots();
 }
 ```
+
+## Known problems
+
+### RP2040 support
+
+- Uses the [earlephilhower core](https://github.com/earlephilhower/arduino-pico)
+- Doing a 'soft reboot' (eg from reflashing) seems to crash on startup, but starting from cold and powering on works fine.
+- Using FreeRTOS multithreading fails if the second core is used (via setup1() and loop1()) - using the 'interrupts-based' version of the RP2040 uClock support seems to solve this.
+- Tick ticking may be off due to repeating_timer following from the end of previous tick, rather than following the start of the previous tick.  

examples/RP2040ClockBlink/RP2040ClockBlink.ino

@@ -11,6 +11,8 @@
 
 #include <uClock.h>
 
+#define ATOMIC(X) { uint32_t __interrupt_mask = save_and_disable_interrupts(); X; restore_interrupts(__interrupt_mask); }
+
 uint8_t bpm_blink_timer = 1;
 void handle_bpm_led(uint32_t tick)
 {
@@ -50,14 +52,14 @@ void setup() {
 
   // A led to count bpms
   pinMode(LED_BUILTIN, OUTPUT);
-  digitalWrite(LED_BUILTIN, HIGH);
+  /*digitalWrite(LED_BUILTIN, HIGH);
   delay(500);
   digitalWrite(LED_BUILTIN, LOW);
   delay(500);
   digitalWrite(LED_BUILTIN, HIGH);
   delay(500);
   digitalWrite(LED_BUILTIN, LOW);
-  delay(500);
+  delay(500);*/
 
   
   Serial.begin(115200);
@@ -88,5 +90,5 @@ void loop() {
   //MIDI_USB.read();
   //count++;
   //if (millis()%1000==0)
-  //  Serial.println("looped!");
+  //  ATOMIC(Serial.println("looped!"));
 }

examples/RP2040UsbMasterMidiClock/RP2040UsbMasterMidiClock.ino

@@ -9,10 +9,17 @@
 
 Adafruit_USBD_MIDI usb_midi;
 MIDI_CREATE_INSTANCE(Adafruit_USBD_MIDI, usb_midi, MIDI_USB);
-
 //MIDI_CREATE_INSTANCE(HardwareSerial, Serial1, MIDI);
+
 #include <uClock.h>
 
+#define ATOMIC(X) { uint32_t __interrupt_mask = save_and_disable_interrupts(); X; restore_interrupts(__interrupt_mask); }
+//#define LED_BUILTIN PIN_LED_B
+//#define WAIT_FOR_SERIAL
+#define ENABLE_MULTICORE    
+
+volatile uint32_t count = 0;
+
 uint8_t bpm_blink_timer = 1;
 void handle_bpm_led(uint32_t tick)
 {
@@ -34,6 +41,8 @@ void onSync24Callback(uint32_t tick) {
   // Send MIDI_CLOCK to external gears
   MIDI_USB.sendRealTime(midi::Clock);
   handle_bpm_led(tick);
+
+  Serial.printf("ticked with %u\n", tick);
 }
 
 void onClockStart() {
@@ -44,6 +53,16 @@ void onClockStop() {
   MIDI_USB.sendRealTime(midi::Stop);
 }
 
+#ifdef ENABLE_MULTICORE
+  void setup1() {
+  }
+
+  void loop1() {
+    if (count%1000==0)
+      ATOMIC(Serial.println("loop1()!"); Serial.flush());
+  }
+#endif
+
 void setup() {
 #if defined(ARDUINO_ARCH_MBED) && defined(ARDUINO_ARCH_RP2040)
   // Manual begin() is required on core without built-in support for TinyUSB such as mbed rp2040
@@ -56,8 +75,10 @@ void setup() {
   pinMode(LED_BUILTIN, OUTPUT);
   
   Serial.begin(115200);
-  while (!Serial)
+  #ifdef WAIT_FOR_SERIAL
-    delay(1);
+    while (!Serial)
+      delay(1);
+  #endif
   
   // wait until device mounted
   while( !TinyUSBDevice.mounted() ) {
@@ -76,13 +97,17 @@ void setup() {
   uClock.setOnClockStart(onClockStart);  
   uClock.setOnClockStop(onClockStop);
   // Set the clock BPM to 126 BPM
-  uClock.setTempo(126);
+  uClock.setTempo(60);
   // Starts the clock, tick-tac-tick-tac..
   Serial.println("about to uClock.start()..."); Serial.flush();
   uClock.start();
-  Serial.println("uClock.start()ed!"); Serial.flush();
+  ATOMIC(Serial.println("uClock.start()ed!"); Serial.flush();)
 }
 
 // Do it whatever to interface with Clock.stop(), Clock.start(), Clock.setTempo() and integrate your environment...
 void loop() {
+  MIDI_USB.read();
+  count++;
+  if (millis()%1000==0)
+    ATOMIC(Serial.println("loop()!"); Serial.flush(););
 }

src/platforms/rp2040.h

@@ -1,57 +1,98 @@
 #include <Arduino.h>
-#include "FreeRTOS.h"
-#include <task.h>
-#include <semphr.h>
 #include "pico/sync.h"
 
-// RPi-specific timer
+#define MULTICORE
-struct repeating_timer timer;
+
-
+#ifdef MULTICORE
-// FreeRTOS main clock task size in bytes
+    // use interrupt version -- works for 2 cores ie can run loop1() and loop() simultaneously as well as the clock callback?
-#define CLOCK_STACK_SIZE    5*1024 // adjust for your needs, a sequencer with heavy serial handling should be large in size
+
-TaskHandle_t taskHandle;
+    // RPi-specific timer
-// mutex to protect the shared resource
+    struct repeating_timer timer;
-SemaphoreHandle_t _mutex;
+
-// mutex control for task
+    #define ATOMIC(X) { uint32_t __interrupt_mask = save_and_disable_interrupts(); X; restore_interrupts(__interrupt_mask); }
-#define ATOMIC(X) xSemaphoreTake(_mutex, portMAX_DELAY); X; xSemaphoreGive(_mutex);
+
-
+    // forward declaration of uClockHandler
-// forward declaration of uClockHandler
+    void uClockHandler();
-void uClockHandler();
+
-
+    // ISR handler -- called when tick happens
-// ISR handler -- called when tick happens
+    bool handlerISR(repeating_timer *timer)
-bool handlerISR(repeating_timer *timer)
+    {
-{
-    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
-    // Send a notification to task1
-    vTaskNotifyGiveFromISR(taskHandle, &xHigherPriorityTaskWoken);
-    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
-
-    return true;
-}
-
-// task for user clock process
-void clockTask(void *pvParameters)
-{
-    while (1) {
-        // wait for a notification from ISR
-        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
         uClockHandler();
+
+        return true;
+    }
+
+    void initTimer(uint32_t init_clock)
+    {
+        // set up RPi interrupt timer
+        // todo: actually should be -init_clock so that timer is set to start init_clock us after last tick, instead of init_clock us after finished processing last tick!
+        add_repeating_timer_us(init_clock, &handlerISR, NULL, &timer);
+    }
+
+    void setTimer(uint32_t us_interval) {
+        cancel_repeating_timer(&timer);
+        // todo: actually should be -us_interval so that timer is set to start init_clock us after last tick, instead of init_clock us after finished processing last tick!
+        add_repeating_timer_us(us_interval, &handlerISR, NULL, &timer);
+    }
+#else
+    // use FreeRTOS scheduling/mutex version -- doesn't work (task starts but does not run) if using loop1() ie core 2
+
+    #include "FreeRTOS.h"
+    #include <task.h>
+    #include <semphr.h>
+
+    // RPi-specific timer
+    struct repeating_timer timer;
+
+    // FreeRTOS main clock task size in bytes
+    #define CLOCK_STACK_SIZE    5*1024 // adjust for your needs, a sequencer with heavy serial handling should be large in size
+    TaskHandle_t taskHandle;
+    // mutex to protect the shared resource
+    SemaphoreHandle_t _mutex;
+    // mutex control for task
+    #define ATOMIC(X) xSemaphoreTake(_mutex, portMAX_DELAY); X; xSemaphoreGive(_mutex);
+
+    // forward declaration of uClockHandler
+    void uClockHandler();
+
+    // ISR handler -- called when tick happens
+    bool handlerISR(repeating_timer *timer)
+    {
+        BaseType_t xHigherPriorityTaskWoken = pdFALSE;
+        // Send a notification to task1
+        vTaskNotifyGiveFromISR(taskHandle, &xHigherPriorityTaskWoken);
+        portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
+
+        return true;
     }
-}
 
-void initTimer(uint32_t init_clock)
+    // task for user clock process
-{
+    void clockTask(void *pvParameters)
-    // initialize the mutex for shared resource access
+    {
-    _mutex = xSemaphoreCreateMutex();
+        while (1) {
+            // wait for a notification from ISR
+            ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
+            uClockHandler();
+        }
+    }
+
+    void initTimer(uint32_t init_clock)
+    {
+        // initialize the mutex for shared resource access
+        _mutex = xSemaphoreCreateMutex();
 
-    // create the clockTask
+        // create the clockTask
-    xTaskCreate(clockTask, "clockTask", CLOCK_STACK_SIZE, NULL, 1, &taskHandle);
+        xTaskCreate(clockTask, "clockTask", CLOCK_STACK_SIZE, NULL, 1, &taskHandle);
 
-    // set up RPi interrupt timer
+        // set up RPi interrupt timer
-    add_repeating_timer_us(init_clock, &handlerISR, NULL, &timer);
+        // todo: actually should be -init_clock so that timer is set to start init_clock us after last tick, instead of init_clock us after finished processing last tick!
-}
+        add_repeating_timer_us(init_clock, &handlerISR, NULL, &timer);
+    }
+
+    void setTimer(uint32_t us_interval) {
+        cancel_repeating_timer(&timer);
+        // todo: actually should be -us_interval so that timer is set to start init_clock us after last tick, instead of init_clock us after finished processing last tick!
+        add_repeating_timer_us(us_interval, &handlerISR, NULL, &timer);
+    }
 
-void setTimer(uint32_t us_interval) {
+#endif
-    cancel_repeating_timer(&timer);
-	add_repeating_timer_us(us_interval, &handlerISR, NULL, &timer);
-}