Skip to content

Commit f4966a1

Browse files
drashnatzarc
drashna
and
tzarc
authored
[Docs] Squeezing space out of AVR (#15243)
* [Docs] Squeezing space out of AVR * Add more info * Apply suggestions from code review Co-authored-by: Nick Brassel <nick@tzarc.org> * Add oled section * Apply suggestions from code review Co-authored-by: Nick Brassel <nick@tzarc.org> * Update layers and intro wording * Rename doc file * add get_u8_str support * oled clarifications Co-authored-by: Nick Brassel <nick@tzarc.org> Co-authored-by: Nick Brassel <nick@tzarc.org>
1 parent 32a87d3 commit f4966a1

File tree

3 files changed

+182
-0
lines changed

3 files changed

+182
-0
lines changed

‎docs/_summary.md

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
* [Troubleshooting QMK](faq_misc.md)
1414
* [Debugging QMK](faq_debug.md)
1515
* [Keymap FAQ](faq_keymap.md)
16+
* [Squeezing Space from AVR](squeezing_avr.md)
1617
* [Glossary](reference_glossary.md)
1718

1819
* Configurator

‎docs/squeezing_avr.md

+180
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Squeezing the most out of AVR
2+
3+
AVR is severely resource-constrained, and as QMK continues to grow, it is approaching a point where support for AVR may need to be moved to legacy status as newer development is unable to fit into those constraints.
4+
5+
However, if you need to reduce the compiled size of your firmware, there are a number of options to do so.
6+
7+
## `rules.mk` Settings
8+
First and foremost is enabling link time optimization. To do so, add this to your rules.mk:
9+
```make
10+
LTO_ENABLE = yes
11+
```
12+
This will cause the final step to take longer, but should get you a smaller compiled size. This also disables Action Functions, and Action Macros, both of which are deprecated.
13+
This will get you the most savings, in most situations.
14+
15+
From there, disabling extraneous systems will help -- e.g.:
16+
```make
17+
CONSOLE_ENABLE = no
18+
COMMAND_ENABLE = no
19+
MOUSEKEY_ENABLE = no
20+
EXTRAKEY_ENABLE = no
21+
```
22+
This disables some of the functionality that you may not need. But note that extrakeys disables stuff like the media keys and system volume control.
23+
24+
If that isn't enough to get your firmware down to size, then there are some additional features that you can disable:
25+
```make
26+
SPACE_CADET_ENABLE = no
27+
GRAVE_ESC_ENABLE = no
28+
MAGIC_ENABLE = no
29+
```
30+
These features are enabled by default, but may not be needed. Double check to make sure, though.
31+
Largest in size is "magic" -- the QMK magic keycodes -- which control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling it will disable those functions.
32+
33+
## `config.h` Settings
34+
35+
If you've done all of that, and you don't want to disable features like RGB, Audio, OLEDs, etc, there are some additional options that you can add to your config.h that can help.
36+
37+
Starting with Lock Key support. If you have an Cherry MX Lock switch (lucky you!), you don't want to do this. But chances are, you don't. In that case, add this to your `config.h`:
38+
```c
39+
#undef LOCKING_SUPPORT_ENABLE
40+
#undef LOCKING_RESYNC_ENABLE
41+
```
42+
Oneshots. If you're not using these, you can disable the feature by adding this to your `config.h`:
43+
```c
44+
#define NO_ACTION_ONESHOT
45+
```
46+
The same with tapping keys (mod tap, layer tap, etc)
47+
```c
48+
#define NO_ACTION_TAPPING
49+
```
50+
## Audio Settings
51+
52+
If you're using the Audio feature, by default that includes the music mode feature. This tranlates matrix positions into notes. It's neat for sure, but most likely, you're not using it. You can disable it by adding this to your `config.h`:
53+
```c
54+
#define NO_MUSIC_MODE
55+
```
56+
And by adding this to your `rules.mk`
57+
```make
58+
MUSIC_ENABLE = no
59+
```
60+
61+
## Layers
62+
63+
There are also some options for layers, that can reduce the firmware size. All of these settngs are for your `config.h`.
64+
65+
You can limit the number of layers that the firmware uses -- if you're using less than 8 layers in total:
66+
```c
67+
#define LAYER_STATE_8BIT
68+
```
69+
or if you require up to 16 layers instead:
70+
```c
71+
#define LAYER_STATE_16BIT
72+
```
73+
Or if you're not using layers at all, you can outright remove the functionality altogether:
74+
```c
75+
#define NO_ACTION_LAYER
76+
```
77+
78+
79+
## OLED tweaks
80+
81+
One place you can save a bunch of space here is by not using `sprintf` or `snprintf`. This function call takes up ~1.5kB of firmware space, and can be rewritten. For instance, WPM uses this a lot.
82+
83+
You can convert this:
84+
```c
85+
// OLD CODE
86+
char wpm_str[4] = {0};
87+
sprintf(wpm_str, "WPM: %03d", get_current_wpm());
88+
oled_write(wpm_str, ' '), false);
89+
```
90+
into this:
91+
```c
92+
// NEW CODE
93+
oled_write_P(PSTR("WPM: "), false);
94+
oled_write(get_u8_str(get_current_wpm(), ' '), false);
95+
```
96+
which outputs `WPM: 5`. Or this:
97+
```c
98+
// NEW CODE
99+
oled_write_P(PSTR("WPM: "), false);
100+
oled_write(get_u8_str(get_current_wpm(), '0'), false);
101+
```
102+
which outputs `WPM: 005`.
103+
104+
## RGB Settings
105+
106+
If you're using RGB on your board, both RGB Light (Underglow) and RGB Matrix (per key RGB) now require defines to enable different animations -- some keyboards enable a lot of animations by default, so you can generally gain back some space by disabling specific animations if you don't use them.. For RGB Light you can disable these in your keymap's `config.h`:
107+
```c
108+
#undef RGBLIGHT_ANIMATIONS
109+
#undef RGBLIGHT_EFFECT_BREATHING
110+
#undef RGBLIGHT_EFFECT_RAINBOW_MOOD
111+
#undef RGBLIGHT_EFFECT_RAINBOW_SWIRL
112+
#undef RGBLIGHT_EFFECT_SNAKE
113+
#undef RGBLIGHT_EFFECT_KNIGHT
114+
#undef RGBLIGHT_EFFECT_CHRISTMAS
115+
#undef RGBLIGHT_EFFECT_STATIC_GRADIENT
116+
#undef RGBLIGHT_EFFECT_RGB_TEST
117+
#undef RGBLIGHT_EFFECT_ALTERNATING
118+
#undef RGBLIGHT_EFFECT_TWINKLE
119+
```
120+
121+
For RGB Matrix, these need to be explicitly enabled as well. To disable any that were enabled by the keyboard, add one or more of these to your keymap's `config.h`:
122+
```c
123+
#undef ENABLE_RGB_MATRIX_ALPHAS_MODS
124+
#undef ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN
125+
#undef ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT
126+
#undef ENABLE_RGB_MATRIX_BREATHING
127+
#undef ENABLE_RGB_MATRIX_BAND_SAT
128+
#undef ENABLE_RGB_MATRIX_BAND_VAL
129+
#undef ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT
130+
#undef ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL
131+
#undef ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT
132+
#undef ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL
133+
#undef ENABLE_RGB_MATRIX_CYCLE_ALL
134+
#undef ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT
135+
#undef ENABLE_RGB_MATRIX_CYCLE_UP_DOWN
136+
#undef ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON
137+
#undef ENABLE_RGB_MATRIX_CYCLE_OUT_IN
138+
#undef ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL
139+
#undef ENABLE_RGB_MATRIX_CYCLE_PINWHEEL
140+
#undef ENABLE_RGB_MATRIX_CYCLE_SPIRAL
141+
#undef ENABLE_RGB_MATRIX_DUAL_BEACON
142+
#undef ENABLE_RGB_MATRIX_RAINBOW_BEACON
143+
#undef ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS
144+
#undef ENABLE_RGB_MATRIX_RAINDROPS
145+
#undef ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS
146+
#undef ENABLE_RGB_MATRIX_HUE_BREATHING
147+
#undef ENABLE_RGB_MATRIX_HUE_PENDULUM
148+
#undef ENABLE_RGB_MATRIX_HUE_WAVE
149+
#undef ENABLE_RGB_MATRIX_PIXEL_FRACTAL
150+
#undef ENABLE_RGB_MATRIX_PIXEL_RAIN
151+
152+
#undef ENABLE_RGB_MATRIX_TYPING_HEATMAP
153+
#undef ENABLE_RGB_MATRIX_DIGITAL_RAIN
154+
155+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE
156+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE
157+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE
158+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE
159+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS
160+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS
161+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS
162+
#undef ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS
163+
#undef ENABLE_RGB_MATRIX_SPLASH
164+
#undef ENABLE_RGB_MATRIX_MULTISPLASH
165+
#undef ENABLE_RGB_MATRIX_SOLID_SPLASH
166+
#undef ENABLE_RGB_MATRIX_SOLID_MULTISPLASH
167+
```
168+
169+
# Final Thoughts
170+
171+
If you've done all of this, and your firmware is still too large, then it's time. It's time to consider making the switch to ARM. Unfortunately, right now is the worst possible time for that, due to the silicon shortage, and supply chain issues. Getting an ARM chip is difficult, at best, and significantly overpriced, at worst.
172+
-- Drashna
173+
174+
That said, there are a number of Pro Micro replacements with ARM controllers:
175+
* [Proton C](https://qmk.fm/proton-c/) (out of stock)
176+
* [Bonsai C](https://github.com/customMK/Bonsai-C) (Open Source, DIY/PCBA)
177+
* [Raspberry Pi 2040](https://www.sparkfun.com/products/18288) (not currently supported, no ETA)
178+
179+
There are other, non-Pro Micro compatible boards out there. The most popular being:
180+
* [WeAct Blackpill F411](https://www.aliexpress.com/item/1005001456186625.html) (~$6 USD)

‎docs/syllabus.md

+1
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ These topics start to dig into some of the features that QMK supports. You don't
3131
* [RGB Lighting](feature_rgblight.md)
3232
* [RGB Matrix](feature_rgb_matrix.md)
3333
* [Tap-Hold Configuration](tap_hold.md)
34+
* [Squeezing Space from AVR](squeezing_avr.md)
3435
* **Learn More About Keymaps**
3536
* [Keymaps](keymap.md)
3637
* [Custom Functions and Keycodes](custom_quantum_functions.md)

0 commit comments

Comments
 (0)