diff --git a/NEWS.md b/NEWS.md index 3690ec91..ec6b5f52 100644 --- a/NEWS.md +++ b/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 diff --git a/doc/plugin/FirmwareDump.md b/doc/plugin/FirmwareDump.md new file mode 100644 index 00000000..fa55c12e --- /dev/null +++ b/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 +#include +#include + +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] diff --git a/src/Kaleidoscope-FirmwareDump.h b/src/Kaleidoscope-FirmwareDump.h new file mode 100644 index 00000000..df2f37d6 --- /dev/null +++ b/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 . + */ + +#pragma once + +#include diff --git a/src/kaleidoscope/plugin/FirmwareDump.cpp b/src/kaleidoscope/plugin/FirmwareDump.cpp new file mode 100644 index 00000000..d5cfe22e --- /dev/null +++ b/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 . + */ + +#include +#include +#include + +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; diff --git a/src/kaleidoscope/plugin/FirmwareDump.h b/src/kaleidoscope/plugin/FirmwareDump.h new file mode 100644 index 00000000..91fe7a03 --- /dev/null +++ b/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 . + */ + +#pragma once + +#include + +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;