Added sketch exploration

This commit adds a new template hook exploreSketch() that allows plugins to efficiently
obtain compile-time known information about the sketch.
The hook is called before setup and is passed a _Sketch
template parameter that wraps two more types Plugins and StaticKeymap, whose static constexpr methods can be used
to explore the registered plugins and the static keymap.

Signed-off-by: Florian Fleissner <[email protected]>

Author: Florian Fleissner

examples/Internal/Sketch_Exploration/Makefile

@@ -0,0 +1,55 @@
+# This stub makefile for a Kaleidoscope example pulls in all the targets
+# required to build the example
+
+UNAME_S := $(shell uname -s)
+
+ifeq ($(UNAME_S),Darwin)
+SKETCHBOOK_DIR ?= $(HOME)/Documents/Arduino
+PACKAGE_DIR ?= $(HOME)/Library/Arduino15
+else
+SKETCHBOOK_DIR ?= $(HOME)/Arduino
+PACKAGE_DIR ?= $(HOME)/.arduino15
+endif
+
+
+ARDUINO_INSTALLED_ENV=$(shell ls -dt $(PACKAGE_DIR)/packages/keyboardio/hardware/avr 2>/dev/null |head -n 1)
+MANUALLY_INSTALLED_ENV=$(shell ls -dt $(SKETCHBOOK_DIR)/hardware/keyboardio/avr 2>/dev/null |head -n 1)
+
+
+
+ifneq ("$(wildcard $(ARDUINO_INSTALLED_ENV)/boards.txt)","")
+
+ifneq ("$(wildcard $(MANUALLY_INSTALLED_ENV)/boards.txt)","")
+
+$(info ***************************************************************************)
+$(info It appears that you have installed two copies of Kaleidoscope. One copy was)
+$(info installed using Arduino's "Board Manager", while the other was installed by)
+$(info hand, probably using "git".)
+$(info )
+$(info This will likely cause some trouble as you try to build keyboard firmware)
+$(info using Kaleidoscope. You may want to remove either: )
+$(info )
+$(info $(PACKAGE_DIR)/packages/keyboardio/ which was installed using Arduino)
+$(info )
+$(info or)
+$(info )
+$(info $(SKETCHBOOK_DIR)/hardware/keyboardio/ which was installed by hand.)
+$(info )
+$(info ***************************************************************************)
+$(info )
+	
+endif
+
+BOARD_HARDWARE_PATH = $(ARDUINO_INSTALLED_ENV)
+KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR ?= build-tools/makefiles/
+KALEIDOSCOPE_BUILDER_DIR ?= $(ARDUINO_INSTALLED_ENV)/libraries/Kaleidoscope/bin/
+
+
+
+endif
+
+
+BOARD_HARDWARE_PATH ?= $(SKETCHBOOK_DIR)/hardware
+KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR ?= keyboardio/avr/build-tools/makefiles/
+
+include $(BOARD_HARDWARE_PATH)/$(KALEIDOSCOPE_PLUGIN_MAKEFILE_DIR)/rules.mk

examples/Internal/Sketch_Exploration/Sketch_Exploration.ino

@@ -0,0 +1,139 @@
+/* -*- mode: c++ -*-
+ * Basic -- A very basic Kaleidoscope example
+ * Copyright (C) 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"
+
+
+// This example demonstrates how a plugin can gather information about
+// the keymap at compile time, e.g. to adapt its behavior, safe resources, ...
+
+/* *INDENT-OFF* */
+KEYMAPS(
+  [0] = KEYMAP_STACKED
+  (
+   Key_NoKey,    Key_1, Key_1, Key_1, 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_NoKey,
+
+   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_NoKey
+  ),
+)
+/* *INDENT-ON* */
+
+using namespace kaleidoscope::sketch_exploration;
+
+class BPlugin : public kaleidoscope::Plugin {};
+class CPlugin : public kaleidoscope::Plugin {};
+
+// A simple plugin that defines just one hook.
+//
+class APlugin : public kaleidoscope::Plugin {
+
+ public:
+  APlugin() : has_key_1_{false} {}
+
+  template<typename _Sketch>
+  kaleidoscope::EventHandlerResult exploreSketch() {
+
+    // Static keymap exploration
+
+    typedef typename _Sketch::StaticKeymap K;
+
+    // Important: Always make sure to call _Sketch::StaticKeymap's methods
+    //            in a constexpr context. This is done by
+    //            passing their value to a constexpr temporary variable.
+
+    constexpr uint8_t n_key_1 = K::collect(NumKeysEqual{Key_1});
+    static_assert(n_key_1 == 3, "Error determining key count");
+
+    constexpr bool has_key_1 = K::collect(HasKey{Key_1});
+    static_assert(has_key_1, "Error querying key existence");
+    has_key_1_ = has_key_1; // Assign the temporary that was computed
+    // at compile time.
+
+    constexpr Key max_key = K::collect(MaxKeyRaw{});
+    static_assert(max_key.getRaw() > 0, "");
+
+    static_assert(K::getKey(0 /*layer*/, KeyAddr{2, 3}) == Key_D,
+                  "Key lookup failed");
+
+    constexpr auto n_layers = K::nLayers();
+    constexpr auto layer_size = K::layerSize();
+
+    // Plugin exploration
+    //
+    // Use macros ENTRY_TYPE, ENRTY_IS_LAST, PLUGIN_POSITION,
+    // PLUGIN_IS_REGISTERED and NUM_OCCURRENCES to retreive information
+    // about the plugins that are registered in the sketch.
+
+    typedef typename _Sketch::Plugins P;
+
+    static_assert(std::is_same<ENTRY_TYPE(P, 0), APlugin>::value, "");
+    static_assert(std::is_same<ENTRY_TYPE(P, 1), BPlugin>::value, "");
+
+    static_assert(P::size == 3, "");
+
+    static_assert(!ENRTY_IS_LAST(P, 0), "");
+    static_assert(!ENRTY_IS_LAST(P, 1), "");
+    static_assert(ENRTY_IS_LAST(P, 2), "");
+
+    static_assert(PLUGIN_POSITION(P, APlugin) == 0, "");
+    static_assert(PLUGIN_POSITION(P, BPlugin) == 1, "");
+    static_assert(PLUGIN_POSITION(P, CPlugin) == -1, "");
+
+    static_assert(PLUGIN_IS_REGISTERED(P, APlugin) == true, "");
+    static_assert(PLUGIN_IS_REGISTERED(P, BPlugin) == true, "");
+    static_assert(PLUGIN_IS_REGISTERED(P, CPlugin) == false, "");
+
+    static_assert(NUM_OCCURRENCES(P, APlugin) == 2, "");
+    static_assert(NUM_OCCURRENCES(P, BPlugin) == 1, "");
+    static_assert(NUM_OCCURRENCES(P, CPlugin) == 0, "");
+
+    return kaleidoscope::EventHandlerResult::OK;
+  }
+
+ private:
+
+  bool has_key_1_;
+};
+
+APlugin a_plugin1, a_plugin2;
+BPlugin b_plugin;
+
+KALEIDOSCOPE_INIT_PLUGINS(
+  a_plugin1,
+  b_plugin,
+  a_plugin2
+)
+
+void setup() {
+  Kaleidoscope.setup();
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}

src/kaleidoscope/Kaleidoscope.cpp

@@ -36,6 +36,7 @@ Kaleidoscope_::setup(void) {
   // properly.
   device().serialPort().begin(9600);
 
+  kaleidoscope::sketch_exploration::pluginsExploreSketch();
   kaleidoscope::Hooks::onSetup();
 
   device().setup();

src/kaleidoscope/Kaleidoscope.h

@@ -59,6 +59,7 @@ static constexpr DEPRECATED(LED_COUNT) uint8_t LED_COUNT = kaleidoscope_internal
 #include "kaleidoscope/key_events.h"
 #include "kaleidoscope/hid.h"
 #include "kaleidoscope/layers.h"
+#include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
 #include "kaleidoscope/macro_map.h"
 #include "kaleidoscope_internal/event_dispatch.h"
 #include "kaleidoscope_internal/LEDModeManager.h"

src/kaleidoscope/event_handlers.h

@@ -220,7 +220,19 @@ class SignatureCheckDummy {};
              _CURRENT_IMPLEMENTATION,                                     __NL__ \
                _NOT_ABORTABLE,                                            __NL__ \
                (),(),(), /* non template */                               __NL__ \
-               (),(),##__VA_ARGS__)
+               (),(),##__VA_ARGS__)                                       __NL__ \
+                                                                          __NL__ \
+   /* Called before setup to enable plugins at compile time            */ __NL__ \
+   /* to explore the sketch.                                           */ __NL__ \
+   OPERATION(exploreSketch ,                                              __NL__ \
+             1,                                                           __NL__ \
+             _CURRENT_IMPLEMENTATION,                                     __NL__ \
+               _NOT_ABORTABLE,                                            __NL__ \
+               (,typename _Sketch),                                       __NL__ \
+               (,_Sketch),                                                __NL__ \
+               (,kaleidoscope::SignatureCheckDummy),                      __NL__ \
+               (),                                                        __NL__ \
+               (),##__VA_ARGS__)
 
 // The following function macro lists event handler/hook method names and
 // available versions. It is used to auto-generate code that is
@@ -273,4 +285,8 @@ class SignatureCheckDummy {};
                                                                         __NL__ \
    START(afterEachCycle, 1)                                             __NL__ \
       OP(afterEachCycle, 1)                                             __NL__ \
-   END(afterEachCycle, 1)
+   END(afterEachCycle, 1)                                               __NL__ \
+                                                                        __NL__ \
+   START(exploreSketch, 1)                                              __NL__ \
+      OP(exploreSketch, 1)                                              __NL__ \
+   END(exploreSketch, 1)

src/kaleidoscope/hooks.cpp

@@ -45,4 +45,18 @@ _FOR_EACH_EVENT_HANDLER(INSTANTIATE_WEAK_HOOK_FUNCTION)
 
 #undef INSTANTIATE_WEAK_HOOK_FUNCTION
 
+namespace sketch_exploration {
+class Sketch;
+}
+
+// Make sure that there is no undefined symbol if KALEIDOSCOPE_INIT_PLUGINS(...)
+// is not invoked in the user's sketch.
+//
+template<>
+__attribute__((weak))
+EventHandlerResult Hooks::exploreSketch
+<sketch_exploration::Sketch>() {
+  return EventHandlerResult::OK;
+};
+
 } // namespace kaleidoscope

src/kaleidoscope/hooks.h

@@ -41,6 +41,10 @@ class LEDControl;
 // Forward declaration to enable friend declarations.
 class Layer_;
 
+namespace sketch_exploration {
+void pluginsExploreSketch();
+} // namespace sketch_exploration
+
 // The reason why the hook routing entry point functions live within
 // class Hooks and not directly within a namespace is, that we want
 // to restrict who is allowed to trigger hooks, mainly to prevent
@@ -60,6 +64,7 @@ class Hooks {
   friend class Kaleidoscope_;
   friend class ::kaleidoscope::Layer_;
   friend class ::kaleidoscope::plugin::LEDControl;
+  friend void ::kaleidoscope::sketch_exploration::pluginsExploreSketch();
 
   // ::handleKeyswitchEvent(...) calls Hooks::onKeyswitchEvent.
   friend void ::handleKeyswitchEvent(kaleidoscope::Key mappedKey,

src/kaleidoscope/layers.h

@@ -21,6 +21,7 @@
 #include "kaleidoscope/keymaps.h"
 #include "kaleidoscope/device/device.h"
 #include "kaleidoscope_internal/device.h"
+#include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
 
 // Macro for defining the keymap. This should be used in the sketch
 // file (*.ino) to define the keymap[] array that holds the user's
@@ -33,7 +34,9 @@
   /* This deprecated compatibility wrapper is removed by the linker if  __NL__ \
      it is not accessed nowhere.                                        __NL__ \
   */                                                                    __NL__ \
-  kaleidoscope::internal::Keymaps2DInterface keymaps;
+  kaleidoscope::internal::Keymaps2DInterface keymaps;                   __NL__ \
+                                                                        __NL__ \
+  _INIT_SKETCH_EXPLORATION
 
 extern uint8_t layer_count;
 

src/kaleidoscope_internal/event_dispatch.h

@@ -38,7 +38,7 @@
 #include "kaleidoscope/hooks.h"
 #include "kaleidoscope_internal/eventhandler_signature_check.h"
 #include "kaleidoscope/event_handlers.h"
-#include "kaleidoscope_internal/keymap_exploration.h"
+#include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
 
 // Some words about the design of hook routing:
 //
@@ -214,4 +214,6 @@
                                                                               __NL__ \
   /* This generates a PROGMEM array-kind-of data structure that contains   */ __NL__ \
   /* LEDModeFactory entries                                                */ __NL__ \
-  _INIT_LED_MODE_MANAGER(__VA_ARGS__)
+  _INIT_LED_MODE_MANAGER(__VA_ARGS__)                                         __NL__ \
+                                                                              __NL__ \
+  _INIT_PLUGIN_EXPLORATION(__VA_ARGS__)