New/updated examples: UART MIDI, WAV Writer, and QSPI Erase Timing (#697)

* adds optional realtime callback, and improved logging to UART MIDI example.

* new examples for Realtime use of WAV writer, and a profiling/benchmarking example for QSPI erasures

* code style, and naming consistency of WavWriter_Realtime example

Author: stephenhensley

examples/MIDI_UART_Input/MIDI_UART_Input.cpp

@@ -1,23 +1,97 @@
 /** Example of setting reading MIDI Input via UART
- *
  *
  *  This can be used with any 5-pin DIN or TRS connector that has been wired up
  *  to one of the UART Rx pins on Daisy.
  *  This will use D14 as the UART 1 Rx pin
  *
  *  This example will also log incoming messages to the serial port for general MIDI troubleshooting
+ *
+ *  This includes a demonstration of managing System Realtime messages immediately via
+ *  an optional callback. This can be disabled by setting, `kUseRealtimeCallback` to false.
+ *  in which case all messages while run through the typical MIDI event queue.
  */
 #include "daisy_seed.h"
 
 /** This prevents us from having to type "daisy::" in front of a lot of things. */
 using namespace daisy;
 
+/** Select whether to use the optional system realtime callback or not. */
+constexpr const bool kUseRealtimeCallback = true;
+
+/** Indicates from where the MIDI Message was logged */
+enum class Source
+{
+    Queue,
+    RealtimeCb,
+    Unknown,
+};
+
+/** Wrapper type that adds a timestamp and source to the MIDI event. */
+struct SourcedMidiEvent
+{
+    MidiEvent message;
+    Source    src;
+    uint32_t  timestamp;
+
+    SourcedMidiEvent(MidiEvent e, Source s)
+    {
+        message   = e;
+        src       = s;
+        timestamp = System::GetNow();
+    }
+
+    SourcedMidiEvent() : src(Source::Unknown), timestamp(0xffffffff) {}
+};
+
 /** Global Hardware access */
 DaisySeed       hw;
 MidiUartHandler midi;
 
 /** FIFO to hold messages as we're ready to print them */
-FIFO<MidiEvent, 128> event_log;
+FIFO<SourcedMidiEvent, 128> event_log;
+
+
+/** Helper for getting human readable strings from realtime messages */
+const char* GetStringForRealTimeType(SystemRealTimeType type)
+{
+    switch(type)
+    {
+        case SystemRealTimeType::TimingClock: return "Timing Clock";
+        case SystemRealTimeType::SRTUndefined0: return "SRT Undefined0";
+        case SystemRealTimeType::Start: return "Start";
+        case SystemRealTimeType::Continue: return "Continue";
+        case SystemRealTimeType::Stop: return "Stop";
+        case SystemRealTimeType::SRTUndefined1: return "SRT Undefined1";
+        case SystemRealTimeType::ActiveSensing: return "ActiveSensing";
+        case SystemRealTimeType::Reset: return "Reset";
+        default: return "Unknown Type...";
+    }
+}
+
+/** Helper for getting a string for the source */
+const char* GetStringForSource(Source src)
+{
+    switch(src)
+    {
+        case Source::Queue: return "Queue";
+        case Source::RealtimeCb: return "Realtime Callback";
+        case Source::Unknown:
+        default: return "Unknown";
+    }
+}
+
+/**  Optional callback for synchronous realtime message handling
+ *
+ *   Typically, you would handle your timing-sensitive behavior
+ *   right here to take advantage of the syncronous handling.
+ *   In this case, we're just going to forward this to the log
+ *   to make sure no messages are missed.
+*/
+void MidiRealtimeCallback(MidiEvent& event)
+{
+    auto ev = SourcedMidiEvent(event, Source::RealtimeCb);
+    event_log.PushBack(ev);
+}
 
 int main(void)
 {
@@ -29,7 +103,14 @@ int main(void)
     MidiUartHandler::Config midi_config;
     midi.Init(midi_config);
 
-    midi.StartReceive();
+    if(kUseRealtimeCallback)
+    {
+        midi.StartReceiveRt(MidiRealtimeCallback);
+    }
+    else
+    {
+        midi.StartReceive();
+    }
 
     uint32_t now      = System::GetNow();
     uint32_t log_time = System::GetNow();
@@ -39,10 +120,10 @@ int main(void)
     {
         now = System::GetNow();
 
-        /** Process MIDI in the background */
+        /** Monitor MIDI status, and trigger recovery of MIDI Rx if necessary */
         midi.Listen();
 
-        /** Loop through any MIDI Events */
+        /** Loop through any MIDI Events in the queue */
         while(midi.HasEvents())
         {
             MidiEvent msg = midi.PopEvent();
@@ -56,16 +137,17 @@ int main(void)
                     // Do something on Note On events
                     {
                         uint8_t bytes[3] = {0x90, 0x00, 0x00};
-                        bytes[1] = msg.data[0];
-                        bytes[2] = msg.data[1];
+                        bytes[1]         = msg.data[0];
+                        bytes[2]         = msg.data[1];
                         midi.SendMessage(bytes, 3);
                     }
                     break;
                 default: break;
             }
 
-            /** Regardless of message, let's add the message data to our queue to output */
-            event_log.PushBack(msg);
+            /** Regardless of message, let's add the message data to our queue to output to the log */
+            auto ev = SourcedMidiEvent(msg, Source::Queue);
+            event_log.PushBack(ev);
         }
 
         /** Now separately, every 5ms we'll print the top message in our queue if there is one */
@@ -74,17 +156,35 @@ int main(void)
             log_time = now;
             if(!event_log.IsEmpty())
             {
-                auto msg = event_log.PopFront();
-                char outstr[128];
+                auto        event = event_log.PopFront();
+                auto        msg   = event.message;
+                char        outstr[128];
                 const char* type_str = MidiEvent::GetTypeAsString(msg);
-                sprintf(outstr,
-                        "time:\t%ld\ttype: %s\tChannel:  %d\tData MSB: "
-                        "%d\tData LSB: %d\n",
-                        now,
-                        type_str,
-                        msg.channel,
-                        msg.data[0],
-                        msg.data[1]);
+                if(msg.type == MidiMessageType::SystemRealTime)
+                {
+                    const char* src_str = GetStringForSource(event.src);
+                    const char* desc_str
+                        = GetStringForRealTimeType(msg.srt_type);
+                    sprintf(outstr,
+                            "time:\t%ld\ttype: %s - %s\tsource: %s\n",
+                            event.timestamp,
+                            type_str,
+                            desc_str,
+                            src_str);
+                }
+                else
+                {
+                    // Only realtime messages are capable of hitting the realtime
+                    // callback so we do not need to include the source here.
+                    sprintf(outstr,
+                            "time:\t%ld\ttype: %s\tChannel:  %d\tData MSB: "
+                            "%d\tData LSB: %d\n",
+                            event.timestamp,
+                            type_str,
+                            msg.channel,
+                            msg.data[0],
+                            msg.data[1]);
+                }
                 hw.PrintLine(outstr);
             }
         }

examples/QSPI_EraseTiming/CMakeLists.txt

@@ -0,0 +1,3 @@
+set(FIRMWARE_NAME QSPI_EraseTiming)
+set(FIRMWARE_SOURCES main.cpp)
+include(DaisyProject)

examples/QSPI_EraseTiming/Makefile

@@ -0,0 +1,12 @@
+# Project Name
+TARGET = QSPI_EraseTiming
+
+# Sources
+CPP_SOURCES = main.cpp
+
+# Library Locations
+LIBDAISY_DIR = ../..
+
+# Core location, and generic Makefile.
+SYSTEM_FILES_DIR = $(LIBDAISY_DIR)/core
+include $(SYSTEM_FILES_DIR)/Makefile

examples/QSPI_EraseTiming/main.cpp

@@ -0,0 +1,145 @@
+/** Test program for evaluating QSPI erase performance.
+ *  This program will perform multiple write-erase cycles
+ *  on the first 256kB bytes of the QSPI.
+ */
+#include "daisy_seed.h"
+#include <cmath>
+
+/** This prevents us from having to type "daisy::" in front of a lot of things. */
+using namespace daisy;
+
+struct TestProfile
+{
+    uint32_t erase_dur, write_dur;
+    bool     pass;
+};
+
+DaisySeed hw;
+
+/** statically allocated workspace for creation/validation of data
+ *  256kB so we can look at multiple blocks of 64kB if we want.
+*/
+static const size_t kWorkspaceSize = 0x40000;
+static uint8_t      workspace[kWorkspaceSize];
+
+TestProfile EraseWriteValidate(QSPIHandle& qspi, size_t test_size)
+{
+    TestProfile res;
+
+    // Erase
+    auto start = System::GetNow();
+    qspi.Erase(0, test_size);
+    auto end      = System::GetNow();
+    res.erase_dur = end - start;
+
+    // Write
+    start = System::GetNow();
+    qspi.Write(0, test_size, workspace);
+    end           = System::GetNow();
+    res.write_dur = end - start;
+
+    // Validate write
+    dsy_dma_invalidate_cache_for_buffer((uint8_t*)(0x90000000), test_size);
+    uint8_t* mem = (uint8_t*)(0x90000000);
+    res.pass     = true;
+    for(size_t i = 0; i < test_size; i++)
+    {
+        if(mem[i] != 0x00)
+            res.pass = false;
+    }
+    return res;
+}
+
+int main(void)
+{
+    /** Initialize our hardware */
+    hw.Init();
+
+    /** Start Log */
+    hw.StartLog(true);
+    // without these delays the printing seems to just get lost before being output?
+    System::Delay(100);
+    hw.PrintLine("Beginning Erasure Timing Tests...");
+
+    // Naive write data, but since erase sets all bytes 0xff, we'll just flip'em.
+    std::fill(workspace, workspace + kWorkspaceSize, 0x00);
+
+    hw.PrintLine("Test 1: Erase, Write and Validate a single 4kB sector.");
+    hw.PrintLine("\tstarting...");
+    auto t1_res = EraseWriteValidate(hw.qspi, 0x1000);
+    hw.PrintLine("\tErase Time: %dms", t1_res.erase_dur);
+    hw.PrintLine("\tWrite Time: %dms", t1_res.write_dur);
+    hw.PrintLine("\tValidated Write: %s", t1_res.pass ? "Pass" : "Fail");
+    hw.PrintLine("\tfinished.");
+
+    hw.PrintLine("Test 2: Erase, Write, and Validate a single 64kB block");
+    hw.PrintLine("\tstarting...");
+    auto t2_res = EraseWriteValidate(hw.qspi, 0x10000);
+    hw.PrintLine("\tErase Time: %dms", t2_res.erase_dur);
+    hw.PrintLine("\tWrite Time: %dms", t2_res.write_dur);
+    hw.PrintLine("\tValidated Write: %s", t2_res.pass ? "Pass" : "Fail");
+    hw.PrintLine("\tfinished.");
+
+    hw.PrintLine("Test 3: Erase 256kB in one call (internally 4x 64kB erases)");
+    size_t test_size = 0x40000;
+    auto   start     = System::GetNow();
+    hw.qspi.Erase(0, test_size);
+    auto end       = System::GetNow();
+    auto erase_dur = end - start;
+    hw.PrintLine("\tTotal Erase Time: %dms", erase_dur);
+
+    hw.PrintLine("4: Erase 256kB in 4x 64kB blocks/fn calls");
+    uint32_t t4_durs[4] = {0};
+    test_size           = 0x10000;
+    start               = System::GetNow();
+    for(size_t i = 0; i < 4; i++)
+    {
+        auto istart     = System::GetNow();
+        auto start_addr = 0 + (test_size * i);
+        hw.qspi.Erase(start_addr, start_addr + test_size);
+        auto iend  = System::GetNow();
+        t4_durs[i] = iend - istart;
+    }
+    end       = System::GetNow();
+    erase_dur = end - start;
+    hw.PrintLine("\t0: %dms\t1: %dms\t2: %dms\t3: %dms",
+                 t4_durs[0],
+                 t4_durs[1],
+                 t4_durs[2],
+                 t4_durs[3]);
+    hw.PrintLine("\tTotal Erase Time: %dms", erase_dur);
+    hw.PrintLine("\tfinished.");
+
+    hw.PrintLine("5: Erase 256kB in 64x 4kB blocks/fn calls");
+    uint32_t t5_durs[64] = {0};
+    test_size            = 0x1000;
+    start                = System::GetNow();
+    for(size_t i = 0; i < 64; i++)
+    {
+        auto istart     = System::GetNow();
+        auto start_addr = 0 + (test_size * i);
+        hw.qspi.Erase(start_addr, start_addr + test_size);
+        auto iend  = System::GetNow();
+        t5_durs[i] = iend - istart;
+    }
+    end       = System::GetNow();
+    erase_dur = end - start;
+
+    for(size_t i = 0; i < 64; i++)
+    {
+        hw.Print("\t%d: %dms", i, t5_durs[i]);
+        if(i % 4 == 3)
+            hw.Print("\n");
+    }
+
+    hw.PrintLine("\tTotal Erase Time: %dms", erase_dur);
+    hw.PrintLine("\tfinished.");
+
+    hw.PrintLine("Done.");
+
+    /** Infinite Loop to Blink when completed. */
+    while(1)
+    {
+        hw.SetLed((System::GetNow() & 511) > 255);
+    }
+}

examples/WavWriter_Realtime/CMakeLists.txt

@@ -0,0 +1,3 @@
+set(FIRMWARE_NAME WavWriter_Realtime)
+set(FIRMWARE_SOURCES main.cpp)
+include(DaisyProject)

examples/WavWriter_Realtime/Makefile

@@ -0,0 +1,14 @@
+# Project Name
+TARGET = WavWriter_Realtime
+
+# Sources
+CPP_SOURCES = main.cpp
+
+USE_FATFS=1
+
+# Library Locations
+LIBDAISY_DIR = ../..
+
+# Core location, and generic Makefile.
+SYSTEM_FILES_DIR = $(LIBDAISY_DIR)/core
+include $(SYSTEM_FILES_DIR)/Makefile