Add a new plugin which wraps and configures ArduinoTrace to make print statement debugging easier

Import ArduinoTrace.h as of c225e14638fcb48e4392e38ab1155dbc1e8eb13a
from https://github.com/bblanchon/ArduinoTrace/blob/master/ArduinoTrace.h

plugins/Kaleidoscope-Devel-ArduinoTrace/README.md

@@ -0,0 +1,59 @@
+# Kaleidoscope-Devel-ArduinoTrace
+
+A development and debugging aid, this plugin imports and initializes an embedded copy of the ArduinoTrace library from https://github.com/bblanchon/ArduinoTrace
+
+It is primarly intended for use on our simulator, though in theory, it should work when run on normal hardware, too
+
+## Using the plugin
+
+The plugin comes with reasonable defaults (see below), and can be used out of
+the box, without any further configuration:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-Devel-ArduinoTrace.h>
+
+/* ... */
+
+void setup (void) {
+  Kaleidoscope.setup ();
+  TRACE()
+}
+
+
+void someMethod(uint8_t value) {
+	uint8_t other_value;
+
+	TRACE()
+	DUMP(value)
+	other_value = someOtherMethod(value);
+	DUMP(other_value)
+}
+```
+
+Running in the simulator, you should see output like:
+
+```
+basic-keypress.ino:492: void setup()
+Runtime.cpp:51: void kaleidoscope::Runtime_::loop()
+Runtime.cpp:53: millis_at_cycle_start_ = 4
+```
+
+
+While this plugin is primarily intended to be used in the Kaleidoscope simulator, it should work on actual hardware. On the simulator, output is directed to DebugStderr. On hardware, it defaults to Serial.
+
+To configure ArduinoTrace, there are a number of constants you can `#define` before you `#include` the plugin. They're documented [upstream][upstream:docs].
+
+
+## Plugin methods
+
+This plugin does not itself offer up any API methods or use any
+plugin hooks, instead exposing the "TRACE" and "DUMP" macros provided
+by ArduinoTrace
+
+
+## Further reading
+
+Have a look at the [docs][upstream:docs] for ArduinoTrace on GitHub.
+
+ [upstream:docs]: https://github.com/bblanchon/ArduinoTrace#arduinotrace

plugins/Kaleidoscope-Devel-ArduinoTrace/library.properties

@@ -0,0 +1,7 @@
+name=Kaleidoscope-Devel-ArduinoTrace
+version=0.0.0
+sentence=A debugging aid to make ArduinoTrace available while debugging Kaleidoscope
+maintainer=Kaleidoscope's Developers <jesse@keyboard.io>
+url=https://github.com/keyboardio/Kaleidoscope
+author=Keyboardio
+paragraph=

plugins/Kaleidoscope-Devel-ArduinoTrace/src/ArduinoTrace.h

@@ -0,0 +1,194 @@
+// ArduinoTrace - github.com/bblanchon/ArduinoTrace
+// Copyright Benoit Blanchon 2018-2020
+// MIT License
+//
+// A simple tracing macro to debug you program.
+//
+// Recipe to find where the code crashes:
+//  1. sprinkle your code with TRACE()
+//  2. run the program
+//  3. view all traces in the Serial monitor
+//
+// Each trace includes the:
+//  * the filename
+//  * the line number
+//  * the current function
+//  * the template parameters (if any)
+
+#pragma once
+
+#include <Arduino.h>
+
+#ifndef ARDUINOTRACE_ENABLE
+#define ARDUINOTRACE_ENABLE 1
+#endif
+
+#if ARDUINOTRACE_ENABLE == 1
+
+#ifndef ARDUINOTRACE_SERIAL
+#define ARDUINOTRACE_SERIAL Serial
+#endif
+
+#ifndef ARDUINOTRACE_ENABLE_PROGMEM
+#ifdef PROGMEM
+#define ARDUINOTRACE_ENABLE_PROGMEM 1
+#else
+#define ARDUINOTRACE_ENABLE_PROGMEM 0
+#endif
+#endif
+
+#ifndef ARDUINOTRACE_ENABLE_FULLPATH
+#define ARDUINOTRACE_ENABLE_FULLPATH 0
+#else
+#define ARDUINOTRACE_ENABLE_FULLPATH 1
+#endif
+
+#ifndef ARDUINOTRACE_FUNCTION_NAME_IN_FLASH
+#if defined(ESP8266)
+#define ARDUINOTRACE_FUNCTION_NAME_IN_FLASH 1
+#else
+#define ARDUINOTRACE_FUNCTION_NAME_IN_FLASH 0
+#endif
+#endif
+
+namespace ArduinoTrace {
+constexpr size_t strlen(const char *str) {
+  return str[0] ? strlen(str + 1) + 1 : 0;
+}
+
+template <char... chars>
+struct string {
+#if ARDUINOTRACE_ENABLE_PROGMEM
+  const __FlashStringHelper *data() {
+    static const char buffer[] PROGMEM = {chars...};
+    return reinterpret_cast<const __FlashStringHelper *>(buffer);
+  }
+#else
+  const char *data() {
+    static const char buffer[] = {chars...};
+    return buffer;
+  }
+#endif
+};
+
+template <typename TSourceString, size_t remainingLength,
+          char... collectedChars>
+struct string_maker {
+  using result =
+    typename string_maker < TSourceString, remainingLength - 1,
+    TSourceString::data()[remainingLength - 1],
+    collectedChars... >::result;
+};
+
+#if ARDUINOTRACE_ENABLE_FULLPATH == 0
+template <typename TSourceString, size_t remainingLength,
+          char... collectedChars>
+struct string_maker<TSourceString, remainingLength, '/', collectedChars...> {
+  using result = string<collectedChars..., '\0'>;
+};
+
+template <typename TSourceString, size_t remainingLength,
+          char... collectedChars>
+struct string_maker<TSourceString, remainingLength, '\\', collectedChars...> {
+  using result = string<collectedChars..., '\0'>;
+};
+#endif
+
+template <typename TSourceString, char... collectedChars>
+struct string_maker<TSourceString, 0, collectedChars...> {
+  using result = string<collectedChars..., '\0'>;
+};
+
+template <typename TStringSource>
+using make_string =
+  typename string_maker<TStringSource, strlen(TStringSource::data())>::result;
+
+struct Initializer {
+  template <typename TSerial>
+  Initializer(TSerial &serial, int bauds) {
+    serial.begin(bauds);
+    while (!serial) continue;
+  }
+};
+
+template <typename TFilename, typename TPrefix>
+struct Printer {
+  template <typename TSerial, typename TValue>
+  Printer(TSerial &serial, const TValue &content) {
+    serial.print(make_string<TFilename> {}.data());
+    serial.print(make_string<TPrefix> {}.data());
+    serial.println(content);
+    serial.flush();
+  }
+};
+}  // namespace ArduinoTrace
+
+#define ARDUINOTRACE_STRINGIFY(X) #X
+#define ARDUINOTRACE_CONCAT(X, Y) X##Y
+
+#if ARDUINOTRACE_ENABLE_PROGMEM
+#define ARDUINOTRACE_FLASHIFY(X) F(X)
+#else
+#define ARDUINOTRACE_FLASHIFY(X) X
+#endif
+
+#if ARDUINOTRACE_FUNCTION_NAME_IN_FLASH
+#define ARDUINOTRACE_FUNCTION_NAME \
+  reinterpret_cast<const __FlashStringHelper *>(__PRETTY_FUNCTION__)
+#else
+#define ARDUINOTRACE_FUNCTION_NAME __PRETTY_FUNCTION__
+#endif
+
+#define ARDUINOTRACE_PRINT(id, file, prefix, content)                         \
+  {                                                                           \
+    struct __filename {                                                       \
+      constexpr static char const *data() { return file; }                    \
+    };                                                                        \
+    struct __prefix {                                                         \
+      constexpr static char const *data() { return prefix; }                  \
+    };                                                                        \
+    ArduinoTrace::Printer<__filename, __prefix> __tracer(ARDUINOTRACE_SERIAL, \
+                                                         content);            \
+  }
+
+#define ARDUINOTRACE_INITIALIZE(id, bauds)                          \
+  ArduinoTrace::Initializer ARDUINOTRACE_CONCAT(__initializer, id)( \
+      ARDUINOTRACE_SERIAL, bauds);
+
+#define ARDUINOTRACE_TRACE_PREFIX(line) ":" ARDUINOTRACE_STRINGIFY(line) ": "
+
+#define ARDUINOTRACE_DUMP_PREFIX(line, variable) \
+  ":" ARDUINOTRACE_STRINGIFY(line) ": " #variable " = "
+
+// Initializes the Serial port
+//
+// Use this macro only if you want to call TRACE() at global scope,
+// in other cases, call Serial.begin() in your setup() function, as usual.
+#define ARDUINOTRACE_INIT(bauds) ARDUINOTRACE_INITIALIZE(__COUNTER__, bauds);
+
+// Adds a trace in the Serial port
+//
+// Call this macro anywhere, including at global scope.
+// However, if you use it at global scope, you need to call ARDUINOTRACE_INIT()
+// first, otherwise, the Serial port will not be ready.
+#define TRACE()                                           \
+  ARDUINOTRACE_PRINT(__COUNTER__, __FILE__,               \
+                     ARDUINOTRACE_TRACE_PREFIX(__LINE__), \
+                     ARDUINOTRACE_FUNCTION_NAME)
+
+// Prints the value of a variable.
+//
+// This function will print the name and the value of the variable to the
+// Serial. If you use it at global scope, you need to call ARDUINOTRACE_INIT()
+// first, otherwise, the Serial port will not be ready.
+#define DUMP(variable)                      \
+  ARDUINOTRACE_PRINT(__COUNTER__, __FILE__, \
+                     ARDUINOTRACE_DUMP_PREFIX(__LINE__, variable), variable)
+
+#else  // ie ARDUINOTRACE_ENABLE == 0
+
+#define ARDUINOTRACE_INIT(bauds)
+#define TRACE()
+#define DUMP(variable)
+
+#endif

plugins/Kaleidoscope-Devel-ArduinoTrace/src/Kaleidoscope-Devel-ArduinoTrace.h

@@ -0,0 +1,30 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Devel-ArduinoTrace -- an ArduinoTrace affordance for kaleidoscope debugging
+ * Copyright (C) 2017  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "kaleidoscope/Runtime.h"
+
+#ifndef ARDUINOTRACE_SERIAL
+#ifdef KALEIDOSCOPE_VIRTUAL_BUILD
+#define ARDUINOTRACE_SERIAL DebugStderr
+#endif
+#endif
+
+#include "ArduinoTrace.h"
+
+ARDUINOTRACE_INIT(9600)