Upgrade MRI to version 1.5

This upgrades the version of the MRI library sources used by
KernelDebug and ThreadDebug to the latest that I am actively
supporting.

Changes that will benefit both ThreadDebug and KernelDebug include:
* I added the libraries/MRI/src/variants folder to hold the definition
  of g_memoryMapXml specific to each Arduino variant which supports
  MRI. Before these definitions were duplicated between ThreadDebug and
  KernelDebug.
* Has cache fix to enable soft breakpoints for code running out of RAM.
* Fixed cases where single stepping would sometimes hang if the code
  being stepped over caused a crash.
* I have added a DebugSerial object which can be used in place of
  Serial and/or SerialUSB to send output to the GDB console during the
  development process. MRI contains changes which make sending such
  output to GDB more efficient so I added this DebugSerial object to
  take advantage of it. The ThreadDebug example has been modified to
  show using this object to allow Serial.print() calls when
  using ThreadDebug which previously caused problems.

Some of the changes included in this version update will benefit
ThreadDebug:
* Platform_CommSendBuffer() is now overridden by ThreadDebug to send
  packets to GDB in one USB call instead of sending a byte at a
  time as it did before.
* The original RTX OS handlers like SVCall, PendSV, and SysTick only
  need to be saved once, during init, and not each time that
  ThreadDebug's versions are switched in.
* When running a test pass on ThreadDebug this time, I noticed that
  user threads weren't being locked as expected when I used the
  `set scheduler-locking step` command in GDB. I have always had this
  case in my test pass so I don't know how I didn't notice it was
  broken before. Anyway it is now fixed by making sure that the RTX
  idle thread is never allowed to remain frozen. If it has been
  requested by GDB to be frozen, it is thawed at one priority level
  higher than normal so that it stops all other frozen threads from
  running.

Other changes might not be a direct benefit to ThreadDebug but they
will be for KernelDebug:
* Faults will now pend to DebugMon so that invalid memory accesses
  initiated from GDB will no longer result in double fault CPU hard
  hangs. This pending to DebugMon for faults was actually copied from
  behavior first created for ThreadDebug back in 2020.
* Better handling of crashes the occur when the stack pointer becomes
  corrupted. Previously stacking exceptions could result in CPU hard
  hangs due to double faulting.
* Now has better code to handle single stepping through critical
  sections.
* Can now modify the current SP pointer from GDB. Probably not
  something most people would want to do though. Can also update the
  value of the PRIMASK, BASEPRI, FAULTMASK, and CONTROL special
  registers.

Other important updates to MRI included in version 1.5 are:
* Can now step into Standard C Library calls like memset() with no
  weird side effects.
* MRI now supports running the DebugMon interrupt handler at priorities
  other than 0. This allows important code such as USB or Bluetooth
  stacks to run in the background while GDB/MRI are debugging lower
  priority code. I first explored this ability for ThreadDebug but now
  use it in other projects to do things like communicate with GDB over
  BLE.
* Anywhere that the application under debug might want to call into
  MRI (semihosting, setting debugger hooks, etc), it now uses unique
  hardcoded `bkpt` instructions rather than just making function calls.
  This allows them to be called when MRI is installed as a separate
  boot loader on a device.
* Unescaping of binary packet data sent from GDB has been pushed lower
  down into the software stack, to the packet layer. This is where it
  should have been done in the first place.

Thanks go to @xiaoxiang781216, @icecream95, and @PetteriAimonen for
their MRI contributions that are included in this update.

Author: adamgreen

libraries/KernelDebug/library.properties

@@ -1,5 +1,5 @@
 name=KernelDebug
-version=1.0.0
+version=1.5.0
 author=Adam Green <[email protected]>
 maintainer=Arduino <[email protected]>
 sentence=The GDB compatible kernel debug monitor for Cortex-M devices.

libraries/KernelDebug/src/KernelDebug.cpp

@@ -1,4 +1,4 @@
-/* Copyright 2020 Adam Green (https://github.com/adamgreen/)
+/* Copyright 2022 Adam Green (https://github.com/adamgreen/)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -31,6 +31,7 @@ extern "C" {
     // Source code for armv7-m module which is included here, configured for supporting kernel mode debugging.
     #include <architectures/armv7-m/armv7-m.x>
     #include <architectures/armv7-m/debug_cm3.h>
+    #include <variants/mri_variant.h>
 }
 
 
@@ -134,8 +135,10 @@ static void readThreadContext(MriContext* pContext, uint32_t* pSP, osRtxThread_t
 // Forward declaration of external functions used by KernelDebug.
 // Will be setting initial breakpoint on setup() routine.
 extern "C" void setup();
-// The debugger uses this handler to catch faults, debug events, etc.
+// The debugger uses this handler to handle debug events, etc.
 extern "C" void mriExceptionHandler(void);
+// The debugger uses this handler to handle faults.
+extern "C" void mriFaultHandler(void);
 
 
 
@@ -241,10 +244,10 @@ static void restoreSystemHandlerPriorities(const SystemHandlerPriorities* pPrior
 
 static void switchFaultHandlersToDebugger(void)
 {
-    NVIC_SetVector(HardFault_IRQn,        (uint32_t)&mriExceptionHandler);
-    NVIC_SetVector(MemoryManagement_IRQn, (uint32_t)&mriExceptionHandler);
-    NVIC_SetVector(BusFault_IRQn,         (uint32_t)&mriExceptionHandler);
-    NVIC_SetVector(UsageFault_IRQn,       (uint32_t)&mriExceptionHandler);
+    NVIC_SetVector(HardFault_IRQn,        (uint32_t)&mriFaultHandler);
+    NVIC_SetVector(MemoryManagement_IRQn, (uint32_t)&mriFaultHandler);
+    NVIC_SetVector(BusFault_IRQn,         (uint32_t)&mriFaultHandler);
+    NVIC_SetVector(UsageFault_IRQn,       (uint32_t)&mriFaultHandler);
 }
 
 
@@ -287,27 +290,6 @@ void Platform_CommSendChar(int character)
 
 
 
-static const char g_memoryMapXml[] = "<?xml version=\"1.0\"?>"
-                                     "<!DOCTYPE memory-map PUBLIC \"+//IDN gnu.org//DTD GDB Memory Map V1.0//EN\" \"http://sourceware.org/gdb/gdb-memory-map.dtd\">"
-                                     "<memory-map>"
-                                     "<memory type=\"ram\" start=\"0x00000000\" length=\"0x10000\"> </memory>"
-                                     "<memory type=\"flash\" start=\"0x08000000\" length=\"0x200000\"> <property name=\"blocksize\">0x20000</property></memory>"
-                                     "<memory type=\"ram\" start=\"0x10000000\" length=\"0x48000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x1ff00000\" length=\"0x20000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x20000000\" length=\"0x20000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x24000000\" length=\"0x80000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x30000000\" length=\"0x48000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x38000000\" length=\"0x10000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x38800000\" length=\"0x1000\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x58020000\" length=\"0x2c00\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x58024400\" length=\"0xc00\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x58025400\" length=\"0x800\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x58026000\" length=\"0x800\"> </memory>"
-                                     "<memory type=\"ram\" start=\"0x58027000\" length=\"0x400\"> </memory>"
-                                     "<memory type=\"flash\" start=\"0x90000000\" length=\"0x10000000\"> <property name=\"blocksize\">0x200</property></memory>"
-                                     "<memory type=\"ram\" start=\"0x60000000\" length=\"0x800000\"> </memory>"
-                                     "</memory-map>";
-
 extern "C" uint32_t Platform_GetDeviceMemoryMapXmlSize(void)
 {
     return sizeof(g_memoryMapXml) - 1;
@@ -331,12 +313,7 @@ extern "C" uint32_t Platform_GetUidSize(void)
     return 0;
 }
 
-extern "C" int Semihost_IsDebuggeeMakingSemihostCall(void)
-{
-    return 0;
-}
-
-int Semihost_HandleSemihostRequest(void)
+int Semihost_HandleMbedSemihostRequest(PlatformSemihostParameters* pParameters)
 {
     return 0;
 }
@@ -617,3 +594,55 @@ void Platform_RtosSetThreadState(uint32_t threadId, PlatformThreadState state)
 void Platform_RtosRestorePrevThreadState(void)
 {
 }
+
+
+
+
+
+// This class can be used instead of Serial for sending output to the PC via GDB.
+DebugSerial::DebugSerial()
+{
+}
+
+// Methods that must be implemented for Print subclasses.
+size_t DebugSerial::write(uint8_t byte)
+{
+    return write(&byte, sizeof(byte));
+}
+
+size_t DebugSerial::write(const uint8_t *pBuffer, size_t size)
+{
+    const int    STDOUT_FILE_NO = 1;
+    const char*  pCurr = (const char*)pBuffer;
+    int          bytesWritten = 0;
+
+    while (size > 0) {
+        int result = mriNewlib_SemihostWrite(STDOUT_FILE_NO, pCurr, size);
+        if (result == -1) {
+            break;
+        }
+        size -= result;
+        pCurr += result;
+        bytesWritten += result;
+    }
+    return bytesWritten;
+}
+
+void DebugSerial::flush()
+{
+}
+
+void DebugSerial::begin(unsigned long baud, uint16_t mode)
+{
+    // Silence compiler warnings about unused parameters.
+    (void)baud;
+    (void)mode;
+}
+
+void DebugSerial::end()
+{
+}
+
+
+// Instantiate the single instance of this stream.
+class DebugSerial arduino::DebugSerial;

libraries/KernelDebug/src/KernelDebug.h

@@ -62,4 +62,27 @@ class KernelDebug {
     #define debugBreak()  { __asm volatile ("bkpt #0"); }
 #endif
 
+
+// This class can be used instead of Serial for sending output to the PC via GDB.
+class DebugSerial : public Print
+{
+public:
+    DebugSerial();
+
+    // Leaving out input Stream related methods so that compiler throws errors if user tries to use them.
+
+    // Methods that must be implemented for Print subclasses.
+    virtual size_t write(uint8_t);
+    virtual size_t write(const uint8_t *buffer, size_t size);
+    virtual void   flush();
+
+    // Additional methods defined by HardwareSerial that user might call.
+    void begin(unsigned long baud) { begin(baud, SERIAL_8N1); }
+    void begin(unsigned long baudrate, uint16_t config);
+    void end();
+    operator bool() { return true; }
+
+protected:
+} extern DebugSerial;
+
 } // namespace arduino