Different ways to allocate RAM usage for your feature

Rockbox has a "No Malloc" policy you can read about at WhyNoMalloc but sometimes you really do need to grab some buffer possibly temporarily. This page will explain the different methods available.

Compile-time RAM layout

As an example, this list shows the sections in a compiled rockbox.elf, indicating how RAM is allocated at compile-time. The section arrangement varies somewhat between platforms and is determined by the linker script (firmware/target/arm/as3525/app.lds in this case, for the Sansa e200v2). The interesting parts for memory allocation are audiobuf, codecbuf, and pluginbuf.

Size	Name	Description
32 B	.vectors	ARM interrupt vectors
460 KiB	.text	Machine code
102 KiB	.rodata	Read-only (const) global data
8 KiB	.data	Global data
8 KiB	.stack	Stack for the initial thread
384 KiB	.bss	Global data initialized with zero
5679 KiB	audiobuf	Audio buffer for audio and/or miscellaneous data
1024 KiB	codecbuf	Codec buffer for codecs and their data
512 KiB	pluginbuf	Plugin buffer for plugins and their data
7 KiB	.iram	Machine code and global data (.icode, .irodata, .idata), in fast IRAM
97 KiB	.ibss	Global data initialized with zero, in fast IRAM

When a plugin is loaded, its code and data go in the start of pluginbuf. Codecs work the same way.

Allocation methods

Note that this covers getting memory in the first place. In some cases, a full malloc() is unavoidable; you must get a large buffer with one of these methods and use TLSF to allocate within the large buffer.

Global variables

By far the easiest method:

static char my_buffer[BUFFER_SIZE];

This can be used anywhere. In a codec or plugin, space will be reserved in codecbuf or pluginbuf until the codec/plugin is unloaded. Otherwise, space will be reserved permanently in .data, .rodata, or .bss.

• Easy, fast, no overhead.
• Can't be freed or resized.
• Size must be known at compile-time.

Allocate from soundbuf

char *my_buffer = buffer_alloc(BUFFER_SIZE);

This takes some space from the front of soundbuf. It can't be used by plugins or codecs, since it can't be freed. This method is useful when the size required is known at boot-time.

• Easy, fast, no overhead.
• Can't be freed or resized.
• Playback must be stopped to allocate more.

Use the rest of the codec/plugin buffer

size_t size_available;
// In codec:
void *my_buffer = ci->codec_get_buffer(&size_available);
// In plugin:
void *my_buffer = rb->plugin_get_buffer(&size_available);

This is used by codecs/plugins to get the rest of the codec/plugin buffer. This space is reserved for the codec/plugin anyway, so you may as well use it!

• Easy, fast, no overhead.
• Limited to the size left in the buffer, which depends on the platform.

Steal the sound buffer

size_t size_available;
void *my_buffer = rb->plugin_get_audio_buffer(&size_available);

If a plugin stops playback, it can use the sound buffer.

• Lots of space.
• Playback must be stopped the entire time the sound buffer is used.

Use buflib

BuflibMemoryManagement is a project to allocate memory more dynamically. The project is just beginning as of May 2011.

• Flexible.
• Allocations can move around whenever buflib is called or other threads are running. You need to keep track of the current location.
• Other aspects of the project have not yet been determined.