[Core] Refactor `keyevent_t` for 1ms timing resolution (#15847)

6 files changed, 106 insertions, 91 deletions

diff --git a/quantum/action_tapping.c b/quantum/action_tapping.c
index dbb5b8d4e5..362b15105c 100644
--- a/quantum/action_tapping.c
+++ b/quantum/action_tapping.c
@@ -15,14 +15,10 @@
 #        error "IGNORE_MOD_TAP_INTERRUPT is no longer necessary as it is now the default behavior of mod-tap keys. Please remove it from your config."
 #    endif
 
-#    define IS_TAPPING() IS_EVENT(tapping_key.event)
-#    define IS_TAPPING_PRESSED() (IS_TAPPING() && tapping_key.event.pressed)
-#    define IS_TAPPING_RELEASED() (IS_TAPPING() && !tapping_key.event.pressed)
-#    define IS_TAPPING_KEY(k) (IS_TAPPING() && KEYEQ(tapping_key.event.key, (k)))
 #    ifndef COMBO_ENABLE
-#        define IS_TAPPING_RECORD(r) (IS_TAPPING() && KEYEQ(tapping_key.event.key, (r->event.key)))
+#        define IS_TAPPING_RECORD(r) (KEYEQ(tapping_key.event.key, (r->event.key)))
 #    else
-#        define IS_TAPPING_RECORD(r) (IS_TAPPING() && KEYEQ(tapping_key.event.key, (r->event.key)) && tapping_key.keycode == r->keycode)
+#        define IS_TAPPING_RECORD(r) (KEYEQ(tapping_key.event.key, (r->event.key)) && tapping_key.keycode == r->keycode)
 #    endif
 #    define WITHIN_TAPPING_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < GET_TAPPING_TERM(get_record_keycode(&tapping_key, false), &tapping_key))
 #    define WITHIN_QUICK_TAP_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < GET_QUICK_TAP_TERM(get_record_keycode(&tapping_key, false), &tapping_key))
@@ -94,7 +90,7 @@ void action_tapping_process(keyrecord_t record) {
             ac_dprintf("OVERFLOW: CLEAR ALL STATES\n");
             clear_keyboard();
             waiting_buffer_clear();
-            tapping_key = (keyrecord_t){};
+            tapping_key = (keyrecord_t){0};
         }
     }
 
@@ -121,7 +117,7 @@ void action_tapping_process(keyrecord_t record) {
  * conditional uses of it are hidden inside macros named TAP_...
  */
 #    if (defined(AUTO_SHIFT_ENABLE) && defined(RETRO_SHIFT)) || defined(PERMISSIVE_HOLD_PER_KEY) || defined(HOLD_ON_OTHER_KEY_PRESS_PER_KEY)
-#        define TAP_DEFINE_KEYCODE uint16_t tapping_keycode = get_record_keycode(&tapping_key, false)
+#        define TAP_DEFINE_KEYCODE const uint16_t tapping_keycode = get_record_keycode(&tapping_key, false)
 #    else
 #        define TAP_DEFINE_KEYCODE
 #    endif
@@ -167,12 +163,37 @@ void action_tapping_process(keyrecord_t record) {
  */
 /* return true when key event is processed or consumed. */
 bool process_tapping(keyrecord_t *keyp) {
-    keyevent_t event = keyp->event;
+    const keyevent_t event = keyp->event;
+
+    // state machine is in the "reset" state, no tapping key is to be
+    // processed
+    if (IS_NOEVENT(tapping_key.event) && IS_EVENT(event)) {
+        if (event.pressed && is_tap_record(keyp)) {
+            // the currently pressed key is a tapping key, therefore transition
+            // into the "pressed" tapping key state
+            ac_dprintf("Tapping: Start(Press tap key).\n");
+            tapping_key = *keyp;
+            process_record_tap_hint(&tapping_key);
+            waiting_buffer_scan_tap();
+            debug_tapping_key();
+            return true;
+        } else {
+            // the current key is just a regular key, pass it on for regular
+            // processing
+            process_record(keyp);
+            return true;
+        }
+    }
+
     TAP_DEFINE_KEYCODE;
 
-    // if tapping
-    if (IS_TAPPING_PRESSED()) {
+    // process "pressed" tapping key state
+    if (tapping_key.event.pressed) {
         if (WITHIN_TAPPING_TERM(event) || MAYBE_RETRO_SHIFTING(event)) {
+            if (IS_NOEVENT(event)) {
+                // early return for tick events
+                return true;
+            }
             if (tapping_key.tap.count == 0) {
                 if (IS_TAPPING_RECORD(keyp) && !event.pressed) {
 #    if defined(AUTO_SHIFT_ENABLE) && defined(RETRO_SHIFT)
@@ -196,7 +217,7 @@ bool process_tapping(keyrecord_t *keyp) {
                 // clang-format off
                 else if (
                     (
-                        IS_RELEASED(event) && waiting_buffer_typed(event) &&
+                        !event.pressed && waiting_buffer_typed(event) &&
                         TAP_GET_PERMISSIVE_HOLD
                     )
                     // Causes nested taps to not wait past TAPPING_TERM/RETRO_SHIFT
@@ -214,7 +235,7 @@ bool process_tapping(keyrecord_t *keyp) {
                             || (
                                 TAP_IS_RETRO
                                 && (event.key.col != tapping_key.event.key.col || event.key.row != tapping_key.event.key.row)
-                                && IS_RELEASED(event) && waiting_buffer_typed(event)
+                                && !event.pressed && waiting_buffer_typed(event)
                             )
                         )
                     )
@@ -222,7 +243,7 @@ bool process_tapping(keyrecord_t *keyp) {
                     // clang-format on
                     ac_dprintf("Tapping: End. No tap. Interfered by typing key\n");
                     process_record(&tapping_key);
-                    tapping_key = (keyrecord_t){};
+                    tapping_key = (keyrecord_t){0};
                     debug_tapping_key();
                     // enqueue
                     return false;
@@ -231,7 +252,7 @@ bool process_tapping(keyrecord_t *keyp) {
                  * Without this unexpected repeating will occur with having fast repeating setting
                  * https://github.com/tmk/tmk_keyboard/issues/60
                  */
-                else if (IS_RELEASED(event) && !waiting_buffer_typed(event)) {
+                else if (!event.pressed && !waiting_buffer_typed(event)) {
                     // Modifier/Layer should be retained till end of this tapping.
                     action_t action = layer_switch_get_action(event.key);
                     switch (action.kind.id) {
@@ -267,7 +288,7 @@ bool process_tapping(keyrecord_t *keyp) {
                         if (TAP_GET_HOLD_ON_OTHER_KEY_PRESS) {
                             ac_dprintf("Tapping: End. No tap. Interfered by pressed key\n");
                             process_record(&tapping_key);
-                            tapping_key = (keyrecord_t){};
+                            tapping_key = (keyrecord_t){0};
                             debug_tapping_key();
                             // enqueue
                             return false;
@@ -295,6 +316,7 @@ bool process_tapping(keyrecord_t *keyp) {
                             .event.key     = tapping_key.event.key,
                             .event.time    = event.time,
                             .event.pressed = false,
+                            .event.type    = tapping_key.event.type,
 #    ifdef COMBO_ENABLE
                             .keycode = tapping_key.keycode,
 #    endif
@@ -307,9 +329,7 @@ bool process_tapping(keyrecord_t *keyp) {
                     debug_tapping_key();
                     return true;
                 } else {
-                    if (IS_EVENT(event)) {
-                        ac_dprintf("Tapping: key event while last tap(>0).\n");
-                    }
+                    ac_dprintf("Tapping: key event while last tap(>0).\n");
                     process_record(keyp);
                     return true;
                 }
@@ -322,15 +342,18 @@ bool process_tapping(keyrecord_t *keyp) {
                 debug_event(event);
                 ac_dprintf("\n");
                 process_record(&tapping_key);
-                tapping_key = (keyrecord_t){};
+                tapping_key = (keyrecord_t){0};
                 debug_tapping_key();
                 return false;
             } else {
+                if (IS_NOEVENT(event)) {
+                    return true;
+                }
                 if (IS_TAPPING_RECORD(keyp) && !event.pressed) {
                     ac_dprintf("Tapping: End. last timeout tap release(>0).");
                     keyp->tap = tapping_key.tap;
                     process_record(keyp);
-                    tapping_key = (keyrecord_t){};
+                    tapping_key = (keyrecord_t){0};
                     return true;
                 } else if (is_tap_record(keyp) && event.pressed) {
                     if (tapping_key.tap.count > 1) {
@@ -341,6 +364,7 @@ bool process_tapping(keyrecord_t *keyp) {
                             .event.key     = tapping_key.event.key,
                             .event.time    = event.time,
                             .event.pressed = false,
+                            .event.type    = tapping_key.event.type,
 #    ifdef COMBO_ENABLE
                             .keycode = tapping_key.keycode,
 #    endif
@@ -353,16 +377,20 @@ bool process_tapping(keyrecord_t *keyp) {
                     debug_tapping_key();
                     return true;
                 } else {
-                    if (IS_EVENT(event)) {
-                        ac_dprintf("Tapping: key event while last timeout tap(>0).\n");
-                    }
+                    ac_dprintf("Tapping: key event while last timeout tap(>0).\n");
                     process_record(keyp);
                     return true;
                 }
             }
         }
-    } else if (IS_TAPPING_RELEASED()) {
+    }
+    // process "released" tapping key state
+    else {
         if (WITHIN_TAPPING_TERM(event) || MAYBE_RETRO_SHIFTING(event)) {
+            if (IS_NOEVENT(event)) {
+                // early return for tick events
+                return true;
+            }
             if (event.pressed) {
                 if (IS_TAPPING_RECORD(keyp)) {
                     if (WITHIN_QUICK_TAP_TERM(event) && !tapping_key.tap.interrupted && tapping_key.tap.count > 0) {
@@ -393,35 +421,20 @@ bool process_tapping(keyrecord_t *keyp) {
                     return true;
                 }
             } else {
-                if (IS_EVENT(event)) ac_dprintf("Tapping: other key just after tap.\n");
+                ac_dprintf("Tapping: other key just after tap.\n");
                 process_record(keyp);
                 return true;
             }
         } else {
-            // FIX: process_action here?
-            // timeout. no sequential tap.
+            // Timeout - reset state machine.
             ac_dprintf("Tapping: End(Timeout after releasing last tap): ");
             debug_event(event);
             ac_dprintf("\n");
-            tapping_key = (keyrecord_t){};
+            tapping_key = (keyrecord_t){0};
             debug_tapping_key();
             return false;
         }
     }
-    // not tapping state
-    else {
-        if (event.pressed && is_tap_record(keyp)) {
-            ac_dprintf("Tapping: Start(Press tap key).\n");
-            tapping_key = *keyp;
-            process_record_tap_hint(&tapping_key);
-            waiting_buffer_scan_tap();
-            debug_tapping_key();
-            return true;
-        } else {
-            process_record(keyp);
-            return true;
-        }
-    }
 }
 
 /** \brief Waiting buffer enq
@@ -484,15 +497,18 @@ __attribute__((unused)) bool waiting_buffer_has_anykey_pressed(void) {
  * FIXME: Needs docs
  */
 void waiting_buffer_scan_tap(void) {
-    // tapping already is settled
-    if (tapping_key.tap.count > 0) return;
-    // invalid state: tapping_key released && tap.count == 0
-    if (!tapping_key.event.pressed) return;
+    // early return if:
+    // - tapping already is settled
+    // - invalid state: tapping_key released && tap.count == 0
+    if ((tapping_key.tap.count > 0) || !tapping_key.event.pressed) {
+        return;
+    }
 
     for (uint8_t i = waiting_buffer_tail; i != waiting_buffer_head; i = (i + 1) % WAITING_BUFFER_SIZE) {
-        if (IS_TAPPING_KEY(waiting_buffer[i].event.key) && !waiting_buffer[i].event.pressed && WITHIN_TAPPING_TERM(waiting_buffer[i].event)) {
-            tapping_key.tap.count       = 1;
-            waiting_buffer[i].tap.count = 1;
+        keyrecord_t *candidate = &waiting_buffer[i];
+        if (IS_EVENT(candidate->event) && KEYEQ(candidate->event.key, tapping_key.event.key) && !candidate->event.pressed && WITHIN_TAPPING_TERM(candidate->event)) {
+            tapping_key.tap.count = 1;
+            candidate->tap.count  = 1;
             process_record(&tapping_key);
 
             ac_dprintf("waiting_buffer_scan_tap: found at [%u]\n", i);
diff --git a/quantum/encoder.c b/quantum/encoder.c
index 3aee340249..8053913e8d 100644
--- a/quantum/encoder.c
+++ b/quantum/encoder.c
@@ -147,12 +147,12 @@ void encoder_init(void) {
 #ifdef ENCODER_MAP_ENABLE
 static void encoder_exec_mapping(uint8_t index, bool clockwise) {
     // The delays below cater for Windows and its wonderful requirements.
-    action_exec(clockwise ? ENCODER_CW_EVENT(index, true) : ENCODER_CCW_EVENT(index, true));
+    action_exec(clockwise ? MAKE_ENCODER_CW_EVENT(index, true) : MAKE_ENCODER_CCW_EVENT(index, true));
 #    if ENCODER_MAP_KEY_DELAY > 0
     wait_ms(ENCODER_MAP_KEY_DELAY);
 #    endif // ENCODER_MAP_KEY_DELAY > 0
 
-    action_exec(clockwise ? ENCODER_CW_EVENT(index, false) : ENCODER_CCW_EVENT(index, false));
+    action_exec(clockwise ? MAKE_ENCODER_CW_EVENT(index, false) : MAKE_ENCODER_CCW_EVENT(index, false));
 #    if ENCODER_MAP_KEY_DELAY > 0
     wait_ms(ENCODER_MAP_KEY_DELAY);
 #    endif // ENCODER_MAP_KEY_DELAY > 0
diff --git a/quantum/keyboard.c b/quantum/keyboard.c
index 6f1ad33b61..90f6d6f8da 100644
--- a/quantum/keyboard.c
+++ b/quantum/keyboard.c
@@ -462,7 +462,7 @@ static inline void generate_tick_event(void) {
     static uint16_t last_tick = 0;
     const uint16_t  now       = timer_read();
     if (TIMER_DIFF_16(now, last_tick) != 0) {
-        action_exec(TICK_EVENT);
+        action_exec(MAKE_TICK_EVENT);
         last_tick = now;
     }
 }
diff --git a/quantum/keyboard.h b/quantum/keyboard.h
index f82f2fa58a..bf1890d10b 100644
--- a/quantum/keyboard.h
+++ b/quantum/keyboard.h
@@ -30,65 +30,64 @@ typedef struct {
     uint8_t row;
 } keypos_t;
 
+typedef enum keyevent_type_t { TICK_EVENT = 0, KEY_EVENT = 1, ENCODER_CW_EVENT = 2, ENCODER_CCW_EVENT = 3, COMBO_EVENT = 4 } keyevent_type_t;
+
 /* key event */
 typedef struct {
-    keypos_t key;
-    bool     pressed;
-    uint16_t time;
+    keypos_t        key;
+    uint16_t        time;
+    keyevent_type_t type;
+    bool            pressed;
 } keyevent_t;
 
 /* equivalent test of keypos_t */
 #define KEYEQ(keya, keyb) ((keya).row == (keyb).row && (keya).col == (keyb).col)
 
 /* special keypos_t entries */
-#define KEYLOC_TICK 255
-#define KEYLOC_COMBO 254
 #define KEYLOC_ENCODER_CW 253
 #define KEYLOC_ENCODER_CCW 252
 
-/* Rules for No Event:
- * 1) (time == 0) to handle (keyevent_t){} as empty event
- * 2) Matrix(255, 255) to make TICK event available
- */
-static inline bool IS_NOEVENT(keyevent_t event) {
-    return event.time == 0 || (event.key.row == KEYLOC_TICK && event.key.col == KEYLOC_TICK);
-}
-static inline bool IS_EVENT(keyevent_t event) {
-    return !IS_NOEVENT(event);
-}
-static inline bool IS_KEYEVENT(keyevent_t event) {
-    return event.key.row < MATRIX_ROWS && event.key.col < MATRIX_COLS;
+static inline bool IS_NOEVENT(const keyevent_t event) {
+    return event.type == TICK_EVENT;
 }
-static inline bool IS_COMBOEVENT(keyevent_t event) {
-    return event.key.row == KEYLOC_COMBO;
+static inline bool IS_EVENT(const keyevent_t event) {
+    return event.type != TICK_EVENT;
 }
-static inline bool IS_ENCODEREVENT(keyevent_t event) {
-    return event.key.row == KEYLOC_ENCODER_CW || event.key.row == KEYLOC_ENCODER_CCW;
+static inline bool IS_KEYEVENT(const keyevent_t event) {
+    return event.type == KEY_EVENT;
 }
-static inline bool IS_PRESSED(keyevent_t event) {
-    return IS_EVENT(event) && event.pressed;
+static inline bool IS_COMBOEVENT(const keyevent_t event) {
+    return event.type == COMBO_EVENT;
 }
-static inline bool IS_RELEASED(keyevent_t event) {
-    return IS_EVENT(event) && !event.pressed;
+static inline bool IS_ENCODEREVENT(const keyevent_t event) {
+    return event.type == ENCODER_CW_EVENT || event.type == ENCODER_CCW_EVENT;
 }
 
-/* Common keyevent object factory */
+/* Common keypos_t object factory */
 #define MAKE_KEYPOS(row_num, col_num) ((keypos_t){.row = (row_num), .col = (col_num)})
 
+/* Common keyevent_t object factory */
+#define MAKE_EVENT(row_num, col_num, press, event_type) ((keyevent_t){.key = MAKE_KEYPOS((row_num), (col_num)), .pressed = (press), .time = timer_read(), .type = (event_type)})
+
 /**
  * @brief Constructs a key event for a pressed or released key.
  */
-#define MAKE_KEYEVENT(row_num, col_num, press) ((keyevent_t){.key = MAKE_KEYPOS((row_num), (col_num)), .pressed = (press), .time = (timer_read() | 1)})
+#define MAKE_KEYEVENT(row_num, col_num, press) MAKE_EVENT((row_num), (col_num), (press), KEY_EVENT)
+
+/**
+ * @brief Constructs a combo event.
+ */
+#define MAKE_COMBOEVENT(press) MAKE_EVENT(0, 0, (press), COMBO_EVENT)
 
 /**
  * @brief Constructs a internal tick event that is used to drive the internal QMK state machine.
  */
-#define TICK_EVENT MAKE_KEYEVENT(KEYLOC_TICK, KEYLOC_TICK, false)
+#define MAKE_TICK_EVENT MAKE_EVENT(0, 0, false, TICK_EVENT)
 
 #ifdef ENCODER_MAP_ENABLE
 /* Encoder events */
-#    define ENCODER_CW_EVENT(enc_id, press) MAKE_KEYEVENT(KEYLOC_ENCODER_CW, (enc_id), (press))
-#    define ENCODER_CCW_EVENT(enc_id, press) MAKE_KEYEVENT(KEYLOC_ENCODER_CCW, (enc_id), (press))
+#    define MAKE_ENCODER_CW_EVENT(enc_id, press) MAKE_EVENT(KEYLOC_ENCODER_CW, (enc_id), (press), ENCODER_CW_EVENT)
+#    define MAKE_ENCODER_CCW_EVENT(enc_id, press) MAKE_EVENT(KEYLOC_ENCODER_CCW, (enc_id), (press), ENCODER_CCW_EVENT)
 #endif // ENCODER_MAP_ENABLE
 
 /* it runs once at early stage of startup before keyboard_init. */
diff --git a/quantum/process_keycode/process_combo.c b/quantum/process_keycode/process_combo.c
index ce6725c402..b1b49d3019 100644
--- a/quantum/process_keycode/process_combo.c
+++ b/quantum/process_keycode/process_combo.c
@@ -145,7 +145,7 @@ static queued_combo_t combo_buffer[COMBO_BUFFER_LENGTH];
 static inline void release_combo(uint16_t combo_index, combo_t *combo) {
     if (combo->keycode) {
         keyrecord_t record = {
-            .event   = MAKE_KEYEVENT(KEYLOC_COMBO, KEYLOC_COMBO, false),
+            .event   = MAKE_COMBOEVENT(false),
             .keycode = combo->keycode,
         };
 #ifndef NO_ACTION_TAPPING
@@ -233,7 +233,7 @@ static inline void dump_key_buffer(void) {
             process_record(record);
 #endif
         }
-        record->event.time = 0;
+        record->event.type = TICK_EVENT;
 
 #if defined(CAPS_WORD_ENABLE) && defined(AUTO_SHIFT_ENABLE)
         // Edge case: preserve the weak Left Shift mod if both Caps Word and
@@ -333,8 +333,8 @@ void apply_combo(uint16_t combo_index, combo_t *combo) {
         KEY_STATE_DOWN(state, key_index);
         if (ALL_COMBO_KEYS_ARE_DOWN(state, key_count)) {
             // this in the end executes the combo when the key_buffer is dumped.
-            record->keycode   = combo->keycode;
-            record->event.key = MAKE_KEYPOS(KEYLOC_COMBO, KEYLOC_COMBO);
+            record->keycode    = combo->keycode;
+            record->event.type = COMBO_EVENT;
 
             qrecord->combo_index = combo_index;
             ACTIVATE_COMBO(combo);
@@ -343,7 +343,7 @@ void apply_combo(uint16_t combo_index, combo_t *combo) {
         } else {
             // key was part of the combo but not the last one, "disable" it
             // by making it a TICK event.
-            record->event.time = 0;
+            record->event.type = TICK_EVENT;
         }
     }
     drop_combo_from_buffer(combo_index);
diff --git a/quantum/process_keycode/process_steno.c b/quantum/process_keycode/process_steno.c
index 8ba98bd4bb..d5ad61ba85 100644
--- a/quantum/process_keycode/process_steno.c
+++ b/quantum/process_keycode/process_steno.c
@@ -173,13 +173,13 @@ bool process_steno(uint16_t keycode, keyrecord_t *record) {
     switch (keycode) {
 #ifdef STENO_ENABLE_ALL
         case QK_STENO_BOLT:
-            if (IS_PRESSED(record->event)) {
+            if (record->event.pressed) {
                 steno_set_mode(STENO_MODE_BOLT);
             }
             return false;
 
         case QK_STENO_GEMINI:
-            if (IS_PRESSED(record->event)) {
+            if (record->event.pressed) {
                 steno_set_mode(STENO_MODE_GEMINI);
             }
             return false;
@@ -193,7 +193,7 @@ bool process_steno(uint16_t keycode, keyrecord_t *record) {
         }
 #endif // STENO_COMBINEDMAP
         case STN__MIN ... STN__MAX:
-            if (IS_PRESSED(record->event)) {
+            if (record->event.pressed) {
                 n_pressed_keys++;
                 switch (mode) {
 #ifdef STENO_ENABLE_BOLT