Reducing PROGMEM and RAM Usage

From Arduboy Wiki
Revision as of 01:55, 20 July 2024 by Sublinear (talk | contribs) (Fix link to Compiler Explorer)
Jump to navigation Jump to search

Overview

The Arduboy only has 28KiB or 29KiB (FX) of PROGMEM and 2.5KiB of RAM. While making a game, these can run out very quickly. This page aims to help you recover some of your precious PROGMEM and RAM.

Tips for Reducing PROGMEM

  • Look through your code in Ardens for large functions that shouldn't be there. Here is a step-by-step example: (Note: this will only work with .elf files, .hex files don't provide enough information.)
    • Launch Ardens and drag your .elf file on it.
    • Open the disassembly tab (Windows>Debugger>Disassembly)
      Opening the disassembly tab.
    • Click on the "Jump to Function" dropdown.
      The example contents of the Jump to Function dropdown. Note the amount of floating-point functions present.
    • Scan the dropdown for anything unexpected.
    • In our example, there are a huge amount of float functions that are taking up a lot of space.
    • How can we fix this? In our source code, we can change x from a float to a uint8_t:
#include <Arduboy2.h>

Arduboy2 arduboy;

-- float x;

++ uint8_t x;

void setup() {

    arduboy.begin();
    arduboy.setFrameRate(10);

}

void loop() {

    if (!arduboy.nextFrame()) return;

    arduboy.clear();
    x++;

    arduboy.print(x / 10);
    arduboy.display();

}
    • That small modification will save us thousands of bytes!
  • Use https://godbolt.org/z/8vhWqj8KE (pre-configured with correct settings) to see the assembly that the provided code will generate. You don't need to know assembly, the most important thing is if you see a function call to do an arithmetic operation, you may be able to avoid it. This is helpful to avoid division and mod, as discussed below.
  • Use arduboy.boot(); and arduboy.safeMode(); instead of arduboy.begin();. arduboy.systemButtons(); and arduboy.waitNoButtons(); can also be added for convenience (turning on and off sound at bootup). Note that this will get rid of the scrolling logo.
  • Use Arduboy2Base instead of Arduboy2 if you don’t use text.
  • Use smaller integer sizes when possible. For example, instead of using int/ int16_t for a screen position, you can use int8_t. Because the Arduboy has an 8-bit CPU, anything larger adds extra instructions/functions.
  • Avoid using floats! The Arduboy has no hardware floating point, so 5+KiB can be included to do it in software. Fixed point is much faster and smaller
  • Avoid using division/mod whenever possible; the Arduboy does not have hardware division, so code is included to do it in software. This not only increases PROGMEM, it slows your program down. Here are some alternatives to division/mod:
    • Use powers of 2 when dividing/using mod; the compiler can optimize these into shifts/bitwise ands, which are very fast. For example, try to use x /= 4; instead of of x /= 3;This becomes especially important when you are working with a tile map: It's best to use tiles with powers of 2.
    • Instead of using mod to wrap a number (unless you can do it with a power of 2), use an if statement. For example, instead of writing x %= 3,  write  if (x > 2) x = 0;.
  • As a last resort, you can remove the USB stack by adding the ARDUBOY_NO_USB macro in your code in global scope. This gains you an extra 3KiB of PROGMEM to use. Be aware of the fact that this makes it very hard to upload a new game onto a non-FX Arduboy, as the uploader cannot put it into bootloader mode. The ARDUBOY_NO_USB macro helps by giving the option to put the Arduboy back into bootloader mode when the down button is held as the Arduboy is turned on. There also is a function in the Arduboy2 library called arduboy.exitToBootloader(). FX-enabled Arduboys do not have this problem as by holding up and down for multiple seconds or turning off and on again will put it into bootloader mode and allow uploads to continue. It is highly recommended when posting a game to tell others in bold letters: "This game removes the USB stack. [If FX is not required] Press down while turning on to go into bootloader mode."

Tips for Reducing RAM

  • Put PROGMEM on arrays/data that will not change. Note you will have to use pgm_read_byte(&array[index]) or some variant of it (see documentation here).
  • Declare variables constexpr if they do not change.
  • Put string literals in PROGMEM by surrounding them with the F("string literal here") macro. Pharap's FlashStringHelper library is very helpful when dealing with strings in PROGMEM.
  • Use locals instead of globals when possible. Locals are stored on the stack and exist only in a scope, while globals are stored for the entire lifetime of the program.
  • Pack variables into bits as much as possible. For example, instead of using an array of 8 bools, use 1 byte with each bit representing a bool. Reading and writing bits can be done with bitRead(number, bit) and bitWrite(number, bit, value).