diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..fcfd956 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,72 @@ +name: CI + +on: + push: + branches: + - master + release: + types: + - published + pull_request: + +jobs: + build: + name: Build + runs-on: ${{ matrix.os }} + + strategy: + matrix: + os: [macos-latest, windows-2019, ubuntu-latest] + + steps: + - uses: actions/checkout@v2 + + - name: Compile and Package + shell: bash + run: | + make clean all + 7z a ./build/mdloader-${RUNNER_OS}.zip ./build/mdloader* + + - uses: actions/upload-artifact@v2 + with: + name: ${{ matrix.os }} + path: build/mdloader*.zip + + publish_release: + name: Publish (Release) + runs-on: ubuntu-latest + + needs: [build] + + if: github.event.release.tag_name + + steps: + - uses: actions/download-artifact@v2 + + - uses: softprops/action-gh-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + name: ${{ github.event.release.name }} + files: | + ./*/mdloader* + + publish_beta: + name: Publish (Beta) + runs-on: ubuntu-latest + + needs: [build] + + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} + + steps: + - uses: actions/download-artifact@v2 + + - uses: marvinpinto/action-automatic-releases@latest + with: + repo_token: "${{ secrets.GITHUB_TOKEN }}" + automatic_release_tag: "beta" + prerelease: true + title: "Latest Beta" + files: | + ./*/mdloader* diff --git a/Makefile b/Makefile index cbffc63..599496b 100644 --- a/Makefile +++ b/Makefile @@ -14,8 +14,6 @@ OBJFILES = $(patsubst %.c,%.o,$(SRCFILES)) OBJS = $(addprefix $(OBJDIR)/,$(OBJFILES)) all: $(OBJDIR)/$(OUTNAME) - $(info Copying applets to ${OBJDIR}...) - @cp applet-*.bin $(OBJDIR) $(info Done!) $(OBJDIR)/$(OUTNAME): $(OBJS) diff --git a/README.md b/README.md index 175779f..7716102 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,41 @@ -### tl;dr +### User instructions 1. Follow the instructions here to download the executable for your operating system: https://github.com/Massdrop/mdloader/releases 2. Plug in your keyboard. -3. Press the reset button on your keyboard. +3. In your terminal, change to the directory where you downloaded the executable file. -4. In your terminal, change to the directory where you downloaded the executable and applet-*.bin file(s). +4. Move your compiled firmware to the same directory as the executable file. -5. **Windows** - Run `mdloader_windows.exe --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware. -**Linux** - Run `mdloader_linux --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware. -**Mac** - Run `mdloader_mac --first --download FILE_NAME --restart`. If you downloaded with Mac Safari, run `mdloader_mac.dms --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware. +5. Run the following command: +``` +./mdloader --first --download FILE_NAME --restart +``` +**Note**: Replace `FILE_NAME` with the filename of your compiled firmware. + +6. You should see the message: +``` +Scanning for device for 60 seconds +..... +``` + +7. Within 60 seconds, press the reset button on your keyboard. For most keyboards running the default firmware, you can hold `Fn` + `b` for half a second and release to reset your keyboard (you will see the LEDs turn off). For CTRL keyboards in the first production run running original firmware or of the first method does not work for you, you will need to use a pin to press the reset button through the hole in the bottom of the keyboard. -6. Enjoy (important) +8. You should see a series of messages similar to: +``` +Device port: /dev/cu.usbmodem234431 (SAMD51J18A) + +Opening port '/dev/cu.usbmodem234431'... Success! +Found MCU: SAMD51J18A +Bootloader version: v2.18Sep 4 2018 16:48:28 +Applet Version: 1 +Writing firmware... Complete! +Booting device... Success! +Closing port... Success! +``` + +9. Afterwards, you should see the keyboard's LEDs light up again (if your configuration has LEDs enabled) and the keyboard should respond to typing. Your keyboard is now running the new firmware you specified. ----- @@ -22,9 +45,9 @@ Massdrop Loader is used to read firmware from and write firmware to Massdrop key ## Supported operating systems -Windows XP or greater (32-bit and 64-bit versions, USB Serial driver in drv_win folder) -Linux x86 (32-bit and 64-bit versions) -Mac OS X +- Windows XP or greater (32-bit and 64-bit versions, USB Serial driver in drv_win folder) +- Linux x86 (32-bit and 64-bit versions) +- Mac OS X ## Supported devices @@ -32,13 +55,13 @@ Massdrop keyboard's featuring Microchip's SAM-BA bootloader. ## Building -Enter mdloader directory where Makefile is located and excute: +Enter mdloader directory where Makefile is located and execute: -`make` +``` +make +``` -This will create a `build` directory with the compiled executable and required applet-*.bin files. -Run `./build/mdloader` to test. -Note that the target MCU applet file must exist in the directory the executable is called from. +This will create a `build` directory with the compiled executable. Run `./build/mdloader` to test. ## Usage ``` @@ -54,6 +77,7 @@ Usage: mdloader [options] ... -s --size size Read firmware size of -D --download file Write firmware from into device -t --test Test mode (download/upload writes disabled, upload outputs data to stdout, restart disabled) + --ignore-eep Ignore differences in SmartEEPROM configuration --cols count Hex listing column count [8] --colw width Hex listing column width [4] --restart Restart device after successful programming @@ -61,7 +85,9 @@ Usage: mdloader [options] ... To write firmware to the device and restart it: -`mdloader --first --download new_firmware.hex --restart` +``` +mdloader --first --download new_firmware.hex --restart` +``` The program will now be searching for your device. Press the reset switch found through the small hole on the back case or by appropriate key sequence to enter programming mode and allow programming to commence. Firmware may be provided as a binary ending in .bin or an Intel HEX format ending in .hex, but .hex is preferred for data integrity. @@ -69,14 +95,16 @@ Note that safeguards are in place to prevent overwriting the bootloader section To read firmware from the device: -`mdloader --first --upload read_firmware.bin --addr 0x4000 --size 0x10000` +``` +mdloader --first --upload read_firmware.bin --addr 0x4000 --size 0x10000 +``` -Where --addr and --size are set as desired. +Where `--addr` and `--size` are set as desired. Note the output of reading firmware will be in binary format. -Test mode may be invoked with the --test switch to test operations while preventing firmware modification. +Test mode may be invoked with the `--test` switch to test operations while preventing firmware modification. Test mode also allows viewing of binary data from a read instead of writing to a file. ## Troubleshooting -Linux: User may need to be added to group dialout to access programming port +**Linux**: User may need to be added to group dialout to access programming port diff --git a/applet-flash-samd51j18a.bin b/applet-mdflash.bin similarity index 100% rename from applet-flash-samd51j18a.bin rename to applet-mdflash.bin diff --git a/incbin/.travis.yml b/incbin/.travis.yml new file mode 100644 index 0000000..4337da6 --- /dev/null +++ b/incbin/.travis.yml @@ -0,0 +1,12 @@ +language: c + +os: +- linux +- osx + +compiler: +- gcc +- clang + +script: +- make -C test test diff --git a/incbin/README.md b/incbin/README.md new file mode 100644 index 0000000..cada41f --- /dev/null +++ b/incbin/README.md @@ -0,0 +1,167 @@ +# incbin + +Include binary files in your C/C++ applications with ease + +## Example + +``` c + #include "incbin.h" + + INCBIN(Icon, "icon.png"); + + // This translation unit now has three symbols + // const unsigned char gIconData[]; + // const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer + // const unsigned int gIconSize; + + // Reference in other translation units like this + INCBIN_EXTERN(Icon); + + // This translation unit now has three extern symbols + // Use `extern "C"` in case of writing C++ code + // extern const unsigned char gIconData[]; + // extern const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer + // extern const unsigned int gIconSize; +``` + +## Portability + +Known to work on the following compilers + +* GCC +* Clang +* PathScale +* Intel +* Solaris & Sun Studio +* Green Hills +* SNC (ProDG) +* Diab C++ (WindRiver) +* XCode +* ArmCC +* RealView +* ImageCraft +* Stratus VOS C +* TinyCC +* cparser & libfirm +* LCC +* MSVC _See MSVC below_ + +If your compiler is not listed, as long as it supports GCC inline assembler, this +should work. + +## MISRA +INCBIN can be used in MISRA C setting. However it should be independently checked +due to its use of inline assembly to achieve what it does. Independent verification +of the header has been done several times based on commit: 7e327a28ba5467c4202ec37874beca7084e4b08c + +## Alignment + +The data included by this tool will be aligned on the architectures word boundary +unless some variant of SIMD is detected, then it's aligned on a byte boundary that +respects SIMD convention just incase your binary data may be used in vectorized +code. The table of the alignments for SIMD this header recognizes is as follows: + +| SIMD | Alignment | +|-----------------------------------------|-----------| +| SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 | 16 | +| Neon | 16 | +| AVX, AVX2 | 32 | +| AVX512 | 64 | + +## Prefix +By default, `incbin.h` emits symbols with a `g` prefix. This can be adjusted by +defining `INCBIN_PREFIX` before including `incbin.h` with a desired prefix. For +instance + +``` c + #define INCBIN_PREFIX g_ + #include "incbin.h" + INCBIN(test, "test.txt"); + + // This translation unit now has three symbols + // const unsigned char g_testData[]; + // const unsigned char *const g_testEnd; + // const unsigned int g_testSize; +``` + +You can also choose to have no prefix by defining the prefix with nothing, for example: + +``` c + #define INCBIN_PREFIX + #include "incbin.h" + INCBIN(test, "test.txt"); + + // This translation unit now has three symbols + // const unsigned char testData[]; + // const unsigned char *const testEnd; + // const unsigned int testSize; +``` + +## Style +By default, `incbin.h` emits symbols with `CamelCase` style. This can be adjusted +by defining `INCBIN_STYLE` before including `incbin.h` to change the style. There +are two possible styles to choose from + +* INCBIN_STYLE_CAMEL (CamelCase) +* INCBIN_STYLE_SNAKE (snake_case) + +For instance: + +``` c + #define INCBIN_STYLE INCBIN_STYLE_SNAKE + #include "incbin.h" + INCBIN(test, "test.txt"); + + // This translation unit now has three symbols + // const unsigned char gtest_data[]; + // const unsigned char *const gtest_end; + // const unsigned int gtest_size; +``` + +Combining both the style and prefix allows for you to adjust `incbin.h` to suite +your existing style and practices. + +## Overriding Linker Output section +By default, `incbin.h` emits into the read-only linker output section used on +the detected platform. If you need to override this for whatever reason, you +can manually specify the linker output section. + +For example, to emit data into program memory for +[esp8266/Arduino](github.com/esp8266/Arduino): + +``` c +#define INCBIN_OUTPUT_SECTION ".irom.text" +#include "incbin.h" +INCBIN(Foo, "foo.txt"); +// Data is emitted into program memory that never gets copied to RAM +``` + +## Explanation + +`INCBIN` is a macro which uses the inline assembler provided by almost all +compilers to include binary files. It achieves this by utilizing the `.incbin` +directive of the inline assembler. It then uses the assembler to calculate the +size of the included binary and exports two global symbols that can be externally +referenced in other translation units which contain the data and size of the +included binary data respectively. + +## MSVC + +Supporting MSVC is slightly harder as MSVC lacks an inline assembler which can +include data. To support this we ship a tool which can process source files +containing `INCBIN` macro usage and generate an external source file containing +the data of all of them combined. This file is named `data.c` by default. +Just include it into your build and use the `incbin.h` to reference data as +needed. It's suggested you integrate this tool as part of your projects's +pre-build events so that this can be automated. A more comprehensive list of +options for this tool can be viewed by invoking the tool with `-help` + +If you're using a custom prefix, be sure to specify the prefix on the command +line with `-p ` so that everything matches up; similarly, if you're +using a custom style, be sure to specify the style on the command line with +`-S