Arduboy Wiki - User contributions [en]

Reducing PROGMEM and RAM Usage

2024-07-20T01:55:06Z

Sublinear: Fix link to Compiler Explorer

== Overview ==
The [[What is the Arduboy|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)[[File:Open Disassembly Tab.png|thumb|206x206px|Opening the disassembly tab.]]
** Click on the "Jump to Function" dropdown.[[File:Example Function Dropdown in Ardens.png|thumb|269x269px|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:
<pre>
#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();

}
</pre>

** 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 <code>arduboy.boot();</code> and <code>arduboy.safeMode();</code> instead of <code>arduboy.begin();</code>. <code>arduboy.systemButtons();</code> and <code>arduboy.waitNoButtons();</code> can also be added for convenience (turning on and off sound at bootup). Note that this will get rid of the scrolling logo.
* Use <code>Arduboy2Base</code> instead of <code>Arduboy2</code> if you don’t use text.
** You can also switch to [https://github.com/BotiKis/Arduboy-TinyFont TinyFont] or [https://github.com/filmote/Font3x5 Font3x5]/[https://github.com/filmote/Font4x6 Font4x6], which use less bytes.
* Use smaller integer sizes when possible. For example, instead of using <code>int</code>/ <code>int16_t</code> for a screen position, you can use <code>int8_t</code>. Because the [[What is the Arduboy|Arduboy]] has an 8-bit CPU, anything larger adds extra instructions/functions.
* Avoid using floats! The [[What is the Arduboy|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 [[What is the Arduboy|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 <code>x /= 4;</code> instead of of <code>x /= 3;</code>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 <code>x %= 3</code>, write <code>if (x > 2) x = 0;</code>.
* As a last resort, you can remove the USB stack by adding the <code>ARDUBOY_NO_USB</code> 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 [[What is the Arduboy|Arduboy]], as the uploader cannot put it into bootloader mode.''' The <code>ARDUBOY_NO_USB</code> macro helps by giving the option to put the [[What is the Arduboy|Arduboy]] back into bootloader mode when the down button is held as the [[What is the Arduboy|Arduboy]] is turned on. There also is a function in the Arduboy2 library called <code>[https://mlxxxp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/classArduboy2Core.html#adc24b0f64d1a1ead904a1bdbaf8a776b arduboy.exitToBootloader()]</code>. [[What is the Arduboy#Arduboy FX|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 <code>pgm_read_byte(&array[index])</code> or some variant of it (see documentation [https://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html here]).
* Declare variables <code>constexpr</code> if they do not change.
* Put string literals in PROGMEM by surrounding them with the <code>F("string literal here")</code> macro. Pharap's [https://github.com/Pharap/FlashStringHelperDemo 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 <code>bitRead(number, bit)</code> and <code>bitWrite(number, bit, value)</code>.

Main Page

2024-07-09T23:09:09Z

Sublinear: /* Tutorials */ Added link to Reducing PROGMEM and RAM Usage

== Getting started ==

* [[What is the Arduboy|What is the Arduboy?]]
** [[What is the Arduboy#Arduboy Variants|Arduboy Variants]]
* [[Installing Games]]
* [[Developing Games]]

Don't know where to start at all? See the official [https://www.arduboy.com/quick-start Quickstart guide] for a simplified overview.

There is also a [https://community.arduboy.com/t/quick-start-guide/2790 Legacy Quickstart guide] that might be of some use (made for older Arduboy variants but still mostly relevant)

== Community ==

Come chat with the community and show off your games at https://community.arduboy.com/! The bulk of the Arduboy community exists on the forums; there isn't an official Discord/etc.

* '''Main Arduboy website:''' https://www.arduboy.com/
* '''Community website:''' https://community.arduboy.com/

== Tools ==
* [[Ardens]] - Debugger, profiler, and emulator
* [[Arduboy Toolset]] - Various tools for uploading, converting, etc
* [[Cart Builder]] - Home for the official flashcart + all games made available for it
* [[Arduboy-Python-Utilities]] - Command line python tools for uploading, converting, etc

== Tutorials ==
* Misc.
** [[Reducing PROGMEM and RAM Usage]]
* State Machines
** [[State%20Machines|Introduction]]
** [[State Machines - Organising Variables|Organising Variables]]
* High Scores
** [[High Score - Getting Started|Getting Started]]
** [[High Score - High Scores and Slots|High Scores and Slots]]
** [[High Score - Capturing The Players Initials|Capturing The Players Initials]]
** [[High Score - Creating a New Entry in the Correct Location|Creating a New Entry in the Correct Location]]
** [[High Score - Writing it to the EEPROM|Writing it to the EEPROM]]
* Frogger
** [[Frogger Getting Started|Getting Started]]
** [[Frogger - Implementing the Cars|Implementing the Cars]]
** [[Frogger - Mixing up the Car Movements|Mixing up the Car Movements]]
** [[Frogger - Adding the Frog|Adding the Player's Frog]]
** [[Frogger - Collision Detection and Explosion Graphics|Collision Detection and Explosion Graphics]]
** [[Frogger - Adding Logs and Turtles|Adding Logs and Turtles]]
** [[Frogger - Turtle Submerge Logic|Turtle Submerge Logic]]
** [[Frogger - Adding Home Logic|Adding Home Logic]]
** [[Frogger - Adding Score Logic|Adding Score Logic]]
** [[Frogger - Adding a Title and Game Over Screen|Adding a Title and Game Over Screen]]

== Documentation ==
* [[Flashcart Format]]

Reducing PROGMEM and RAM Usage

2024-07-09T23:00:46Z

Sublinear: Added page for Reducing PROGMEM and RAM Usage.

== Overview ==
The [[What is the Arduboy|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)[[File:Open Disassembly Tab.png|thumb|206x206px|Opening the disassembly tab.]]
** Click on the "Jump to Function" dropdown.[[File:Example Function Dropdown in Ardens.png|thumb|269x269px|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:<pre>
#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();

}
</pre>
** That small modification will save us thousands of bytes!
* Use [https://godbolt.org/#g:!((g:!((g:!((h:codeEditor,i:(filename:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,selection:(endColumn:2,endLineNumber:7,positionColumn:2,positionLineNumber:7,selectionStartColumn:2,selectionStartLineNumber:7,startColumn:2,startLineNumber:7),source:'//+Type+your+code+here,+or+load+an+example.%0A%23include+%3Cstdint.h%3E%0A%0Auint8_t+div_thousand(uint32_t+x)+%7B%0A%0A++++return+x+/+1024%3B%0A%7D'),l:'5',n:'1',o:'C%2B%2B+source+%231',t:'0')),k:50,l:'4',n:'0',o:'',s:0,t:'0'),(g:!((h:compiler,i:(compiler:avrg1410,filters:(b:'0',binary:'1',binaryObject:'1',commentOnly:'0',debugCalls:'1',demangle:'0',directives:'0',execute:'1',intel:'0',libraryCode:'0',trim:'1',verboseDemangling:'0'),flagsViewOpen:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,libs:!(),options:'-O2+-mmcu%3Datmega32u4',overrides:!(),selection:(endColumn:1,endLineNumber:1,positionColumn:1,positionLineNumber:1,selectionStartColumn:1,selectionStartLineNumber:1,startColumn:1,startLineNumber:1),source:1),l:'5',n:'0',o:'+AVR+gcc+14.1.0+(Editor+%231)',t:'0')),k:50,l:'4',n:'0',o:'',s:0,t:'0')),l:'2',n:'0',o:'',t:'0')),version:4 Godbolt] 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 <code>arduboy.boot();</code> and <code>arduboy.safeMode();</code> instead of <code>arduboy.begin();</code>. <code>arduboy.systemButtons();</code> and <code>arduboy.waitNoButtons();</code> can also be added for convenience (turning on and off sound at bootup). Note that this will get rid of the scrolling logo.
* Use <code>Arduboy2Base</code> instead of <code>Arduboy2</code> if you don’t use text.
** You can also switch to [https://github.com/BotiKis/Arduboy-TinyFont TinyFont] or [https://github.com/filmote/Font3x5 Font3x5]/[https://github.com/filmote/Font4x6 Font4x6], which use less bytes.
* Use smaller integer sizes when possible. For example, instead of using <code>int</code>/ <code>int16_t</code> for a screen position, you can use <code>int8_t</code>. Because the [[What is the Arduboy|Arduboy]] has an 8-bit CPU, anything larger adds extra instructions/functions.
* Avoid using floats! The [[What is the Arduboy|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 [[What is the Arduboy|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 <code>x /= 4;</code> instead of of <code>x /= 3;</code>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 <code>x %= 3</code>, write <code>if (x > 2) x = 0;</code>.
* As a last resort, you can remove the USB stack by adding the <code>ARDUBOY_NO_USB</code> 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 [[What is the Arduboy|Arduboy]], as the uploader cannot put it into bootloader mode.''' The <code>ARDUBOY_NO_USB</code> macro helps by giving the option to put the [[What is the Arduboy|Arduboy]] back into bootloader mode when the down button is held as the [[What is the Arduboy|Arduboy]] is turned on. There also is a function in the Arduboy2 library called <code>[https://mlxxxp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/classArduboy2Core.html#adc24b0f64d1a1ead904a1bdbaf8a776b arduboy.exitToBootloader()]</code>. [[What is the Arduboy#Arduboy FX|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 <code>pgm_read_byte(&array[index])</code> or some variant of it (see documentation [https://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html here]).
* Declare variables <code>constexpr</code> if they do not change.
* Put string literals in PROGMEM by surrounding them with the <code>F("string literal here")</code> macro. Pharap's [https://github.com/Pharap/FlashStringHelperDemo 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 <code>bitRead(number, bit)</code> and <code>bitWrite(number, bit, value)</code>.

File:Example Function Dropdown in Ardens.png

2024-07-09T21:59:13Z

Sublinear:

This shows the contents of the Jump to Function dropdown in Ardens.

File:Open Disassembly Tab.png

2024-07-09T21:53:22Z

Sublinear:

A screenshot of how to open the disassembly tab in Ardens.