diff --git a/firmware/keyboard/ergodox/layout/common/keys.c.h b/firmware/keyboard/ergodox/layout/common/keys.c.h index da98312..8b845df 100644 --- a/firmware/keyboard/ergodox/layout/common/keys.c.h +++ b/firmware/keyboard/ergodox/layout/common/keys.c.h @@ -217,11 +217,38 @@ void R(shR2kcap) (void) { KF(2_keys_capslock)(false, KEYBOARD__RightShift); } * * This prepares the Teensy to load a new firmware. If you press this without * meaning to, you must turn your keyboard off then on again (usually by - * unplugging it, then plugging it back in) + * unplugging it, then plugging it back in). */ void P(btldr) (void) { KF(jump_to_bootloader)(); } void R(btldr) (void) {} +/** keys/dmp_sram/description + * type the contents of SRAM, in ihex format + * + * This may take a while. To cancel, you must turn your keyboard off then on + * again (usually by unplugging it, then plugging it back in). + */ +void P(dmp_sram) (void) { KF(dump_sram_ihex)( (void *)0, (void *)-1 ); } +void R(dmp_sram) (void) {} + +/** keys/dmp_prog/description + * type the contents of PROGMEM, in ihex format + * + * This may take a while. To cancel, you must turn your keyboard off then on + * again (usually by unplugging it, then plugging it back in). + */ +void P(dmp_prog) (void) { KF(dump_progmem_ihex)( (void *)0, (void *)-1 ); } +void R(dmp_prog) (void) {} + +/** keys/dmp_eepr/description + * type the contents of the EEPROM, in ihex format + * + * This may take a while. To cancel, you must turn your keyboard off then on + * again (usually by unplugging it, then plugging it back in). + */ +void P(dmp_eepr) (void) { KF(dump_eeprom_ihex)( (void *)0, (void *)-1 ); } +void R(dmp_eepr) (void) {} + // ---------------------------------------------------------------------------- // --- layer ------------------------------------------------------------------ diff --git a/firmware/keyboard/ergodox/layout/templates/kinesis-mod.c.h b/firmware/keyboard/ergodox/layout/templates/kinesis-mod.c.h index e0c420f..48ce19c 100644 --- a/firmware/keyboard/ergodox/layout/templates/kinesis-mod.c.h +++ b/firmware/keyboard/ergodox/layout/templates/kinesis-mod.c.h @@ -70,13 +70,6 @@ void kb__led__logical_off(char led) { KEYS__LAYER__NUM_PUSH(10, 3); KEYS__LAYER__NUM_POP(10); -// TODO dbg -void P(test)(void){ - KF(dump_progmem_ihex)(0, (void *)-1); -} -void R(test)(void){} -// TODO /dbg - // ---------------------------------------------------------------------------- // layout @@ -150,11 +143,9 @@ shL2kcap, T_z, T_x, T_c, T_v, T_b, lpupo1l1, nop, nop, nop, nop, nop, nop, // right hand ..... ......... ......... ......... ......... ......... ......... - nop, nop, nop, nop, nop, nop, test, -// TODO dbg -// nop, nop, nop, nop, nop, nop, nop, - nop, nop, nop, nop, nop, nop, nop, - nop, nop, nop, nop, nop, nop, + nop, nop, nop, nop, nop, nop, dmp_sram, + nop, nop, nop, nop, nop, nop, dmp_prog, + nop, nop, nop, nop, nop, dmp_eepr, nop, nop, nop, nop, nop, nop, nop, nop, nop, nop, nop, nop, nop, nop, diff --git a/firmware/lib/layout/key-functions.h b/firmware/lib/layout/key-functions.h index bcaa10c..1803d7c 100644 --- a/firmware/lib/layout/key-functions.h +++ b/firmware/lib/layout/key-functions.h @@ -27,9 +27,9 @@ void key_functions__toggle (uint8_t keycode); // device void key_functions__jump_to_bootloader (void); -void key_functions__dump_sram_ihex (void * from, void * last); // TODO: documentation -void key_functions__dump_progmem_ihex (void * from, void * last); // TODO: documentation -void key_functions__dump_eeprom_ihex (void * from, void * last); // TODO: documentation +void key_functions__dump_sram_ihex (void * from, void * last); +void key_functions__dump_progmem_ihex (void * from, void * last); +void key_functions__dump_eeprom_ihex (void * from, void * last); // special void key_functions__toggle_capslock (void); @@ -86,6 +86,43 @@ void key_functions__type_string (const char * string); * For reflashing the controller. */ +// === (group) dump...ihex() === +/** functions/(group) dump...ihex/description + * Type, in ihex format, the specified data from the appropriate memory space. + * + * Members: + * - `key_functions__dump_sram_ihex`: Types data from the SRAM + * - `key_functions__dump_progmem_ihex`: Types data from the PROGMEM + * - `key_functions__dump_eeprom_ihex`: Types data from the EEPROM + * + * Arguments: + * - `from`: A pointer to the location from which to start reading + * - `last`: A pointer to the last location from which to read + * + * Usage notes: + * - To print the entire contents of, e.g., SRAM, write + * + * key_functions__dump_sram_ihex( (void *)0, (void *)-1 ); + * + * See "Implementation notes" below. + * + * Warnings: + * - These functions may take a long time to complete, and there is no way to + * stop them aside from resetting the controller. + * - It may occur to you that one could read out the contents of PROGMEM using + * the appropriate function, and then use the resulting ihex file to reflash + * a Teensy. I would *not* recommend doing this however, unless you really + * know what you're doing, or you're prepared for the chance that you might + * mess something up. + * + * Implementation notes: + * - If `last` is greater than the maximum addressable location of the + * appropriate memory space, `last` should be set to the maximum addressable + * location. This will allow users to use `(void *)-1` (or `(void + * *)UINT16_MAX`) as the `last` location when they wish to read until the end + * of addressable memory. + */ + // ---------------------------------------------------------------------------- // special -------------------------------------------------------------------- diff --git a/firmware/lib/layout/key-functions/device/atmega32u4.c b/firmware/lib/layout/key-functions/device/atmega32u4.c index dce90ad..d17d036 100644 --- a/firmware/lib/layout/key-functions/device/atmega32u4.c +++ b/firmware/lib/layout/key-functions/device/atmega32u4.c @@ -48,30 +48,34 @@ static uint8_t progmem_read(void * from) { } /** functions/dump_ihex/description - * TODO: description + * Type, in ihex format, all data between `from` and `last`, inclusive. * * Arguments: - * - `read`: TODO - * - `from`: TODO - * - `last`: TODO + * - `read`: A pointer to a function that takes a memory address and returns 1 + * byte of data (presumably from that memory address, in whatever address + * space we're dealing with) + * - `from`: A pointer to the location from which to start reading + * - `last`: A pointer to the last location from which to read * * Notes: * - See [the Wikipedia article] (http://en.wikipedia.org/wiki/Intel_HEX) on - * the Intel hex (ihex) format. + * the Intel HEX (ihex) format. * * Implementation notes: * - When the loop starts, `from` might be `0`, and `last` might be * `UINT16_MAX`, in which case `from == last+1`. We need to ignore this on * the first iteration, hence the do-while loop and the `from != last+1` part - * of the first conditional. When this condition occurs again, it will be - * because `from` was incremented one past `last`, and the loop should be - * terminated. + * of the first conditional. When this condition occurs after the first + * iteration, it will be because `from` was incremented one past `last`, and + * the loop should be terminated. * - Pointer comparisons in C are interesting... Specifically, `last-from+1 < * line_width` seems to cast `last-from+1` to the same type as `line_width` * (`uint8_t`) which causes problems since pointers on this platform are 16 * bits. Casting either side of the expression to `uint16_t` seems to solve - * the problem. It feels cleaner to me to cast the pointer side because - * comparisons between pointers and integers is only implementation defined. + * the problem. It feels cleaner to me to cast the pointer side, because + * comparison between pointers and integers is only implementation defined, + * whereas comparison between two integers ought to be defined by the + * standard. */ static void dump_ihex( uint8_t (*read)(void *), void * from, diff --git a/firmware/lib/timer.h b/firmware/lib/timer.h index f5075fe..b371ef7 100644 --- a/firmware/lib/timer.h +++ b/firmware/lib/timer.h @@ -88,8 +88,8 @@ void timer___tick_keypresses (void); * - Should be called exactly once by `main()` before entering the run loop. */ -// === (group) get === -/** functions/(group) get/description +// === (group) get...() === +/** functions/(group) get.../description * Return the number of "ticks" since the given timer was initialized * (mod 2^16) *