1
0
Fork 0

Add documentation and fix formating (#4860)

This commit is contained in:
Drashna Jaelre 2019-01-17 09:04:35 -08:00 committed by MechMerlin
parent f97894d8db
commit 5fcca9a226

View file

@ -17,82 +17,76 @@ uint32_t default_layer_state = 0;
/** \brief Default Layer State Set At user Level /** \brief Default Layer State Set At user Level
* *
* FIXME: Needs docs * Run user code on default layer state change
*/ */
__attribute__((weak)) __attribute__((weak))
uint32_t default_layer_state_set_user(uint32_t state) { uint32_t default_layer_state_set_user(uint32_t state) {
return state; return state;
} }
/** \brief Default Layer State Set At Keyboard Level /** \brief Default Layer State Set At Keyboard Level
* *
* FIXME: Needs docs * Run keyboard code on default layer state change
*/ */
__attribute__((weak)) __attribute__((weak))
uint32_t default_layer_state_set_kb(uint32_t state) { uint32_t default_layer_state_set_kb(uint32_t state) {
return default_layer_state_set_user(state); return default_layer_state_set_user(state);
} }
/** \brief Default Layer State Set /** \brief Default Layer State Set
* *
* FIXME: Needs docs * Static function to set the default layer state, prints debug info and clears keys
*/ */
static void default_layer_state_set(uint32_t state) static void default_layer_state_set(uint32_t state) {
{ state = default_layer_state_set_kb(state);
state = default_layer_state_set_kb(state); debug("default_layer_state: ");
debug("default_layer_state: "); default_layer_debug(); debug(" to ");
default_layer_debug(); debug(" to "); default_layer_state = state;
default_layer_state = state; default_layer_debug(); debug("\n");
default_layer_debug(); debug("\n");
#ifdef STRICT_LAYER_RELEASE #ifdef STRICT_LAYER_RELEASE
clear_keyboard_but_mods(); // To avoid stuck keys clear_keyboard_but_mods(); // To avoid stuck keys
#else #else
clear_keyboard_but_mods_and_keys(); // Don't reset held keys clear_keyboard_but_mods_and_keys(); // Don't reset held keys
#endif #endif
} }
/** \brief Default Layer Print /** \brief Default Layer Print
* *
* FIXME: Needs docs * Print out the hex value of the 32-bit default layer state, as well as the value of the highest bit.
*/ */
void default_layer_debug(void) void default_layer_debug(void) {
{ dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state));
dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state));
} }
/** \brief Default Layer Set /** \brief Default Layer Set
* *
* FIXME: Needs docs * Sets the default layer state.
*/ */
void default_layer_set(uint32_t state) void default_layer_set(uint32_t state) {
{ default_layer_state_set(state);
default_layer_state_set(state);
} }
#ifndef NO_ACTION_LAYER #ifndef NO_ACTION_LAYER
/** \brief Default Layer Or /** \brief Default Layer Or
* *
* FIXME: Needs docs * Turns on the default layer based on matching bits between specifed layer and existing layer state
*/ */
void default_layer_or(uint32_t state) void default_layer_or(uint32_t state) {
{ default_layer_state_set(default_layer_state | state);
default_layer_state_set(default_layer_state | state);
} }
/** \brief Default Layer And /** \brief Default Layer And
* *
* FIXME: Needs docs * Turns on default layer based on matching enabled bits between specifed layer and existing layer state
*/ */
void default_layer_and(uint32_t state) void default_layer_and(uint32_t state) {
{ default_layer_state_set(default_layer_state & state);
default_layer_state_set(default_layer_state & state);
} }
/** \brief Default Layer Xor /** \brief Default Layer Xor
* *
* FIXME: Needs docs * Turns on default layer based on non-matching bits between specifed layer and existing layer state
*/ */
void default_layer_xor(uint32_t state) void default_layer_xor(uint32_t state) {
{ default_layer_state_set(default_layer_state ^ state);
default_layer_state_set(default_layer_state ^ state);
} }
#endif #endif
@ -104,170 +98,168 @@ uint32_t layer_state = 0;
/** \brief Layer state set user /** \brief Layer state set user
* *
* FIXME: Needs docs * Runs user code on layer state change
*/ */
__attribute__((weak)) __attribute__((weak))
uint32_t layer_state_set_user(uint32_t state) { uint32_t layer_state_set_user(uint32_t state) {
return state; return state;
} }
/** \brief Layer state set keyboard /** \brief Layer state set keyboard
* *
* FIXME: Needs docs * Runs keyboard code on layer state change
*/ */
__attribute__((weak)) __attribute__((weak))
uint32_t layer_state_set_kb(uint32_t state) { uint32_t layer_state_set_kb(uint32_t state) {
return layer_state_set_user(state); return layer_state_set_user(state);
} }
/** \brief Layer state set /** \brief Layer state set
* *
* FIXME: Needs docs * Sets the layer to match the specifed state (a bitmask)
*/ */
void layer_state_set(uint32_t state) void layer_state_set(uint32_t state) {
{ state = layer_state_set_kb(state);
state = layer_state_set_kb(state); dprint("layer_state: ");
dprint("layer_state: "); layer_debug(); dprint(" to ");
layer_debug(); dprint(" to "); layer_state = state;
layer_state = state; layer_debug(); dprintln();
layer_debug(); dprintln();
#ifdef STRICT_LAYER_RELEASE #ifdef STRICT_LAYER_RELEASE
clear_keyboard_but_mods(); // To avoid stuck keys clear_keyboard_but_mods(); // To avoid stuck keys
#else #else
clear_keyboard_but_mods_and_keys(); // Don't reset held keys clear_keyboard_but_mods_and_keys(); // Don't reset held keys
#endif #endif
} }
/** \brief Layer clear /** \brief Layer clear
* *
* Turn off all layers. * Turn off all layers
*/ */
void layer_clear(void) void layer_clear(void) {
{ layer_state_set(0);
layer_state_set(0);
} }
/** \brief Layer state is /** \brief Layer state is
* *
* Return whether the given state is on (it might still be shadowed by a higher state, though). * Return whether the given state is on (it might still be shadowed by a higher state, though)
*/ */
bool layer_state_is(uint8_t layer) bool layer_state_is(uint8_t layer) {
{ return layer_state_cmp(layer_state, layer);
return layer_state_cmp(layer_state, layer);
} }
/** \brief Layer state compare /** \brief Layer state compare
* *
* FIXME: Needs docs * Used for comparing layers {mostly used for unit testing}
*/ */
bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) { bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) {
if (!cmp_layer_state) { return layer == 0; } if (!cmp_layer_state) { return layer == 0; }
return (cmp_layer_state & (1UL<<layer)) != 0; return (cmp_layer_state & (1UL<<layer)) != 0;
} }
/** \brief Layer move /** \brief Layer move
* *
* Turn on the given layer and turn off all other layers. * Turns on the given layer and turn off all other layers
*/ */
void layer_move(uint8_t layer) void layer_move(uint8_t layer) {
{ layer_state_set(1UL<<layer);
layer_state_set(1UL<<layer);
} }
/** \brief Layer on /** \brief Layer on
* *
* Turn on the given layer. * Turns on given layer
*/ */
void layer_on(uint8_t layer) void layer_on(uint8_t layer) {
{ layer_state_set(layer_state | (1UL<<layer));
layer_state_set(layer_state | (1UL<<layer));
} }
/** \brief Layer off /** \brief Layer off
* *
* FIXME: Needs docs * Turns off given layer
*/ */
void layer_off(uint8_t layer) void layer_off(uint8_t layer) {
{ layer_state_set(layer_state & ~(1UL<<layer));
layer_state_set(layer_state & ~(1UL<<layer));
} }
/** \brief Layer invert /** \brief Layer invert
* *
* Toggle the given layer (set it if it's unset, or unset it if it's set). * Toggle the given layer (set it if it's unset, or unset it if it's set)
*/ */
void layer_invert(uint8_t layer) void layer_invert(uint8_t layer) {
{ layer_state_set(layer_state ^ (1UL<<layer));
layer_state_set(layer_state ^ (1UL<<layer));
} }
/** \brief Layer or /** \brief Layer or
* *
* FIXME: Needs docs * Turns on layers based on matching bits between specifed layer and existing layer state
*/ */
void layer_or(uint32_t state) void layer_or(uint32_t state) {
{ layer_state_set(layer_state | state);
layer_state_set(layer_state | state);
} }
/** \brief Layer and /** \brief Layer and
* *
* FIXME: Needs docs * Turns on layers based on matching enabled bits between specifed layer and existing layer state
*/ */
void layer_and(uint32_t state) void layer_and(uint32_t state) {
{ layer_state_set(layer_state & state);
layer_state_set(layer_state & state);
} }
/** \brief Layer xor /** \brief Layer xor
* *
* FIXME: Needs docs * Turns on layers based on non-matching bits between specifed layer and existing layer state
*/ */
void layer_xor(uint32_t state) void layer_xor(uint32_t state) {
{ layer_state_set(layer_state ^ state);
layer_state_set(layer_state ^ state);
} }
/** \brief Layer debug printing /** \brief Layer debug printing
* *
* Print out the hex value of the 32-bit layer state, as well as the value of the highest bit. * Print out the hex value of the 32-bit layer state, as well as the value of the highest bit.
*/ */
void layer_debug(void) void layer_debug(void) {
{ dprintf("%08lX(%u)", layer_state, biton32(layer_state));
dprintf("%08lX(%u)", layer_state, biton32(layer_state));
} }
#endif #endif
#if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE) #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
/** \brief source layer cache
*/
uint8_t source_layers_cache[(MATRIX_ROWS * MATRIX_COLS + 7) / 8][MAX_LAYER_BITS] = {{0}}; uint8_t source_layers_cache[(MATRIX_ROWS * MATRIX_COLS + 7) / 8][MAX_LAYER_BITS] = {{0}};
void update_source_layers_cache(keypos_t key, uint8_t layer) /** \brief update source layers cache
{ *
const uint8_t key_number = key.col + (key.row * MATRIX_COLS); * Updates the cached keys when changing layers
const uint8_t storage_row = key_number / 8; */
const uint8_t storage_bit = key_number % 8; void update_source_layers_cache(keypos_t key, uint8_t layer) {
const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
const uint8_t storage_row = key_number / 8;
const uint8_t storage_bit = key_number % 8;
for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
source_layers_cache[storage_row][bit_number] ^= source_layers_cache[storage_row][bit_number] ^=
(-((layer & (1U << bit_number)) != 0) (-((layer & (1U << bit_number)) != 0)
^ source_layers_cache[storage_row][bit_number]) ^ source_layers_cache[storage_row][bit_number])
& (1U << storage_bit); & (1U << storage_bit);
} }
} }
uint8_t read_source_layers_cache(keypos_t key) /** \brief read source layers cache
{ *
const uint8_t key_number = key.col + (key.row * MATRIX_COLS); * reads the cached keys stored when the layer was changed
const uint8_t storage_row = key_number / 8; */
const uint8_t storage_bit = key_number % 8; uint8_t read_source_layers_cache(keypos_t key) {
uint8_t layer = 0; const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
const uint8_t storage_row = key_number / 8;
const uint8_t storage_bit = key_number % 8;
uint8_t layer = 0;
for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) { for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
layer |= layer |=
((source_layers_cache[storage_row][bit_number] ((source_layers_cache[storage_row][bit_number]
& (1U << storage_bit)) != 0) & (1U << storage_bit)) != 0)
<< bit_number; << bit_number;
} }
return layer; return layer;
} }
#endif #endif
@ -278,61 +270,58 @@ uint8_t read_source_layers_cache(keypos_t key)
* when the layer is switched after the down event but before the up * when the layer is switched after the down event but before the up
* event as they may get stuck otherwise. * event as they may get stuck otherwise.
*/ */
action_t store_or_get_action(bool pressed, keypos_t key) action_t store_or_get_action(bool pressed, keypos_t key) {
{
#if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE) #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
if (disable_action_cache) { if (disable_action_cache) {
return layer_switch_get_action(key);
}
uint8_t layer;
if (pressed) {
layer = layer_switch_get_layer(key);
update_source_layers_cache(key, layer);
}
else {
layer = read_source_layers_cache(key);
}
return action_for_key(layer, key);
#else
return layer_switch_get_action(key); return layer_switch_get_action(key);
#endif }
}
uint8_t layer;
/** \brief Layer switch get layer if (pressed) {
* layer = layer_switch_get_layer(key);
* FIXME: Needs docs update_source_layers_cache(key, layer);
*/ }
int8_t layer_switch_get_layer(keypos_t key) else {
{ layer = read_source_layers_cache(key);
#ifndef NO_ACTION_LAYER }
action_t action; return action_for_key(layer, key);
action.code = ACTION_TRANSPARENT;
uint32_t layers = layer_state | default_layer_state;
/* check top layer first */
for (int8_t i = 31; i >= 0; i--) {
if (layers & (1UL<<i)) {
action = action_for_key(i, key);
if (action.code != ACTION_TRANSPARENT) {
return i;
}
}
}
/* fall back to layer 0 */
return 0;
#else #else
return biton32(default_layer_state); return layer_switch_get_action(key);
#endif
}
/** \brief Layer switch get layer
*
* Gets the layer based on key info
*/
int8_t layer_switch_get_layer(keypos_t key) {
#ifndef NO_ACTION_LAYER
action_t action;
action.code = ACTION_TRANSPARENT;
uint32_t layers = layer_state | default_layer_state;
/* check top layer first */
for (int8_t i = 31; i >= 0; i--) {
if (layers & (1UL<<i)) {
action = action_for_key(i, key);
if (action.code != ACTION_TRANSPARENT) {
return i;
}
}
}
/* fall back to layer 0 */
return 0;
#else
return biton32(default_layer_state);
#endif #endif
} }
/** \brief Layer switch get layer /** \brief Layer switch get layer
* *
* FIXME: Needs docs * Gets action code based on key position
*/ */
action_t layer_switch_get_action(keypos_t key) action_t layer_switch_get_action(keypos_t key) {
{ return action_for_key(layer_switch_get_layer(key), key);
return action_for_key(layer_switch_get_layer(key), key);
} }