Merge remote-tracking branch 'plugin/CycleTimeReport/f/monorepo' into f/monorepo-stage2

doc/plugin/CycleTimeReport.md

@@ -0,0 +1,53 @@
+# Kaleidoscope-CycleTimeReport
+
+A development and debugging aid, this plugin will measure average mainloop times
+(in microseconds) and print it to `Serial` periodically. While not the most
+reliable way to measure the speed of processing, it gives a reasonable
+indication nevertheless.
+
+## 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-CycleTimeReport.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(CycleTimeReport);
+
+void setup (void) {
+  Serial.begin(9600);
+  Kaleidoscope.setup ();
+}
+```
+
+## Plugin methods
+
+The plugin provides a single object, `CycleTimeReport`, with the following
+property. All times are in milliseconds.
+
+### `.average_loop_time`
+
+> A read-only by contract value, the average time of main loop lengths between
+> two reports.
+
+## Overrideable methods
+
+### `cycleTimeReport()`
+
+> Reports the average loop time. By default, it does so over `Serial`, every
+> time when the report period is up.
+>
+> It can be overridden, to change how the report looks, or to make the report
+> toggleable, among other things.
+>
+> It takes no arguments, and returns nothing, but has access to
+> `CycleTimeReport.average_loop_time` above.
+
+## Further reading
+
+Starting from the [example][plugin:example] is the recommended way of getting
+started with the plugin.
+
+ [plugin:example]: ../../examples/CycleTimeReport/CycleTimeReport.ino

examples/CycleTimeReport/CycleTimeReport.ino

@@ -0,0 +1,50 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-CycleTimeReport -- Scan cycle time reporting
+ * Copyright (C) 2017, 2018  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/>.
+ */
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-CycleTimeReport.h>
+
+const Key keymaps[][ROWS][COLS] PROGMEM = {
+  [0] = KEYMAP_STACKED
+  (
+    Key_NoKey,    Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
+    Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
+    Key_PageUp,   Key_A, Key_S, Key_D, Key_F, Key_G,
+    Key_PageDown,   Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
+
+    Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
+    Key_skip,
+
+    Key_skip,  Key_6, Key_7, Key_8,     Key_9,      Key_0,         Key_skip,
+    Key_Enter, Key_Y, Key_U, Key_I,     Key_O,      Key_P,         Key_Equals,
+    Key_H, Key_J, Key_K,     Key_L,      Key_Semicolon, Key_Quote,
+    Key_skip,  Key_N, Key_M, Key_Comma, Key_Period, Key_Slash,     Key_Minus,
+
+    Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
+    Key_skip),
+};
+
+KALEIDOSCOPE_INIT_PLUGINS(CycleTimeReport);
+
+void setup() {
+  Serial.begin(9600);
+  Kaleidoscope.setup();
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}

src/Kaleidoscope-CycleTimeReport.h

@@ -0,0 +1,20 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-CycleTimeReport -- Scan cycle time reporting
+ * 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/plugin/CycleTimeReport.h>

src/kaleidoscope/plugin/CycleTimeReport.cpp

@@ -0,0 +1,62 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-CycleTimeReport -- Scan cycle time reporting
+ * Copyright (C) 2017, 2018  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/>.
+ */
+
+#include <Kaleidoscope-CycleTimeReport.h>
+
+namespace kaleidoscope {
+namespace plugin {
+uint32_t CycleTimeReport::next_report_time_;
+uint32_t CycleTimeReport::loop_start_time_;
+uint32_t CycleTimeReport::average_loop_time;
+
+EventHandlerResult CycleTimeReport::onSetup() {
+  next_report_time_ = millis() + 1000;
+  return EventHandlerResult::OK;
+}
+
+EventHandlerResult CycleTimeReport::beforeEachCycle() {
+  loop_start_time_ = micros();
+  return EventHandlerResult::OK;
+}
+
+EventHandlerResult CycleTimeReport::afterEachCycle() {
+  uint32_t loop_time = micros() - loop_start_time_;
+
+  if (average_loop_time)
+    average_loop_time = (average_loop_time + loop_time) / 2;
+  else
+    average_loop_time = loop_time;
+
+  if (millis() >= next_report_time_) {
+    cycleTimeReport();
+
+    average_loop_time = 0;
+    next_report_time_ = millis() + 1000;
+  }
+
+  return EventHandlerResult::OK;
+}
+
+}
+}
+
+__attribute__((weak)) void cycleTimeReport(void) {
+  Serial.print(F("# average loop time: "));
+  Serial.println(CycleTimeReport.average_loop_time);
+}
+
+kaleidoscope::plugin::CycleTimeReport CycleTimeReport;

src/kaleidoscope/plugin/CycleTimeReport.h

@@ -0,0 +1,43 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-CycleTimeReport -- Scan cycle time reporting
+ * Copyright (C) 2017, 2018  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.h>
+
+namespace kaleidoscope {
+namespace plugin {
+class CycleTimeReport : public kaleidoscope::Plugin {
+ public:
+  CycleTimeReport() {}
+
+  EventHandlerResult onSetup();
+  EventHandlerResult beforeEachCycle();
+  EventHandlerResult afterEachCycle();
+
+  static uint32_t average_loop_time;
+
+ private:
+  static uint32_t next_report_time_;
+  static uint32_t loop_start_time_;
+};
+}
+}
+
+void cycleTimeReport(void);
+
+extern kaleidoscope::plugin::CycleTimeReport CycleTimeReport;