From a0959f1b3393d284b3aa11162497e8851fd94bca Mon Sep 17 00:00:00 2001 From: Simon Arlott <70171+nomis@users.noreply.github.com> Date: Wed, 16 Jun 2021 05:00:37 +0100 Subject: [PATCH] Add asym_eager_defer_pk debounce type (#12689) --- docs/feature_debounce_type.md | 4 +- quantum/debounce/asym_eager_defer_pk.c | 171 ++++++++ .../tests/asym_eager_defer_pk_tests.cpp | 374 ++++++++++++++++++ quantum/debounce/tests/rules.mk | 5 + quantum/debounce/tests/testlist.mk | 3 +- 5 files changed, 554 insertions(+), 3 deletions(-) create mode 100644 quantum/debounce/asym_eager_defer_pk.c create mode 100644 quantum/debounce/tests/asym_eager_defer_pk_tests.cpp diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 3ad74224c1..306185fe83 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -121,16 +121,16 @@ DEBOUNCE_TYPE = Where name of algorithm is one of: * ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant. -* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. +* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. * ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key * ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. +* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed. ### A couple algorithms that could be implemented in the future: * ```sym_defer_pr``` * ```sym_eager_g``` -* ```asym_eager_defer_pk``` ### Use your own debouncing code You have the option to implement you own debouncing algorithm. To do this: diff --git a/quantum/debounce/asym_eager_defer_pk.c b/quantum/debounce/asym_eager_defer_pk.c new file mode 100644 index 0000000000..24380dc5e5 --- /dev/null +++ b/quantum/debounce/asym_eager_defer_pk.c @@ -0,0 +1,171 @@ +/* + * Copyright 2017 Alex Ong + * Copyright 2020 Andrei Purdea + * Copyright 2021 Simon Arlott + * + * 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, either version 2 of the License, or + * (at your option) any later version. + * + * 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 . + */ + +/* +Basic symmetric per-key algorithm. Uses an 8-bit counter per key. +When no state changes have occured for DEBOUNCE milliseconds, we push the state. +*/ + +#include "matrix.h" +#include "timer.h" +#include "quantum.h" +#include + +#ifdef PROTOCOL_CHIBIOS +# if CH_CFG_USE_MEMCORE == FALSE +# error ChibiOS is configured without a memory allocator. Your keyboard may have set `#define CH_CFG_USE_MEMCORE FALSE`, which is incompatible with this debounce algorithm. +# endif +#endif + +#ifndef DEBOUNCE +# define DEBOUNCE 5 +#endif + +// Maximum debounce: 127ms +#if DEBOUNCE > 127 +# undef DEBOUNCE +# define DEBOUNCE 127 +#endif + +#define ROW_SHIFTER ((matrix_row_t)1) + +typedef struct { + bool pressed : 1; + uint8_t time : 7; +} debounce_counter_t; + +#if DEBOUNCE > 0 +static debounce_counter_t *debounce_counters; +static fast_timer_t last_time; +static bool counters_need_update; +static bool matrix_need_update; + +#define DEBOUNCE_ELAPSED 0 + +static void update_debounce_counters_and_transfer_if_expired(matrix_row_t raw[], matrix_row_t cooked[], uint8_t num_rows, uint8_t elapsed_time); +static void transfer_matrix_values(matrix_row_t raw[], matrix_row_t cooked[], uint8_t num_rows); + +// we use num_rows rather than MATRIX_ROWS to support split keyboards +void debounce_init(uint8_t num_rows) { + debounce_counters = malloc(num_rows * MATRIX_COLS * sizeof(debounce_counter_t)); + int i = 0; + for (uint8_t r = 0; r < num_rows; r++) { + for (uint8_t c = 0; c < MATRIX_COLS; c++) { + debounce_counters[i++].time = DEBOUNCE_ELAPSED; + } + } +} + +void debounce_free(void) { + free(debounce_counters); + debounce_counters = NULL; +} + +void debounce(matrix_row_t raw[], matrix_row_t cooked[], uint8_t num_rows, bool changed) { + bool updated_last = false; + + if (counters_need_update) { + fast_timer_t now = timer_read_fast(); + fast_timer_t elapsed_time = TIMER_DIFF_FAST(now, last_time); + + last_time = now; + updated_last = true; + if (elapsed_time > UINT8_MAX) { + elapsed_time = UINT8_MAX; + } + + if (elapsed_time > 0) { + update_debounce_counters_and_transfer_if_expired(raw, cooked, num_rows, elapsed_time); + } + } + + if (changed || matrix_need_update) { + if (!updated_last) { + last_time = timer_read_fast(); + } + + transfer_matrix_values(raw, cooked, num_rows); + } +} + +static void update_debounce_counters_and_transfer_if_expired(matrix_row_t raw[], matrix_row_t cooked[], uint8_t num_rows, uint8_t elapsed_time) { + debounce_counter_t *debounce_pointer = debounce_counters; + + counters_need_update = false; + matrix_need_update = false; + + for (uint8_t row = 0; row < num_rows; row++) { + for (uint8_t col = 0; col < MATRIX_COLS; col++) { + matrix_row_t col_mask = (ROW_SHIFTER << col); + + if (debounce_pointer->time != DEBOUNCE_ELAPSED) { + if (debounce_pointer->time <= elapsed_time) { + debounce_pointer->time = DEBOUNCE_ELAPSED; + + if (debounce_pointer->pressed) { + // key-down: eager + matrix_need_update = true; + } else { + // key-up: defer + cooked[row] = (cooked[row] & ~col_mask) | (raw[row] & col_mask); + } + } else { + debounce_pointer->time -= elapsed_time; + counters_need_update = true; + } + } + debounce_pointer++; + } + } +} + +static void transfer_matrix_values(matrix_row_t raw[], matrix_row_t cooked[], uint8_t num_rows) { + debounce_counter_t *debounce_pointer = debounce_counters; + + for (uint8_t row = 0; row < num_rows; row++) { + matrix_row_t delta = raw[row] ^ cooked[row]; + for (uint8_t col = 0; col < MATRIX_COLS; col++) { + matrix_row_t col_mask = (ROW_SHIFTER << col); + + if (delta & col_mask) { + if (debounce_pointer->time == DEBOUNCE_ELAPSED) { + debounce_pointer->pressed = (raw[row] & col_mask); + debounce_pointer->time = DEBOUNCE; + counters_need_update = true; + + if (debounce_pointer->pressed) { + // key-down: eager + cooked[row] ^= col_mask; + } + } + } else if (debounce_pointer->time != DEBOUNCE_ELAPSED) { + if (!debounce_pointer->pressed) { + // key-up: defer + debounce_pointer->time = DEBOUNCE_ELAPSED; + } + } + debounce_pointer++; + } + } +} + +bool debounce_active(void) { return true; } +#else +# include "none.c" +#endif diff --git a/quantum/debounce/tests/asym_eager_defer_pk_tests.cpp b/quantum/debounce/tests/asym_eager_defer_pk_tests.cpp new file mode 100644 index 0000000000..fe374c3dfa --- /dev/null +++ b/quantum/debounce/tests/asym_eager_defer_pk_tests.cpp @@ -0,0 +1,374 @@ +/* Copyright 2021 Simon Arlott + * + * 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, either version 2 of the License, or + * (at your option) any later version. + * + * 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 "gtest/gtest.h" + +#include "debounce_test_common.h" + +TEST_F(DebounceTest, OneKeyShort1) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 1ms delay */ + {1, {{0, 1, UP}}, {}}, + + /* + * Until the eager timer on DOWN is observed to finish, the defer timer + * on UP can't start. There's no workaround for this because it's not + * possible to debounce an event that isn't being tracked. + * + * sym_defer_pk has the same problem but the test has to track that the + * key changed state so the DOWN timer is always allowed to finish + * before starting the UP timer. + */ + {5, {}, {}}, + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort2) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 2ms delay */ + {2, {{0, 1, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort3) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 3ms delay */ + {3, {{0, 1, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort4) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 4ms delay */ + {4, {{0, 1, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort5) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Release key after 5ms delay */ + {5, {{0, 1, UP}}, {}}, + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort6) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Release key after 6ms delay */ + {6, {{0, 1, UP}}, {}}, + + {11, {}, {{0, 1, UP}}}, /* 5ms after UP at time 6 */ + /* Press key again after 1ms delay */ + {12, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort7) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Release key after 7ms delay */ + {7, {{0, 1, UP}}, {}}, + + {12, {}, {{0, 1, UP}}}, /* 5ms after UP at time 7 */ + /* Press key again after 1ms delay */ + {13, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort8) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 1ms delay */ + {1, {{0, 1, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + + {10, {}, {{0, 1, UP}}}, /* 5ms after UP at time 7 */ + /* Press key again after 0ms delay (scan 2) */ + {10, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyShort9) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Release key after 1ms delay */ + {1, {{0, 1, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + + /* Press key again after 0ms delay (same scan) before debounce finishes */ + {10, {{0, 1, DOWN}}, {}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyBouncing1) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + {1, {{0, 1, UP}}, {}}, + {2, {{0, 1, DOWN}}, {}}, + {3, {{0, 1, UP}}, {}}, + {4, {{0, 1, DOWN}}, {}}, + {5, {{0, 1, UP}}, {}}, + {6, {{0, 1, DOWN}}, {}}, + {7, {{0, 1, UP}}, {}}, + {8, {{0, 1, DOWN}}, {}}, + {9, {{0, 1, UP}}, {}}, + {10, {{0, 1, DOWN}}, {}}, + {11, {{0, 1, UP}}, {}}, + {12, {{0, 1, DOWN}}, {}}, + {13, {{0, 1, UP}}, {}}, + {14, {{0, 1, DOWN}}, {}}, + {15, {{0, 1, UP}}, {}}, + + {20, {}, {{0, 1, UP}}}, + /* Press key again after 1ms delay */ + {21, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyBouncing2) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + /* Change twice in the same time period */ + {1, {{0, 1, UP}}, {}}, + {1, {{0, 1, DOWN}}, {}}, + /* Change three times in the same time period */ + {2, {{0, 1, UP}}, {}}, + {2, {{0, 1, DOWN}}, {}}, + {2, {{0, 1, UP}}, {}}, + /* Change twice in the same time period */ + {6, {{0, 1, DOWN}}, {}}, + {6, {{0, 1, UP}}, {}}, + /* Change three times in the same time period */ + {7, {{0, 1, DOWN}}, {}}, + {7, {{0, 1, UP}}, {}}, + {7, {{0, 1, DOWN}}, {}}, + /* Change twice in the same time period */ + {8, {{0, 1, UP}}, {}}, + {8, {{0, 1, DOWN}}, {}}, + /* Change three times in the same time period */ + {9, {{0, 1, UP}}, {}}, + {9, {{0, 1, DOWN}}, {}}, + {9, {{0, 1, UP}}, {}}, + + {14, {}, {{0, 1, UP}}}, + /* Press key again after 1ms delay */ + {15, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, OneKeyLong) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + {25, {{0, 1, UP}}, {}}, + + {30, {}, {{0, 1, UP}}}, + + {50, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + {75, {{0, 1, UP}}, {}}, + + {80, {}, {{0, 1, UP}}}, + + {100, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + runEvents(); +} + +TEST_F(DebounceTest, TwoKeysShort) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + {1, {{0, 2, DOWN}}, {{0, 2, DOWN}}}, + /* Release key after 2ms delay */ + {2, {{0, 1, UP}}, {}}, + {3, {{0, 2, UP}}, {}}, + + {5, {}, {}}, /* See OneKeyShort1 */ + {6, {}, {}}, /* See OneKeyShort1 */ + + {10, {}, {{0, 1, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + /* Press key again after 1ms delay */ + {11, {{0, 1, DOWN}}, {{0, 1, DOWN}, {0, 2, UP}}}, /* 5ms+5ms after DOWN at time 0 */ + {12, {{0, 2, DOWN}}, {{0, 2, DOWN}}}, /* 5ms+5ms after DOWN at time 0 */ + }); + runEvents(); +} + + +TEST_F(DebounceTest, OneKeyDelayedScan1) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Processing is very late, immediately release key */ + {300, {{0, 1, UP}}, {}}, + + {305, {}, {{0, 1, UP}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan2) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Processing is very late, immediately release key */ + {300, {{0, 1, UP}}, {}}, + + /* Processing is very late again */ + {600, {}, {{0, 1, UP}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan3) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Processing is very late */ + {300, {}, {}}, + /* Release key after 1ms */ + {301, {{0, 1, UP}}, {}}, + + {306, {}, {{0, 1, UP}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan4) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Processing is very late */ + {300, {}, {}}, + /* Release key after 1ms */ + {301, {{0, 1, UP}}, {}}, + + /* Processing is very late again */ + {600, {}, {{0, 1, UP}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan5) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + {5, {{0, 1, UP}}, {}}, + + /* Processing is very late */ + {300, {}, {{0, 1, UP}}}, + /* Immediately press key again */ + {300, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan6) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + {5, {{0, 1, UP}}, {}}, + + /* Processing is very late */ + {300, {}, {{0, 1, UP}}}, + + /* Press key again after 1ms */ + {301, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan7) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + {5, {{0, 1, UP}}, {}}, + + /* Press key again before debounce expires */ + {300, {{0, 1, DOWN}}, {}}, + }); + time_jumps_ = true; + runEvents(); +} + +TEST_F(DebounceTest, OneKeyDelayedScan8) { + addEvents({ /* Time, Inputs, Outputs */ + {0, {{0, 1, DOWN}}, {{0, 1, DOWN}}}, + + /* Processing is a bit late */ + {50, {}, {}}, + /* Release key after 1ms */ + {51, {{0, 1, UP}}, {}}, + + /* Processing is a bit late again */ + {100, {}, {{0, 1, UP}}}, + }); + time_jumps_ = true; + runEvents(); +} diff --git a/quantum/debounce/tests/rules.mk b/quantum/debounce/tests/rules.mk index 29fda7889f..66928d7eb6 100644 --- a/quantum/debounce/tests/rules.mk +++ b/quantum/debounce/tests/rules.mk @@ -37,3 +37,8 @@ debounce_sym_eager_pr_DEFS := $(DEBOUNCE_COMMON_DEFS) debounce_sym_eager_pr_SRC := $(DEBOUNCE_COMMON_SRC) \ $(QUANTUM_PATH)/debounce/sym_eager_pr.c \ $(QUANTUM_PATH)/debounce/tests/sym_eager_pr_tests.cpp + +debounce_asym_eager_defer_pk_DEFS := $(DEBOUNCE_COMMON_DEFS) +debounce_asym_eager_defer_pk_SRC := $(DEBOUNCE_COMMON_SRC) \ + $(QUANTUM_PATH)/debounce/asym_eager_defer_pk.c \ + $(QUANTUM_PATH)/debounce/tests/asym_eager_defer_pk_tests.cpp diff --git a/quantum/debounce/tests/testlist.mk b/quantum/debounce/tests/testlist.mk index 16ce8a0a8e..c54c45aa63 100644 --- a/quantum/debounce/tests/testlist.mk +++ b/quantum/debounce/tests/testlist.mk @@ -2,4 +2,5 @@ TEST_LIST += \ debounce_sym_defer_g \ debounce_sym_defer_pk \ debounce_sym_eager_pk \ - debounce_sym_eager_pr + debounce_sym_eager_pr \ + debounce_asym_eager_defer_pk