Merge pull request #543 from keyboardio/plugin/firmwaredump

Add a FirmwareDump plugin

NEWS.md

@@ -124,6 +124,10 @@ We integrated the [LEDWavepool](doc/plugin/LED-Wavepool.md) plugin by [ToyKeeper
 
 The [WinKeyToggle](doc/plugin/WinKeyToggle.md) plugin assists with toggling the Windows key on and off - a little something for those of us who game under Windows and are tired of accidentally popping up the start menu.
 
+### FirmwareDump
+
+The [FirmwareDump](doc/plugin/FirmwareDump.md) plugin makes it possible to dump one's firmware over Focus.
+
 ## Breaking changes
 
 ### The `RxCy` macros and peeking into the keyswitch state

doc/plugin/FirmwareDump.md

@@ -0,0 +1,43 @@
+# Kaleidoscope-FirmwareDump
+
+This plugin provides a single Focus command: `firmware.dump`, which dumps the
+firmware's executable code. One might rightfully wonder what purpose this serves
+when the source code is available, but rest assured, there is one: in case one
+wants to temporarily replace their firmware, then put it back on, without having
+to carry the HEX file around, this command makes that possible: dump the
+contents, turn them into HEX, and it can be re-flashed at any point. We get a
+HEX file on-demand, and don't have to carry it around!
+
+The intended primary user of this feature is [Chrysalis][chrysalis].
+
+ [chrysalis]: https://github.com/keyboardio/Chrysalis
+
+## Using the plugin
+
+To use the plugin, include the header, and add it to your list of plugins:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-FocusSerial.h>
+#include <Kaleidoscope-FirmwareDump.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(FocusSerial, FirmwareDump);
+
+void setup () {
+  Kaleidoscope.setup();
+}
+```
+
+## Focus commands
+
+The plugin provides a single [Focus][FocusSerial] command:
+
+ [FocusSerial]: FocusSerial.md
+
+### `firmware.dump`
+
+> Dumps the entire firmware (bootloader not included), even the unused parts.
+
+## Dependencies
+
+* [Kaleidoscope-FocusSerial][FocusSerial]

src/Kaleidoscope-FirmwareDump.h

@@ -0,0 +1,20 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-FirmwareDump -- Firmware dumper for Kaleidoscope
+ * Copyright (C) 2019  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/FirmwareDump.h>

src/kaleidoscope/plugin/FirmwareDump.cpp

@@ -0,0 +1,70 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-FirmwareDump -- Firmware dumper for Kaleidoscope
+ * Copyright (C) 2019  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-FirmwareDump.h>
+#include <Kaleidoscope-FocusSerial.h>
+#include <avr/boot.h>
+
+namespace kaleidoscope {
+namespace plugin {
+
+EventHandlerResult FirmwareDump::onSetup() {
+  enum {
+    BOOT_SIZE_4096 = 0b000,
+    BOOT_SIZE_2048 = 0b010,
+    BOOT_SIZE_1024 = 0b100,
+    BOOT_SIZE_512  = 0b110
+  };
+
+  uint8_t high_fuse = boot_lock_fuse_bits_get(GET_HIGH_FUSE_BITS);
+
+  if (high_fuse & BOOT_SIZE_512) {
+    bootloader_size_ = 512;
+  } else if (high_fuse & BOOT_SIZE_1024) {
+    bootloader_size_ = 1024;
+  } else if (high_fuse & BOOT_SIZE_2048) {
+    bootloader_size_ = 2048;
+  } else {
+    bootloader_size_ = 4096;
+  }
+
+  return EventHandlerResult::OK;
+}
+
+EventHandlerResult FirmwareDump::onFocusEvent(const char *command) {
+  const char *cmd = PSTR("firmware.dump");
+
+  if (::Focus.handleHelp(command, cmd))
+    return EventHandlerResult::OK;
+
+  if (strcmp_P(command, cmd) != 0)
+    return EventHandlerResult::OK;
+
+  uint16_t flash_size = (FLASHEND + 1L);
+
+  for (uint32_t i = 0; i < flash_size - bootloader_size_; i++) {
+    uint8_t b = pgm_read_byte(i);
+    Focus.send(b);
+  }
+
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
+}
+}
+
+kaleidoscope::plugin::FirmwareDump FirmwareDump;

src/kaleidoscope/plugin/FirmwareDump.h

@@ -0,0 +1,38 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-FirmwareDump -- Firmware dumper for Kaleidoscope
+ * Copyright (C) 2019  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 FirmwareDump : public kaleidoscope::Plugin {
+ public:
+  FirmwareDump() {}
+
+  EventHandlerResult onSetup();
+  EventHandlerResult onFocusEvent(const char *command);
+ private:
+  uint16_t bootloader_size_;
+};
+
+}
+}
+
+extern kaleidoscope::plugin::FirmwareDump FirmwareDump;