Improve and Cleanup Shutdown callbacks (qmk#21060)

Co-authored-by: Dasky <[email protected]>

docs/custom_quantum_functions.md

@@ -283,6 +283,65 @@ void suspend_wakeup_init_user(void) {
 * Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
 * Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
 
+
+# Keyboard Shutdown/Reboot Code
+
+This function gets called whenever the firmware is reset, whether it's a soft reset or reset to the bootloader. This is the spot to use for any sort of cleanup, as this happens right before the actual reset. And it can be useful for turning off different systems (such as RGB, onboard screens, etc).
+
+Additionally, it differentiates between the soft reset (eg, rebooting back into the firmware) or jumping to the bootloader.
+
+Certain tasks are performed during shutdown too. The keyboard is cleared, music and midi is stopped (if enabled), the shutdown chime is triggered (if audio is enabled), and haptic is stopped.
+
+If `jump_to_bootloader` is set to `true`, this indicates that the board will be entering the bootloader for a new firmware flash, whereas `false` indicates that this is happening for a soft reset and will load the firmware agaim immediately (such as when using `QK_REBOOT` or `QK_CLEAR_EEPROM`).
+
+As there is a keyboard and user level function, returning `false` for the user function will disable the keyboard level function, allowing for customization.
+
+?> Bootmagic does not trigger `shutdown_*()` as it happens before most of the initialization process.
+
+### Example `shutdown_kb()` Implementation
+
+```c
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
+ 
+ if (jump_to_bootloader) {
+ // red for bootloader
+ rgb_matrix_set_color_all(RGB_OFF);
+ } else {
+ // off for soft reset
+ rgb_matrix_set_color_all(RGB_GREEN);
+ }
+ // force flushing -- otherwise will never happen
+ rgb_matrix_update_pwm_buffers();
+ return true;
+}
+```
+
+### Example `shutdown_user()` Implementation
+
+```c
+bool shutdown_user(bool jump_to_bootloader) {
+ if (jump_to_bootloader) {
+ // red for bootloader
+ rgb_matrix_set_color_all(RGB_RED);
+ } else {
+ // off for soft reset
+ rgb_matrix_set_color_all(RGB_OFF);
+ }
+ // force flushing -- otherwise will never happen
+ rgb_matrix_update_pwm_buffers();
+ // false to not process kb level
+ return false;
+}
+```
+
+### Keyboard shutdown/reboot Function Documentation
+
+* Keyboard/Revision: `bool shutdown_kb(bool jump_to_bootloader)`
+* Keymap: `bool shutdown_user(bool jump_to_bootloader)`
+
 # Deferred Execution :id=deferred-execution
 
 QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk.

docs/feature_oled_driver.md

@@ -183,22 +183,8 @@ void oled_render_boot(bool bootloader) {
  oled_render_dirty(true);
 }
 
-bool reboot = false;
-
-bool uint16_t keycode, keyrecord_t *record) {
- if (record->event.pressed) {
-
-  // Display a special message prior to rebooting...
-  if (keycode == QK_BOOT) {
-  reboot = true;
-  }
- }
-
- return true;
-}
-
-void shutdown_user(void) {
- oled_render_boot(reboot);
+bool shutdown_user(bool jump_to_bootloader) {
+ oled_render_boot(jump_to_bootloader);
 }
 
 ```

keyboards/40percentclub/gherkin/keymaps/mjt/keymap.c

@@ -66,15 +66,12 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 
 #ifdef AUDIO_ENABLE
 
-float tone_startup[][2] = SONG(STARTUP_SOUND);
 float tone_qwerty[][2] = SONG(QWERTY_SOUND);
 float tone_dvorak[][2] = SONG(DVORAK_SOUND);
 float tone_colemak[][2] = SONG(COLEMAK_SOUND);
 float tone_plover[][2] = SONG(PLOVER_SOUND);
 float tone_plover_gb[][2] = SONG(PLOVER_GOODBYE_SOUND);
-float music_scale[][2] = SONG(MUSIC_SCALE_SOUND);
 
-float tone_goodbye[][2] = SONG(GOODBYE_SOUND);
 #endif
 
 void persistant_default_layer_set(uint16_t default_layer) {
@@ -166,39 +163,9 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  return true;
 }
 
-void matrix_init_user(void) {
- #ifdef AUDIO_ENABLE
- startup_user();
- #endif
+void matrix_scan_user(void) {
 }
 
-#ifdef AUDIO_ENABLE
-
-void startup_user(void)
-{
- _delay_ms(20); // gets rid of tick
- PLAY_SONG(tone_startup);
-}
-
-void shutdown_user(void)
-{
- PLAY_SONG(tone_goodbye);
- _delay_ms(150);
- stop_all_notes();
-}
-
-void music_on_user(void)
-{
- music_scale_user();
-}
-
-void music_scale_user(void)
-{
- PLAY_SONG(music_scale);
-}
-
-#endif
-
 //Tap Dance Definitions
 tap_dance_action_t tap_dance_actions[] = {
  //Tap once for Esc, twice for Caps Lock

keyboards/bastardkb/charybdis/3x5/keymaps/bstiq/keymap.c

@@ -210,15 +210,3 @@ layer_state_t layer_state_set_kb(layer_state_t state) {
 // Forward-declare this helper function since it is defined in rgb_matrix.c.
 void rgb_matrix_update_pwm_buffers(void);
 #endif
-
-void shutdown_user(void) {
-#ifdef RGBLIGHT_ENABLE
- rgblight_enable_noeeprom();
- rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
- rgblight_setrgb(RGB_RED);
-#endif // RGBLIGHT_ENABLE
-#ifdef RGB_MATRIX_ENABLE
- rgb_matrix_set_color_all(RGB_RED);
- rgb_matrix_update_pwm_buffers();
-#endif // RGB_MATRIX_ENABLE
-}

keyboards/bastardkb/charybdis/3x5/keymaps/via/keymap.c

@@ -255,15 +255,3 @@ layer_state_t layer_state_set_user(layer_state_t state) {
 // rgb_matrix.c.
 void rgb_matrix_update_pwm_buffers(void);
 #endif
-
-void shutdown_user(void) {
-#ifdef RGBLIGHT_ENABLE
- rgblight_enable_noeeprom();
- rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
- rgblight_setrgb(RGB_RED);
-#endif // RGBLIGHT_ENABLE
-#ifdef RGB_MATRIX_ENABLE
- rgb_matrix_set_color_all(RGB_RED);
- rgb_matrix_update_pwm_buffers();
-#endif // RGB_MATRIX_ENABLE
-}

keyboards/bastardkb/charybdis/3x6/keymaps/via/keymap.c

@@ -134,15 +134,3 @@ layer_state_t layer_state_set_user(layer_state_t state) {
 // Forward-declare this helper function since it is defined in rgb_matrix.c.
 void rgb_matrix_update_pwm_buffers(void);
 #endif
-
-void shutdown_user(void) {
-#ifdef RGBLIGHT_ENABLE
- rgblight_enable_noeeprom();
- rgblight_mode_noeeprom(1);
- rgblight_setrgb(RGB_RED);
-#endif // RGBLIGHT_ENABLE
-#ifdef RGB_MATRIX_ENABLE
- rgb_matrix_set_color_all(RGB_RED);
- rgb_matrix_update_pwm_buffers();
-#endif // RGB_MATRIX_ENABLE
-}

keyboards/bastardkb/charybdis/4x6/keymaps/via/keymap.c

@@ -157,15 +157,3 @@ layer_state_t layer_state_set_user(layer_state_t state) {
 // Forward-declare this helper function since it is defined in rgb_matrix.c.
 void rgb_matrix_update_pwm_buffers(void);
 #endif
-
-void shutdown_user(void) {
-#ifdef RGBLIGHT_ENABLE
- rgblight_enable_noeeprom();
- rgblight_mode_noeeprom(1);
- rgblight_setrgb(RGB_RED);
-#endif // RGBLIGHT_ENABLE
-#ifdef RGB_MATRIX_ENABLE
- rgb_matrix_set_color_all(RGB_RED);
- rgb_matrix_update_pwm_buffers();
-#endif // RGB_MATRIX_ENABLE
-}

keyboards/bastardkb/charybdis/charybdis.c

@@ -382,3 +382,20 @@ void matrix_scan_kb(void) {
  matrix_scan_user();
 }
 #endif // KEYBOARD_bastardkb_charybdis_3x5_blackpill || KEYBOARD_bastardkb_charybdis_4x6_blackpill
+
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
+#ifdef RGBLIGHT_ENABLE
+ rgblight_enable_noeeprom();
+ rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
+ rgblight_setrgb(RGB_RED);
+#endif // RGBLIGHT_ENABLE
+#ifdef RGB_MATRIX_ENABLE
+ void rgb_matrix_update_pwm_buffers(void);
+ rgb_matrix_set_color_all(RGB_RED);
+ rgb_matrix_update_pwm_buffers();
+#endif // RGB_MATRIX_ENABLE
+ return true;
+}

keyboards/bastardkb/dilemma/3x5_2/keymaps/bstiq/keymap.c

@@ -210,15 +210,3 @@ layer_state_t layer_state_set_kb(layer_state_t state) {
 // Forward-declare this helper function since it is defined in rgb_matrix.c.
 void rgb_matrix_update_pwm_buffers(void);
 #endif
-
-void shutdown_user(void) {
-#ifdef RGBLIGHT_ENABLE
- rgblight_enable_noeeprom();
- rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
- rgblight_setrgb(RGB_RED);
-#endif // RGBLIGHT_ENABLE
-#ifdef RGB_MATRIX_ENABLE
- rgb_matrix_set_color_all(RGB_RED);
- rgb_matrix_update_pwm_buffers();
-#endif // RGB_MATRIX_ENABLE
-}

keyboards/bastardkb/dilemma/3x5_3/keymaps/bstiq/keymap.c

@@ -210,7 +210,7 @@ layer_state_t layer_state_set_user(layer_state_t state) {
 void rgb_matrix_update_pwm_buffers(void);
 #endif
 
-void shutdown_user(void) {
+bool shutdown_user(bool jump_to_bootloader) {
 #ifdef RGBLIGHT_ENABLE
  rgblight_enable_noeeprom();
  rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
@@ -220,4 +220,5 @@ void shutdown_user(void) {
  rgb_matrix_set_color_all(RGB_RED);
  rgb_matrix_update_pwm_buffers();
 #endif // RGB_MATRIX_ENABLE
+ return true;
 }

keyboards/bastardkb/dilemma/dilemma.c

@@ -343,3 +343,20 @@ void keyboard_pre_init_kb(void) {
 
  keyboard_pre_init_user();
 }
+
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
+#ifdef RGBLIGHT_ENABLE
+ rgblight_enable_noeeprom();
+ rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
+ rgblight_setrgb(RGB_RED);
+#endif // RGBLIGHT_ENABLE
+#ifdef RGB_MATRIX_ENABLE
+ void rgb_matrix_update_pwm_buffers(void);
+ rgb_matrix_set_color_all(RGB_RED);
+ rgb_matrix_update_pwm_buffers();
+#endif // RGB_MATRIX_ENABLE
+ return true;
+}

keyboards/bemeier/bmek/bmek.c

@@ -15,9 +15,12 @@
  */
 #include "quantum.h"
 
-__attribute__((weak))
-void shutdown_user(void) {
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
 #ifdef RGBLIGHT_ENABLE
  rgblight_setrgb(255, 0, 0);
 #endif
+ return true;
 }

keyboards/dmqdesign/spin/keymaps/spidey3_pad/keymap.c

@@ -147,11 +147,12 @@ void keyboard_post_init_user(void) {
  do_rgb_layers(layer_state, LAYER_BASE, LAYER_BASE_END);
 }
 
-void shutdown_user(void) {
+bool shutdown_user(bool jump_to_bootloader) {
  clear_rgb_layers();
  rgblight_enable();
  rgblight_mode_noeeprom(RGBLIGHT_MODE_STATIC_LIGHT);
  rgblight_sethsv_noeeprom(HSV_RED);
+ return false;
 }
 
 void spidey_glow(void) {
@@ -218,4 +219,3 @@ void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
  break;
  }
 }
-

keyboards/dumbpad/v0x/v0x.c

@@ -22,10 +22,14 @@ void keyboard_pre_init_kb(void) {
  keyboard_pre_init_user();
 }
 
-void shutdown_user(void) {
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
  // Shutdown LEDs
  writePinLow(LED_00);
  writePinLow(LED_01);
+ return true;
 }
 
 layer_state_t layer_state_set_kb(layer_state_t state) {

keyboards/dumbpad/v0x_dualencoder/v0x_dualencoder.c

@@ -22,10 +22,14 @@ void keyboard_pre_init_kb(void) {
  keyboard_pre_init_user();
 }
 
-void shutdown_user(void) {
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
  // Shutdown LEDs
  writePinLow(LED_00);
  writePinLow(LED_01);
+ return true;
 }
 
 layer_state_t layer_state_set_kb(layer_state_t state) {

keyboards/dumbpad/v0x_right/v0x_right.c

@@ -22,10 +22,14 @@ void keyboard_pre_init_kb(void) {
  keyboard_pre_init_user();
 }
 
-void shutdown_user(void) {
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
  // Shutdown LEDs
  writePinLow(LED_00);
  writePinLow(LED_01);
+ return true;
 }
 
 layer_state_t layer_state_set_kb(layer_state_t state) {

keyboards/dumbpad/v1x/v1x.c

@@ -23,11 +23,15 @@ void keyboard_pre_init_kb(void) {
  keyboard_pre_init_user();
 }
 
-void shutdown_user(void) {
+bool shutdown_kb(bool jump_to_bootloader) {
+ if (!shutdown_user(jump_to_bootloader)) {
+ return false;
+ }
  // Shutdown LEDs
  writePinLow(LED_00);
  writePinLow(LED_01);
  writePinLow(LED_02);
+ return true;
 }
 
 layer_state_t layer_state_set_kb(layer_state_t state) {